quantnodes 3.0.0__py3-none-any.whl

QuantNodes/research/factor_test/nodes/_base.py

@@ -0,0 +1,91 @@
+# coding: utf-8
+"""Pydantic 化节点公共基类 / Pydantic-config Node Base.
+
+抽取 12 节点 __init__ 的 Union 校验样板 (~144 行重复) 到此处.
+子类只需声明 ``ConfigSchema = XxxNodeConfig`` 即可:
+
+>>> class FooNode(PydanticConfigNode):
+...     ConfigSchema = FooNodeConfig
+...     def _execute(self, input_data=None, **kw): ...
+
+构造时:
+- ``isinstance(config, ConfigSchema)``  → 直接使用
+- ``dict / None``                       → ``ConfigSchema.model_validate``
+- 其他类型                              → ``TypeError``
+"""
+
+from typing import Any, ClassVar, Optional, Union
+
+from pydantic import BaseModel
+
+from QuantNodes.core.node import BaseNode
+
+
+class PydanticConfigNode(BaseNode):
+    """统一处理 12 节点的 ``Union[dict, ConfigSchema, None]`` 配置入参.
+
+    子类必须设置 ``ConfigSchema``; 构造完成后, 实例上挂载:
+
+    - ``self.cfg`` : ``ConfigSchema`` 实例 (推荐访问入口)
+    - ``self.config``: ``dict`` (BaseNode 协议要求)
+    - ``self._xxx`` : 由 ``_ALIASES`` 声明的 cfg 字段别名 (向后兼容)
+
+    自动 alias 规则 (Phase G3):
+    声明 ``_ALIASES = {"_data_path": "data_path", ...}`` 后, 基类
+    ``__init__`` 自动 copy cfg 字段到 self._xxx。list/tuple 字段会被浅拷贝
+    以避免下游误改 cfg。
+    """
+
+    ConfigSchema: ClassVar[type[BaseModel]]
+    _ALIASES: ClassVar[dict[str, str]] = {}
+
+    def __init__(
+        self,
+        name: Optional[str] = None,
+        config: Union[dict, BaseModel, None] = None,
+        **kwargs: Any,
+    ) -> None:
+        Schema = self.ConfigSchema
+        if isinstance(config, Schema):
+            cfg = config
+            super().__init__(name, cfg.model_dump(), **kwargs)
+        elif isinstance(config, dict) or config is None:
+            cfg = Schema.model_validate(config or {})
+            super().__init__(name, config, **kwargs)
+        else:
+            raise TypeError(
+                f"config must be dict/None/{Schema.__name__}, "
+                f"got {type(config).__name__}"
+            )
+        self.cfg: BaseModel = cfg
+        # Auto-apply aliases
+        for alias, field in self._ALIASES.items():
+            value = getattr(self.cfg, field)
+            if isinstance(value, list):
+                value = list(value)  # shallow copy
+            elif isinstance(value, tuple):
+                value = list(value)
+            setattr(self, alias, value)
+
+    def _ctx(self, context: dict) -> dict:
+        """Drill into context['LoadData'] dict (Phase G4)."""
+        return context.get("LoadData", {})
+
+    def _ctx_load(self, context: dict, key: str, default=None):
+        """Get one key from context['LoadData'] (Phase G4).
+
+        Replaces 13 sites of: ``context.get('LoadData', {}).get(KEY)``.
+        """
+        return self._ctx(context).get(key, default)
+
+    def _factor_data(self, context: dict):
+        """Return FactorNeutralize output if set, else FactorPreprocess (Phase G4).
+
+        Replaces the 4-line pattern in 4 analysis nodes (ic_analyzer,
+        factor_score, group_analyzer, risk_correlation). Returns None
+        if neither is set, leaving None-handling to the caller.
+        """
+        neutralized = context.get("FactorNeutralize")
+        if neutralized is not None:
+            return neutralized
+        return context.get("FactorPreprocess")

QuantNodes/research/factor_test/nodes/adjust_date_node.py

@@ -0,0 +1,48 @@
+# coding: utf-8
+"""Node 4: 调仓日生成 / Adjust Date Node
+
+Migrated from date_utils.py:134-191 get_adjust_date()
+"""
+
+import pandas as pd
+
+from QuantNodes.research.factor_test.nodes._base import PydanticConfigNode
+from QuantNodes.research.factor_test.nodes.configs import AdjustDateNodeConfig
+from QuantNodes.research.factor_test.utils.date_utils import get_adjust_date
+
+
+class AdjustDateNode(PydanticConfigNode):
+    """根据起始日、截止日、调仓模式生成调仓日序列
+
+    输入: context["LoadData"] 的输出
+    输出: adj_dates (yyyymmdd int DataFrame)
+    """
+
+    ConfigSchema = AdjustDateNodeConfig
+    _ALIASES = {
+        "_adj_date_beg": "adj_date_beg",
+        "_adj_date_end": "adj_date_end",
+        "_adj_mode": "adj_mode",
+    }
+
+    def _execute(self, input_data=None, **kwargs) -> pd.DataFrame:
+        # T0-3: H10 启动校验 (避免静默跑废日期)
+        if self._adj_date_beg is None or self._adj_date_end is None:
+            raise ValueError(
+                f"AdjustDateNode 需要 adj_date_beg 和 adj_date_end 字段 "
+                f"(H10: 默认 None, 当前 beg={self._adj_date_beg}, end={self._adj_date_end})"
+            )
+
+        context = kwargs.get('context', {})
+        load_data = context.get('LoadData') or input_data or {}
+
+        trade_dt = load_data['trade_dt']
+
+        adj_dates = get_adjust_date(
+            trade_dt,
+            self._adj_date_beg,
+            self._adj_date_end,
+            tuple(self._adj_mode)
+        )
+
+        return adj_dates

QuantNodes/research/factor_test/nodes/configs.py

@@ -0,0 +1,240 @@
+# coding: utf-8
+"""12 节点 Pydantic 配置模型 / Node Configuration Models
+
+Phase 3.1 T0: 12 节点的 __init__ 改 Union 接受 (dict / *Config / None),
+内部 model_validate() 校验, 保留 self._xxx 实例属性 (向后兼容 5 处测试).
+
+拼写错 (extra="forbid") 立即 ValidationError, 跨进程 model_dump() → dict 链稳定.
+
+Phase R3-A (2026-06-19): Schema 收敛
+- 8 节点 Config 直接继承 config.py 子模型 (避免字段重复定义)
+- 4 节点 (LoadData/AdjustDate/SamplePool/Report) 字段语义不同, 保留独立定义
+- 单一真值源: 改默认值只改 config.py 一处即可同步到 nodes/configs.py
+
+Phase 1.4: register_node_config 装饰器
+- 替代手工维护的 NODE_CONFIG_SCHEMAS 路由表
+- 用法: @register_node_config("GroupAnalyzer") class GroupAnalyzerNodeConfig(GroupSetting): ...
+- 自动注册到 NODE_CONFIG_SCHEMAS, 避免新增节点时漏改路由表
+"""
+
+from typing import Optional
+from pydantic import BaseModel, Field, ConfigDict
+
+from QuantNodes.research.factor_test.config import (
+    FactorSetting,
+    GroupSetting,
+    ICSetting,
+    LongShortSetting,
+    PreprocessSetting,
+    RiskCorrelationSetting,
+    ScoreSetting,
+    TradableSetting,
+)
+
+
+_FORBID = ConfigDict(extra="forbid")
+
+
+class _NodeBase(BaseModel):
+    """12 节点 Config 公共基类
+    - extra="forbid": 拼写错立即 ValidationError (新防线)
+    """
+    model_config = _FORBID
+
+
+# ── 节点名 → Config Schema 路由表 (Phase 1.4: 装饰器自动注册) ─────
+NODE_CONFIG_SCHEMAS: dict[str, type[BaseModel]] = {}
+
+
+def register_node_config(node_name: str):
+    """装饰器: 将 Config Schema 注册到 NODE_CONFIG_SCHEMAS[node_name]。
+
+    Phase 1.4: 替代手工维护的路由表。新增节点 Config 时只需:
+        @register_node_config("MyNode")
+        class MyNodeConfig(BaseModel):
+            ...
+
+    Args:
+        node_name: 节点在 pipeline 中的名称 (与 BaseNode 子类的注册名一致)
+
+    Returns:
+        装饰器函数, 接受 Config 类并原样返回 (同时写入 NODE_CONFIG_SCHEMAS)
+
+    Raises:
+        TypeError: 装饰的不是 pydantic BaseModel 子类
+        ValueError: 重复注册同一 node_name (且类不同)
+    """
+    def decorator(cls: type[BaseModel]) -> type[BaseModel]:
+        if not issubclass(cls, BaseModel):
+            raise TypeError(
+                f"@register_node_config({node_name!r}) requires a pydantic "
+                f"BaseModel subclass, got {cls!r}"
+            )
+        if node_name in NODE_CONFIG_SCHEMAS:
+            existing = NODE_CONFIG_SCHEMAS[node_name]
+            if existing is not cls:
+                raise ValueError(
+                    f"NODE_CONFIG_SCHEMAS[{node_name!r}] already registered "
+                    f"to {existing.__name__}; refusing to overwrite with {cls.__name__}"
+                )
+        NODE_CONFIG_SCHEMAS[node_name] = cls
+        return cls
+    return decorator
+
+
+# ── 注册所有 12 节点 Config (Phase 1.4: 装饰器替代手工表) ─────────
+@register_node_config("LoadData")
+class LoadDataNodeConfig(_NodeBase):
+    """Node 1: LoadDataNode 配置
+
+    P-2: data_path 改 Field(...) 必填, 启动时报 ValidationError (None/缺字段).
+    现有 test_data_loader_edges.py:309-316 已显式提供 load_keys 但缺 data_path,
+    需更新为提供 data_path (load_keys 测试不变).
+    """
+    data_path: str = Field(..., description="数据根目录 (P-2 必填, 启动校验)")
+    load_keys: list = Field(
+        default_factory=lambda: [
+            "stklist", "trade_dt", "cp", "id_citic1", "mv_float",
+            "st", "suspend", "ud_limit", "ipo_days",
+        ],
+        description="需要加载的数据 key 列表 (M7 默认含 tradability 必需键)",
+    )
+    factor: Optional[FactorSetting] = Field(
+        default=None, description="因子配置 (None=不加载因子)",
+    )
+
+
+@register_node_config("SamplePoolFilter")
+class SamplePoolNodeConfig(_NodeBase):
+    """Node 2: SamplePoolFilterNode 配置
+
+    M9: index_mapping 可自定义，合并全局默认 INDEX_MAPPING。
+    M12: i18n_name_map 可自定义行业代码→名称映射，覆盖全局默认 INDUSTRY_MAPPING。
+
+    字段语义独立于 PreprocessSetting (sample_index/sample_industry 是节点专属),
+    保留独立定义.
+    """
+    sample_index: str = Field(
+        default="all", description="样本池: all/HS300/ZZ500/ZZ800/custom",
+    )
+    sample_industry: str = Field(
+        default="all", description="行业筛选: all/中信行业名",
+    )
+    sample_index_customdir: Optional[tuple] = Field(
+        default=None, description="自定义样本池路径 (sample_index=custom 时必填)",
+    )
+    index_mapping: Optional[dict[str, tuple[str, str]]] = Field(
+        default=None, description="自定义指数映射 (覆盖全局默认 INDEX_MAPPING)",
+    )
+    i18n_name_map: Optional[dict[str, str]] = Field(
+        default=None, description="自定义行业代码→名称映射 (覆盖全局默认 INDUSTRY_MAPPING)",
+    )
+
+
+@register_node_config("TradabilityFilter")
+class TradabilityNodeConfig(_NodeBase):
+    """Node 3: TradabilityFilterNode 配置"""
+    tradable: TradableSetting = Field(
+        default_factory=TradableSetting,
+        description="可交易性配置 (no_st/no_suspended/no_up_down_limit/min_ipo_days/trace)",
+    )
+
+
+@register_node_config("AdjustDate")
+class AdjustDateNodeConfig(_NodeBase):
+    """Node 4: AdjustDateNode 配置
+
+    H10 兼容: adj_date_beg/end 默认 None → _execute 启动校验抛 ValueError,
+    避免静默跑废日期范围.
+
+    字段语义独立 (adj_date_beg/end 在 PreprocessSetting 中是预处理日期窗口,
+    在节点中是调仓日生成范围), 保留独立定义.
+    """
+    adj_date_beg: Optional[int] = Field(
+        default=None, description="起始日期 yyyymmdd (None → 启动报错)",
+    )
+    adj_date_end: Optional[int] = Field(
+        default=None, description="截止日期 yyyymmdd (None → 启动报错)",
+    )
+    adj_mode: list = Field(
+        default_factory=lambda: ["M", "end"],
+        description="调仓模式: [mode, position], mode=M/W/Q/D, position=end/start",
+    )
+
+
+@register_node_config("FactorPreprocess")
+class PreprocessNodeConfig(BaseModel):
+    """Node 5: FactorPreprocessNode 配置 (R3-A: 继承 config.py::PreprocessSetting 子集字段).
+
+    字段全部从 PreprocessSetting 继承 (missing/extreme/norm/mad_n/pct_low/pct_high/i18n_name_map),
+    通过 model_dump(include={...}) 切片传入。改 mad_n 默认值只需改 PreprocessSetting 一处.
+    """
+    model_config = _FORBID
+    missing: str = PreprocessSetting.model_fields["missing"]
+    extreme: str = PreprocessSetting.model_fields["extreme"]
+    norm: str = PreprocessSetting.model_fields["norm"]
+    mad_n: float = PreprocessSetting.model_fields["mad_n"]
+    pct_low: float = PreprocessSetting.model_fields["pct_low"]
+    pct_high: float = PreprocessSetting.model_fields["pct_high"]
+    i18n_name_map: Optional[dict[str, str]] = PreprocessSetting.model_fields["i18n_name_map"]
+
+
+@register_node_config("FactorNeutralize")
+class NeutralizeNodeConfig(BaseModel):
+    """Node 6: FactorNeutralizeNode 配置 (R3-A: 继承 PreprocessSetting 中性化字段)."""
+    model_config = _FORBID
+    industry_neutral: bool = PreprocessSetting.model_fields["industry_neutral"]
+    risk_neutral: bool = PreprocessSetting.model_fields["risk_neutral"]
+    risk_factors: list = PreprocessSetting.model_fields["risk_factors"]
+
+
+@register_node_config("ICAnalyzer")
+class ICAnalyzerNodeConfig(ICSetting):
+    """Node 7: ICAnalyzerNode 配置 (R3-A: 继承 ICSetting)."""
+    model_config = _FORBID
+
+
+@register_node_config("GroupAnalyzer")
+class GroupAnalyzerNodeConfig(GroupSetting):
+    """Node 8: GroupAnalyzerNode 配置 (R3-A: 继承 GroupSetting)."""
+    model_config = _FORBID
+
+
+@register_node_config("LongShort")
+class LongShortNodeConfig(LongShortSetting):
+    """Node 9: LongShortNode 配置 (R3-A: 继承 LongShortSetting)."""
+    model_config = _FORBID
+
+
+@register_node_config("FactorScore")
+class ScoreNodeConfig(ScoreSetting):
+    """Node 10: FactorScoreNode 配置 (R3-A: 继承 ScoreSetting).
+
+    T0-2: 4 字段 (enabled/n_industries=29/n_size_groups=3/n_quantile_groups=5)
+    全部继承自 ScoreSetting.
+    """
+    model_config = _FORBID
+
+
+@register_node_config("RiskCorrelation")
+class RiskCorrelationNodeConfig(RiskCorrelationSetting):
+    """Node 11: RiskCorrelationNode 配置 (R3-A: 继承 RiskCorrelationSetting)."""
+    model_config = _FORBID
+
+
+@register_node_config("FactorTestReport")
+class ReportNodeConfig(_NodeBase):
+    """Node 12: FactorTestReportNode 配置
+
+    P-1: dir 路径优先级 env QUANTNODES_OUTPUT_DIR > expanduser > default='./output/'.
+
+    字段语义独立 (OutputSetting.dir vs ReportNodeConfig.dir 同名但生命周期不同),
+    保留独立定义.
+    """
+    dir: str = Field(
+        default="./output/", description="输出目录 (P-1: env > expanduser > default)",
+    )
+    format: list = Field(
+        default_factory=lambda: ["parquet", "json"],
+        description="输出格式",
+    )

QuantNodes/research/factor_test/nodes/factor_neutralize_node.py

@@ -0,0 +1,87 @@
+# coding=utf-8
+"""Node 6: 因子中性化 / Factor Neutralize Node
+
+Migrated from factor_utils.py:534-625 neutralize()
+
+Phase 2.1 (Chain of Responsibility):
+  - 原 70 行 _neutralize 三个 if/elif 分支 (industry only / risk only / both)
+    替换为 chain dispatch.
+  - 中性化逻辑 (设计矩阵 X 组装) 抽到 nodes/neutralizers.py:
+      Neutralizer (ABC) / IndustryNeutralizer / RiskNeutralizer
+      build_neutralizer_chain() / apply_neutralizer_chain()
+  - 新增中性化类型 (如 StyleNeutralizer) 只需新增一个 Neutralizer 子类,
+    _execute 无需修改.
+"""
+
+import logging
+
+import pandas as pd
+
+from QuantNodes.research.factor_test.nodes._base import PydanticConfigNode
+from QuantNodes.research.factor_test.nodes.configs import NeutralizeNodeConfig
+from QuantNodes.research.factor_test.nodes.neutralizers import (
+    apply_neutralizer_chain,
+    build_neutralizer_chain,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class FactorNeutralizeNode(PydanticConfigNode):
+    """行业/风险因子中性化 (OLS 残差)
+
+    输入: factor_std, industry, risk_factors
+    输出: factor_neutral
+    """
+
+    ConfigSchema = NeutralizeNodeConfig
+    _ALIASES = {
+        "_if_industry": "industry_neutral",
+        "_if_risk": "risk_neutral",
+        "_risk_factor_specs": "risk_factors",
+    }
+
+    def _execute(self, input_data=None, **kwargs) -> pd.DataFrame:
+        context = kwargs.get('context', {})
+        factor_std = context.get('FactorPreprocess')
+        if factor_std is None:
+            raise ValueError("因子预处理数据缺失")
+
+        if not self._if_industry and not self._if_risk:
+            return factor_std
+
+        industry = self._ctx_load(context, 'id_citic1')
+        if industry is None and self._if_industry:
+            raise ValueError("行业数据缺失")
+
+        # 加载风险因子
+        risk_data = []
+        if self._if_risk and self._risk_factor_specs:
+            loader = self._ctx_load(context, '_loader')
+            for file_key, factor_key in self._risk_factor_specs:
+                try:
+                    if file_key == 'risk_factor.h5':
+                        rf = loader.load_h5(file_key, factor_key)
+                    else:
+                        rf = loader.load_custom((file_key, factor_key))
+                    if loader.valid_shape(rf):
+                        rf = loader.add_index(rf)
+                    risk_data.append(rf)
+                except Exception as e:
+                    logger.warning(f"加载风险因子 {factor_key} 失败: {e}")
+
+        return self._neutralize(factor_std, self._if_industry, industry,
+                                self._if_risk, risk_data)
+
+    def _neutralize(self, factor_i, if_industry, industry, if_risk, risk_data):
+        """中性化处理 (Phase 2.1: 委托给 chain).
+
+        Phase 2.1 行为完全等价于旧实现:
+          - chain 为空 → 返回 factor_i (全 nan, 与原 _neutralize 入口一致)
+          - 4 种 flag 组合的输出与原 branch 1/2/3 bitwise 一致
+        """
+        chain = build_neutralizer_chain(if_industry, if_risk, industry, risk_data)
+        if not chain:
+            # 无 neutralizer 时返回原 factor (保留 nan 模式), 与旧 line 40 一致
+            return factor_i
+        return apply_neutralizer_chain(factor_i, chain)

QuantNodes/research/factor_test/nodes/factor_preprocess_node.py

@@ -0,0 +1,222 @@
+# coding: utf-8
+"""Node 5: 因子预处理 / Factor Preprocess Node
+
+Migrated from factor_utils.py:310-532 preprocess_onePeriod + preprocess_factor
+Phase 1: 原样迁移保持行为一致性
+Phase 2: 逐步替换为 QuantNodes section_ops 算子
+Phase 3 (H5, 2026-06-20): vectorised _preprocess_one_period's per-date
+  Python loop into DataFrame-level operations (groupby/transform/clip/sub).
+  Expected 10-100x speedup on the preprocess step.
+"""
+
+import numpy as np
+import pandas as pd
+from scipy.stats import norm as scipy_norm
+
+from QuantNodes.research.factor_test.nodes._base import PydanticConfigNode
+from QuantNodes.research.factor_test.nodes.configs import PreprocessNodeConfig
+from QuantNodes.research.factor_test.nodes.preprocess_strategies import (
+    build_preprocess_strategies,
+)
+
+
+class FactorPreprocessNode(PydanticConfigNode):
+    """因子预处理: 缺失值填充 + 去极值 + 标准化
+
+    输入: factor, tradable, adj_dates, industry
+    输出: factor_std (预处理后的因子, 仅调仓日)
+
+    Phase 2.2 (Strategy pattern): 3 类预处理 (missing fill / de-extreme /
+    normalise) 抽到 preprocess_strategies.py, _preprocess_vectorized 退化为
+    简单的 3 行 dispatch. 新增策略类型 (如 winsorize) 只需新增一个 Strategy
+    子类, 本文件无需修改.
+    """
+
+    ConfigSchema = PreprocessNodeConfig
+    _ALIASES = {
+        "_missing": "missing",
+        "_extreme": "extreme",
+        "_norm": "norm",
+        "_mad_n": "mad_n",
+        "_pct_low": "pct_low",
+        "_pct_high": "pct_high",
+        "_i18n_name_map": "i18n_name_map",
+    }
+
+    def _execute(self, input_data=None, **kwargs) -> pd.DataFrame:
+        context = kwargs.get('context', {})
+        factor = self._ctx_load(context, 'factor')
+        tradable = context.get('TradabilityFilter')
+        adj_dates = context.get('AdjustDate')
+
+        if factor is None:
+            raise ValueError("因子数据缺失")
+        if tradable is None:
+            tradable = pd.DataFrame(np.ones_like(factor.values))
+
+        # 合并可交易性
+        tradable_factor = factor * tradable
+
+        # 提取调仓日的因子值
+        adj_date_values = (
+            adj_dates.iloc[:, 0].values
+            if isinstance(adj_dates, pd.DataFrame)
+            else adj_dates
+        )
+        tradable_factor_adj = tradable_factor.loc[tradable_factor.index.isin(adj_date_values)]
+        tradable_adj = tradable.loc[tradable.index.isin(adj_date_values)]
+
+        # 行业数据
+        industry = self._ctx_load(context, 'id_citic1')
+        industry_adj = (
+            industry.loc[industry.index.isin(adj_date_values)]
+            if industry is not None else None
+        )
+
+        # Vectorised preprocessing (H5, 2026-06-20).
+        result = self._preprocess_vectorized(
+            tradable_factor_adj, tradable_adj, industry_adj,
+            missing=self._missing, extreme=self._extreme, norm=self._norm,
+        )
+
+        # 清理索引
+        if hasattr(result.index, 'get_level_values'):
+            result.index = result.index.get_level_values(0).values
+        if hasattr(result.columns, 'get_level_values'):
+            result.columns = result.columns.get_level_values(0).values
+
+        return result
+
+    # ------------------------------------------------------------------
+    # Vectorised preprocessing (H5, 2026-06-20, refactored Phase 2.2)
+    # ------------------------------------------------------------------
+    def _preprocess_vectorized(
+        self,
+        tradable_factor: pd.DataFrame,
+        tradable: pd.DataFrame,
+        industry: pd.DataFrame | None,
+        *,
+        missing: str,
+        extreme: str,
+        norm: str,
+    ) -> pd.DataFrame:
+        """Apply missing-fill + de-extreme + normalise across all dates.
+
+        Replaces the previous ``apply(_preprocess_one_period, axis=1)`` loop.
+        Each step is a vectorised DataFrame operation, dispatched via
+        strategy pattern (Phase 2.2).
+
+          1. Tradable mask (per-row): factor where tradable != 0 & notnan,
+             else NaN.
+          2. Missing fill ('ind_avg'): per (date, industry) group mean.
+          3. De-extreme ('median'): per-date median +/- n * MAD.
+          4. De-extreme ('pct_shrink'): per-date quantiles.
+          5. Norm ('zscore'): per-date (x - mean) / std.
+          6. Norm ('norm'): per-date rank -> scipy.stats.norm.ppf.
+
+        Behavioural parity: produces same NaN pattern and same numeric
+        result as the per-date loop, to within floating-point noise.
+
+        Phase 2.2: 3 个 strategy 通过 build_preprocess_strategies() 构造,
+        apply() 顺序串接. 原硬编码 if 链消除.
+        """
+        result = tradable_factor.copy()
+
+        # 1. Tradable mask (vectorised)
+        if tradable is not None:
+            tradable_mask = tradable.reindex(index=result.index, columns=result.columns)
+            tradable_mask = tradable_mask.notna() & (tradable_mask != 0)
+            result = result.where(tradable_mask, np.nan)
+
+        # Phase 2.2: dispatch via 3 strategies
+        missing_s, extreme_s, norm_s = build_preprocess_strategies(missing, extreme, norm)
+        result = missing_s.apply(result, industry=industry)
+        result = extreme_s.apply(
+            result, mad_n=self._mad_n,
+            pct_low=self._pct_low, pct_high=self._pct_high,
+        )
+        result = norm_s.apply(result)
+
+        return result
+
+    # ------------------------------------------------------------------
+    # Legacy per-date loop (kept for reference / fallback)
+    # ------------------------------------------------------------------
+    def _preprocess_one_period(self, factor_i, tradable_adj, industry_adj, method):
+        """对单日因子值进行预处理 (legacy per-date loop, kept for reference).
+
+        H5 (2026-06-20): _execute now uses _preprocess_vectorized instead.
+        This method is preserved for unit-testing the legacy semantics but
+        is no longer called from the pipeline.
+        """
+        factor_i_new_all = factor_i.copy()
+
+        # 获取当日可交易和行业数据
+        date_key = factor_i.name[0] if hasattr(factor_i.name, '__len__') else factor_i.name
+
+        if tradable_adj is not None and date_key in tradable_adj.index:
+            tradable_i = tradable_adj.loc[date_key]
+        else:
+            return factor_i_new_all
+
+        if industry_adj is not None and date_key in industry_adj.index:
+            ind_i = industry_adj.loc[date_key]
+        else:
+            ind_i = pd.Series(np.nan, index=factor_i.index)
+
+        # 合并数据
+        df = pd.DataFrame({
+            'factor': factor_i,
+            'ind': ind_i,
+            'tradable': tradable_i,
+        }, index=factor_i.index)
+
+        # 剔除不可交易
+        df = df.loc[df['tradable'].notna() & (df['tradable'] != 0)]
+        if df.empty:
+            return factor_i_new_all
+
+        df['ind'] = df['ind'].replace(np.nan, 0)
+        df['factor_filled'] = df['factor'].copy()
+
+        # 1. 缺失值处理
+        if method['missing'] == 'ind_avg':
+            has_ind = df['ind'] > 0
+            if has_ind.any():
+                df.loc[has_ind, 'factor_filled'] = (
+                    df.loc[has_ind].groupby('ind')['factor']
+                    .transform(lambda x: x.fillna(x.mean()))
+                )
+
+        # 2. 去极值
+        if method['extreme'] == 'median':
+            n = self._mad_n  # M5: 可调
+            d_m = df['factor_filled'].dropna().median()
+            d_mad = (df['factor_filled'] - d_m).abs().dropna().median()
+            df['factor_filled'] = df['factor_filled'].clip(d_m - n * d_mad, d_m + n * d_mad)
+        elif method['extreme'] == 'pct_shrink':
+            q1 = df['factor_filled'].quantile(self._pct_low)   # M5: 可调
+            q2 = df['factor_filled'].quantile(self._pct_high)  # M5: 可调
+            df['factor_filled'] = df['factor_filled'].clip(q1, q2)
+
+        # 3. 标准化
+        if method['norm'] == 'zscore':
+            f_mean = df['factor_filled'].dropna().mean()
+            f_std = df['factor_filled'].dropna().std(ddof=1)
+            if f_std > 0:
+                df['factor_filled'] = (df['factor_filled'] - f_mean) / f_std
+        elif method['norm'] == 'norm':
+            valid = df['factor_filled'].notna()
+            if valid.sum() > 1:
+                df.loc[valid, 'rank'] = df.loc[valid, 'factor_filled'].rank(pct=True)
+                # 处理 0 和 1 的边界
+                ranks = df['rank'].dropna()
+                df['rank'] = df['rank'].clip(
+                    lower=ranks[ranks > 0].min() * 0.5 if (ranks > 0).any() else 0.01,
+                    upper=(ranks[ranks < 1].max() + 1) * 0.5 if (ranks < 1).any() else 0.99
+                )
+                df['factor_filled'] = scipy_norm.ppf(df['rank'], 0, 1)
+
+        # 写回
+        factor_i_new_all.loc[df.index] = df['factor_filled'].values
+        return factor_i_new_all