qka 2.5.3.dev2__tar.gz → 2.5.4__tar.gz

{qka-2.5.3.dev2 → qka-2.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qka
-Version: 2.5.3.dev2
+Version: 2.5.4
 Summary: QKA（快量化 / Quant Kit for A-shares）- 简洁易用的 A 股量化回测框架
 Project-URL: Home, https://github.com/zsrl/qka
 Project-URL: Repository, https://github.com/zsrl/qka

{qka-2.5.3.dev2 → qka-2.5.4}/qka/core/accessor.py

@@ -34,6 +34,10 @@ class DataAccessor:
         )
         self._dates: deque = deque(maxlen=max_window)
         self._last_date = None  # 避免同一 bar 内多次 push 重复记录日期
+        # 同一根 bar 内 get() 的结果是不变的，缓存起来复用。
+        # 实测一次回测里 get 被调 28953 次（平均每根 bar 17 次），每次都重建
+        # 451 项 dict + Series，累计 15 秒。缓存后每根 bar 每个因子只建一次。
+        self._cache: dict[str, pd.Series] = {}
 
     def push(self, date, factor: str, data: dict):
         """
@@ -48,6 +52,9 @@ class DataAccessor:
         if date != self._last_date:
             self._dates.append(date)
             self._last_date = date
+            self._cache.clear()          # 换 bar：上一根 bar 的横截面全失效
+        else:
+            self._cache.pop(factor, None)  # 同一 bar 内同因子被重推，旧值作废
         for symbol, value in data.items():
             self._buffer[factor][symbol].append(value)
 
@@ -60,9 +67,16 @@ class DataAccessor:
 
         Returns:
             pd.Series，index=股票代码，values=最新值
+
+        注意：返回值是同一根 bar 内共享的缓存对象，**只读**，不要原地修改。
         """
+        cached = self._cache.get(factor)
+        if cached is not None:
+            return cached
         data = {sym: vals[-1] for sym, vals in self._buffer.get(factor, {}).items()}
-        return pd.Series(data)
+        series = pd.Series(data)
+        self._cache[factor] = series
+        return series
 
     def history(self, factor: str, window: int = 20) -> pd.DataFrame:
         """
@@ -88,3 +102,4 @@ class DataAccessor:
         self._buffer.clear()
         self._dates.clear()
         self._last_date = None
+        self._cache.clear()

{qka-2.5.3.dev2 → qka-2.5.4}/qka/core/backtest.py

@@ -4,6 +4,9 @@
 包含完整的交易记录、绩效分析和可视化功能。
 """
 
+import logging
+from pathlib import Path
+
 import pandas as pd
 import numpy as np
 import dask.dataframe as dd
@@ -13,6 +16,8 @@ from qka.core.broker import Broker
 from qka.core.accessor import DataAccessor
 from qka.core.sizing import SizingAccessor
 
+logger = logging.getLogger(__name__)
+
 
 class Backtest:
     """
@@ -41,7 +46,8 @@ class Backtest:
         self.results = None
         self.initial_cash = None  # 由 run() 设置
         self.metrics = None
-        self._benchmark_data = None
+        self._benchmark_data = None       # 基准收盘价序列（HTML 报告画曲线用）
+        self._benchmark_returns = None    # 基准日收益（算 alpha/beta 用）
         # 报告里算夏普用的无风险利率（年化，小数）。默认 3%，与历史报告可比。
         # 要换口径就在 run() 之后直接改这个属性。因子那边用 Data(risk_free=...)
         # 可以逐窗口时变，回测是一整段区间的单一指标，这里保持一个可覆写的数。
@@ -81,6 +87,42 @@ class Backtest:
             by_factor[factor][symbol] = val
         return dict(by_factor)
 
+    @staticmethod
+    def _build_layout(columns):
+        """列名 → {factor: [(symbol, 列号)]}，**整段回测只解析一次**。
+
+        列名格式 `{symbol}|{factor}`，所有 bar 共用同一套列。原来每根 bar 都
+        `rsplit` 一遍全部列名：451 只 × 8 字段 × 1646 天 = 594 万次字符串切分，
+        纯属重复劳动（实测 `_parse_row` 累计 19 秒）。
+        """
+        layout: dict[str, list[tuple[str, int]]] = defaultdict(list)
+        for i, col in enumerate(columns):
+            if not isinstance(col, str) or '|' not in col:
+                continue
+            sym, _, factor = col.rpartition('|')
+            layout[factor].append((sym, i))
+        return dict(layout)
+
+    def _run_bars(self, dates, values, layout):
+        """逐 bar 驱动：推数据 → 策略决策 → broker 撮合。
+
+        values 是 (days × cols) 的 numpy 数组，按位置取值。比 `df.iterrows()`
+        快一个量级 —— iterrows 每行都要构造一个 Series 并做 dtype 推断
+        （实测这两项合计 20 秒以上）。
+        """
+        data_acc = self.strategy._data
+        broker = self.strategy.broker
+        push = data_acc.push
+        on_bar = self.strategy.on_bar
+
+        for i, date in enumerate(dates):
+            row = values[i]
+            for factor, entries in layout.items():
+                push(date, factor, {sym: row[ci] for sym, ci in entries})
+            broker.timestamp = date
+            on_bar(date)
+            broker.on_bar(date, data_acc.get)
+
     def run(self, cash: float = 100000.0,
             start_date: str = None, end_date: str = None,
             benchmark: Optional[str] = None,
@@ -125,85 +167,112 @@ class Backtest:
         # 获取数据
         raw = self.data.get(lazy=True, start_date=start_date, end_date=end_date)
 
-        # 加载基准数据
+        # 加载基准数据（同时算出日收益，供 metrics 里的 alpha/beta 使用）
         if benchmark:
-            self._load_benchmark(benchmark)
+            self._load_benchmark(benchmark, start_date, end_date)
 
         if isinstance(raw, dd.DataFrame):
-            # ── dask 模式：分区迭代 ──
+            # ── dask 模式 ──
             ddf: dd.DataFrame = raw
             n_rows = len(ddf)
 
-            if n_rows > 500:
-                # 大规模：先算 index，再按日期分块读取
-                index = ddf.index.compute()
-                chunk_size = 500
+            # 分块是为了控制内存，**不是越小越好**：原来写死每块 500 行，
+            # 451 只票 × 1646 天被切成 4 块，dask 反复建图、反复读 parquet 元数据
+            # （实测 dask.tokenize 被调 50 万次、累计 10 秒）。按 ~200MB 预算反推行数。
+            _cols = max(1, len(ddf.columns))
+            chunk_size = max(500, int(200 * 1024 * 1024 / (_cols * 8)))
 
+            if n_rows <= chunk_size:
+                # 一次装得下：直接 compute。**不要**再走 `ddf.loc[首:尾].compute()` ——
+                # 单块时那等于多套一层 dask 图，实测白白多花 25 秒。
+                df = ddf.compute()
+                self._run_bars(df.index, df.to_numpy(), self._build_layout(df.columns))
+            else:
+                index = ddf.index.compute()
+                layout = None
                 for start in range(0, n_rows, chunk_size):
                     end = min(start + chunk_size, n_rows)
                     date_start, date_end = index[start], index[end - 1]
 
                     chunk = ddf.loc[date_start:date_end].compute()
-                    for dt, row in chunk.iterrows():
-                        by_factor = self._parse_row(row)
-                        for factor, data in by_factor.items():
-                            self.strategy._data.push(dt, factor, data)
-                        # dask 路径：策略使用 self.get() / self.history()
-                        self.strategy.broker.timestamp = dt
-                        self.strategy.on_bar(dt)
-                        self.strategy.broker.on_bar(
-                            dt, self.strategy._data.get
-                        )
-            else:
-                # 小规模：一次加载，零开销
-                df = ddf.compute()
-                for date, row in df.iterrows():
-                    by_factor = self._parse_row(row)
-                    for factor, data in by_factor.items():
-                        self.strategy._data.push(date, factor, data)
-                    self.strategy.broker.timestamp = date
-                    self.strategy.on_bar(date)
-                    self.strategy.broker.on_bar(
-                        date, self.strategy._data.get
-                    )
+                    # 列布局整段只算一次：所有分块的列完全一致
+                    if layout is None:
+                        layout = self._build_layout(chunk.columns)
+                    self._run_bars(chunk.index, chunk.to_numpy(), layout)
         else:
             # ── pandas 模式：向后兼容（测试 mock 数据等） ──
             df: pd.DataFrame = raw
-            for date, row in df.iterrows():
-                by_factor = self._parse_row(row)
-                for factor, data in by_factor.items():
-                    self.strategy._data.push(date, factor, data)
-                self.strategy.broker.timestamp = date
-                self.strategy.on_bar(date)
-                self.strategy.broker.on_bar(
-                    date, self.strategy._data.get
-                )
+            self._run_bars(df.index, df.to_numpy(), self._build_layout(df.columns))
 
         # 保存回测结果
         self.results = self.strategy.broker.trades
         self.metrics = self._compute_metrics()
 
-    def _load_benchmark(self, benchmark_code: str):
-        """
-        加载基准指数数据
+    def _load_benchmark(self, benchmark_code: str, start_date=None, end_date=None):
+        """加载基准指数，同时算出**日收益序列**（`self._benchmark_returns`）。
+
+        🚨 两个坑（都在这次改掉）：
+
+        1. 原来这里新建一个 `Data(symbols=[code])` 再 `get()` —— 走的是 Data 的默认
+           source/adjust，跟回测本体可能根本不是同一个目录；本地没缓存时还会去联网。
+           现在直接用回测本体已经定好的缓存目录（`self.data.target_dir`），同源同口径。
+
+        2. 原来的数据只喂给 `generate_report()` 画一条对照曲线，`_compute_metrics()`
+           一点没用上 —— 所以 `bt.run(benchmark='000300.SH')` 跑完，metrics 里
+           **看不到 alpha / beta**。现在把日收益留一份，指标那边直接用。
 
         Args:
             benchmark_code: 基准代码，如 '000300.SH'
+            start_date / end_date: 回测区间，基准只取这一段（对齐才有意义）
         """
+        self._benchmark_data = None
+        self._benchmark_returns = None
+
+        # 基准文件的候选位置 —— 按顺序找，第一个存在的就用：
+        #   ① `{datadir}/{source}/{period}/{adjust}/` —— 和回测本体同一个目录
+        #      （qkadata 也把指数写进了 hfq，跟个股同步更新，最新）
+        #   ② `{datadir}/{source}/{period}/index/` —— 指数集中的地方
+        #      （桌面端/其他环境可能只同步这一个目录）
+        candidates = []
+        target = getattr(self.data, 'target_dir', None)
+        if target:
+            candidates.append(Path(target) / f"{benchmark_code}.parquet")
+        datadir = getattr(self.data, 'datadir', None)
+        if datadir:
+            candidates.append(
+                Path(datadir) / str(getattr(self.data, 'source', 'tickflow'))
+                / str(getattr(self.data, 'period', '1d')) / 'index'
+                / f"{benchmark_code}.parquet")
+
+        path = next((p for p in candidates if p.exists()), None)
+        if path is None:
+            logger.warning('基准行情文件不存在，alpha/beta 算不了，找过：%s',
+                           [str(p) for p in candidates])
+            return
+
         try:
-            from qka.core.data import Data
-            bm_data = Data(symbols=[benchmark_code])
-            bm_df = bm_data.get(lazy=False)
-            if bm_df is not None and not bm_df.empty:
-                # 提取 close 列（可能是多股票 MultiIndex，取第一只）
-                close_col = [c for c in bm_df.columns if 'close' in str(c).lower()]
-                if close_col:
-                    self._benchmark_data = bm_df[close_col[0]]
-                else:
-                    self._benchmark_data = bm_df.iloc[:, 0]
-                print(f"基准数据加载成功: {benchmark_code}，{len(bm_df)} 个交易日")
-        except Exception as e:
-            print(f"基准数据加载失败: {e}")
+            df = pd.read_parquet(path)
+            if 'date' not in df.columns:
+                df = df.reset_index()          # 写入时把 date 存成了 index
+            if 'close' not in df.columns:
+                logger.warning(f'基准文件缺 close 列，跳过：{path}')
+                return
+
+            df['date'] = df['date'].astype(str).str[:10]
+            if start_date is not None:
+                df = df[df['date'] >= str(start_date)[:10]]
+            if end_date is not None:
+                df = df[df['date'] <= str(end_date)[:10]]
+            if len(df) < 20:
+                logger.warning(f'基准数据只有 {len(df)} 天，样本太短，跳过 alpha/beta')
+                return
+
+            df = df.drop_duplicates('date').set_index('date').sort_index()
+            close = df['close'].astype(float)
+            self._benchmark_data = close
+            self._benchmark_returns = close.pct_change().dropna()
+        except Exception as exc:               # 基准出问题不该让整个回测失败
+            logger.warning(f'基准数据加载失败（不影响回测）：{exc}')
 
     def _compute_metrics(self) -> dict:
         """计算绩效指标。无数据时返回空 dict。"""
@@ -294,7 +363,7 @@ class Backtest:
         # 总手续费
         total_commission = self.strategy.broker.total_commission
 
-        return {
+        metrics = {
             'initial_cash': initial,
             'final_equity': final,
             'total_return_pct': total_return,
@@ -310,6 +379,46 @@ class Backtest:
             'n_days': n_days,
         }
 
+        metrics.update(self._benchmark_metrics(daily_returns))
+        return metrics
+
+    def _benchmark_metrics(self, daily_returns: pd.Series) -> dict:
+        """相对基准的指标：基准收益 / alpha / beta / 信息比率。
+
+        只在 `run(benchmark=...)` 且基准文件读到了才有；否则返回空 dict，
+        metrics 里就不出现这些键（调用方按缺字段处理，别造假数据）。
+
+        回归本身交给 `Analysis.alpha_beta` —— 口径只有一处，不在这里重写公式。
+        """
+        bench = getattr(self, '_benchmark_returns', None)
+        if bench is None or len(bench) < 2:
+            return {}
+
+        rp = daily_returns.copy()
+        rp.index = [str(i)[:10] for i in rp.index]
+        rp = rp[rp.index.isin(bench.index)]
+        if len(rp) < 20:                     # 样本太短，回归没有意义
+            return {}
+
+        from qka.core.analysis import Analysis
+
+        x = bench.loc[rp.index].astype(float)
+        y = rp.astype(float)
+
+        ab = Analysis().alpha_beta(y.values, x.values, rf=self.risk_free_rate)
+        out = {
+            'benchmark_return_pct': float((1 + x).prod() - 1) * 100,
+            'alpha_pct': float(ab.alpha) * 100,
+            'beta': float(ab.beta),
+            'benchmark_n_days': int(len(x)),
+        }
+        try:
+            out['information_ratio'] = float(
+                Analysis().information_ratio(y.values, x.values))
+        except Exception:                     # 跟踪误差为 0 时会算不出来，不致命
+            pass
+        return out
+
     def report(self, title: str = "未命名策略", output_path: Optional[str] = None) -> str:
         """
         生成自包含的 HTML 回测报告