feat(factors): 添加 cs_mean 函数并增强 max_/min_ 单参数支持

- 新增 cs_mean 截面均值函数,支持 GTJA Alpha127 等因子转换
- max_/min_ 支持单参数调用,默认使用 252 天(约 1 年)滚动窗口
This commit is contained in:
2026-03-15 18:00:48 +08:00
parent c6ebab0e58
commit f943cc98d0
21 changed files with 1204 additions and 3980 deletions

View File

@@ -418,6 +418,26 @@ def cs_demean(x: Union[Node, str]) -> FunctionNode:
return FunctionNode("cs_demean", x)
def cs_mean(x: Union[Node, str]) -> FunctionNode:
"""截面均值。
计算因子在横截面上的平均值。
Args:
x: 输入因子表达式或字段名字符串
Returns:
FunctionNode: 函数调用节点
Example:
>>> from src.factors.api import close, cs_mean
>>> expr = cs_mean((close - 100) ** 2)
>>> print(expr)
cs_mean(((close - 100) ** 2))
"""
return FunctionNode("cs_mean", x)
# ==================== 数学函数 ====================
@@ -507,41 +527,53 @@ def abs(x: Union[Node, str]) -> FunctionNode:
return FunctionNode("abs", x)
def max_(x: Union[Node, str], y: Union[Node, str, int, float]) -> FunctionNode:
"""逐元素最大值。
def max_(
x: Union[Node, str], y: Union[Node, str, int, float, None] = None
) -> FunctionNode:
"""最大值。
智能分发逻辑:
- 单参数:调用 ts_max(x, 252) 计算滚动窗口最大值(默认 252 天≈1年
- 如果 y 是正整数 (y > 0),调用 ts_max(x, y) 滚动窗口最大值
- 否则,调用逐元素 max(x, y)
注意:避免 MAX(CLOSE - DELAY(CLOSE, 1), 0) 这类场景被错误路由到 ts_max
Args:
x: 第一个因子表达式或字段名字符串
y: 第二个因子表达式、字段名字符串或正整数(窗口大小)
x: 第一个因子表达式或字段名字符串,或单参数时的输入序列
y: 可选,第二个因子表达式、字段名字符串或正整数(窗口大小)
Returns:
FunctionNode: 函数调用节点
"""
if y is None:
# 单参数:默认使用 252 天(约 1 年交易日)窗口
return ts_max(x, 252)
if isinstance(y, int) and y > 0:
return ts_max(x, y)
return FunctionNode("max", x, _ensure_node(y))
def min_(x: Union[Node, str], y: Union[Node, str, int, float]) -> FunctionNode:
"""逐元素最小值。
def min_(
x: Union[Node, str], y: Union[Node, str, int, float, None] = None
) -> FunctionNode:
"""最小值。
智能分发逻辑:
- 单参数:调用 ts_min(x, 252) 计算滚动窗口最小值(默认 252 天≈1年
- 如果 y 是正整数 (y > 0),调用 ts_min(x, y) 滚动窗口最小值
- 否则,调用逐元素 min(x, y)
Args:
x: 第一个因子表达式或字段名字符串
y: 第二个因子表达式、字段名字符串或正整数(窗口大小)
x: 第一个因子表达式或字段名字符串,或单参数时的输入序列
y: 可选,第二个因子表达式、字段名字符串或正整数(窗口大小)
Returns:
FunctionNode: 函数调用节点
"""
if y is None:
# 单参数:默认使用 252 天(约 1 年交易日)窗口
return ts_min(x, 252)
if isinstance(y, int) and y > 0:
return ts_min(x, y)
return FunctionNode("min", x, _ensure_node(y))