quantnodes 3.0.0__py3-none-any.whl

QuantNodes/research/factor_test/nodes/ic_analyzer_node.py

@@ -0,0 +1,112 @@
+# coding: utf-8
+"""Node 7: IC 分析 / IC Analyzer Node
+
+Migrated from factor_performance.py:111-158 cal_ic()
+"""
+
+
+import numpy as np
+import pandas as pd
+
+from QuantNodes.research.factor_test.nodes._base import PydanticConfigNode
+from QuantNodes.research.factor_test.nodes.configs import ICAnalyzerNodeConfig
+
+
+class ICAnalyzerNode(PydanticConfigNode):
+    """计算 IC / Rank IC / ICIR / 因子 rank 自相关性
+
+    输入: factor_neutral, price
+    输出: {ic, rank_ic, ic_result, rank_ic_result, factor_rank_autocorr}
+    """
+
+    ConfigSchema = ICAnalyzerNodeConfig
+    _ALIASES = {"_min_group_size": "min_group_size"}
+
+    def _execute(self, input_data=None, **kwargs) -> dict:
+        context = kwargs.get('context', {})
+        factor_data = self._factor_data(context)
+        price = self._ctx_load(context, 'price')
+
+        if factor_data is None or price is None:
+            raise ValueError("因子或价格数据缺失")
+
+        return self._calc_ic(factor_data, price, self._min_group_size)
+
+    def _calc_ic(self, factor_data, price, group):
+        """计算 IC 系列
+
+        H4 (2026-06-20): vectorised per-date corr loop into DataFrame.corrwith.
+        Old loop did N separate Series.corr() calls (each O(K log K) over
+        K stocks); now one vectorised pairwise correlation across rows.
+        Typically 5-50x speedup on the hot path.
+
+        Empty / low-sample dates (nonan < group) are masked to NaN via
+        a per-row count of notnull values, preserving the original guard.
+        """
+        adj_dates = factor_data.index.tolist()
+
+        # 对齐价格到调仓日
+        price_adj = price.loc[price.index.isin(adj_dates)]
+
+        # 下一期收益
+        stock_cycle_ret = price_adj.pct_change(fill_method=None).shift(-1)
+
+        # 共同日期 (factor_data 与 stock_cycle_ret 都有)
+        common_dates = factor_data.index.intersection(stock_cycle_ret.index)
+        f = factor_data.loc[common_dates]
+        r = stock_cycle_ret.loc[common_dates]
+
+        # Per-date valid sample count (preserves <group guard).
+        per_date_count = f.notna().sum(axis=1)
+        valid_mask = per_date_count >= group
+
+        # Pearson IC (vectorised: one corr per row)
+        ic = f.corrwith(r, axis=1)
+        ic = ic.where(valid_mask, np.nan)
+        ic = ic.reindex(adj_dates)
+
+        # Spearman Rank IC (rank each row, then corrwith)
+        rank_f = f.rank(axis=1)
+        rank_r = r.rank(axis=1)
+        rank_ic = rank_f.corrwith(rank_r, axis=1)
+        rank_ic = rank_ic.where(valid_mask, np.nan)
+        rank_ic = rank_ic.reindex(adj_dates)
+
+        # 因子 rank 自相关 (rank(this row) vs rank(next row))
+        factor_rank = factor_data.rank(axis=1)
+        factor_rank_next = factor_rank.shift(-1)
+        common_dates2 = factor_rank.index.intersection(factor_rank_next.index)
+        factor_rank_autocorr = factor_rank.loc[common_dates2].corrwith(
+            factor_rank_next.loc[common_dates2], axis=1, method='spearman'
+        )
+        factor_rank_autocorr = factor_rank_autocorr.reindex(adj_dates)
+
+        # 评价指标
+        ic_result = pd.Series([
+            ic.mean(), ic.std(ddof=1),
+            ic.mean() / ic.std(ddof=1) if ic.std(ddof=1) != 0 else np.nan,
+            ic.mean() / ic.std(ddof=1) * np.sqrt(ic.notna().sum() - 1)
+            if ic.std(ddof=1) != 0 else np.nan,
+            ((ic > 0).sum() / ic.count()) if ic.count() > 0 else np.nan,
+            ((ic < 0).sum() / ic.count()) if ic.count() > 0 else np.nan,
+        ], index=['IC均值', 'IC标准差', 'ICIR', 'IC_T值', 'IC为正比例', 'IC为负比例'])
+
+        rank_ic_result = pd.Series([
+            rank_ic.mean(), rank_ic.std(ddof=1),
+            rank_ic.mean() / rank_ic.std(ddof=1) if rank_ic.std(ddof=1) != 0 else np.nan,
+            rank_ic.mean() / rank_ic.std(ddof=1) * np.sqrt(rank_ic.notna().sum() - 1)
+            if rank_ic.std(ddof=1) != 0 else np.nan,
+            ((rank_ic > 0).sum() / rank_ic.count()) if rank_ic.count() > 0 else np.nan,
+            ((rank_ic < 0).sum() / rank_ic.count()) if rank_ic.count() > 0 else np.nan,
+        ], index=[
+            'rankIC均值', 'rankIC标准差', 'rankICIR',
+            'rankIC_T值', 'rankIC为正比例', 'rankIC为负比例',
+        ])
+
+        return {
+            'ic': ic,
+            'rank_ic': rank_ic,
+            'ic_result': ic_result,
+            'rank_ic_result': rank_ic_result,
+            'factor_rank_autocorr': factor_rank_autocorr,
+        }

QuantNodes/research/factor_test/nodes/load_data_node.py

@@ -0,0 +1,100 @@
+# coding: utf-8
+"""Node 1: 加载数据 / Load Data Node"""
+
+import logging
+from typing import Dict
+
+import pandas as pd
+
+from QuantNodes.research.factor_test.nodes._base import PydanticConfigNode
+from QuantNodes.research.factor_test.utils.data_loader import DataLoader
+from QuantNodes.research.factor_test.utils.safe_load import (
+    safe_load_factor,
+    safe_load_h5,
+    try_load_panels,
+)
+from QuantNodes.research.factor_test.nodes.configs import LoadDataNodeConfig
+
+logger = logging.getLogger(__name__)
+
+
+class LoadDataNode(PydanticConfigNode):
+    """加载因子数据、价格、行业、市值等
+
+    输入: config (LoadDataNodeConfig: data_path + load_keys + factor)
+    输出: Dict[str, pd.DataFrame]
+    """
+
+    ConfigSchema = LoadDataNodeConfig
+    _ALIASES = {
+        "_data_path": "data_path",
+        "_load_keys": "load_keys",
+        "_factor_config": "factor",
+    }
+
+    def _execute(self, input_data=None, **kwargs) -> Dict[str, pd.DataFrame]:
+        # P-2: 空字符串校验 (Pydantic Field(...) 不挡空串, 需显式检查)
+        if not self._data_path:
+            raise ValueError(
+                "data_path required (P-2: 启动报错, 防止 None 数据目录导致下游谜之失败)"
+            )
+
+        loader = DataLoader(self._data_path)
+        result = {}
+
+        # 加载因子
+        if self._factor_config:
+            factor = safe_load_factor(
+                loader, self._factor_config.factor_dir, self._factor_config.name
+            )
+            if factor is None:
+                raise ValueError(
+                    f"因子加载失败: dir={self._factor_config.factor_dir}, "
+                    f"name={self._factor_config.name}"
+                )
+            # 检查是否有索引, 没有则添加
+            if hasattr(factor, 'columns') and factor.columns.dtype == 'int64':
+                if loader.valid_shape(factor):
+                    factor = loader.add_index(factor)
+                else:
+                    raise ValueError(
+                        f"因子 {self._factor_config.name} shape 不一致: {factor.shape}"
+                    )
+            else:
+                stklist, trade_dt = loader.get_stock_axis()
+                factor = factor.reindex(index=trade_dt.iloc[:, 0], columns=stklist.iloc[:, 0])
+            result['factor'] = factor
+
+        # 加载价格 (price 几乎所有下游节点都需要, 强制加载)
+        price = safe_load_h5(loader, 'stk_daily.h5', 'cp')
+        if price is not None:
+            result['price'] = price
+        else:
+            logger.warning("LoadDataNode: 未找到 price 数据 (stk_daily.h5/cp)")
+
+        # 加载其他数据
+        for key in self._load_keys:
+            if key in ('stklist', 'trade_dt'):
+                continue  # 已通过 get_axis 处理
+            if key in result:
+                continue  # 已加载
+            data = try_load_panels(loader, key)
+            if data is not None:
+                result[key] = data
+            else:
+                logger.warning("LoadDataNode: 跳过 %s (stk_daily.h5/index_daily.h5 都不存在)", key)
+
+        # 加载指数收盘价 (用于对冲基准)
+        index_cp = safe_load_h5(loader, 'index_daily.h5', 'index_cp', axis_type='index')
+        if index_cp is not None:
+            result['index_cp'] = index_cp
+        else:
+            logger.debug("LoadDataNode: 未找到 index_cp 数据 (index_daily.h5/index_cp)")
+
+        # 保存 loader 和轴数据供下游使用
+        result['_loader'] = loader
+        stklist, trade_dt = loader.get_stock_axis()
+        result['stklist'] = stklist
+        result['trade_dt'] = trade_dt
+
+        return result

QuantNodes/research/factor_test/nodes/long_short_node.py

@@ -0,0 +1,93 @@
+# coding: utf-8
+"""Node 9: 多空组合 / Long-Short Node
+
+Migrated from factor_performance.py:562-617 cal_longshort_ret()
+"""
+
+
+import pandas as pd
+
+from QuantNodes.research.factor_test.nodes._base import PydanticConfigNode
+from QuantNodes.research.factor_test.nodes.configs import LongShortNodeConfig
+from QuantNodes.research.factor_test.utils.labels import L_S_COLS, NET_COLS
+from QuantNodes.research.factor_test.utils.performance_metrics import evaluation
+
+
+class LongShortNode(PydanticConfigNode):
+    """多空组合构建 + 净值 + 评价
+
+    输入: GroupAnalyzerNode 的输出
+    输出: {net, eva_total, eva_yearly, period_ret}
+    """
+
+    ConfigSchema = LongShortNodeConfig
+    _ALIASES = {"_factor_direction": "factor_direction"}
+
+    def _execute(self, input_data=None, **kwargs) -> dict:
+        context = kwargs.get('context', {})
+        group_result = context.get('GroupAnalyzer')
+        if group_result is None:
+            raise ValueError("分组分析数据缺失")
+
+        return self._calc_longshort(group_result, self._factor_direction)
+
+    def _calc_longshort(self, group_result, factor_ori):
+        """计算多空净值"""
+        n_groups = group_result['n_groups']
+        adj_dates = group_result['adjust_dates']
+
+        if factor_ori == 1:
+            long_n = n_groups
+            short_n = 1
+        else:
+            long_n = 1
+            short_n = n_groups
+
+        # 各期收益
+        long_ret = group_result['group_ret'][long_n]
+        short_ret = group_result['group_ret'][short_n]
+        longshort_ret = long_ret - short_ret
+
+        # 净值
+        daily_net_long = group_result['daily_net_simp'][long_n]
+        daily_net_short = group_result['daily_net_simp'][short_n]
+        daily_exc_long = group_result['daily_excnet_simp'][long_n]
+        daily_exc_short = group_result['daily_excnet_simp'][short_n]
+
+        # 多空净值 (单利)
+        daily_net_longshort = daily_net_long - daily_net_short + 1
+
+        # 评价
+        eva_longshort = evaluation(daily_net_longshort, adj_dates)
+
+        # 合并结果
+        eva_l_s_ls = pd.concat([
+            group_result['group_eva_exc'][long_n],
+            group_result['group_eva_exc'][short_n],
+            eva_longshort.iloc[0, 1:],
+        ], axis=1)
+        eva_l_s_ls.columns = L_S_COLS
+
+        period_ret = pd.concat([long_ret, short_ret, longshort_ret], axis=1)
+        period_ret.columns = L_S_COLS
+
+        net = pd.concat([
+            daily_net_long, daily_net_short,
+            daily_exc_long, daily_exc_short,
+            daily_net_longshort,
+        ], axis=1)
+        net.columns = NET_COLS
+
+        eva_yearly = {
+            '多头超额': group_result['group_eva_exc_yearly'].get(long_n),
+            '空头超额': group_result['group_eva_exc_yearly'].get(short_n),
+            '多空': eva_longshort.iloc[1:] if len(eva_longshort) > 1 else pd.DataFrame(),
+        }
+
+        return {
+            'net': net,
+            'eva_total': eva_l_s_ls,
+            'eva_yearly': eva_yearly,
+            'period_ret': period_ret,
+            'longshort_ret': longshort_ret,
+        }

QuantNodes/research/factor_test/nodes/neutralizers.py

@@ -0,0 +1,222 @@
+# coding=utf-8
+"""Neutralizer 抽象与具体实现 (Chain of Responsibility, Phase 2.1)。
+
+将原 factor_neutralize_node.py::_neutralize 中 3 个几乎相同的 if/elif
+分支 (industry only / risk only / both) 抽象为:
+
+  Neutralizer (ABC)
+    ├── IndustryNeutralizer   # 行业哑变量
+    └── RiskNeutralizer       # 风险因子列
+
+  build_neutralizer_chain(if_industry, if_risk, industry, risk_data) -> list
+  apply_neutralizer_chain(factor_i, chain) -> factor_neut
+
+每个 neutralizer 负责自己的"设计矩阵 X 组装", apply_neutralizer_chain
+负责统一的"按日期循环 + OLS + 写残差"流程。新增中性化类型
+(如 StyleNeutralizer) 只需新增一个 Neutralizer 子类, _execute
+无需修改。
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+import numpy as np
+import pandas as pd
+import statsmodels.api as sm
+
+
+# ============================================================================
+# Abstract base
+# ============================================================================
+
+class Neutralizer(ABC):
+    """中性化器抽象基类 (Chain of Responsibility 的一环).
+
+    子类实现 build_design_matrix() 返回指定日期的 X (设计矩阵).
+    is_active() 用于 build_neutralizer_chain 过滤无效环节.
+    """
+
+    name: str = ""
+
+    @abstractmethod
+    def build_design_matrix(
+        self,
+        date: pd.Timestamp,
+        factor_i: pd.DataFrame,
+    ) -> Optional[pd.DataFrame]:
+        """为指定日期组装设计矩阵 X (index=股票代码, columns=回归变量).
+
+        Returns:
+            X: 索引 = 股票代码, 列 = 哑变量/风险因子值
+            None: 跳过此日期 (无足够数据)
+        """
+        raise NotImplementedError
+
+    def is_active(self) -> bool:
+        """默认: neutralizer 始终 active. 子类可覆盖 (如缺数据时关闭)."""
+        return True
+
+
+# ============================================================================
+# Concrete: Industry
+# ============================================================================
+
+class IndustryNeutralizer(Neutralizer):
+    """行业中性化: 对 industry Series 做 one-hot dummy encoding.
+
+    行为与原 _neutralize branch 2 (lines 98-114) 一致:
+      - industry NaN 替换为 0
+      - 每个日期生成 dummies
+      - 去掉全 0 列 (sum > 0 过滤)
+    """
+
+    name = "industry"
+
+    def __init__(self, industry: Optional[pd.Series]) -> None:
+        self.industry = (
+            industry.copy().replace(np.nan, 0) if industry is not None else None
+        )
+
+    def is_active(self) -> bool:
+        return self.industry is not None
+
+    def build_design_matrix(
+        self, date: pd.Timestamp, factor_i: pd.DataFrame,
+    ) -> Optional[pd.DataFrame]:
+        if self.industry is None or date not in self.industry.index:
+            return None
+        ind_j = self.industry.loc[date]
+        dum_ind = pd.get_dummies(ind_j)
+        # 与原代码一致: 去掉全 0 列
+        return dum_ind.loc[:, dum_ind.sum() > 0]
+
+
+# ============================================================================
+# Concrete: Risk
+# ============================================================================
+
+class RiskNeutralizer(Neutralizer):
+    """风险因子中性化: 把加载的 risk_data 横向 concat 为 X.
+
+    输出 X 形状: index=股票代码, columns=risk_factors (与 IndustryNeutralizer 一致).
+    这样 apply_neutralizer_chain 中的 pd.merge(..., left_index=True, right_index=True) 能正确合并.
+
+    注: 原 _neutralize branch 3 (lines 116-135) 用 pd.concat(..., axis=1) 组装 X,
+    得到 (n_risks, n_stocks) 形状 (index=range(n_risks), columns=stock_codes),
+    与后续 merge 不匹配, 是 latent bug. 本实现修正.
+    """
+
+    name = "risk"
+
+    def __init__(self, risk_data: list) -> None:
+        self.risk_data = risk_data
+
+    def is_active(self) -> bool:
+        return bool(self.risk_data)
+
+    def build_design_matrix(
+        self, date: pd.Timestamp, factor_i: pd.DataFrame,
+    ) -> Optional[pd.DataFrame]:
+        cols: List[pd.DataFrame] = []
+        for i, rf in enumerate(self.risk_data):
+            if date not in rf.index:
+                continue
+            # rf.loc[date] 是 Series, index=股票代码 (因为 rf.columns=股票代码)
+            # 转为 1 列 DataFrame (index=股票代码, column=rf_i)
+            col = rf.loc[date].to_frame(name=f"rf_{i}")
+            cols.append(col)
+        if not cols:
+            return None
+        # 横向 concat (axis=1) 沿股票代码 index 对齐
+        return pd.concat(cols, axis=1)
+
+
+# ============================================================================
+# Chain construction & execution
+# ============================================================================
+
+def build_neutralizer_chain(
+    if_industry: bool,
+    if_risk: bool,
+    industry: Optional[pd.Series],
+    risk_data: list,
+) -> List[Neutralizer]:
+    """根据配置构造 chain, 自动过滤 is_active() == False 的环节.
+
+    顺序固定: [Industry, Risk] (与原代码 if/elif 优先级一致).
+
+    Args:
+        if_industry: 是否启用行业中性化
+        if_risk: 是否启用风险因子中性化
+        industry: 行业 Series (None 时 IndustryNeutralizer 自动 inactive)
+        risk_data: 风险因子 list (空时 RiskNeutralizer 自动 inactive)
+
+    Returns:
+        List[Neutralizer]: 启用的 neutralizer 列表 (空表示无需中性化)
+    """
+    chain: List[Neutralizer] = []
+    if if_industry:
+        chain.append(IndustryNeutralizer(industry))
+    if if_risk:
+        chain.append(RiskNeutralizer(risk_data))
+    return [n for n in chain if n.is_active()]
+
+
+def apply_neutralizer_chain(
+    factor_i: pd.DataFrame, chain: List[Neutralizer],
+) -> pd.DataFrame:
+    """执行 chain: 每个 neutralizer 顺序回归, 取残差作为新因子值.
+
+    行为与原 _neutralize 三分支 (lines 74-135) 等价:
+      - 3 个分支的差异在 X 组装 (build_design_matrix 各自负责)
+      - 公共的"按日期循环 + merge + OLS + 写残差"在此统一
+
+    Args:
+        factor_i: 每日一行, index=日期, columns=股票代码
+        chain: build_neutralizer_chain 返回的列表
+
+    Returns:
+        factor_neut: 残差矩阵 (空 chain 时返回 factor_i.copy() 保留 nan 模式)
+    """
+    factor_neut = factor_i.copy() * np.nan
+    if not chain:
+        return factor_neut
+
+    for date_j in factor_i.index:
+        if factor_i.loc[date_j].notna().sum() == 0:
+            continue
+        # 收集所有 neutralizer 的 X
+        X_parts: List[pd.DataFrame] = []
+        for neutralizer in chain:
+            X_part = neutralizer.build_design_matrix(date_j, factor_i)
+            if X_part is not None:
+                X_parts.append(X_part)
+        if not X_parts:
+            continue
+        # 合并 X (与原 branch 1 一致: merge suffixes=('', '_rf'))
+        X = X_parts[0]
+        for xp in X_parts[1:]:
+            X = pd.merge(
+                X, xp, left_index=True, right_index=True, suffixes=("", "_rf"),
+            )
+        # y + X 对齐 + dropna
+        lm_data = pd.merge(
+            factor_i.loc[date_j].to_frame(), X,
+            left_index=True, right_index=True,
+            suffixes=("_y", "_x"),
+        ).dropna()
+        # OLS 需要 lm_data 长度 > 参数数 (含常数项)
+        if len(lm_data) > X.shape[1]:
+            # 转 float: IndustryNeutralizer 的 dummies 是 bool, sm.add_constant
+            # 在 bool 上报 "numpy boolean subtract" 错误. 转 float 修复此 bug
+            # (原 _neutralize branch 2 同样会失败, 是 latent bug)
+            X_values = lm_data.iloc[:, 1:].values.astype(float)
+            model = sm.OLS(
+                lm_data.iloc[:, 0].values,
+                sm.add_constant(X_values),
+            )
+            resid = model.fit().resid
+            factor_neut.loc[date_j, lm_data.index.values] = resid
+
+    return factor_neut