quantnodes 3.0.0__py3-none-any.whl

QuantNodes/factor_node/factor_db.py

@@ -0,0 +1,421 @@
+# coding=utf-8
+"""因子数据库
+
+⚠️ DEPRECATED (v3.0+): 此模块为历史占位, 所有抽象方法返回 0 或 None,
+无生产子类实现。
+
+详见 [`docs/33-data-access-architecture.md`](../docs/33-data-access-architecture.md) 第 5 节 "Deprecated L2"。
+
+替代方案:
+- SQL 因子存储 → 使用 L1 `database_node/BaseDBNode`
+- 因子元数据 / Wiki → 使用 L7 `research/wiki.py::WikiFactorProxy`
+- Table 4 polars 数据 → 使用 L6 `research/quant_alpha/evaluation/contracts.py::DataLoader`
+
+保留原因: 保持向后兼容 (factor_node/__init__.py re-export),
+下个大版本 (v4.0) 将删除此模块。
+
+包含 FactorDB（只读接口）和 WritableFactorDB（可写入接口）
+v2.0: 移除 traits 依赖
+"""
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+from QuantNodes.factor_node.quant_nodes_object import QuantNodesObject
+
+
+@dataclass
+class FactorDB(QuantNodesObject):
+    """因子库基类（只读接口）⚠️ DEPRECATED
+
+    数据库由若干张因子表组成。
+    不支持某个操作时，方法产生错误。
+    没有相关数据时，方法返回 None。
+
+    .. deprecated::
+        v3.0+. 所有方法返回 0/None, 无生产实现。
+        请使用 `database_node.BaseDBNode` (L1) 或
+        `research.wiki.WikiFactorProxy` (L7)。
+    """
+    name: str = "FactorDB"
+
+    def connect(self) -> int:
+        """连接到数据库
+
+        Returns:
+            0 表示成功
+        """
+        return 0
+
+    def disconnect(self) -> int:
+        """断开数据库连接
+
+        Returns:
+            0 表示成功
+        """
+        return 0
+
+    def isAvailable(self) -> bool:
+        """检查数据库是否可用
+
+        Returns:
+            True 表示可用
+        """
+        return True
+
+    @property
+    def TableNames(self) -> List[str]:
+        """获取所有表名
+
+        Returns:
+            表名列表
+        """
+        return []
+
+    def getTable(
+        self, table_name: str, args: Optional[Dict[str, Any]] = None
+    ) -> Optional["FactorTable"]:  # noqa: F821
+        """获取因子表对象
+
+        Args:
+            table_name: 表名
+            args: 额外参数
+
+        Returns:
+            FactorTable 对象，不存在返回 None
+        """
+        return None
+
+    def getID(self) -> List[str]:
+        """获取 ID 序列
+
+        Returns:
+            ID 列表
+        """
+        return []
+
+    def getDateTime(self) -> List[Any]:
+        """获取时间点序列
+
+        Returns:
+            时间点列表
+        """
+        return []
+
+
+class WritableFactorDB(FactorDB):
+    """可写入的因子数据库"""
+
+    def renameTable(self, old_table_name: str, new_table_name: str) -> int:
+        """重命名表
+
+        Args:
+            old_table_name: 旧表名
+            new_table_name: 新表名
+
+        Returns:
+            0 表示成功
+        """
+        return 0
+
+    def deleteTable(self, table_name: str) -> int:
+        """删除表
+
+        Args:
+            table_name: 表名
+
+        Returns:
+            0 表示成功
+        """
+        return 0
+
+    def setTableMetaData(
+        self,
+        table_name: str,
+        key: Optional[str] = None,
+        value: Optional[Any] = None,
+        meta_data: Optional[Dict[str, Any]] = None,
+    ) -> int:
+        """设置表的元数据
+
+        Args:
+            table_name: 表名
+            key: 元数据键
+            value: 元数据值
+            meta_data: 元数据字典
+
+        Returns:
+            0 表示成功
+        """
+        return 0
+
+    def renameFactor(
+        self,
+        table_name: str,
+        old_factor_name: str,
+        new_factor_name: str,
+    ) -> int:
+        """重命名因子
+
+        Args:
+            table_name: 表名
+            old_factor_name: 旧因子名
+            new_factor_name: 新因子名
+
+        Returns:
+            0 表示成功
+        """
+        return 0
+
+    def deleteFactor(self, table_name: str, factor_names: List[str]) -> int:
+        """删除因子
+
+        Args:
+            table_name: 表名
+            factor_names: 因子名列表
+
+        Returns:
+            0 表示成功
+        """
+        return 0
+
+    def setFactorMetaData(
+        self,
+        table_name: str,
+        ifactor_name: str,
+        key: Optional[str] = None,
+        value: Optional[Any] = None,
+        meta_data: Optional[Dict[str, Any]] = None,
+    ) -> int:
+        """设置因子的元数据
+
+        Args:
+            table_name: 表名
+            ifactor_name: 因子名称
+            key: 元数据键
+            value: 元数据值
+            meta_data: 元数据字典
+
+        Returns:
+            0 表示成功
+        """
+        return 0
+
+    def writeData(
+        self,
+        data: Any,
+        table_name: str,
+        if_exists: str = "update",
+        data_type: Optional[Dict[str, str]] = None,
+        **kwargs,
+    ) -> int:
+        """写入数据
+
+        Args:
+            data: 数据
+            table_name: 表名
+            if_exists: 如果存在 ("append", "update")
+            data_type: 数据类型字典 {因子名: 数据类型}
+            **kwargs: 其他参数
+
+        Returns:
+            0 表示成功
+        """
+        return 0
+
+    def offsetDateTime(
+        self,
+        lag: int,
+        table_name: str,
+        factor_names: List[str],
+        args: Optional[Dict[str, Any]] = None,
+    ) -> int:
+        """时间平移
+
+        沿着时间轴将所有数据纵向移动 lag 期
+        lag > 0 向前移动，lag < 0 向后移动
+        空出来的地方填 nan
+
+        Args:
+            lag: 平移期数
+            table_name: 表名
+            factor_names: 因子名列表
+            args: 额外参数
+
+        Returns:
+            0 表示成功
+        """
+        if lag == 0:
+            return 0
+        FT = self.getTable(table_name, args=args)
+        if FT is None:
+            return -1
+        Data = FT.readData(
+            factor_names=factor_names,
+            ids=self.getID(),
+            dts=self.getDateTime(),
+            args=args,
+        )
+        if lag > 0:
+            Data.iloc[:, lag:, :] = Data.iloc[:, :-lag, :].values
+            Data.iloc[:, :lag, :] = None
+        elif lag < 0:
+            Data.iloc[:, :lag, :] = Data.iloc[:, -lag:, :].values
+            Data.iloc[:, lag:, :] = None
+        DataType = FT.getFactorMetaData(
+            factor_names, key="DataType", args=args
+        ).to_dict()
+        self.deleteFactor(table_name, factor_names)
+        self.writeData(Data, table_name, data_type=DataType)
+        return 0
+
+    def _read_transform_write(
+        self,
+        table_name: str,
+        factor_names: List[str],
+        ids: List[str],
+        dts: List[Any],
+        transform_fn,
+        args: Optional[Dict[str, Any]] = None,
+        if_exists: str = "update",
+    ) -> int:
+        """通用读取-变换-写入模式
+
+        Args:
+            table_name: 表名
+            factor_names: 因子名列表
+            ids: ID 列表
+            dts: 时间点列表
+            transform_fn: 变换函数，接收 (Data, FT) 返回变换后的 Data
+            args: 额外参数
+            if_exists: 写入模式
+
+        Returns:
+            0 表示成功, -1 表示表不存在
+        """
+        FT = self.getTable(table_name, args=args)
+        if FT is None:
+            return -1
+        Data = FT.readData(
+            factor_names=factor_names, ids=ids, dts=dts, args=args
+        )
+        Data = transform_fn(Data, FT)
+        if Data is not None:
+            self.writeData(Data, table_name, if_exists=if_exists)
+        return 0
+
+    def changeData(
+        self,
+        table_name: str,
+        factor_names: List[str],
+        ids: List[str],
+        dts: List[Any],
+        args: Optional[Dict[str, Any]] = None,
+    ) -> int:
+        """数据变换
+
+        通过某种变换函数得到新的时间序列和ID序列
+
+        Args:
+            table_name: 表名
+            factor_names: 因子名列表
+            ids: ID 列表
+            dts: 时间点列表
+            args: 额外参数
+
+        Returns:
+            0 表示成功
+        """
+        def _transform(Data, FT):
+            DataType = FT.getFactorMetaData(
+                factor_names, key="DataType", args=args
+            ).to_dict()
+            self.deleteFactor(table_name, factor_names)
+            self.writeData(Data, table_name, data_type=DataType)
+            return None  # Already written
+        return self._read_transform_write(table_name, factor_names, ids, dts, _transform, args)
+
+    def fillNA(
+        self,
+        filled_value: Any,
+        table_name: str,
+        factor_names: List[str],
+        ids: List[str],
+        dts: List[Any],
+        args: Optional[Dict[str, Any]] = None,
+    ) -> int:
+        """填充缺失值
+
+        Args:
+            filled_value: 填充值
+            table_name: 表名
+            factor_names: 因子名列表
+            ids: ID 列表
+            dts: 时间点列表
+            args: 额外参数
+
+        Returns:
+            0 表示成功
+        """
+        def _transform(Data, FT):
+            Data.fillna(filled_value, inplace=True)
+            return Data
+        return self._read_transform_write(
+            table_name, factor_names, ids, dts, _transform, args
+        )
+
+    def replaceData(
+        self,
+        old_value: Any,
+        new_value: Any,
+        table_name: str,
+        factor_names: List[str],
+        ids: List[str],
+        dts: List[Any],
+        args: Optional[Dict[str, Any]] = None,
+    ) -> int:
+        """替换数据
+
+        Args:
+            old_value: 旧值
+            new_value: 新值
+            table_name: 表名
+            factor_names: 因子名列表
+            ids: ID 列表
+            dts: 时间点列表
+            args: 额外参数
+
+        Returns:
+            0 表示成功
+        """
+        def _transform(Data, FT):
+            return Data.where(Data != old_value, new_value)
+        return self._read_transform_write(
+            table_name, factor_names, ids, dts, _transform, args
+        )
+
+    def optimizeData(self, table_name: str, factor_names: List[str]) -> int:
+        """优化数据
+
+        Args:
+            table_name: 表名
+            factor_names: 因子名列表
+
+        Returns:
+            0 表示成功
+        """
+        return 0
+
+    def fixData(self, table_name: str, factor_names: List[str]) -> int:
+        """修复数据
+
+        依赖具体实现，不保证一定修复
+
+        Args:
+            table_name: 表名
+            factor_names: 因子名列表
+
+        Returns:
+            0 表示成功
+        """
+        return 0

QuantNodes/factor_node/factor_functions/__init__.py

@@ -0,0 +1,252 @@
+# coding=utf-8
+"""
+factor_functions - 因子函数实现层
+
+本模块包含所有算子的核心实现，按类别拆分为子模块：
+- time_ops: 时间序列算子
+- section_ops: 截面算子
+- math_ops: 数学算子
+- composite_ops: 组合算子
+- talib_ops: TA-Lib 技术指标
+
+注册表 API：
+- list_operators()
+- get_operator()
+- operator_info()
+- generate_documentation()
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+# 导入辅助函数和注册表
+from QuantNodes.factor_node.factor_functions._helpers import (
+    _OPERATOR_REGISTRY,
+    OperatorCategory,
+    register_operator,
+    _ensure_expr,
+)
+
+# 导入子模块（触发算子注册）
+from QuantNodes.factor_node.factor_functions import time_ops
+from QuantNodes.factor_node.factor_functions import section_ops
+from QuantNodes.factor_node.factor_functions import math_ops
+from QuantNodes.factor_node.factor_functions import composite_ops
+
+# 导入常用函数供直接使用
+from QuantNodes.factor_node.factor_functions.math_ops import (
+    ceil, floor, fix, applymap,
+    nanargmax, nanargmin, nanmedian, nanquantile, nancount, nanprod,
+    astype, replace, fetch,
+    abs as ff_abs, log as ff_log, sign, sqrt as ff_sqrt, square, clip,
+    isnull, notnull, fill_null, fill_zero, nan_to_null,
+    pow as ff_pow,
+    nanmax, nanmin, nanmean, nansum, nanstd, nanvar,
+    where, fillna,
+    add, sub, mul, div,
+    log1p, if_then_else, market_cap,
+    weighted_sum, combine,
+    book_to_market, earnings_to_market,
+)
+
+from QuantNodes.factor_node.factor_functions.time_ops import (
+    rolling_mean, rolling_std, rolling_max, rolling_min, rolling_sum,
+    rolling_median, rolling_var,
+    rolling_prod, rolling_skew, rolling_kurt, rolling_count,
+    rolling_argmax, rolling_argmin,
+    rolling_corr, rolling_cov, rolling_quantile, rolling_rank,
+    ewm_var, ewm_mean, ewm_std, ewm_corr, ewm_cov,
+    expanding_mean, expanding_std, expanding_sum,
+    expanding_max, expanding_min, expanding_median, expanding_count,
+    expanding_var, expanding_kurt, expanding_skew, expanding_quantile,
+    expanding_corr, expanding_cov,
+    ts_mean, ts_std, ts_corr, ts_cov, ts_rank, ts_delta, ts_lag,
+    ts_argmax, ts_argmin, ts_lead, ts_pct_change,
+    decay_linear, decay_exp, vwap, rolling_change_rate,
+    regress, zscored, ts_shift, diff, lag, delay, ref, shift,
+    delta, pct_change,
+    correlation, covariance,
+    ts_prod,
+)
+
+from QuantNodes.factor_node.factor_functions.section_ops import (
+    rank, zscore, winsorize, neutralize, neutralize_market, scale,
+    ic, rank_ic, group_norm, group_winsorize,
+    standardizeZScore, orthogonalize, mad,
+    fillNaNByFun, fillNaNByRegress,
+    cross_sectional_rank, cross_sectional_zscore,
+    cross_sectional_mean, cross_sectional_std, cross_sectional_sum,
+    standardizeRank, weightStandardize,
+)
+
+from QuantNodes.factor_node.factor_functions.composite_ops import (
+    aggregate, disaggregate,
+    aggr_sum, aggr_mean, aggr_max, aggr_min, aggr_std, aggr_var,
+    aggr_median, aggr_count, aggr_prod, aggr_quantile,
+    merge, chg_ids, blend, nav, rebase,
+)
+
+# 为测试兼容性导出 (shadow builtins)
+abs = ff_abs
+log = ff_log
+pow = ff_pow
+sqrt = ff_sqrt
+
+
+# ==============================================================================
+# 注册表查询 API
+# ==============================================================================
+
+def list_operators(category: Optional[str] = None, include_custom: bool = True) -> List[str]:
+    """列出所有算子名称
+
+    Args:
+        category: 可选，限定分类
+        include_custom: 是否包含自定义算子（默认 True）
+    """
+    if include_custom:
+        from QuantNodes.operators.registry import _CustomOperatorRegistry
+
+        custom = _CustomOperatorRegistry.list(category)
+        builtin = list(_OPERATOR_REGISTRY.get(category, {}).keys()) if category else [
+            name for cat in _OPERATOR_REGISTRY for name in _OPERATOR_REGISTRY[cat]
+        ]
+        seen = set()
+        result = []
+        for name in custom + builtin:
+            if name not in seen:
+                seen.add(name)
+                result.append(name)
+        return result
+
+    if category:
+        return list(_OPERATOR_REGISTRY.get(category, {}).keys())
+    return [name for cat in _OPERATOR_REGISTRY for name in _OPERATOR_REGISTRY[cat]]
+
+
+def get_operator(name: str, category: Optional[str] = None) -> Optional[Callable]:
+    """根据名称获取算子函数（级联查询：先自定义注册表，再内置注册表）"""
+    from QuantNodes.operators.registry import _CustomOperatorRegistry
+
+    func = _CustomOperatorRegistry.get(name, category)
+    if func is not None:
+        return func
+
+    if category:
+        op = _OPERATOR_REGISTRY.get(category, {}).get(name)
+        return op["func"] if op else None
+
+    for cat in _OPERATOR_REGISTRY:
+        if name in _OPERATOR_REGISTRY[cat]:
+            return _OPERATOR_REGISTRY[cat][name]["func"]
+    return None
+
+
+def operator_info(name: str, category: Optional[str] = None) -> Optional[Dict[str, Any]]:
+    """获取算子详细信息（级联查询：先自定义注册表，再内置注册表）"""
+    from QuantNodes.operators.registry import _CustomOperatorRegistry
+
+    info = _CustomOperatorRegistry.info(name)
+    if info is not None:
+        return info
+
+    if category:
+        op = _OPERATOR_REGISTRY.get(category, {}).get(name)
+        return op if op else None
+
+    for cat in _OPERATOR_REGISTRY:
+        if name in _OPERATOR_REGISTRY[cat]:
+            return _OPERATOR_REGISTRY[cat][name]
+    return None
+
+
+def generate_documentation(output_format: str = "markdown", category: Optional[str] = None) -> str:
+    """生成算子文档"""
+    if category:
+        ops = {category: _OPERATOR_REGISTRY.get(category, {})}
+    else:
+        ops = _OPERATOR_REGISTRY
+
+    if output_format == "json":
+        import json
+        serializable = {}
+        for cat, cat_ops in ops.items():
+            serializable[cat] = {}
+            for name, info in cat_ops.items():
+                serializable[cat][name] = {k: v for k, v in info.items() if k != "func"}
+        return json.dumps(serializable, indent=2, ensure_ascii=False)
+
+    lines = []
+    for cat, cat_ops in ops.items():
+        if not cat_ops:
+            continue
+        lines.append(f"\n## {cat.upper()}")
+        lines.append(f"共 {len(cat_ops)} 个算子\n")
+        for name, info in sorted(cat_ops.items()):
+            lines.append(f"### {name}")
+            if info.get("doc"):
+                lines.append(f"{info['doc']}")
+            lines.append(f"- 参数: {info.get('parameters', [])}")
+            lines.append(f"- 签名: {info.get('signature', '')}")
+            lines.append("")
+
+    return "\n".join(lines)
+
+
+__all__ = [
+    "list_operators",
+    "get_operator",
+    "operator_info",
+    "generate_documentation",
+    "register_operator",
+    "OperatorCategory",
+    "_OPERATOR_REGISTRY",
+    "_ensure_expr",
+    # math_ops
+    "ceil", "floor", "fix", "applymap",
+    "nanargmax", "nanargmin", "nanmedian", "nanquantile", "nancount", "nanprod",
+    "astype", "replace", "fetch",
+    "ff_abs", "ff_log", "sign", "ff_sqrt", "square", "clip",
+    "isnull", "notnull", "fill_null", "fill_zero", "nan_to_null",
+    "ff_pow",
+    "nanmax", "nanmin", "nanmean", "nansum", "nanstd", "nanvar",
+    "where", "fillna",
+    "add", "sub", "mul", "div",
+    "log1p", "if_then_else", "market_cap",
+    "weighted_sum", "combine", "book_to_market", "earnings_to_market",
+    # time_ops
+    "rolling_mean", "rolling_std", "rolling_max", "rolling_min", "rolling_sum",
+    "rolling_median", "rolling_var",
+    "rolling_prod", "rolling_skew", "rolling_kurt", "rolling_count",
+    "rolling_argmax", "rolling_argmin",
+    "rolling_corr", "rolling_cov", "rolling_quantile", "rolling_rank",
+    "ewm_var", "ewm_mean", "ewm_std", "ewm_corr", "ewm_cov",
+    "expanding_mean", "expanding_std", "expanding_sum",
+    "expanding_max", "expanding_min", "expanding_median", "expanding_count",
+    "expanding_var", "expanding_kurt", "expanding_skew", "expanding_quantile",
+    "expanding_corr", "expanding_cov",
+    "ts_mean", "ts_std", "ts_corr", "ts_cov", "ts_rank", "ts_delta", "ts_lag",
+    "ts_argmax", "ts_argmin", "ts_lead", "ts_pct_change",
+    "decay_linear", "decay_exp", "vwap", "rolling_change_rate",
+    "regress", "zscored", "ts_shift", "diff", "lag", "delay", "ref", "shift",
+    "delta", "pct_change", "correlation", "covariance", "ts_prod",
+    # section_ops
+    "rank", "zscore", "winsorize", "neutralize", "neutralize_market", "scale",
+    "ic", "rank_ic", "group_norm", "group_winsorize",
+    "standardizeZScore", "orthogonalize", "mad",
+    "fillNaNByFun", "fillNaNByRegress",
+    "cross_sectional_rank", "cross_sectional_zscore",
+    "cross_sectional_mean", "cross_sectional_std", "cross_sectional_sum",
+    "standardizeRank", "weightStandardize",
+    # composite_ops
+    "aggregate", "disaggregate",
+    "aggr_sum", "aggr_mean", "aggr_max", "aggr_min", "aggr_std", "aggr_var",
+    "aggr_median", "aggr_count", "aggr_prod", "aggr_quantile",
+    "merge", "chg_ids", "blend", "nav", "rebase",
+    # submodules for side-effect registration
+    "time_ops",
+    "section_ops",
+    "math_ops",
+    "composite_ops",
+]