常用入口

语言：简体中文 · English

portfolio-backtester 提供五类调用入口，覆盖从高层回测规范到低层持仓回放的不同需求。初次使用时，建议从入口 1 开始。

1. 使用组合规范运行回测（推荐）

新代码建议使用 BacktestSpec 和 run_backtest。StrategySpec 负责选股和权重设置，ExecutionModel 负责开仓价、退出规则、成本、滑点和筛选约束。回测区间和调仓设置保存在 BacktestSpec 中。

import pandas as pd

from portfolio_backtester import BacktestSpec, StrategySpec, run_backtest
from portfolio_backtester.execution import build_execution_model

# scores 的 DataFrame 构造省略。它至少包含 trade_date、symbol、signal 和 close。
execution = build_execution_model(
    None,
    default_cost_bps=10.0,
    default_exit_price_policy="strict",
    default_exit_fallback_policy="ffill",
    default_price_col="close",
)
spec = BacktestSpec(
    strategy=StrategySpec(
        name="topk-demo",
        type="topk_buffered_long_only",
        score_col="signal",
        top_k=20,
        buffer_exit=5,
        weighting="equal",
    ),
    execution=execution,
    rebalance_dates=(
        pd.Timestamp("2026-01-05"),
        pd.Timestamp("2026-01-12"),
    ),
    shift_days=1,
    trading_days_per_year=252,
)

result = run_backtest(scores, spec)

BacktestSpec.to_mapping() 可以生成适合写入 JSON 或 YAML 的配置，BacktestSpec.from_mapping() 可以恢复规范。行情表不写入配置，信号和定价数据在运行时传给 run_backtest。

研究低换手策略时，可以设置 selection_min_score 和 max_new_names_per_rebalance。如果需要限制新证券排名，并让未填满的槽位保留现金，可以组合使用 entry_rank_cutoff 和 target_weight_policy="fixed_slot"。如果目标名单不应受开仓日价格或可交易性影响，可以设置 selection_price_policy="target_first"。默认情况下，entry_rank_cutoff 为 None，target_weight_policy 为 normalized，selection_price_policy 为 execution_aware，以维持既有入口行为。完整语义见组合式回测规范。

输入数据通常需要以下字段：

trade_date
symbol
分数列，例如 signal
价格列，例如 close
执行模型需要的流动性列或可交易标记

2. 使用历史 Top-K 兼容入口

backtest_topk 保留原有签名和默认行为。它会把参数转换为 StrategySpec、ExecutionModel 和 BacktestSpec，再调用统一的执行路径。现阶段该入口不会发出弃用警告。

from portfolio_backtester import backtest_topk

3. 先构造持仓，再单独回测

使用 StrategySpec 和 construct_positions_from_strategy 生成标准持仓，再把结果交给 run_position_backtest。这种方式便于检查目标持仓、保存中间结果和复用定价逻辑。

from portfolio_backtester import StrategySpec, construct_positions_from_strategy

4. 回放已有目标持仓

使用 PositionBacktestConfig 和 run_position_backtest。这种方式适合从其他模型、优化器或人工流程接收持仓。这个底层入口只负责策略自身收益、成本和风险汇总，不持有 benchmark 数据。

5. 对持仓回测做 benchmark 评估

需要 tracking error、Information Ratio、alpha、beta、相关系数和主动收益时，使用 evaluate_position_backtest。benchmark 日收益会先按每个持有期的 entry/exit 日期复合，随后才与策略 period returns 对齐。

from portfolio_backtester import PositionBacktestConfig, evaluate_position_backtest

evaluation = evaluate_position_backtest(
    positions=positions,
    pricing=pricing,
    periods=periods,
    config=PositionBacktestConfig(transaction_cost_bps=10.0),
    benchmark_return_series=benchmark_daily_returns,
)

strategy_stats = evaluation.backtest.summary["stats"]
benchmark_stats = evaluation.benchmark_stats
active_stats = evaluation.active_stats

基准行情表也可以通过 benchmark_df 传入。价格列与策略不一致时，显式设置 benchmark_entry_price_col 和 benchmark_exit_price_col。