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,48 @@
|
||||
"""研究引擎抽象与默认实现（业务层依赖本接口，可替换引擎）。
|
||||
|
||||
切换引擎（如未来在支持平台启用 Qlib）只需注入不同实现 —— 业务代码不变。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Protocol
|
||||
|
||||
import pandas as pd
|
||||
|
||||
from app.domain.entities.research import BacktestResult, FactorTestReport, ResearchSpec
|
||||
from app.quant.local_engine import (
|
||||
TopKBacktestRunner,
|
||||
build_factor_panels,
|
||||
composite_score,
|
||||
run_spec_factor_test,
|
||||
)
|
||||
|
||||
|
||||
class QuantEngine(Protocol):
|
||||
"""研究引擎端口：因子面板构建 / 因子测试 / 回测。"""
|
||||
|
||||
name: str
|
||||
|
||||
def run_factor_test(
|
||||
self, daily: pd.DataFrame, spec: ResearchSpec, horizon_days: int = 21
|
||||
) -> FactorTestReport: ...
|
||||
|
||||
def run_backtest(self, daily: pd.DataFrame, spec: ResearchSpec) -> BacktestResult: ...
|
||||
|
||||
|
||||
class LocalEngine:
|
||||
"""默认引擎：纯 pandas 实现（无 Qlib 依赖），见 local_engine.py 的纪律说明。"""
|
||||
|
||||
name = "local"
|
||||
|
||||
def run_factor_test(
|
||||
self, daily: pd.DataFrame, spec: ResearchSpec, horizon_days: int = 21
|
||||
) -> FactorTestReport:
|
||||
report, _panels = run_spec_factor_test(daily, spec, horizon_days)
|
||||
return report
|
||||
|
||||
def run_backtest(self, daily: pd.DataFrame, spec: ResearchSpec) -> BacktestResult:
|
||||
panels = build_factor_panels(daily, spec.factors)
|
||||
score = composite_score(panels)
|
||||
close = daily.pivot(index="trade_date", columns="symbol", values="close").sort_index()
|
||||
return TopKBacktestRunner(spec, score, close).run()
|
||||
@@ -0,0 +1,102 @@
|
||||
"""因子评估：截面 IC / RankIC / ICIR / 分层收益（AGENT.md §23）。
|
||||
|
||||
输入均为 面板（index=trade_date, columns=symbol）：
|
||||
- factor：因子值
|
||||
- forward：未来 horizon 期收益（每行是「当日可见、未来实现」的收益，用于横截面相关）
|
||||
|
||||
任何消费侧必须保证 factor 行 t 只用 <= t 的信息，forward 是 t 之后的实现 ——
|
||||
两者错位即未来函数，由数据构造方负责（本模块只做统计）。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import math
|
||||
|
||||
import pandas as pd
|
||||
|
||||
from app.domain.entities.research import FactorTestReport, QuantileReturn
|
||||
|
||||
MIN_CROSS_SECTION = 5 # 少于该样本数的日期跳过（避免噪声 IC）
|
||||
|
||||
|
||||
def cross_sectional_ic(
|
||||
factor: pd.DataFrame, forward: pd.DataFrame, method: str = "pearson"
|
||||
) -> pd.Series:
|
||||
"""逐日横截面相关（pearson=IC；spearman=RankIC 用 rank+pearson 等价，免 scipy）。"""
|
||||
rows: dict[pd.Timestamp, float] = {}
|
||||
idx = factor.index.intersection(forward.index)
|
||||
for dt in idx:
|
||||
f = factor.loc[dt].dropna()
|
||||
r = forward.loc[dt].reindex(f.index)
|
||||
pair = pd.concat([f, r], axis=1).dropna()
|
||||
if len(pair) < MIN_CROSS_SECTION:
|
||||
continue
|
||||
a, b = pair.iloc[:, 0], pair.iloc[:, 1]
|
||||
if method == "spearman":
|
||||
a, b = a.rank(), b.rank()
|
||||
ic = a.corr(b)
|
||||
if math.isfinite(ic):
|
||||
rows[dt] = float(ic)
|
||||
return pd.Series(rows, dtype=float).sort_index()
|
||||
|
||||
|
||||
def _icir(series: pd.Series) -> float:
|
||||
if len(series) < 2:
|
||||
return 0.0
|
||||
std = float(series.std(ddof=1))
|
||||
if std == 0 or math.isnan(std):
|
||||
return 0.0
|
||||
return float(series.mean() / std * math.sqrt(len(series)))
|
||||
|
||||
|
||||
def quantile_returns(factor: pd.DataFrame, forward: pd.DataFrame, quantiles: int = 5) -> pd.Series:
|
||||
"""逐日按因子值升序分层，返回各层平均未来收益（跨日再平均）。"""
|
||||
acc = {q: [] for q in range(quantiles)}
|
||||
idx = factor.index.intersection(forward.index)
|
||||
for dt in idx:
|
||||
f = factor.loc[dt].dropna()
|
||||
r = forward.loc[dt].reindex(f.index)
|
||||
pair = pd.concat([f, r], axis=1).dropna()
|
||||
if len(pair) < quantiles * 2:
|
||||
continue
|
||||
try:
|
||||
labels = pd.qcut(pair.iloc[:, 0], quantiles, labels=False, duplicates="drop")
|
||||
except ValueError:
|
||||
continue
|
||||
grouped = pair.iloc[:, 1].groupby(labels).mean()
|
||||
for q, val in grouped.items():
|
||||
acc[int(q)].append(float(val))
|
||||
means = {q: (sum(v) / len(v) if v else float("nan")) for q, v in acc.items()}
|
||||
return pd.Series(means)
|
||||
|
||||
|
||||
def run_factor_test(
|
||||
factor: pd.DataFrame,
|
||||
forward: pd.DataFrame,
|
||||
*,
|
||||
factor_name: str = "",
|
||||
quantiles: int = 5,
|
||||
) -> FactorTestReport:
|
||||
ic = cross_sectional_ic(factor, forward, "pearson")
|
||||
rank_ic = cross_sectional_ic(factor, forward, "spearman")
|
||||
q_ret = quantile_returns(factor, forward, quantiles)
|
||||
|
||||
spread: int | None = None
|
||||
valid = [q for q in range(quantiles) if q in q_ret.index and not math.isnan(q_ret[q])]
|
||||
if len(valid) >= 2 and q_ret[valid[-1]] > q_ret[valid[0]]:
|
||||
spread = int(valid[-1]) # 高分层 > 低分层时报告层号
|
||||
|
||||
report = FactorTestReport(
|
||||
factor_name=factor_name or "factor",
|
||||
ic_mean=float(ic.mean()) if len(ic) else 0.0,
|
||||
icir=_icir(ic),
|
||||
rank_ic_mean=float(rank_ic.mean()) if len(rank_ic) else 0.0,
|
||||
positive_ratio_pct=float((ic > 0).mean() * 100) if len(ic) else 0.0,
|
||||
quantile_returns=[
|
||||
QuantileReturn(quantile=int(q), return_pct=round(float(v) * 100, 4))
|
||||
for q, v in sorted(q_ret.items())
|
||||
],
|
||||
spread_quantile=spread,
|
||||
sample_days=len(ic),
|
||||
)
|
||||
return report
|
||||
@@ -0,0 +1,184 @@
|
||||
"""因子引擎：因子注册表、元数据与计算（Phase 2，低频选股因子）。
|
||||
|
||||
数据形态：行情长表 DataFrame（列 symbol/trade_date/close/high/low/volume/amount），
|
||||
因子计算返回 面板 DataFrame（index=trade_date，columns=symbol）。
|
||||
所有内置因子只用行情字段（无财务），天然规避未来函数；财务因子接入时必须以
|
||||
announce_date 控制可见性（见 domain.entities.market.FinancialIndicator）。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Callable
|
||||
from dataclasses import dataclass
|
||||
|
||||
import pandas as pd
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class FactorDef:
|
||||
"""因子元数据（AGENT.md §22 要求逐项明确）。"""
|
||||
|
||||
name: str
|
||||
description: str
|
||||
formula: str
|
||||
frequency: str = "daily"
|
||||
lookback: int = 20
|
||||
direction: str = "higher_is_better" # | lower_is_better
|
||||
requires: tuple[str, ...] = ("close",)
|
||||
|
||||
|
||||
FactorFn = Callable[[dict[str, pd.DataFrame]], pd.DataFrame]
|
||||
|
||||
|
||||
class FactorError(ValueError):
|
||||
pass
|
||||
|
||||
|
||||
_REGISTRY: dict[str, tuple[FactorDef, FactorFn]] = {}
|
||||
|
||||
|
||||
def register(defn: FactorDef) -> Callable[[FactorFn], FactorFn]:
|
||||
"""装饰器：注册自定义因子。"""
|
||||
|
||||
def deco(fn: FactorFn) -> FactorFn:
|
||||
if defn.name in _REGISTRY:
|
||||
raise FactorError(f"因子 {defn.name} 已注册")
|
||||
_REGISTRY[defn.name] = (defn, fn)
|
||||
return fn
|
||||
|
||||
return deco
|
||||
|
||||
|
||||
def get_factor(name: str) -> tuple[FactorDef, FactorFn]:
|
||||
if name not in _REGISTRY:
|
||||
raise FactorError(f"未知因子：{name}（可用：{', '.join(sorted(_REGISTRY))}）")
|
||||
return _REGISTRY[name]
|
||||
|
||||
|
||||
def list_factors() -> list[FactorDef]:
|
||||
return [d for d, _fn in sorted(_REGISTRY.values(), key=lambda x: x[0].name)]
|
||||
|
||||
|
||||
def compute_factor(name: str, daily: pd.DataFrame) -> tuple[FactorDef, pd.DataFrame]:
|
||||
"""计算因子：从行情长表提取所需字段的面板后调用因子函数。"""
|
||||
defn, fn = get_factor(name)
|
||||
fields: dict[str, pd.DataFrame] = {}
|
||||
for col in defn.requires:
|
||||
panel = daily.pivot(index="trade_date", columns="symbol", values=col).sort_index()
|
||||
panel.index = pd.to_datetime(panel.index)
|
||||
fields[col] = panel
|
||||
return defn, fn(fields)
|
||||
|
||||
|
||||
# ---------- 内置因子 ----------
|
||||
|
||||
|
||||
def _rolling_return(prices: pd.DataFrame, lookback: int) -> pd.DataFrame:
|
||||
return prices / prices.shift(lookback) - 1.0
|
||||
|
||||
|
||||
def _rolling_vol(prices: pd.DataFrame, lookback: int) -> pd.DataFrame:
|
||||
return prices.pct_change().rolling(lookback).std()
|
||||
|
||||
|
||||
@register(
|
||||
FactorDef("momentum_20", "过去 20 个交易日收益率", "close / close.shift(20) - 1", lookback=20)
|
||||
)
|
||||
def _momentum_20(fields: dict[str, pd.DataFrame]) -> pd.DataFrame:
|
||||
return _rolling_return(fields["close"], 20)
|
||||
|
||||
|
||||
@register(
|
||||
FactorDef("momentum_60", "过去 60 个交易日收益率", "close / close.shift(60) - 1", lookback=60)
|
||||
)
|
||||
def _momentum_60(fields: dict[str, pd.DataFrame]) -> pd.DataFrame:
|
||||
return _rolling_return(fields["close"], 60)
|
||||
|
||||
|
||||
@register(
|
||||
FactorDef(
|
||||
"momentum_120", "过去 120 个交易日收益率", "close / close.shift(120) - 1", lookback=120
|
||||
)
|
||||
)
|
||||
def _momentum_120(fields: dict[str, pd.DataFrame]) -> pd.DataFrame:
|
||||
return _rolling_return(fields["close"], 120)
|
||||
|
||||
|
||||
@register(
|
||||
FactorDef(
|
||||
"volatility_20",
|
||||
"过去 20 个交易日收益率波动率",
|
||||
"std(pct_change, 20)",
|
||||
lookback=20,
|
||||
direction="lower_is_better",
|
||||
)
|
||||
)
|
||||
def _volatility_20(fields: dict[str, pd.DataFrame]) -> pd.DataFrame:
|
||||
return _rolling_vol(fields["close"], 20)
|
||||
|
||||
|
||||
@register(
|
||||
FactorDef(
|
||||
"volatility_60",
|
||||
"过去 60 个交易日收益率波动率",
|
||||
"std(pct_change, 60)",
|
||||
lookback=60,
|
||||
direction="lower_is_better",
|
||||
)
|
||||
)
|
||||
def _volatility_60(fields: dict[str, pd.DataFrame]) -> pd.DataFrame:
|
||||
return _rolling_vol(fields["close"], 60)
|
||||
|
||||
|
||||
@register(
|
||||
FactorDef(
|
||||
"close_to_high_60",
|
||||
"收盘价相对 60 日最高价的接近程度",
|
||||
"close / rolling_max(high, 60)",
|
||||
lookback=60,
|
||||
requires=("close", "high"),
|
||||
)
|
||||
)
|
||||
def _close_to_high_60(fields: dict[str, pd.DataFrame]) -> pd.DataFrame:
|
||||
high = fields["high"]
|
||||
return fields["close"] / high.rolling(60).max()
|
||||
|
||||
|
||||
@register(
|
||||
FactorDef(
|
||||
"volume_ratio_5_60",
|
||||
"量比：5 日均量 / 60 日均量",
|
||||
"mean(volume, 5) / mean(volume, 60)",
|
||||
lookback=60,
|
||||
requires=("volume",),
|
||||
)
|
||||
)
|
||||
def _volume_ratio_5_60(fields: dict[str, pd.DataFrame]) -> pd.DataFrame:
|
||||
vol = fields["volume"]
|
||||
return vol.rolling(5).mean() / vol.rolling(60).mean()
|
||||
|
||||
|
||||
@register(
|
||||
FactorDef(
|
||||
"ma_bias_20",
|
||||
"20 日均线乖离率",
|
||||
"(close - ma(close, 20)) / ma(close, 20)",
|
||||
lookback=20,
|
||||
)
|
||||
)
|
||||
def _ma_bias_20(fields: dict[str, pd.DataFrame]) -> pd.DataFrame:
|
||||
close = fields["close"]
|
||||
ma = close.rolling(20).mean()
|
||||
return (close - ma) / ma
|
||||
|
||||
|
||||
@register(
|
||||
FactorDef(
|
||||
"reversal_5",
|
||||
"短期反转：过去 5 日收益率取负（越低越接近超跌）",
|
||||
"-1 * (close / close.shift(5) - 1)",
|
||||
lookback=5,
|
||||
)
|
||||
)
|
||||
def _reversal_5(fields: dict[str, pd.DataFrame]) -> pd.DataFrame:
|
||||
return -1.0 * _rolling_return(fields["close"], 5)
|
||||
@@ -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
|
||||
@@ -0,0 +1,39 @@
|
||||
"""Qlib 后端引擎（桥接占位）。
|
||||
|
||||
当前开发平台为 Linux aarch64 + CPython 3.12：pyqlib 官方仅提供 x86_64 /
|
||||
macOS / Windows 且最高 Python 3.8 的 wheel（实测 uv 解析不可满足），因此
|
||||
Qlib 实现在此平台无法安装运行。
|
||||
|
||||
受支持平台（如 x86_64 Linux + Python 3.11）启用方式：
|
||||
cd backend && uv pip install pyqlib==0.9.7
|
||||
将本模块替换为真实实现：Parquet/本地行情 → QlibDataset → Alpha158 →
|
||||
LightGBM 训练/预测 → 回测，并归一化为 domain.entities.research 输出。
|
||||
|
||||
业务层经 app.quant.engine.QuantEngine Protocol 注入引擎，切换无需改业务代码。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import pandas as pd
|
||||
|
||||
from app.domain.entities.research import BacktestResult, FactorTestReport, ResearchSpec
|
||||
from app.quant.engine import QuantEngine
|
||||
|
||||
_MSG = (
|
||||
"Qlib 引擎需要 pyqlib，当前平台（Linux aarch64 + Python 3.12）无可用 wheel。"
|
||||
"请改用 LocalEngine 或在受支持平台安装 pyqlib 后实现（见本模块 docstring）。"
|
||||
)
|
||||
|
||||
|
||||
class QlibEngine(QuantEngine):
|
||||
"""pyqlib 后端占位：抛 NotImplementedError 并给出启用指引。"""
|
||||
|
||||
name = "qlib"
|
||||
|
||||
def run_factor_test(
|
||||
self, daily: pd.DataFrame, spec: ResearchSpec, horizon_days: int = 21
|
||||
) -> FactorTestReport:
|
||||
raise NotImplementedError(_MSG)
|
||||
|
||||
def run_backtest(self, daily: pd.DataFrame, spec: ResearchSpec) -> BacktestResult:
|
||||
raise NotImplementedError(_MSG)
|
||||
@@ -0,0 +1,93 @@
|
||||
"""研究服务：把 Research Specification 编排为数据获取 + 引擎执行。
|
||||
|
||||
本层是业务入口：API / Agent 只能调用这里的用例（AGENT.md §16/§17），
|
||||
禁止直接拼接引擎配置。数据一律经 Repository 获取（防未来函数由查询层保证）。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import date, timedelta
|
||||
|
||||
import pandas as pd
|
||||
|
||||
from app.domain.entities.market import Stock
|
||||
from app.domain.entities.research import (
|
||||
BacktestResult,
|
||||
FactorTestReport,
|
||||
ResearchSpec,
|
||||
UniverseSpec,
|
||||
)
|
||||
from app.domain.repositories.market import (
|
||||
DailyBarRepository,
|
||||
StockRepository,
|
||||
)
|
||||
from app.quant.engine import QuantEngine
|
||||
|
||||
|
||||
def filter_stocks(stocks: list[Stock], universe: UniverseSpec, as_of: date) -> list[Stock]:
|
||||
"""按股票池口径过滤（名称含 ST 判定 —— 名称快照为当日口径，属历史可追溯数据）。"""
|
||||
out: list[Stock] = []
|
||||
for s in stocks:
|
||||
if s.delist_date is not None and s.delist_date < as_of:
|
||||
continue
|
||||
if universe.exclude_st and s.name and "ST" in s.name.upper():
|
||||
continue
|
||||
if (
|
||||
universe.min_listing_days
|
||||
and s.list_date
|
||||
and (as_of - s.list_date).days < universe.min_listing_days
|
||||
):
|
||||
continue
|
||||
out.append(s)
|
||||
return out
|
||||
|
||||
|
||||
def bars_to_daily_df(bars) -> pd.DataFrame:
|
||||
"""DailyBar 列表 → 引擎长表 DataFrame（symbol/trade_date/ohlc/volume/amount）。
|
||||
|
||||
领域实体中的 Decimal 在此转 float，供 pandas 数值运算（保持 DataFrame 全数值列）。
|
||||
"""
|
||||
df = pd.DataFrame([b.model_dump() for b in bars])
|
||||
if not df.empty:
|
||||
for col in ("open", "high", "low", "close", "volume", "amount"):
|
||||
if col in df.columns:
|
||||
df[col] = df[col].astype(float)
|
||||
return df
|
||||
|
||||
|
||||
class ResearchService:
|
||||
"""研究用例入口（因子测试 / 回测）。依赖注入 Repository 与引擎。"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
stock_repo: StockRepository,
|
||||
daily_repo: DailyBarRepository,
|
||||
engine: QuantEngine,
|
||||
) -> None:
|
||||
self._stock_repo = stock_repo
|
||||
self._daily_repo = daily_repo
|
||||
self._engine = engine
|
||||
|
||||
def run_factor_test(self, spec: ResearchSpec, horizon_days: int = 21) -> FactorTestReport:
|
||||
if spec.type != "factor_test":
|
||||
raise ValueError("factor_test 用例需要 spec.type=factor_test")
|
||||
daily = self._load_daily(spec)
|
||||
return self._engine.run_factor_test(daily, spec, horizon_days=horizon_days)
|
||||
|
||||
def run_backtest(self, spec: ResearchSpec) -> BacktestResult:
|
||||
if spec.type != "backtest":
|
||||
raise ValueError("backtest 用例需要 spec.type=backtest")
|
||||
daily = self._load_daily(spec)
|
||||
return self._engine.run_backtest(daily, spec)
|
||||
|
||||
# ---- 数据装配 ----
|
||||
|
||||
def _load_daily(self, spec: ResearchSpec) -> pd.DataFrame:
|
||||
start, end = spec.period
|
||||
# 回测前预留因子 warmup（lookback≤120 交易日，取 300 自然日余量）
|
||||
data_start = start - timedelta(days=300)
|
||||
stocks = filter_stocks(self._stock_repo.list(), spec.universe, as_of=start)
|
||||
bars: list = []
|
||||
for s in stocks:
|
||||
bars.extend(self._daily_repo.get_range(s.symbol, data_start, end))
|
||||
return bars_to_daily_df(bars)
|
||||
Reference in New Issue
Block a user