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,56 @@
|
||||
"""共享测试装置：合成确定性 A 股行情（含涨跌趋势与噪声，无外部依赖）。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from decimal import Decimal
|
||||
|
||||
import numpy as np
|
||||
import pandas as pd
|
||||
|
||||
|
||||
def synthetic_daily(drifts: dict[str, float], n: int = 320, base: float = 100.0) -> pd.DataFrame:
|
||||
"""生成多股票日线长表。
|
||||
|
||||
每股价格：p[j] = p[j-1] * (1 + drift + 0.012 * sin((j + i) * 0.8)) —— 确定性、
|
||||
趋势 + 微幅周期噪声；含 high/low/volume/amount 供各因子使用。
|
||||
"""
|
||||
dates = pd.bdate_range("2024-01-01", periods=n)
|
||||
rows: list[dict] = []
|
||||
for i, (sym, drift) in enumerate(drifts.items()):
|
||||
price = float(base)
|
||||
for j, d in enumerate(dates):
|
||||
ret = drift + 0.012 * np.sin((j + i) * 0.8)
|
||||
prev = price
|
||||
price = price * (1 + ret)
|
||||
rows.append(
|
||||
{
|
||||
"symbol": sym,
|
||||
"trade_date": d.date(),
|
||||
"open": float(prev),
|
||||
"high": float(price * 1.008),
|
||||
"low": float(min(prev, price) * 0.992),
|
||||
"close": float(price),
|
||||
"volume": float(1_000_000 + j * 1000 + i * 3000),
|
||||
"amount": float(price * (1_000_000 + j * 1000 + i * 3000)),
|
||||
}
|
||||
)
|
||||
return pd.DataFrame(rows)
|
||||
|
||||
|
||||
def bars_dataframe_to_daily_bars(daily: pd.DataFrame) -> list:
|
||||
"""测试辅助：DataFrame → domain DailyBar 实体（供 service/仓储层路径测试）。"""
|
||||
from app.domain.entities.market import DailyBar
|
||||
|
||||
return [
|
||||
DailyBar(
|
||||
symbol=r.symbol,
|
||||
trade_date=r.trade_date,
|
||||
open=Decimal(str(r.open)),
|
||||
high=Decimal(str(r.high)),
|
||||
low=Decimal(str(r.low)),
|
||||
close=Decimal(str(r.close)),
|
||||
volume=Decimal(str(r.volume)),
|
||||
amount=Decimal(str(r.amount)),
|
||||
)
|
||||
for r in daily.itertuples()
|
||||
]
|
||||
@@ -0,0 +1,138 @@
|
||||
"""LocalEngine 回测测试：主路径、成本、涨跌停/不可买约束、无未来函数构造。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import date
|
||||
|
||||
import pandas as pd
|
||||
from app.domain.entities.market import Stock
|
||||
from app.domain.entities.research import (
|
||||
CostSpec,
|
||||
FactorSpec,
|
||||
ResearchSpec,
|
||||
SelectionSpec,
|
||||
UniverseSpec,
|
||||
)
|
||||
from app.quant.engine import LocalEngine
|
||||
from app.quant.service import filter_stocks
|
||||
|
||||
from conftest_quant import synthetic_daily
|
||||
|
||||
|
||||
def _spec(
|
||||
top_n: int = 1,
|
||||
start: date = date(2024, 3, 1),
|
||||
end: date = date(2024, 10, 31),
|
||||
rebalance: str = "monthly",
|
||||
costs: CostSpec | None = None,
|
||||
) -> ResearchSpec:
|
||||
return ResearchSpec(
|
||||
type="backtest",
|
||||
universe=UniverseSpec(exclude_st=False, min_listing_days=0),
|
||||
factors=[FactorSpec(name="momentum_20")],
|
||||
selection=SelectionSpec(top_n=top_n),
|
||||
rebalance=rebalance,
|
||||
period=(start, end),
|
||||
costs=costs or CostSpec(),
|
||||
)
|
||||
|
||||
|
||||
class TestBacktestMain:
|
||||
def test_uptrend_wins_and_profits(self) -> None:
|
||||
daily = synthetic_daily({"600000.SH": 0.004, "600001.SH": -0.002}, n=320)
|
||||
res = LocalEngine().run_backtest(daily, _spec(top_n=1))
|
||||
|
||||
assert res.summary.total_return_pct > 0
|
||||
assert res.summary.final_equity > res.summary.initial_capital
|
||||
assert res.summary.total_trades >= 1
|
||||
assert res.summary.annual_return_pct > 0
|
||||
assert res.equity_curve[0].date == date(2024, 3, 1)
|
||||
assert res.equity_curve[-1].date == date(2024, 10, 31)
|
||||
assert res.monthly_returns
|
||||
assert res.trades
|
||||
# AGENT §24：未建模约束必须显式标注
|
||||
assert any("涨跌停" in item for item in res.unimplemented)
|
||||
assert res.config_snapshot["selection"]["top_n"] == 1
|
||||
|
||||
def test_costs_reduce_returns(self) -> None:
|
||||
daily = synthetic_daily({"600000.SH": 0.004, "600001.SH": -0.002}, n=320)
|
||||
free = CostSpec(commission_rate=0.0, stamp_tax_rate=0.0, slippage_rate=0.0)
|
||||
with_cost = LocalEngine().run_backtest(daily, _spec(top_n=2, costs=CostSpec()))
|
||||
without = LocalEngine().run_backtest(daily, _spec(top_n=2, costs=free))
|
||||
# 有成本时收益不应高于无成本
|
||||
assert with_cost.summary.total_return_pct <= without.summary.total_return_pct + 1e-6
|
||||
|
||||
def test_positions_and_drawdown_wellformed(self) -> None:
|
||||
daily = synthetic_daily({"600000.SH": 0.004, "600001.SH": -0.001}, n=260)
|
||||
res = LocalEngine().run_backtest(daily, _spec(top_n=2))
|
||||
assert res.positions
|
||||
weights = [p.weight for p in res.positions]
|
||||
assert all(0 < w <= 1 for w in weights)
|
||||
assert all(p.value <= 0 for p in res.drawdown)
|
||||
assert res.summary.max_drawdown_pct <= 0
|
||||
|
||||
|
||||
def _limit_up_scenario_daily() -> pd.DataFrame:
|
||||
"""Y 在 2024-07-01 相对前一交易日跳涨 10.5%（主板涨停不可追），且动量高于 X。"""
|
||||
dates = pd.bdate_range("2024-06-03", periods=46)
|
||||
rows = []
|
||||
for j, d in enumerate(dates):
|
||||
x = 100.0 * 1.001**j
|
||||
y = 100.0 * 1.003**j
|
||||
# 2024-07-01 是第 21 个工作日（6/28 周五 → 7/1 周一）
|
||||
if d.date() == date(2024, 7, 1):
|
||||
y = y / 1.003 * 1.105 # 相对前一日 +10.5%，形成涨停
|
||||
rows.append(
|
||||
{
|
||||
"symbol": "600001.SH",
|
||||
"trade_date": d.date(),
|
||||
"close": x,
|
||||
"open": x,
|
||||
"high": x * 1.01,
|
||||
"low": x * 0.99,
|
||||
"volume": 1e6,
|
||||
"amount": 1e8,
|
||||
}
|
||||
)
|
||||
rows.append(
|
||||
{
|
||||
"symbol": "600002.SH",
|
||||
"trade_date": d.date(),
|
||||
"close": y,
|
||||
"open": y,
|
||||
"high": y * 1.01,
|
||||
"low": y * 0.99,
|
||||
"volume": 1e6,
|
||||
"amount": 1e8,
|
||||
}
|
||||
)
|
||||
return pd.DataFrame(rows)
|
||||
|
||||
|
||||
class TestLimitUpConstraint:
|
||||
def test_limit_up_symbol_not_bought(self) -> None:
|
||||
daily = _limit_up_scenario_daily()
|
||||
res = LocalEngine().run_backtest(
|
||||
daily, _spec(top_n=1, start=date(2024, 6, 3), end=date(2024, 8, 2))
|
||||
)
|
||||
# 7/1 调仓：Y 动量更高但涨停不可买 → 当日只能买入 X（8 月 Y 恢复可买，不断言之后）
|
||||
at_0701 = [p for p in res.positions if p.date == date(2024, 7, 1)]
|
||||
assert at_0701, "7/1 调仓后应记录持仓"
|
||||
assert {p.symbol for p in at_0701} == {"600001.SH"}
|
||||
|
||||
|
||||
class TestServiceFilter:
|
||||
def _stock(self, symbol: str, name: str, list_date: date, delist: date | None = None) -> Stock:
|
||||
return Stock(symbol=symbol, name=name, list_date=list_date, delist_date=delist)
|
||||
|
||||
def test_exclude_st_and_new_and_delisted(self) -> None:
|
||||
stocks = [
|
||||
self._stock("600001.SH", "*ST 某某", date(2000, 1, 1)),
|
||||
self._stock("600002.SH", "正常公司", date(2024, 6, 1)), # 上市不足 250 天
|
||||
self._stock("600003.SH", "正常公司", date(2010, 1, 1), delist=date(2023, 6, 1)),
|
||||
self._stock("600004.SH", "正常公司", date(2010, 1, 1)),
|
||||
]
|
||||
kept = filter_stocks(
|
||||
stocks, UniverseSpec(exclude_st=True, min_listing_days=250), as_of=date(2024, 8, 1)
|
||||
)
|
||||
assert [s.symbol for s in kept] == ["600004.SH"]
|
||||
@@ -0,0 +1,89 @@
|
||||
"""因子计算与注册表测试（合成数据、确定性断言方向与相对排序）。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import pandas as pd
|
||||
from app.quant.factors import (
|
||||
FactorDef,
|
||||
FactorError,
|
||||
compute_factor,
|
||||
get_factor,
|
||||
list_factors,
|
||||
register,
|
||||
)
|
||||
|
||||
from conftest_quant import synthetic_daily
|
||||
|
||||
|
||||
def test_registry_builtins_present() -> None:
|
||||
names = {f.name for f in list_factors()}
|
||||
assert {"momentum_20", "momentum_60", "volatility_20", "ma_bias_20"} <= names
|
||||
|
||||
|
||||
def test_unknown_factor_raises() -> None:
|
||||
try:
|
||||
compute_factor("not_a_factor", synthetic_daily({"A": 0.0}))
|
||||
except FactorError:
|
||||
return
|
||||
raise AssertionError("应抛 FactorError")
|
||||
|
||||
|
||||
def test_momentum_ordering_matches_drift() -> None:
|
||||
daily = synthetic_daily({"AAA": 0.002, "BBB": 0.0, "CCC": -0.002}, n=160)
|
||||
_defn, panel = compute_factor("momentum_20", daily)
|
||||
tail = panel.iloc[-1]
|
||||
assert tail["AAA"] > tail["BBB"] > tail["CCC"]
|
||||
assert tail["AAA"] > 0 # 上涨股 20 日动量为正
|
||||
|
||||
|
||||
def test_volatility_ranks_noise() -> None:
|
||||
# 手写：SMOOTH 每日 +0.2%；WILD 在 ±5% 间摆动 → WILD 的 20 日波动率应显著更高
|
||||
|
||||
from datetime import date, timedelta
|
||||
|
||||
dates = [date(2024, 1, 1) + timedelta(days=i) for i in range(120)]
|
||||
rows = []
|
||||
smooth, wild = 100.0, 100.0
|
||||
for j, d in enumerate(dates):
|
||||
smooth *= 1.002
|
||||
wild *= 1.05 if j % 2 == 0 else 0.95
|
||||
for sym, px in (("SMOOTH", smooth), ("WILD", wild)):
|
||||
rows.append(
|
||||
{
|
||||
"symbol": sym,
|
||||
"trade_date": d,
|
||||
"close": px,
|
||||
"high": px,
|
||||
"low": px,
|
||||
"volume": 1e6,
|
||||
"amount": 1e8,
|
||||
}
|
||||
)
|
||||
daily = pd.DataFrame(rows)
|
||||
_defn, panel = compute_factor("volatility_20", daily)
|
||||
assert float(panel["WILD"].iloc[-1]) > float(panel["SMOOTH"].iloc[-1]) * 5
|
||||
|
||||
|
||||
def test_custom_factor_registration() -> None:
|
||||
@register(FactorDef("test_double_close", "close*2 测试因子", "close * 2", lookback=1))
|
||||
def _fn(fields: dict[str, pd.DataFrame]) -> pd.DataFrame:
|
||||
return fields["close"] * 2
|
||||
|
||||
try:
|
||||
daily = synthetic_daily({"A": 0.001}, n=40)
|
||||
defn, panel = compute_factor("test_double_close", daily)
|
||||
assert defn.direction == "higher_is_better"
|
||||
assert float(panel.iloc[-1, 0]) > 200.0
|
||||
finally:
|
||||
# 清理注册表，避免污染其他测试
|
||||
from app.quant import factors as _factors
|
||||
|
||||
_factors._REGISTRY.pop("test_double_close", None) # noqa: SLF001
|
||||
|
||||
|
||||
def test_factor_def_metadata_present() -> None:
|
||||
defn, _fn = get_factor("momentum_60")
|
||||
assert defn.description
|
||||
assert defn.formula
|
||||
assert defn.lookback == 60
|
||||
assert defn.direction in {"higher_is_better", "lower_is_better"}
|
||||
@@ -0,0 +1,125 @@
|
||||
"""ResearchSpec 校验与因子评估（IC/RankIC/分层）测试。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import date
|
||||
|
||||
import numpy as np
|
||||
import pandas as pd
|
||||
import pytest
|
||||
from app.domain.entities.research import (
|
||||
CostSpec,
|
||||
FactorSpec,
|
||||
ResearchSpec,
|
||||
SelectionSpec,
|
||||
UniverseSpec,
|
||||
)
|
||||
from app.quant.evaluation import run_factor_test
|
||||
from app.quant.factors import compute_factor
|
||||
from app.quant.local_engine import composite_score, cross_sectional_zscore, rebalance_dates
|
||||
from pydantic import ValidationError
|
||||
|
||||
from conftest_quant import synthetic_daily
|
||||
|
||||
|
||||
def _spec(start: date = date(2024, 3, 1), end: date = date(2024, 12, 31), **kw) -> ResearchSpec:
|
||||
base = dict(
|
||||
type="backtest",
|
||||
universe=UniverseSpec(exclude_st=False, min_listing_days=0),
|
||||
factors=[FactorSpec(name="momentum_20")],
|
||||
selection=SelectionSpec(top_n=10),
|
||||
rebalance="monthly",
|
||||
period=(start, end),
|
||||
)
|
||||
base.update(kw)
|
||||
return ResearchSpec(**base)
|
||||
|
||||
|
||||
class TestSpecValidation:
|
||||
def test_inverted_period_rejected(self) -> None:
|
||||
with pytest.raises(ValidationError, match="start < end"):
|
||||
_spec(start=date(2024, 12, 1), end=date(2024, 1, 1))
|
||||
|
||||
def test_duplicate_factors_rejected(self) -> None:
|
||||
with pytest.raises(ValidationError, match="重复"):
|
||||
_spec(factors=[FactorSpec(name="momentum_20"), FactorSpec(name="momentum_20")])
|
||||
|
||||
def test_nonpositive_weight_rejected(self) -> None:
|
||||
with pytest.raises(ValidationError):
|
||||
_spec(factors=[FactorSpec(name="momentum_20", weight=0)])
|
||||
|
||||
def test_cost_bounds(self) -> None:
|
||||
with pytest.raises(ValidationError):
|
||||
CostSpec(commission_rate=0.5) # 超过 1%
|
||||
with pytest.raises(ValidationError):
|
||||
CostSpec(slippage_rate=-0.01)
|
||||
|
||||
|
||||
class TestEvaluation:
|
||||
def _panels(self):
|
||||
# 强趋势 + 弱噪声，确保截面排序稳定（drift 差异远大于噪声）
|
||||
drifts = {f"S{i:02d}": v for i, v in enumerate(np.linspace(0.006, -0.006, 12), start=1)}
|
||||
daily = synthetic_daily(drifts, n=260)
|
||||
_d, f20 = compute_factor("momentum_20", daily)
|
||||
_d, f60 = compute_factor("momentum_60", daily)
|
||||
close = daily.pivot(index="trade_date", columns="symbol", values="close").sort_index()
|
||||
close.index = pd.to_datetime(close.index)
|
||||
return daily, f20, f60, close
|
||||
|
||||
def test_cross_sectional_zscore_standardized(self) -> None:
|
||||
_daily, f20, _f60, _close = self._panels()
|
||||
z = cross_sectional_zscore(f20).dropna(how="all")
|
||||
row = z.iloc[60].dropna()
|
||||
assert abs(float(row.mean())) < 1e-9
|
||||
assert abs(float(row.std()) - 1.0) < 1e-6
|
||||
|
||||
def test_composite_score_respects_direction(self) -> None:
|
||||
_daily, f20, _f60, _close = self._panels()
|
||||
pos = composite_score([("m", f20, 1.0, "higher_is_better")])
|
||||
neg = composite_score([("m", f20, 1.0, "lower_is_better")])
|
||||
row_date = f20.dropna(how="all").iloc[100].name
|
||||
sym = f20.loc[row_date].dropna().index[0]
|
||||
assert float(pos.loc[row_date, sym]) == pytest.approx(-float(neg.loc[row_date, sym]))
|
||||
|
||||
def test_momentum_ic_positive_on_trend_data(self) -> None:
|
||||
daily, f20, _f60, close = self._panels()
|
||||
forward = close.shift(-21) / close - 1.0
|
||||
report = run_factor_test(f20, forward, factor_name="momentum_20")
|
||||
assert report.sample_days > 10
|
||||
assert report.ic_mean > 0
|
||||
assert report.rank_ic_mean > 0
|
||||
assert report.positive_ratio_pct > 50
|
||||
|
||||
def test_quantile_monotonic_on_trend(self) -> None:
|
||||
daily, f20, _f60, close = self._panels()
|
||||
forward = close.shift(-21) / close - 1.0
|
||||
report = run_factor_test(f20, forward, factor_name="momentum_20", quantiles=5)
|
||||
qs = {q.quantile: q.return_pct for q in report.quantile_returns}
|
||||
assert qs[4] > qs[0] # 高动量层未来收益高于低动量层
|
||||
assert report.spread_quantile is not None
|
||||
|
||||
def test_rebalance_dates_monthly_first(self) -> None:
|
||||
idx = pd.bdate_range("2024-03-01", "2024-05-31")
|
||||
out = rebalance_dates(idx, "monthly", date(2024, 3, 1))
|
||||
assert [d.strftime("%Y-%m-%d") for d in out][:3] == [
|
||||
"2024-03-01",
|
||||
"2024-04-01",
|
||||
"2024-05-01",
|
||||
]
|
||||
|
||||
def test_rebalance_dates_respects_start(self) -> None:
|
||||
idx = pd.bdate_range("2024-03-01", "2024-05-31")
|
||||
out = rebalance_dates(idx, "monthly", date(2024, 4, 10))
|
||||
assert out and out[0] >= pd.Timestamp("2024-04-10")
|
||||
|
||||
|
||||
class TestSingleStockDegradation:
|
||||
def test_zscore_single_stock_keeps_candidate(self) -> None:
|
||||
from app.quant.local_engine import cross_sectional_zscore
|
||||
|
||||
daily = synthetic_daily({"ONLY": 0.001}, n=80)
|
||||
_d, panel = compute_factor("momentum_20", daily)
|
||||
z = cross_sectional_zscore(panel)
|
||||
valid = z.dropna(how="all")
|
||||
assert not valid.empty
|
||||
assert (valid == 0.0).all().all() # 单股退化为 0，而非 NaN
|
||||
Reference in New Issue
Block a user