quantnodes 3.0.0__py3-none-any.whl

QuantNodes/research/factor_test/utils/data_loader.py

@@ -0,0 +1,141 @@
+# coding: utf-8
+"""统一数据加载器 / Unified Data Loader
+
+Migrated from ~/Public/单因子回测/factor_utils.py (Factor class)
+Security: all exec()/eval() eliminated.
+
+Phase H3 (2026-06-20):
+  - HDF5 stores are cached per file path in self._h5_stores. Previously
+    every load_h5() opened + closed a new HDFStore; now stores stay open
+    for the loader lifetime. Read-mode HDFStore is thread-safe.
+  - Axis data (stock + index) cached after first get_axis() call.
+    add_index() calls get_axis() on every load (10+ per pipeline run),
+    previously 2 H5 opens per call.
+"""
+
+import pandas as pd
+
+from QuantNodes.research.factor_test.utils.file_loaders import _FILE_LOADERS
+
+
+class DataLoader:
+    """统一数据加载接口, 支持 H5/CSV/NPY/Parquet"""
+
+    def __init__(self, api_path: str = './testdata/test_h5_new/'):
+        self.api = api_path if api_path.endswith('/') else api_path + '/'
+        self._h5_stores: dict[str, pd.HDFStore] = {}
+        self._axis_cache: dict[str, tuple] = {}
+
+    def _get_store(self, path: str) -> pd.HDFStore:
+        """Get or lazily open a read-mode HDFStore for `path`."""
+        store = self._h5_stores.get(path)
+        if store is None:
+            store = pd.HDFStore(path, mode='r')
+            self._h5_stores[path] = store
+        return store
+
+    def close(self) -> None:
+        """Close all cached HDFStores. Call at end of pipeline run."""
+        for store in self._h5_stores.values():
+            try:
+                store.close()
+            except Exception:
+                pass
+        self._h5_stores.clear()
+        self._axis_cache.clear()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def load_h5(self, filename: str, key: str) -> pd.DataFrame:
+        """从 H5 文件加载数据 (H3: 复用 cached HDFStore)"""
+        path = self.api + filename
+        return _FILE_LOADERS['.h5'].load(
+            path, key=key, store_getter=self._get_store
+        )
+
+    def load_csv(self, path: str) -> pd.DataFrame:
+        """从 CSV 加载数据"""
+        return _FILE_LOADERS['.csv'].load(path)
+
+    def load_npy(self, path: str) -> pd.DataFrame:
+        """从 NPY 加载数据"""
+        return _FILE_LOADERS['.npy'].load(path)
+
+    def load_parquet(self, path: str) -> pd.DataFrame:
+        """从 Parquet 加载数据"""
+        return _FILE_LOADERS['.parquet'].load(path)
+
+    def load_custom(self, data_dir: tuple) -> pd.DataFrame:
+        """从自定义路径加载因子 (H5/CSV/NPY/Parquet)"""
+        dir_path, filename = data_dir
+        if filename.endswith('.csv'):
+            if dir_path.endswith('/') or dir_path.endswith('\\'):
+                return self.load_csv(dir_path + filename)
+            else:
+                # filename itself is a full path
+                return self.load_csv(filename)
+        elif filename.endswith('.npy'):
+            return self.load_npy(dir_path + filename)
+        elif filename.endswith('.parquet'):
+            if dir_path.endswith('/') or dir_path.endswith('\\'):
+                return self.load_parquet(dir_path + filename)
+            else:
+                # filename itself is a full path
+                return self.load_parquet(filename)
+        elif dir_path.endswith('.h5'):
+            store = self._get_store(dir_path)
+            return store.get(filename)
+        else:
+            raise ValueError(f"不支持的数据格式: {dir_path}, {filename}")
+
+    def load_factor(self, factor_dir: str, factor_name: str) -> pd.DataFrame:
+        """加载因子数据 (统一入口)"""
+        if factor_dir.endswith('.h5'):
+            return self.load_h5(factor_dir, factor_name)
+        ext = '.' + factor_dir.rsplit('.', 1)[-1] if '.' in factor_dir else ''
+        if ext in _FILE_LOADERS and ext != '.h5':
+            return _FILE_LOADERS[ext].load(factor_dir)
+        return self.load_custom((factor_dir, factor_name))
+
+    def get_stock_axis(self) -> tuple:
+        """获取股票列表和交易日序列"""
+        stklist = self.load_h5('stk_daily.h5', 'stklist')
+        trade_dt = self.load_h5('stk_daily.h5', 'trade_dt')
+        return stklist, trade_dt
+
+    def get_index_axis(self) -> tuple:
+        """获取指数列表和交易日序列"""
+        indexlist = self.load_h5('index_daily.h5', 'indexlist')
+        trade_dt = self.load_h5('index_daily.h5', 'trade_dt')
+        return indexlist, trade_dt
+
+    def get_axis(self, axis_type: str = 'stock') -> tuple:
+        """获取轴数据 (H3: cached after first call)"""
+        if axis_type in self._axis_cache:
+            return self._axis_cache[axis_type]
+        if axis_type == 'stock':
+            result = self.get_stock_axis()
+        elif axis_type == 'index':
+            result = self.get_index_axis()
+        else:
+            raise ValueError(f"不支持的 axis_type: {axis_type}")
+        self._axis_cache[axis_type] = result
+        return result
+
+    def add_index(self, factor: pd.DataFrame, axis_type: str = 'stock') -> pd.DataFrame:
+        """给因子添加标准索引 (行=交易日, 列=股票/指数)"""
+        factor = factor.copy()
+        assetlist, trade_dt = self.get_axis(axis_type)
+        factor.index = trade_dt.iloc[:, 0].values
+        factor.columns = assetlist.iloc[:, 0].values
+        return factor
+
+    def valid_shape(self, factor: pd.DataFrame, axis_type: str = 'stock') -> bool:
+        """检查因子 shape 是否为标准矩阵"""
+        assetlist, trade_dt = self.get_axis(axis_type)
+        expected = (len(trade_dt), len(assetlist))
+        return factor.shape == expected

QuantNodes/research/factor_test/utils/date_utils.py

@@ -0,0 +1,232 @@
+# coding: utf-8
+"""日期工具 / Date Utilities
+
+Migrated from ~/Public/单因子回测/date_utils.py
+"""
+
+import pandas as pd
+import numpy as np
+from datetime import datetime
+
+
+def valid_date(trade_dts) -> bool:
+    """验证日期格式, 必须为 yyyymmdd 数值型
+
+    v3.0.0 fix: use ``.iloc[0]`` instead of ``[0]`` for indexing the
+    ``dtypes`` Series. The previous code assumed integer column labels
+    (e.g. ``pd.DataFrame(dates, columns=[0])``), but after
+    ``resample_trade_date`` renames columns to strings the index
+    becomes string-keyed, and ``dtypes[0]`` raises ``KeyError: 0``.
+    """
+    if isinstance(trade_dts, pd.DataFrame):
+        num_lens = len(str(trade_dts.iloc[0, 0]))
+        data_type = trade_dts.dtypes.iloc[0]
+    elif isinstance(trade_dts, pd.Series):
+        num_lens = len(str(trade_dts.iloc[0]))
+        data_type = trade_dts.dtypes
+    else:
+        return False
+    return (num_lens == 8) and (data_type == 'int64')
+
+
+def datenum_to_datetime(trade_dt: pd.DataFrame) -> pd.DataFrame:
+    """将 yyyymmdd int 转换为 datetime"""
+    trade_dt = trade_dt.copy()
+    if isinstance(trade_dt, pd.Series):
+        trade_dt = trade_dt.to_frame()
+    # v3.0.0 fix: ``DataFrame.applymap`` was removed in pandas 3.0; use ``.map``.
+    return trade_dt.map(lambda x: datetime.strptime(str(int(x)), '%Y%m%d'))
+
+
+def datetime_to_datenum(trade_dt: pd.DataFrame) -> pd.DataFrame:
+    """将 datetime 转换为 yyyymmdd int"""
+    trade_dt = trade_dt.copy()
+    # v3.0.0 fix: ``DataFrame.applymap`` was removed in pandas 3.0; use ``.map``.
+    return trade_dt.map(lambda x: int(datetime.strftime(x, '%Y%m%d')))
+
+
+def chg_idx_to_datestr(data):
+    """将 Series/DataFrame 的 int index 转换为 'yyyy/mm/dd' 字符串"""
+    data = data.copy()
+    date_idx = data.index.tolist()
+    date_idx_str = list(map(
+        lambda x: str(x)[:4] + '/' + str(x)[4:6] + '/' + str(x)[6:], date_idx
+    ))
+    data.index = date_idx_str
+    return data
+
+
+def resample_trade_date(trade_dt: pd.DataFrame, rule=('M', 'end')) -> pd.DataFrame:
+    """将交易日重采样为周/月/季
+
+    Args:
+        trade_dt: yyyymmdd int DataFrame, 单列.
+        rule: ``(mode, position)`` 两元组.
+
+            - ``mode``: ``'W'`` (周) / ``'M'`` (月) / ``'Q'`` (季)
+            - ``position``: ``'end'`` 或 ``'begin'``
+
+              L1 (2026-06-21) 新增 alias::
+
+                  'beg' / 'start' / 'first' → 'begin'
+                  'last'                    → 'end'
+
+              用户不再因为写 ``'beg'`` 这类自然简写而踩 ``不支持的 position``
+              错误. 未在 alias 表内的值仍抛 ``ValueError``.
+
+    Returns:
+        DataFrame: 重采样后的 yyyymmdd int 日期序列.
+
+    Raises:
+        ValueError: 日期格式非法 / rule 不是 2 元 tuple / mode 不在 W/M/Q /
+            position 既不在 alias 也不是 begin/end.
+    """
+    trade_date = trade_dt.copy()
+    trade_date.columns = ['trade_dt']
+    if not valid_date(trade_date):
+        raise ValueError("日期格式有误, 请输入 yyyymmdd int 型")
+
+    trade_date = datenum_to_datetime(trade_date)
+
+    if not isinstance(rule, tuple) or len(rule) != 2:
+        raise ValueError("请输入正确的调仓模式 ('M', 'end')")
+
+    mode, position = rule
+
+    # L1 (2026-06-21): 友好 alias 表, 用户写 'beg' 等同 'begin'.
+    _POSITION_ALIASES = {
+        'beg': 'begin',
+        'start': 'begin',
+        'first': 'begin',
+        'last': 'end',
+    }
+    position = _POSITION_ALIASES.get(position, position)
+
+    if mode in ('W', 'M', 'Q'):
+        period_func = {
+            'W': lambda x: x.weekday(),
+            'M': lambda x: x.month,
+            'Q': lambda x: x.quarter,
+        }[mode]
+        trade_date['period'] = trade_date.iloc[:, 0].apply(period_func)
+
+        if position == 'end':
+            trade_date['diff'] = trade_date['period'].diff(-1)
+            trade_date = trade_date.loc[trade_date['diff'] != 0, 'trade_dt'].to_frame()
+        elif position == 'begin':
+            trade_date['diff'] = trade_date['period'].diff(1)
+            trade_date = trade_date.loc[trade_date['diff'] != 0, 'trade_dt'].to_frame()
+        else:
+            raise ValueError(f"不支持的 position: {position}")
+    else:
+        raise ValueError(f"不支持的 resample mode: {mode}")
+
+    return datetime_to_datenum(trade_date)
+
+
+def get_adjust_date(trade_dt: pd.DataFrame, beg_date: int, end_date: int,
+                    adj_mode=('M', 'end')) -> pd.DataFrame:
+    """根据起始日、截止日、调仓模式确定调仓日"""
+    trade_dt = trade_dt.copy()
+
+    if type(beg_date) is not type(end_date) or not isinstance(beg_date, int):
+        raise ValueError("起始日与截止日格式不一致或非 int 型")
+
+    if not isinstance(adj_mode, tuple) or len(adj_mode) != 2:
+        raise ValueError("请输入正确的调仓模式 ('M', 'end')")
+
+    if not valid_date(trade_dt):
+        raise ValueError("trade_dt 格式有误")
+
+    if isinstance(trade_dt, pd.Series):
+        trade_dt = trade_dt.to_frame()
+
+    # 调整起止时间到实际交易日
+    try:
+        beg_date_new = trade_dt[trade_dt >= beg_date].dropna().iloc[0, 0]
+        end_date_new = trade_dt[trade_dt <= end_date].dropna().iloc[-1, 0]
+    except Exception:
+        raise ValueError(
+            f"获取测试起止日期出错, 现有数据: {trade_dt.iloc[0, 0]} ~ {trade_dt.iloc[-1, 0]}"
+        )
+
+    mode = adj_mode[0]
+    if mode in ('M', 'W'):
+        adj_date = resample_trade_date(trade_dt, adj_mode)
+        adj_date = adj_date[(adj_date >= beg_date) & (adj_date <= end_date)].dropna()
+        adj_date = adj_date.astype(trade_dt.iloc[0].values)
+    elif mode == 'D':
+        beg_idx = np.where(trade_dt.iloc[:, 0] == beg_date_new)[0][0]
+        end_idx = np.where(trade_dt.iloc[:, 0] == end_date_new)[0][0]
+        adj_date = trade_dt.iloc[beg_idx:end_idx + 1:adj_mode[1]]
+    elif mode == 'custom':
+        adj_date = adj_mode[1]
+        if not valid_date(adj_date):
+            raise ValueError("自定义调仓日格式有误")
+    else:
+        raise ValueError(f"不支持的调仓模式: {mode}")
+
+    return adj_date
+
+
+def offset_date(date_input, trade_dt_all, n, mode='D', if_modify=False):
+    """日期偏移
+
+    H6: replaced ``arr[arr <= x][-1]`` (O(M) boolean mask per query) with
+    ``arr[idx-1]`` where ``idx = np.searchsorted(arr, x, side='right')``
+    (O(log M) per query). Cumulative gain is K * (M -> log M) where K is
+    the size of date_input and M is the size of trade_dt_all.
+
+    L2 (2026-06-21): 显式越界检查.
+
+        修复: 原 ``adj_date.iloc[adj_date_idx + n]`` 在负索引时**不会** raise
+        IndexError — pandas/numpy 负索引会 wrap-around 到末尾, 导致 n=-1
+        (回退 1 天) 错误返回最后一个调仓日. 现改为显式计算 final_idx, 越界
+        元素按 ``if_modify`` 决定:
+
+        - ``if_modify=False`` (默认): 显式 raise ``IndexError``, 错误信息
+          列出越界 idx.
+        - ``if_modify=True``: ``np.clip`` 到 [0, len(adj_date)-1] 边界.
+
+        行为变化: 之前 silent 错误 (返回末尾日期) → 现在明确报错. 任何依赖
+        wrap-around 的上游代码 (经 grep 确认无) 会受影响.
+    """
+    if isinstance(trade_dt_all, pd.DataFrame):
+        trade_dt_all = trade_dt_all.iloc[:, 0]
+
+    if mode == 'D':
+        adj_date = trade_dt_all
+        adj_values = np.asarray(trade_dt_all.values).ravel()
+    elif mode in ('W', 'M', 'Q'):
+        adj_date = resample_trade_date(trade_dt_all.to_frame(), (mode, 'end'))
+        # resample_trade_date returns a DataFrame; flatten to 1D for searchsorted.
+        adj_values = np.asarray(adj_date.iloc[:, 0].values).ravel()
+    else:
+        raise ValueError(f"不支持的偏移模式: {mode}")
+
+    date_input_arr = np.asarray(list(date_input))
+    # For each x, find largest idx where adj_values[idx] <= x (searchsorted).
+    insert_idx = np.searchsorted(adj_values, date_input_arr, side='right')
+    date_last_idx = np.clip(insert_idx - 1, 0, len(adj_values) - 1)
+    date_last = adj_values[date_last_idx]
+    # Use the same 1D representation for the lookup index.
+    if isinstance(adj_date, pd.DataFrame):
+        adj_index = pd.Index(adj_date.iloc[:, 0])
+    else:
+        adj_index = pd.Index(adj_date)
+    adj_date_idx = adj_index.get_indexer(date_last)
+
+    # L2 (2026-06-21): 显式越界检查 (修复 pandas 负索引 wrap-around silent bug).
+    final_idx = adj_date_idx + n
+    out_of_bounds = (final_idx < 0) | (final_idx >= len(adj_date))
+    if out_of_bounds.any():
+        if if_modify:
+            final_idx = np.clip(final_idx, 0, len(adj_date) - 1)
+        else:
+            raise IndexError(
+                f"offset_date 越界 (n={n}): "
+                f"final_idx={final_idx[out_of_bounds].tolist()} "
+                f"不在 [0, {len(adj_date) - 1}] 范围. "
+                f"设置 if_modify=True 可裁剪到边界."
+            )
+    return np.array(adj_date.iloc[final_idx])

QuantNodes/research/factor_test/utils/file_loaders.py

@@ -0,0 +1,150 @@
+# coding: utf-8
+"""文件格式 Adapter (Phase 3.3)
+
+将 ``DataLoader`` 按扩展名硬编码的读取逻辑抽成 Adapter 族 + registry,
+新增格式只需加一个 ``FileFormatLoader`` 子类并注册, 无需改 DataLoader。
+
+每个 adapter 暴露统一的 ``load(path, *, key=None, store_getter=None)`` 签名:
+  - 扁平文件 (csv/npy/parquet): 只用 ``path``, 忽略 key/store_getter
+  - H5: 用 ``store_getter(path)`` 取得 (可缓存的) HDFStore, 按 ``key``
+    查找 (与 DataLoader.load_h5 的 key 归一化 fallback 一致)
+
+读取行为与重构前的 ``DataLoader.load_*`` bitwise 等价。
+"""
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import Callable, Dict, Optional
+
+import numpy as np
+import pandas as pd
+
+from QuantNodes.core.data_source import DataSource
+
+
+class FileFormatLoader(DataSource):
+    """单一文件格式的读取适配器。
+
+    Attributes:
+        extensions: 该 adapter 负责的扩展名 (含点, 小写), 如 ``('.csv',)``。
+    """
+
+    extensions: tuple = ()
+
+    @abstractmethod
+    def load(
+        self,
+        path: str,
+        *,
+        key: Optional[str] = None,
+        store_getter: Optional[Callable[[str], pd.HDFStore]] = None,
+    ) -> pd.DataFrame:
+        """读取 ``path`` 处的数据为 DataFrame。
+
+        Args:
+            path: 文件路径 (H5 为文件路径, 其余为完整路径)。
+            key: H5 数据集 key (仅 H5 使用)。
+            store_getter: 返回可缓存 HDFStore 的回调 (仅 H5 使用),
+                用于复用 DataLoader 的 ``_h5_stores`` 缓存。
+        """
+        raise NotImplementedError
+
+    def close(self) -> None:
+        """adapter 自身无状态; H5Store 生命周期由 DataLoader 管理。"""
+        return None
+
+
+class CSVLoader(FileFormatLoader):
+    extensions = ('.csv',)
+
+    def load(self, path, *, key=None, store_getter=None):
+        return pd.read_csv(path, index_col=0)
+
+
+class NPYLoader(FileFormatLoader):
+    extensions = ('.npy',)
+
+    def load(self, path, *, key=None, store_getter=None):
+        return pd.DataFrame(np.load(path, allow_pickle=True))
+
+
+class ParquetLoader(FileFormatLoader):
+    extensions = ('.parquet',)
+
+    def load(self, path, *, key=None, store_getter=None):
+        return pd.read_parquet(path)
+
+
+class H5Loader(FileFormatLoader):
+    extensions = ('.h5',)
+
+    def load(self, path, *, key=None, store_getter=None):
+        if store_getter is None:
+            raise ValueError("H5Loader.load requires a store_getter callback")
+        store = store_getter(path)
+        # 标准化 key: HDFStore 自动加 / 前缀
+        norm_key = key if key.startswith('/') else '/' + key
+        if norm_key in store.keys():
+            return store.get(norm_key)
+        if key in store.keys():
+            return store.get(key)
+        raise KeyError(
+            f"Key '{key}' not found in {path}. Available: {store.keys()}"
+        )
+
+
+_FILE_LOADERS: Dict[str, FileFormatLoader] = {}
+
+
+def _register_default_loaders() -> None:
+    for cls in (H5Loader, CSVLoader, NPYLoader, ParquetLoader):
+        loader = cls()
+        for ext in loader.extensions:
+            _FILE_LOADERS[ext] = loader
+
+
+_register_default_loaders()
+
+
+def build_file_loader(ext: str) -> FileFormatLoader:
+    """按扩展名 (含点) 返回对应的 FileFormatLoader 实例。
+
+    Args:
+        ext: 文件扩展名, 含点, 如 ``'.csv'``。
+
+    Returns:
+        FileFormatLoader 实例。
+
+    Raises:
+        ValueError: 扩展名未注册。
+    """
+    loader = _FILE_LOADERS.get(ext)
+    if loader is None:
+        raise ValueError(
+            f"Unsupported file extension: {ext}. "
+            f"Available: {sorted(_FILE_LOADERS)}"
+        )
+    return loader
+
+
+def register_file_loader(loader: FileFormatLoader) -> None:
+    """注册一个新的文件格式 adapter (供扩展)。
+
+    Args:
+        loader: FileFormatLoader 实例, 其 ``extensions`` 决定负责的扩展名。
+
+    Raises:
+        ValueError: extensions 为空或某扩展名已注册。
+    """
+    if not loader.extensions:
+        raise ValueError("loader.extensions must be non-empty")
+    for ext in loader.extensions:
+        if ext in _FILE_LOADERS:
+            raise ValueError(f"extension '{ext}' already registered")
+    for ext in loader.extensions:
+        _FILE_LOADERS[ext] = loader
+
+
+def available_extensions() -> list:
+    """返回已注册的扩展名列表 (排序)。"""
+    return sorted(_FILE_LOADERS)

QuantNodes/research/factor_test/utils/labels.py

@@ -0,0 +1,37 @@
+"""Phase J6 (2026-06-20): Chinese labels for long-short and group analysis output.
+
+Consolidates the hard-coded 中文 column labels used in long_short_node.py
+(group_result dict + DataFrame columns) and group_analyzer_node.py's
+yearly-eva dict keys.
+
+Reuse from tests via:
+    from QuantNodes.research.factor_test.utils.labels import (
+        LONG, SHORT, LONG_EXCESS, SHORT_EXCESS, LONGSHORT,
+        L_S_COLS, NET_COLS,
+    )
+"""
+from __future__ import annotations
+
+
+# Column labels for group results
+LONG: str = "多头"
+SHORT: str = "空头"
+LONG_EXCESS: str = "多头超额"
+SHORT_EXCESS: str = "空头超额"
+LONGSHORT: str = "多空"
+
+# Standard 3-column order for L/S evaluation tables
+L_S_COLS: list[str] = [LONG_EXCESS, SHORT_EXCESS, LONGSHORT]
+
+# Standard 5-column order for the net value table
+NET_COLS: list[str] = [LONG, SHORT, LONG_EXCESS, SHORT_EXCESS, LONGSHORT]
+
+__all__ = [
+    "LONG",
+    "SHORT",
+    "LONG_EXCESS",
+    "SHORT_EXCESS",
+    "LONGSHORT",
+    "L_S_COLS",
+    "NET_COLS",
+]

QuantNodes/research/factor_test/utils/metrics_extractor.py

@@ -0,0 +1,55 @@
+# coding: utf-8
+"""指标提取工具 / Metrics Extractor.
+
+从单次回测的 ``ctx`` (12 节点输出 dict) 提取关键评估指标,
+供 ``TrajectoryEntry.metrics`` / Evolution rank 使用.
+
+Phase R2 (2026-06-19): 从 pipeline_runner.py 末尾抽出, 单一职责.
+"""
+
+from __future__ import annotations
+
+
+def extract_metrics_from_ctx(ctx: dict) -> dict:
+    """从单次回测 ctx 提取关键指标 (IC, Rank IC, ICIR, Sharpe, ARR, MDD, Calmar).
+
+    Args:
+        ctx: ``PipelineRunner.run()`` 的返回值, 通常含
+            ``ICAnalyzer`` / ``LongShort`` 两个键.
+
+    Returns:
+        ``{ic_mean, rank_ic_mean, ic_ir, sharpe, arr, mdd, calmar}`` 的子集
+        (缺失字段不会出现在结果里).
+    """
+    metrics: dict = {}
+    ic = ctx.get("ICAnalyzer") or {}
+    ic_result = ic.get("ic_result") if isinstance(ic, dict) else None
+    if isinstance(ic_result, dict):
+        for src_key, dst_key in (
+            ("IC均值", "ic_mean"),
+            ("Rank IC均值", "rank_ic_mean"),
+            ("ICIR", "ic_ir"),
+        ):
+            if src_key in ic_result and ic_result[src_key] is not None:
+                try:
+                    metrics[dst_key] = float(ic_result[src_key])
+                except (TypeError, ValueError):
+                    pass
+    ls = ctx.get("LongShort") or {}
+    if isinstance(ls, dict):
+        for src_key, dst_key in (
+            ("sharpe", "sharpe"),
+            ("annualized_return", "arr"),
+            ("max_drawdown", "mdd"),
+            ("calmar", "calmar"),
+        ):
+            if src_key in ls and ls[src_key] is not None:
+                try:
+                    metrics[dst_key] = float(ls[src_key])
+                except (TypeError, ValueError):
+                    pass
+    return metrics
+
+
+# 向后兼容别名 (老代码或测试可能 import 私有名)
+_extract_metrics_from_ctx = extract_metrics_from_ctx