qka 2.2.0__tar.gz → 2.2.1.dev2__tar.gz

{qka-2.2.0 → qka-2.2.1.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qka
-Version: 2.2.0
+Version: 2.2.1.dev2
 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.2.0 → qka-2.2.1.dev2}/qka/core/backtest.py

@@ -79,7 +79,7 @@ class Backtest:
 
     def run(self, cash: float = 100000.0,
             start_date: str = None, end_date: str = None,
-            benchmark: Optional[str] = None):
+            benchmark: Optional[str] = None, warmup: int = 0):
         """
         执行回测
 
@@ -95,6 +95,10 @@ class Backtest:
             end_date: 回测截止日期 YYYY-MM-DD，None 表示数据最晚日期
             benchmark: 基准代码，如 '000300.SH'（沪深300）。
                        如果提供，会下载基准数据用于对比。
+            warmup: 指标预热天数（默认 0）。自动多读取 warmup 个交易日的历史数据用于
+                   计算指标，使策略从第一个交易日起即拿到有效指标值，无需手写
+                   warmup guard 跳过前 N 根 bar。仅用于计算，on_bar 调用次数不变。
+                   显式传入（>0）时覆盖 Data 构造时的 warmup 设定。
 
         Returns:
             None。回测结果保存在 self.results、self.metrics、self.trade_history 中。
@@ -105,6 +109,10 @@ class Backtest:
         self.strategy.sizing = SizingAccessor(self.strategy.broker)
         self.strategy._data = DataAccessor()
 
+        # 指标预热：run 显式传入时覆盖 Data 构造时的 warmup 设定
+        if warmup > 0:
+            self.data.warmup = warmup
+
         # 获取数据
         raw = self.data.get(lazy=True, start_date=start_date, end_date=end_date)
 

{qka-2.2.0 → qka-2.2.1.dev2}/qka/core/data.py

@@ -74,6 +74,7 @@ class Data():
         datadir: Optional[Path] = None,
         indicators: Optional[dict] = None,
         extra_fields: Optional[List[str]] = None,
+        warmup: int = 0,
     ):
         """
         初始化数据对象
@@ -92,7 +93,11 @@ class Data():
                 可选值见 BAOSTOCK_EXTRA_FIELDS。追加的列同样遵循 {symbol}|{field} 命名，
                 如 'sh.600000|peTTM'。注意：首次下载后缓存字段固定，变更 extra_fields
                 会自动检测列缺失并重新下载对应股票。
-                
+
+            warmup: 指标预热天数（默认 0）。回测/取数时自动多读取 warmup 个交易日的历史数据
+                用于计算指标，使第 1 个交易日即可拿到有效指标值，无需在策略里手写
+                `if len(hist) < N: continue` 跳过前 N 根 bar。仅用于计算，不会增加 on_bar 调用次数。
+
                 **1. 字典（混搭 ta 函数和自定义因子）：**
                 ```python
                 {
@@ -119,6 +124,7 @@ class Data():
         self.adjust = adjust
         self.source = source
         self.pool_size = pool_size
+        self.warmup = warmup
 
         # extra_fields 白名单校验 + 去重
         self.extra_fields = []
@@ -668,12 +674,13 @@ class Data():
         return df
 
     def _min_rows_for_indicators(self):
-        """计算所有指标所需的最小行数。
+        """计算所有指标所需的最小行数（含显式预热天数）。
 
-        遍历所有指标条目的整数参数，取最大值作为窗口上限的保守估计。
+        遍历所有指标条目的整数参数，取最大值作为窗口上限的保守估计，
+        再与显式 warmup 取较大者。
         """
         if not self._indicators or not isinstance(self._indicators, dict):
-            return 0
+            return self.warmup
         max_window = 0
         for spec in self._indicators.values():
             if callable(spec) or not isinstance(spec, (list, tuple)):
@@ -686,7 +693,7 @@ class Data():
             for v in rest[idx:]:
                 if isinstance(v, int):
                     max_window = max(max_window, v)
-        return max_window
+        return max(max_window, self.warmup)
 
     def _get_from_baostock(
         self, symbol: str,

{qka-2.2.0 → qka-2.2.1.dev2}/skills/qka/references/backtest.md

@@ -19,7 +19,7 @@ bt = Backtest(data, strategy)
 
 ### run()
 
-`run(cash=100000.0, start_date=None, end_date=None, benchmark=None)`
+`run(cash=100000.0, start_date=None, end_date=None, benchmark=None, warmup=0)`
 
 执行回测。注入 broker/sizing/data 后遍历每个交易日，调用 `strategy.on_bar(date)`。
 
@@ -29,6 +29,7 @@ bt = Backtest(data, strategy)
 | `start_date` | `None` | 回测起始日期 `'YYYY-MM-DD'` |
 | `end_date` | `None` | 回测截止日期 |
 | `benchmark` | `None` | 基准指数代码，baostock 格式如 `'sh.000300'` |
+| `warmup` | `0` | 指标预热天数。自动多读 `warmup` 天历史计算指标，使策略第 1 个 bar 起指标即有效（无需手写 warmup guard）。on_bar 调用次数不变；显式传入（>0）时覆盖 Data 的 warmup 设定 |
 
 > 500 bar 以上自动分块迭代，避免一次性加载全量数据。
 

{qka-2.2.0 → qka-2.2.1.dev2}/skills/qka/references/data.md

@@ -26,6 +26,19 @@ data = Data(
 | `benchmark` | `str` | `None` | 基准指数代码，如 `'sh.000300'`。下载后在 `get()` 结果中追加 `benchmark|returns` 列 |
 | `indicators` | `dict` | `None` | 预计算指标，见下方 |
 | `extra_fields` | `list[str]` | `None` | baostock 扩展字段（选股/估值用），见下方 |
+| `warmup` | `int` | `0` | 指标预热天数。回测/取数时自动多读 `warmup` 个交易日历史用于计算指标，使第 1 个交易日即拿到有效指标值（无需手写跳过前 N 根 bar）。仅用于计算，不增加回测 bar 数 |
+
+> **warmup（指标预热）**：若指标/因子需要较长历史窗口（如动量排名需看前 200 天），设 `warmup=200`。
+> qka 会在 `[start_date, end_date]` 之前额外多读 `warmup` 天数据用于计算指标，但返回和回测仍严格从
+> `start_date` 起——策略第 1 个 bar 指标即有值，无需 `continue` 跳过前 N 根 bar。
+>
+> ```python
+> data = Data(
+>     symbols=['sz.000001'],
+>     indicators={'mom200': lambda df: df['close'].pct_change(200)},
+>     warmup=200,   # 自定义指标 qka 推断不出窗口，显式声明预热天数
+> )
+> ```
 
 `get()` 返回的 DataFrame 除了 `open/high/low/close/volume/amount` 六大基本列外，还自动内置一列：
 

{qka-2.2.0 → qka-2.2.1.dev2}/skills/qka/references/strategy.md

@@ -24,6 +24,7 @@ class MyStrategy(Strategy):
 | `__init__` | **必须**调用 `super().__init__()`。不需要传任何参数 |
 | `on_bar` 签名 | 只有 `self` 和 `date`。**没有** `get` 参数（旧版 API，已废弃） |
 | `self.params` | **不存在**。不要写 `self.params.get('fast', 5)`，直接用实例属性 |
+| 预热 guard | **不要**手写 `if len(hist) < N: continue` 跳过前 N 根 bar。改用 `Data(warmup=N)` 或 `bt.run(warmup=N)`，qka 自动多读历史计算指标 |
 
 `Backtest.run()` 在执行时注入以下属性：
 
@@ -75,6 +76,22 @@ hist = self.history('close', 20)  # 最近 20 天的收盘价
 | 列 | 股票代码 |
 | 异常 | 因子不存在时返回空 DataFrame（有索引无列），不抛异常 |
 
+### 指标预热（warmup）
+
+若策略用到的指标/因子需要较长历史窗口（如动量排名需看前 200 天数据），**不要**在 `on_bar` 里
+手写 `if len(hist) < N: continue` 跳过前 N 根 bar。改用 `Data(warmup=N)` 或 `bt.run(warmup=N)`，
+qka 自动在 `[start_date, end_date]` 之前多读 `warmup` 天数据用于计算指标，但回测仍从 `start_date`
+首个交易日开始（`on_bar` 调用次数不变），指标自始有效：
+
+```python
+data = Data(symbols=[...], indicators={...}, warmup=200)   # 构造时声明
+# 或
+bt.run(warmup=200)                                          # 回测时声明（覆盖 Data 的设定）
+```
+
+> 注意：qka 只能从 ta 指标的整数参数自动推断预热窗口；自定义 lambda 指标推断不到，
+> 必须显式用 `warmup` 声明窗口天数，否则开头一段仍为 `NaN`。
+
 ### self.broker / self.sizing
 
 由 `Backtest.run()` 注入（见上方注入表），通过 `self.broker.buy()` / `self.broker.sell()` 和 `self.sizing.percent()` 等方法使用。详见 [Broker](#broker) 和 [SizingAccessor](#sizingaccessor) 独立章节。