alpholio 0.4.0__py3-none-any.whl

alpholio/__init__.py

@@ -0,0 +1,44 @@
+# 跨截面组合回测工具包：Input → Engine → Analyzer → Visualizer 单向数据流
+from .analyzer import Analyzer
+from .api import BacktestResult, backtest
+from .config_schema import AnalyzerConfig, EngineConfig, InputConfig, PipelineConfig, VisualizerConfig
+from .contracts import AnalysisResult, EngineResult, InputBundle, to_legacy_wide
+from .engine import PortfolioEngine
+from .input import InputProcessor
+from .pipeline import PipelineResult, run_pipeline
+from .settings import settings
+from .visualizer import Visualizer
+
+__version__ = "0.4.0"
+__all__ = [
+    # 一行跑通的门面入口
+    "backtest",
+    "BacktestResult",
+    "settings",
+
+    # 核心类
+    "InputProcessor",
+    "PortfolioEngine",
+    "Analyzer",
+    "Visualizer",
+
+    # 辅助函数和数据类
+    "run_pipeline",
+    "PipelineResult",
+    "InputConfig",
+    "EngineConfig",
+    "AnalyzerConfig",
+    "VisualizerConfig",
+    "PipelineConfig",
+
+    # 用于流转的中间产物
+    "InputBundle",
+    "EngineResult",
+    "AnalysisResult",
+
+    # 格式转换函数
+    "to_legacy_wide",
+
+    # 版本号
+    "__version__",
+]

alpholio/analyzer/__init__.py

@@ -0,0 +1,18 @@
+# ③ Analyzer：组合收益 → 指标 / 曲线 / 诊断
+from .analyzer import Analyzer
+from .curves import build_curves, shared_origin, vol_rescale_to_reference
+from .diagnostics import compute_ic, compute_turnover
+from .metrics import METRICS, Metric, MetricContext, build_metric
+
+__all__ = [
+    "Analyzer",
+    "Metric",
+    "METRICS",
+    "MetricContext",
+    "build_metric",
+    "compute_turnover",
+    "compute_ic",
+    "build_curves",
+    "shared_origin",
+    "vol_rescale_to_reference",
+]

alpholio/analyzer/analyzer.py

@@ -0,0 +1,135 @@
+# ③ Analyzer：组合收益 → 指标汇总 + 曲线 + 诊断
+from __future__ import annotations
+
+from typing import Dict, List
+
+import numpy as np
+import pandas as pd
+
+from ..config_schema import AnalyzerConfig
+from ..contracts import (
+    BUCKET,
+    DATE,
+    IC,
+    N_NAMES,
+    RET,
+    SIGNAL,
+    TURNOVER,
+    WEIGHT,
+    AnalysisResult,
+    ContractError,
+    EngineResult,
+    sort_by_bucket,
+)
+from ..frequency import DAILY, resolve
+from .curves import build_curves, shared_origin, vol_rescale_to_reference
+from .diagnostics import compute_ic, compute_turnover
+from .metrics import MetricContext, build_metric
+
+
+class Analyzer:
+    def __init__(self, cfg: AnalyzerConfig) -> None:
+        self.cfg = cfg
+        self.metrics = [build_metric(name) for name in cfg.metrics]
+
+    # 唯一出口
+    def run(self, result: EngineResult) -> AnalysisResult:
+        cfg = self.cfg
+        ppy = self._periods_per_year(result.meta)
+        ctx = MetricContext(periods_per_year=ppy, risk_free_rate=cfg.risk_free_rate)
+
+        turnover = (
+            compute_turnover(
+                result.members,
+                long_short_label=result.meta.get("long_short_label"),
+                long_bucket=result.meta.get("long_bucket"),
+                short_bucket=result.meta.get("short_bucket"),
+            )
+            if cfg.diagnostics.turnover
+            else _empty(SIGNAL, BUCKET, DATE, TURNOVER)
+        )
+        ic = (
+            compute_ic(result.aligned, cfg.diagnostics.ic_min_names)
+            if cfg.diagnostics.ic
+            else _empty(SIGNAL, DATE, IC, N_NAMES)
+        )
+
+        returns = self._rescale(result.returns)
+        origin = shared_origin(returns) if cfg.curves.shared_origin else None
+
+        return AnalysisResult(
+            summary=self._summarize(returns, ctx, turnover, ic),
+            curves=build_curves(returns, cfg.curves.clip_lower, origin),
+            turnover=turnover,
+            ic=ic,
+            meta={
+                "periods_per_year": ppy,
+                "metrics": [m.name for m in self.metrics],
+                "vol_rescaled": bool(cfg.vol_rescale.enabled),
+                "vol_rescale_reference": cfg.vol_rescale.reference if cfg.vol_rescale.enabled else None,
+                **{
+                    k: result.meta[k]
+                    for k in ("frequency", "holding_days", "n_buckets")
+                    if k in result.meta
+                },
+            },
+        )
+
+    # 开关打开时整体替换为缩放后的收益，不再并列输出两套口径
+    def _rescale(self, returns: pd.DataFrame) -> pd.DataFrame:
+        spec = self.cfg.vol_rescale
+        if not spec.enabled:
+            return returns
+        if not spec.reference:
+            raise ContractError(
+                "analyzer.vol_rescale.enabled=true 时必须指定 reference（缩放到哪个基准）"
+            )
+        return vol_rescale_to_reference(returns, spec.reference, spec.min_periods)
+
+    # 年化因子：显式配置优先，否则由「年化基数 / 持有期」推导。
+    # 基数随面板频率：日频取 analyzer.trading_days_per_year（默认 252），月频取 12。
+    # 频率沿 InputBundle → EngineResult.meta 传来，缺省按日频处理。
+    def _periods_per_year(self, engine_meta: Dict) -> float:
+        if self.cfg.periods_per_year:
+            return float(self.cfg.periods_per_year)
+        frequency = resolve(engine_meta.get("frequency", DAILY))
+        base = (
+            frequency.bars_per_year
+            if frequency.is_monthly
+            else float(self.cfg.trading_days_per_year)
+        )
+        holding = int(engine_meta.get("holding_days", 1))
+        return base / max(holding, 1)
+
+    def _summarize(
+        self, returns: pd.DataFrame, ctx: MetricContext, turnover: pd.DataFrame, ic: pd.DataFrame
+    ) -> pd.DataFrame:
+        turnover_mean = _mean_by(turnover, [SIGNAL, BUCKET], TURNOVER)
+        ic_mean = _mean_by(ic, [SIGNAL], IC)
+        rows: List[Dict] = []
+        for (signal, bucket, weight), grp in returns.groupby(
+            [SIGNAL, BUCKET, WEIGHT], sort=True
+        ):
+            series = grp[RET].dropna().to_numpy(dtype=np.float64)
+            if len(series) == 0:
+                continue
+            row = {
+                SIGNAL: signal, BUCKET: bucket, WEIGHT: weight,
+                "n_periods": int(len(series)),
+            }
+            row.update({m.name: m.compute(series, ctx) for m in self.metrics})
+            row[TURNOVER] = turnover_mean.get((signal, bucket), np.nan)
+            row["ic_mean"] = ic_mean.get(signal, np.nan)
+            rows.append(row)
+        return sort_by_bucket(pd.DataFrame(rows), [SIGNAL, WEIGHT])
+
+
+def _empty(*columns: str) -> pd.DataFrame:
+    return pd.DataFrame(columns=list(columns))
+
+
+def _mean_by(frame: pd.DataFrame, keys: List[str], column: str) -> Dict:
+    if frame.empty or column not in frame.columns:
+        return {}
+    grouped = frame.groupby(keys[0] if len(keys) == 1 else keys, sort=False)[column].mean()
+    return grouped.to_dict()

alpholio/analyzer/curves.py

@@ -0,0 +1,85 @@
+# 净值 / 累计对数收益曲线，以及对基准的波动率缩放
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+
+from ..contracts import (
+    BUCKET,
+    CUM_LOG_RET,
+    DATE,
+    EQUITY,
+    REFERENCE_BUCKET,
+    RET,
+    SIGNAL,
+    WEIGHT,
+)
+
+_KEYS = [SIGNAL, BUCKET, WEIGHT]
+
+
+# 所有曲线共用的视觉原点：最早一期的前一个工作日
+def shared_origin(returns: pd.DataFrame) -> pd.Timestamp:
+    return pd.Timestamp(returns[DATE].min()) - pd.tseries.offsets.BDay(1)
+
+
+# 净值走 (1+r) 累乘，对数曲线走 log1p 累加；每条线前置一个零点
+def build_curves(
+    returns: pd.DataFrame,
+    clip_lower: float = -0.99,
+    origin: Optional[pd.Timestamp] = None,
+) -> pd.DataFrame:
+    frames = []
+    for keys, grp in returns.groupby(_KEYS, sort=False):
+        line = grp.dropna(subset=[RET]).sort_values(DATE)
+        if line.empty:
+            continue
+        rets = line[RET].astype(float).clip(lower=clip_lower).to_numpy()
+        body = pd.DataFrame({
+            DATE: line[DATE].to_numpy(),
+            RET: rets,
+            EQUITY: np.cumprod(1.0 + rets),
+            CUM_LOG_RET: np.log1p(rets).cumsum(),
+        })
+        start = origin if origin is not None else shared_origin(line)
+        head = pd.DataFrame({DATE: [start], RET: [0.0], EQUITY: [1.0], CUM_LOG_RET: [0.0]})
+        curve = pd.concat([head, body], ignore_index=True)
+        for name, value in zip(_KEYS, keys):
+            curve[name] = value
+        frames.append(curve)
+    if not frames:
+        return pd.DataFrame(columns=[DATE, *_KEYS, RET, EQUITY, CUM_LOG_RET])
+    out = pd.concat(frames, ignore_index=True)
+    return out[[DATE, *_KEYS, RET, EQUITY, CUM_LOG_RET]]
+
+
+# 全样本单一常数缩放，使各序列波动率对齐基准；基准自身不缩放
+def vol_rescale_to_reference(
+    returns: pd.DataFrame, reference: str, min_periods: int = 20
+) -> pd.DataFrame:
+    ref = returns[(returns[SIGNAL] == reference) & (returns[BUCKET] == REFERENCE_BUCKET)]
+    if ref.empty:
+        ref = returns[returns[SIGNAL] == reference]
+    if ref.empty:
+        raise ValueError(f"vol_scale.reference='{reference}' 在收益表中不存在")
+    targets = {w: _std(g[RET].to_numpy(), min_periods) for w, g in ref.groupby(WEIGHT)}
+
+    def rescale(grp: pd.DataFrame) -> pd.DataFrame:
+        if grp[SIGNAL].iloc[0] == reference:
+            return grp
+        target = targets.get(grp[WEIGHT].iloc[0], np.nan)
+        own = _std(grp[RET].to_numpy(), min_periods)
+        factor = target / own if np.isfinite(target) and np.isfinite(own) and own > 0 else 1.0
+        return grp.assign(**{RET: grp[RET] * factor})
+
+    scaled = [rescale(g) for _, g in returns.groupby(_KEYS, sort=False)]
+    return pd.concat(scaled, ignore_index=True)[returns.columns]
+
+
+def _std(values: np.ndarray, min_periods: int) -> float:
+    finite = values[np.isfinite(values)]
+    if len(finite) < int(min_periods):
+        return float("nan")
+    return float(np.std(finite, ddof=1))

alpholio/analyzer/diagnostics.py

@@ -0,0 +1,72 @@
+# 换手率与信息系数：只依赖 Engine 交出的成分表与对齐面板
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Set
+
+import numpy as np
+import pandas as pd
+
+from ..contracts import (
+    ALPHA,
+    ASSET,
+    BUCKET,
+    DATE,
+    FWD_RET,
+    IC,
+    N_NAMES,
+    SIGNAL,
+    TURNOVER,
+)
+
+
+# 相邻两期成分的 Jaccard 距离；多空桶取多头与空头的并集
+def compute_turnover(
+    members: pd.DataFrame,
+    long_short_label: Optional[str] = None,
+    long_bucket: Optional[str] = None,
+    short_bucket: Optional[str] = None,
+) -> pd.DataFrame:
+    rows: List[Dict] = []
+    for signal, per_signal in members.groupby(SIGNAL, sort=True):
+        previous: Dict[str, Set[str]] = {}
+        for date, frame in per_signal.groupby(DATE, sort=True):
+            current = {
+                str(bucket): set(grp[ASSET])
+                for bucket, grp in frame.groupby(BUCKET, sort=False)
+            }
+            if long_short_label and long_bucket in current and short_bucket in current:
+                current[long_short_label] = current[long_bucket] | current[short_bucket]
+            for bucket, names in current.items():
+                prior = previous.get(bucket)
+                union = (names | prior) if prior is not None else None
+                rows.append({
+                    SIGNAL: signal,
+                    BUCKET: bucket,
+                    DATE: date,
+                    TURNOVER: 1.0 - len(names & prior) / len(union) if union else np.nan,
+                })
+            previous = current
+    return pd.DataFrame(rows, columns=[SIGNAL, BUCKET, DATE, TURNOVER])
+
+
+# 每期截面 alpha 与实现收益的 Spearman 相关（秩的 Pearson）
+def compute_ic(aligned: pd.DataFrame, min_names: int = 20) -> pd.DataFrame:
+    panel = aligned.dropna(subset=[ALPHA, FWD_RET]).copy()
+    if panel.empty:
+        return pd.DataFrame(columns=[SIGNAL, DATE, IC, N_NAMES])
+    keys = [SIGNAL, DATE]
+    x = panel.groupby(keys, sort=False)[ALPHA].rank()
+    y = panel.groupby(keys, sort=False)[FWD_RET].rank()
+    # 秩的 Pearson 相关，用各阶和一次聚合出来，避免逐组 apply
+    stats = panel.assign(_x=x, _y=y, _xx=x * x, _yy=y * y, _xy=x * y).groupby(keys, sort=True).agg(
+        n=("_x", "size"), sx=("_x", "sum"), sy=("_y", "sum"),
+        sxx=("_xx", "sum"), syy=("_yy", "sum"), sxy=("_xy", "sum"),
+    )
+    cov = stats["sxy"] - stats["sx"] * stats["sy"] / stats["n"]
+    var_x = stats["sxx"] - stats["sx"] ** 2 / stats["n"]
+    var_y = stats["syy"] - stats["sy"] ** 2 / stats["n"]
+    with np.errstate(invalid="ignore", divide="ignore"):
+        ic = cov / np.sqrt(var_x * var_y)
+    ic = ic.where(stats["n"] >= int(min_names))
+    out = pd.DataFrame({IC: ic, N_NAMES: stats["n"]}).reset_index()
+    return out[[SIGNAL, DATE, IC, N_NAMES]]

alpholio/analyzer/metrics.py

@@ -0,0 +1,100 @@
+# 组合层指标：可注册、只吃一维简单收益序列
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+import numpy as np
+
+from ..registry import Registry
+
+METRICS: Registry = Registry("metric")
+
+
+@dataclass(frozen=True)
+class MetricContext:
+    periods_per_year: float
+    risk_free_rate: float = 0.0
+
+
+class Metric(ABC):
+    name: str = ""
+
+    @abstractmethod
+    def compute(self, rets: np.ndarray, ctx: MetricContext) -> float:
+        ...
+
+
+@METRICS.register()
+class AnnualizedReturn(Metric):
+    name = "ann_ret"
+
+    def compute(self, rets: np.ndarray, ctx: MetricContext) -> float:
+        return float(rets.mean() * ctx.periods_per_year)
+
+
+# 净值按简单收益累乘，再折回每年一期的复合增长率。与 ann_ret 是两套口径：
+# ann_ret 把单期收益线性放大 P 倍，cagr 则让它们逐期滚动复利。月频面板上后者通常明显
+# 更高——复利的凸性 (1+m)^P − 1 > m·P 压过了波动拖累。净值跌破 0 时复合增长率无定义。
+@METRICS.register()
+class CompoundAnnualGrowthRate(Metric):
+    name = "cagr"
+
+    def compute(self, rets: np.ndarray, ctx: MetricContext) -> float:
+        if len(rets) == 0:
+            return float("nan")
+        equity = float(np.cumprod(1.0 + rets)[-1])
+        if equity <= 0.0:
+            return float("nan")
+        return float(equity ** (ctx.periods_per_year / len(rets)) - 1.0)
+
+
+@METRICS.register()
+class AnnualizedVolatility(Metric):
+    name = "ann_vol"
+
+    def compute(self, rets: np.ndarray, ctx: MetricContext) -> float:
+        if len(rets) < 2:
+            return float("nan")
+        return float(rets.std(ddof=1) * np.sqrt(ctx.periods_per_year))
+
+
+@METRICS.register()
+class Sharpe(Metric):
+    name = "sharpe"
+
+    def compute(self, rets: np.ndarray, ctx: MetricContext) -> float:
+        vol = AnnualizedVolatility().compute(rets, ctx)
+        if not np.isfinite(vol) or vol <= 0:
+            return float("nan")
+        return float((AnnualizedReturn().compute(rets, ctx) - ctx.risk_free_rate) / vol)
+
+
+# 净值按简单收益复利，回撤取全程最低点
+@METRICS.register()
+class MaxDrawdown(Metric):
+    name = "max_drawdown"
+
+    def compute(self, rets: np.ndarray, ctx: MetricContext) -> float:
+        equity = np.cumprod(1.0 + rets)
+        return float((equity / np.maximum.accumulate(equity) - 1.0).min())
+
+
+@METRICS.register()
+class TotalEquity(Metric):
+    name = "total_equity"
+
+    def compute(self, rets: np.ndarray, ctx: MetricContext) -> float:
+        return float(np.cumprod(1.0 + rets)[-1])
+
+
+@METRICS.register()
+class HitRate(Metric):
+    name = "hit_rate"
+
+    def compute(self, rets: np.ndarray, ctx: MetricContext) -> float:
+        return float((rets > 0).mean())
+
+
+def build_metric(name: str) -> Metric:
+    return METRICS.get(name)()