feat(backend): Phase 2 研究引擎 — ResearchSpec / 因子 / 评估 / 低频回测 / 引擎抽象
- domain：ResearchSpec（universe/factors/selection/rebalance/costs 校验）+ 标准化 BacktestResult / FactorTestReport - 因子引擎：注册表 + 元数据，内置 9 个行情因子（momentum/volatility/量比/乖离/反转），支持自定义注册；只用行情字段规避未来函数 - 评估：横截面 IC / RankIC（rank+pearson 免 scipy）/ ICIR / 分层收益 - 回测：TopK 等权低频，无未来函数记账（t 收盘成交、自 t+1 计收益），成本/涨跌停/停牌约束，未建模项显式写入 unimplemented（AGENT §24） - 引擎抽象 QuantEngine + LocalEngine（pandas 默认实现）；qlib_adapter 桥接占位 —— pyqlib 无 aarch64+cp312 wheel（ROADMAP 已备注） - 真实链路冒烟：600519 2024 月度动量回测闭环产出标准结果 - 测试 60 passed / ruff clean
This commit is contained in:
Simon
@@ -0,0 +1,338 @@
|
||||
"""LocalEngine —— 默认研究引擎（纯 pandas，AGENT.md §40 简单可替换优先）。
|
||||
|
||||
无未来函数纪律：
|
||||
- 调仓日 t 的选股只使用 <=t 的因子值与收盘价
|
||||
- 成交发生在 t 收盘（价格 = close[t] ± 滑点）；t 当日组合收益用 t-1 收盘持仓结算，
|
||||
调仓在 t 收盘生效、自 t+1 起计收益 —— 不存在「当日买入当日计收益」的未来函数
|
||||
- 涨跌停 / 停牌约束按可达信息近似建模，未建模部分显式写入结果 unimplemented
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import math
|
||||
from dataclasses import dataclass
|
||||
from datetime import date
|
||||
|
||||
import pandas as pd
|
||||
|
||||
from app.domain.entities.research import (
|
||||
BacktestResult,
|
||||
BacktestSummary,
|
||||
CurvePoint,
|
||||
FactorTestReport,
|
||||
MonthlyReturn,
|
||||
Position,
|
||||
ResearchSpec,
|
||||
Trade,
|
||||
YearlyReturn,
|
||||
)
|
||||
from app.quant.evaluation import run_factor_test
|
||||
from app.quant.factors import FactorDef, compute_factor
|
||||
|
||||
TRADING_DAYS = 252
|
||||
_DEFAULT_UNIMPLEMENTED = [
|
||||
"涨跌停按收盘价相对上一有效收盘近似判定（未建模开盘一字 / 集合竞价路径）",
|
||||
"成交假设发生在调仓日收盘（未建模盘中价格路径与流动性冲击）",
|
||||
]
|
||||
|
||||
|
||||
def _limit_up_ratio(symbol: str) -> float:
|
||||
"""按板块近似涨跌停幅度。"""
|
||||
code = symbol[:3]
|
||||
if code in {"300", "301", "688"}:
|
||||
return 1.199
|
||||
if code.startswith(("8", "4", "92")):
|
||||
return 1.299
|
||||
return 1.099
|
||||
|
||||
|
||||
def cross_sectional_zscore(panel: pd.DataFrame) -> pd.DataFrame:
|
||||
"""截面 z-score。
|
||||
|
||||
候选不足 2 只（如单股票池）时退化为 0：无比较基准，但保留为可候选值；
|
||||
全列缺失才为 NaN（该日不可选股）。
|
||||
"""
|
||||
|
||||
def _row_z(row: pd.Series) -> pd.Series:
|
||||
valid = row.dropna()
|
||||
if len(valid) == 0:
|
||||
return pd.Series(float("nan"), index=row.index)
|
||||
if len(valid) == 1:
|
||||
return pd.Series(0.0, index=row.index)
|
||||
mu, sd = valid.mean(), valid.std()
|
||||
if sd == 0 or math.isnan(sd):
|
||||
return pd.Series(0.0, index=row.index)
|
||||
return (row - mu) / sd
|
||||
|
||||
return panel.apply(_row_z, axis=1)
|
||||
|
||||
|
||||
def composite_score(
|
||||
panels: list[tuple[str, pd.DataFrame, float, str]],
|
||||
) -> pd.DataFrame:
|
||||
"""按 (name, panel, weight, direction) 计算加权复合 zscore。
|
||||
|
||||
direction="lower_is_better" 的因子取负号后相加（统一为「得分高者优先」）。
|
||||
"""
|
||||
total = None
|
||||
for _name, panel, weight, direction in panels:
|
||||
z = cross_sectional_zscore(panel)
|
||||
if direction == "lower_is_better":
|
||||
z = -z
|
||||
contribution = z * weight
|
||||
total = contribution if total is None else total.add(contribution, fill_value=0)
|
||||
assert total is not None
|
||||
return total
|
||||
|
||||
|
||||
def rebalance_dates(index: pd.Index, rebalance: str, start: date) -> list[pd.Timestamp]:
|
||||
"""按频率取首个交易日（>= start）。"""
|
||||
periods = index.to_period("M" if rebalance == "monthly" else "W")
|
||||
seen: dict = {}
|
||||
order: list[pd.Timestamp] = []
|
||||
for ts, per in zip(index, periods, strict=True):
|
||||
if per not in seen:
|
||||
seen[per] = ts
|
||||
order.append(ts)
|
||||
return [ts for ts in order if ts.date() >= start]
|
||||
|
||||
|
||||
@dataclass
|
||||
class EngineResult:
|
||||
equity: pd.Series # index=date -> equity
|
||||
trades: list[Trade]
|
||||
positions: list[Position]
|
||||
rebalance_notional: list[float]
|
||||
|
||||
|
||||
class TopKBacktestRunner:
|
||||
"""TopK 等权、固定调仓频率的低频回测。"""
|
||||
|
||||
def __init__(self, spec: ResearchSpec, score: pd.DataFrame, close: pd.DataFrame) -> None:
|
||||
self.spec = spec
|
||||
close = close.copy()
|
||||
close.index = pd.to_datetime(close.index)
|
||||
self.close = close.sort_index()
|
||||
self.score = score.reindex(self.close.index).sort_index()
|
||||
self.costs = spec.costs
|
||||
# 上一有效收盘（用于涨跌停与收益结算，处理停牌日）
|
||||
self.prev_close = self.close.ffill().shift(1)
|
||||
|
||||
def run(self) -> BacktestResult:
|
||||
end_date = self.spec.period[1]
|
||||
dates = [d for d in self.close.index if self.spec.period[0] <= d.date() <= end_date]
|
||||
rebal = {
|
||||
d
|
||||
for d in rebalance_dates(self.close.index, self.spec.rebalance, self.spec.period[0])
|
||||
if d.date() <= end_date
|
||||
}
|
||||
cash = float(self.spec.initial_capital)
|
||||
shares: dict[str, float] = {}
|
||||
entry_date: dict[str, date] = {}
|
||||
entry_price: dict[str, float] = {}
|
||||
equity_rows: dict[pd.Timestamp, float] = {}
|
||||
trades: list[Trade] = []
|
||||
positions: list[Position] = []
|
||||
notional: list[float] = []
|
||||
|
||||
def _value(d: pd.Timestamp) -> float:
|
||||
total = cash
|
||||
for s, qty in shares.items():
|
||||
if qty <= 0:
|
||||
continue
|
||||
px = self.close.at[d, s] if d in self.close.index else None
|
||||
if px is None or (isinstance(px, float) and math.isnan(px)):
|
||||
continue # 无行情日不计该仓（停牌近似，见 unimplemented）
|
||||
total += float(qty * px)
|
||||
return total
|
||||
|
||||
for d in dates:
|
||||
if d in rebal:
|
||||
cash = self._rebalance(
|
||||
d, cash, shares, entry_date, entry_price, trades, positions, notional
|
||||
)
|
||||
equity_rows[d] = _value(d)
|
||||
|
||||
equity = pd.Series(equity_rows).sort_index()
|
||||
return self._to_result(equity, trades, positions, notional)
|
||||
|
||||
# ---- 调仓（t 收盘执行，自 t+1 生效） ----
|
||||
|
||||
def _rebalance(self, d, cash, shares, entry_date, entry_price, trades, positions, notional):
|
||||
close_d = self.close.loc[d]
|
||||
prev_d = self.prev_close.loc[d]
|
||||
sold_notional = 0.0
|
||||
|
||||
# 1) 卖出：跌停或无价（停牌）持仓保留，其余卖出
|
||||
for s in [s for s in shares if shares[s] > 0]:
|
||||
c, p = close_d[s], prev_d[s]
|
||||
if _nan(c):
|
||||
continue # 停牌无价：保留
|
||||
if not _nan(p) and p > 0 and c / p <= 1.0 - (_limit_up_ratio(s) - 1.0):
|
||||
continue # 跌停无法卖出：保留到下一调仓
|
||||
qty = shares[s]
|
||||
proceeds = qty * float(c) * (1 - self.costs.slippage_rate)
|
||||
fee = proceeds * (self.costs.commission_rate + self.costs.stamp_tax_rate)
|
||||
cash += proceeds - fee
|
||||
sold_notional += proceeds
|
||||
trades.append(
|
||||
Trade(
|
||||
entry_date=entry_date[s],
|
||||
exit_date=d.date(),
|
||||
symbol=s,
|
||||
entry_price=entry_price[s],
|
||||
exit_price=float(c),
|
||||
return_pct=(float(c) / entry_price[s] - 1.0) * 100,
|
||||
)
|
||||
)
|
||||
shares[s] = 0.0
|
||||
entry_date.pop(s, None)
|
||||
entry_price.pop(s, None)
|
||||
|
||||
# 2) 买入：取得分最高且可买的 TopN（涨停 / 无价剔除）
|
||||
score_d = self.score.loc[d].dropna()
|
||||
top = score_d.sort_values(ascending=False).index.tolist()
|
||||
targets: list[str] = []
|
||||
for s in top:
|
||||
if len(targets) >= self.spec.selection.top_n:
|
||||
break
|
||||
c, p = close_d[s], prev_d[s]
|
||||
if _nan(c) or _nan(p) or p <= 0:
|
||||
continue
|
||||
if c / p >= _limit_up_ratio(s):
|
||||
continue # 涨停不可追买
|
||||
targets.append(s)
|
||||
|
||||
if targets:
|
||||
budget = cash / len(targets)
|
||||
for s in targets:
|
||||
c = float(close_d[s])
|
||||
price_in = c * (1 + self.costs.slippage_rate)
|
||||
invest = budget * (1 - self.costs.commission_rate)
|
||||
shares[s] = invest / price_in
|
||||
entry_date[s] = d.date()
|
||||
entry_price[s] = price_in
|
||||
notional.append(budget)
|
||||
cash -= budget * len(targets)
|
||||
|
||||
# 3) 记录调仓后仓位
|
||||
total = cash + sum(
|
||||
float(self.close.at[d, s] * qty)
|
||||
for s, qty in shares.items()
|
||||
if qty > 0 and not _nan(self.close.at[d, s])
|
||||
)
|
||||
if total > 0:
|
||||
for s, qty in shares.items():
|
||||
if qty > 0 and not _nan(self.close.at[d, s]):
|
||||
positions.append(
|
||||
Position(
|
||||
date=d.date(), symbol=s, weight=float(qty * self.close.at[d, s] / total)
|
||||
)
|
||||
)
|
||||
return cash
|
||||
|
||||
# ---- 指标 ----
|
||||
|
||||
def _to_result(self, equity, trades, positions, notional) -> BacktestResult:
|
||||
start, end = equity.index[0].date(), equity.index[-1].date()
|
||||
init = float(self.spec.initial_capital)
|
||||
final = float(equity.iloc[-1])
|
||||
rets = equity.pct_change().dropna()
|
||||
n = len(rets)
|
||||
total_ret = (final / init - 1.0) * 100 if init else 0.0
|
||||
annual = (
|
||||
((final / init) ** (TRADING_DAYS / max(n, 1)) - 1.0) * 100
|
||||
if final > 0 and init > 0
|
||||
else -100.0
|
||||
)
|
||||
mean_r, std_r = (float(rets.mean()), float(rets.std(ddof=1))) if n else (0.0, 0.0)
|
||||
sharpe = mean_r / std_r * math.sqrt(TRADING_DAYS) if std_r and mean_r else 0.0
|
||||
vol = std_r * math.sqrt(TRADING_DAYS) * 100
|
||||
dd = (equity / equity.cummax() - 1.0).min() * 100
|
||||
wins = [t for t in trades if t.return_pct > 0]
|
||||
win_rate = len(wins) / len(trades) * 100 if trades else 0.0
|
||||
avg_turn = (sum(notional) / len(notional) / ((init + final) / 2)) * 100 if notional else 0.0
|
||||
|
||||
eq_pts = [CurvePoint(date=d.date(), value=round(float(v), 2)) for d, v in equity.items()]
|
||||
dd_series = (equity / equity.cummax() - 1.0) * 100
|
||||
drawdown = [
|
||||
CurvePoint(date=d.date(), value=round(float(v), 3)) for d, v in dd_series.items()
|
||||
]
|
||||
|
||||
monthly: list[MonthlyReturn] = []
|
||||
yearly: list[YearlyReturn] = []
|
||||
if len(equity) > 1:
|
||||
m = equity.resample("ME").last().pct_change().dropna()
|
||||
monthly = [
|
||||
MonthlyReturn(
|
||||
year=int(d.year), month=int(d.month), return_pct=round(float(v) * 100, 3)
|
||||
)
|
||||
for d, v in m.items()
|
||||
]
|
||||
y = equity.resample("YE").last().pct_change().dropna()
|
||||
yearly = [
|
||||
YearlyReturn(year=int(d.year), return_pct=round(float(v) * 100, 3))
|
||||
for d, v in y.items()
|
||||
]
|
||||
|
||||
summary = BacktestSummary(
|
||||
start=start,
|
||||
end=end,
|
||||
initial_capital=round(init, 2),
|
||||
final_equity=round(final, 2),
|
||||
total_return_pct=round(total_ret, 3),
|
||||
annual_return_pct=round(annual, 3),
|
||||
sharpe=round(sharpe, 3),
|
||||
max_drawdown_pct=round(float(dd), 3),
|
||||
volatility_pct=round(vol, 3),
|
||||
win_rate_pct=round(win_rate, 2),
|
||||
total_trades=len(trades),
|
||||
avg_turnover_pct=round(avg_turn, 2),
|
||||
)
|
||||
return BacktestResult(
|
||||
summary=summary,
|
||||
equity_curve=eq_pts,
|
||||
drawdown=drawdown,
|
||||
monthly_returns=monthly,
|
||||
yearly_returns=yearly,
|
||||
positions=positions,
|
||||
trades=trades,
|
||||
turnover_pct=round(sum(notional) / max(init, 1) * 100, 2),
|
||||
unimplemented=list(_DEFAULT_UNIMPLEMENTED),
|
||||
config_snapshot=self.spec.model_dump(mode="json"),
|
||||
)
|
||||
|
||||
|
||||
def build_factor_panels(
|
||||
daily: pd.DataFrame, factor_specs
|
||||
) -> list[tuple[str, pd.DataFrame, float, str]]:
|
||||
"""按 spec.factors 计算面板与权重（因子不存在即报错）。"""
|
||||
panels: list[tuple[str, pd.DataFrame, float, str]] = []
|
||||
for fs in factor_specs:
|
||||
defn: FactorDef
|
||||
defn, panel = compute_factor(fs.name, daily)
|
||||
panels.append((fs.name, panel, fs.weight, defn.direction))
|
||||
return panels
|
||||
|
||||
|
||||
def run_spec_factor_test(
|
||||
daily: pd.DataFrame,
|
||||
spec: ResearchSpec,
|
||||
horizon_days: int = 21,
|
||||
) -> tuple[FactorTestReport, dict[str, pd.DataFrame]]:
|
||||
"""单因子测试：因子面板 + 未来 horizon 收益 → FactorTestReport。"""
|
||||
assert spec.type == "factor_test"
|
||||
factor_name = spec.factors[0].name
|
||||
panels = build_factor_panels(daily, spec.factors)
|
||||
panel = panels[0][1]
|
||||
close = daily.pivot(index="trade_date", columns="symbol", values="close").sort_index()
|
||||
forward = close.shift(-horizon_days) / close - 1.0
|
||||
report = run_factor_test(panel, forward, factor_name=factor_name)
|
||||
return report, {factor_name: panel}
|
||||
|
||||
|
||||
def _nan(v) -> bool:
|
||||
try:
|
||||
return bool(math.isnan(float(v)))
|
||||
except (TypeError, ValueError):
|
||||
return False
|
||||
Reference in New Issue
Block a user