book: scaffold + ch00 (execution trail as spine) — evidence exp 8-31, round 3

2026-08-18 22:35:23 +00:00
commit c93424e76c
83 changed files with 17676 additions and 0 deletions
@@ -0,0 +1,70 @@
+"""Minimal custom DataHandler — how to extend TACHandler for a new feature family.
+
+`TACHandler(DataHandlerLP)` already routes lake bars + ta-lib features via
+`LakeFeatureProvider` (see tac_qlib/contrib/data/handler.py). To add a NEW
+feature family (computed once, persisted into the lake features parquet — see
+examples/persist_sp_features.py), you only need to:
+
+  1. persist extra columns into features/market=US/timeframe=1d/symbol=*.parquet
+  2. list them in `feature_fields` (they are prefixed with `$` and de-duped)
+
+A subclass is only needed when the feature must be computed *inside* the qlib
+pipeline (e.g. as an extra processor). This file sketches that pattern.
+
+Reference handler structure (from tac_qlib/contrib/data/handler.py):
+
+    class TACHandler(DataHandlerLP):
+        def __init__(self, instruments, start_time, end_time, freq,
+                     fit_start_time=None, fit_end_time=None,
+                     feature_fields=None, label=None, lake_root=None, market="US",
+                     infer_processors=None, learn_processors=None, **kwargs):
+            loader = QlibDataLoader(configured=(feature_fields or self.DEFAULT_FIELDS), freq=freq)
+            super().__init__(instruments, start_time, end_time, freq=freq,
+                             data_loader=loader,
+                             infer_processors=infer_processors or DEFAULT_INFER_PROCESSORS,
+                             learn_processors=learn_processors or DEFAULT_LEARN_PROCESSORS,
+                             fit_start_time=fit_start_time, fit_end_time=fit_end_time,
+                             process_type=DataHandlerLP.PTYPE_A, **kwargs)
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from tac_qlib.contrib.data.handler import DEFAULT_INFER_PROCESSORS, DEFAULT_LEARN_PROCESSORS, TACHandler
+
+
+class CustomFeaturesHandler(TACHandler):
+    """TACHandler variant that also loads the lake feature columns passed in.
+
+    Usage from YAML — only the handler kwargs change:
+
+        handler:
+            class: CustomFeaturesHandler
+            module_path: tac_qlib.contrib.data.handler   # after adding this class there
+            kwargs:
+                instruments: AAPL,MSFT,QQQ
+                start_time: 2026-03-01
+                end_time: 2026-08-06
+                freq: day
+                lake_root: "{{ LAKE }}"
+                market: US
+                feature_fields: "$close,sp_ou_alpha,sp_hurst_exponent"
+                label: "Ref($close,-6)/Ref($close,-1)-1"
+    """
+
+    def __init__(
+        self,
+        feature_fields: Optional[List[str]] = None,
+        infer_processors: Optional[List[Any]] = None,
+        learn_processors: Optional[List[Any]] = None,
+        **kwargs: Any,
+    ):
+        # `feature_fields` are passed through with the leading `$` stripped by
+        # TACHandler; infer/learn default to the lake-tuned processor stacks.
+        super().__init__(
+            feature_fields=feature_fields,
+            infer_processors=infer_processors or DEFAULT_INFER_PROCESSORS,
+            learn_processors=learn_processors or DEFAULT_LEARN_PROCESSORS,
+            **kwargs,
+        )