codestr 0.2.0__tar.gz → 0.3.0__tar.gz

{codestr-0.2.0 → codestr-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codestr
-Version: 0.2.0
+Version: 0.3.0
 Summary: DSL → Polars Expr compile engine for quantitative factor mining
 Project-URL: Repository, https://github.com/huangbogeng/codestr
 Author: huangbogeng
@@ -115,6 +115,23 @@ cs = CodeStr(df,
 | **TS (时序)** | `over(partition_by=partition_by, order_by=order_by)` |
 | **CS (截面)** | `over(partition_by=order_by, order_by=partition_by)` |
 
+### 混合窗口
+
+`CodeStr.sql()` 会自动把 TS/CS 混合窗口拆成连续的 lazy projection：
+
+```python
+cs.sql(
+    "close * 2 as scaled",
+    "ts_mean(cs_moderate(scaled), 60) as factor",
+)
+```
+
+其语义等价于先生成 `cs_moderate(scaled)` 中间列，再沿资产时间轴
+计算 `ts_mean`。中间列不会出现在返回结果中。
+
+纯 `cs.compile()` 只能返回一个 `pl.Expr`，因此会明确拒绝需要多阶段
+执行的 TS/CS 混合窗口。TS→TS 和 CS→CS 同域嵌套不受影响。
+
 ## 自定义算子
 
 ```python
@@ -139,6 +156,13 @@ cs.sql("ts_ewm(close, 10) as ewm10")
 
 **时序算子** (`ts_udf`)：`ts_mean`, `ts_ema`, `ts_sum`, `ts_std`, `ts_var`, `ts_skew`, `ts_kurt`, `ts_max`, `ts_min`, `ts_mid`, `ts_delay`, `ts_delta`, `ts_mad` 等
 
+滚动统计与 `ts_ema` 支持关键字参数 `min_samples`。滚动统计省略该参数时沿用 Polars 默认值 `None`（需要完整窗口），`ts_ema` 则沿用 Polars 默认值 `1`：
+
+```python
+cs.sql("ts_mean(close, 20, min_samples=5) as ma20")
+cs.sql("ts_ema(close, 10, min_samples=3) as ema10")
+```
+
 ## 项目结构
 
 ```

{codestr-0.2.0 → codestr-0.3.0}/README.md

@@ -84,6 +84,23 @@ cs = CodeStr(df,
 | **TS (时序)** | `over(partition_by=partition_by, order_by=order_by)` |
 | **CS (截面)** | `over(partition_by=order_by, order_by=partition_by)` |
 
+### 混合窗口
+
+`CodeStr.sql()` 会自动把 TS/CS 混合窗口拆成连续的 lazy projection：
+
+```python
+cs.sql(
+    "close * 2 as scaled",
+    "ts_mean(cs_moderate(scaled), 60) as factor",
+)
+```
+
+其语义等价于先生成 `cs_moderate(scaled)` 中间列，再沿资产时间轴
+计算 `ts_mean`。中间列不会出现在返回结果中。
+
+纯 `cs.compile()` 只能返回一个 `pl.Expr`，因此会明确拒绝需要多阶段
+执行的 TS/CS 混合窗口。TS→TS 和 CS→CS 同域嵌套不受影响。
+
 ## 自定义算子
 
 ```python
@@ -108,6 +125,13 @@ cs.sql("ts_ewm(close, 10) as ewm10")
 
 **时序算子** (`ts_udf`)：`ts_mean`, `ts_ema`, `ts_sum`, `ts_std`, `ts_var`, `ts_skew`, `ts_kurt`, `ts_max`, `ts_min`, `ts_mid`, `ts_delay`, `ts_delta`, `ts_mad` 等
 
+滚动统计与 `ts_ema` 支持关键字参数 `min_samples`。滚动统计省略该参数时沿用 Polars 默认值 `None`（需要完整窗口），`ts_ema` 则沿用 Polars 默认值 `1`：
+
+```python
+cs.sql("ts_mean(close, 20, min_samples=5) as ma20")
+cs.sql("ts_ema(close, 10, min_samples=3) as ema10")
+```
+
 ## 项目结构
 
 ```

{codestr-0.2.0 → codestr-0.3.0}/docs/operators.md

@@ -274,33 +274,35 @@ cs.sql("cs_midby(factor, sector, cap_group) as group_median")
 
 > 编译器自动注入窗口配置：`over(partition_by=asset_cols, order_by=datetime_cols)`
 
-滚动、滞后与差分算子的通用签名为 `(expr, windows)`，其中 `windows` 是整数，表示回溯窗口大小。`ts_ema` 的签名为 `(expr, span)`，`span` 必须是正整数。
+滚动统计的通用签名为 `(expr, windows, *, min_samples=None)`，其中 `windows` 是整数，表示回溯窗口大小；`min_samples` 是仅限关键字的正整数参数，省略时沿用 Polars 默认值 `None`（需要完整窗口）。`ts_ema` 的签名为 `(expr, span, *, min_samples=1)`，`span` 和 `min_samples` 都必须是正整数。滞后与差分算子仍使用 `(expr, windows)`，不接收 `min_samples`。
 
 ### 滚动统计
 
 | 算子 | 说明 | 底层实现 |
 |------|------|------|
-| `ts_mean` | 滚动均值 | `rolling_mean(windows)` |
-| `ts_ema` | 递归指数移动平均 | `ewm_mean(span=span, adjust=False, min_samples=1)` |
-| `ts_sum` | 滚动求和 | `rolling_sum(windows)` |
-| `ts_std` | 滚动标准差 | `rolling_std(windows)` |
-| `ts_var` | 滚动方差 | `rolling_var(windows)` |
-| `ts_skew` | 滚动偏度 | `rolling_skew(windows)` |
-| `ts_kurt` | 滚动峰度 | `rolling_kurtosis(windows)` |
-| `ts_max` | 滚动最大值 | `rolling_max(windows)` |
-| `ts_min` | 滚动最小值 | `rolling_min(windows)` |
-| `ts_mid` | 滚动中位数 | `rolling_median(windows)` |
-| `ts_mad` | 滚动 MAD | `median(|x - rolling_median(x)|) × 1.4826` |
-
-> `ts_mad` 乘以常数 1.4826 使其在正态分布下与标准差一致（一致性缩放因子）。
+| `ts_mean` | 滚动均值 | `rolling_mean(windows, min_samples=min_samples)` |
+| `ts_ema` | 递归指数移动平均 | `ewm_mean(span=span, adjust=False, min_samples=min_samples)` |
+| `ts_sum` | 滚动求和 | `rolling_sum(windows, min_samples=min_samples)` |
+| `ts_std` | 滚动标准差 | `rolling_std(windows, min_samples=min_samples)` |
+| `ts_var` | 滚动方差 | `rolling_var(windows, min_samples=min_samples)` |
+| `ts_skew` | 滚动偏度 | `rolling_skew(windows, min_samples=min_samples)` |
+| `ts_kurt` | 滚动峰度 | `rolling_kurtosis(windows, min_samples=min_samples)` |
+| `ts_max` | 滚动最大值 | `rolling_max(windows, min_samples=min_samples)` |
+| `ts_min` | 滚动最小值 | `rolling_min(windows, min_samples=min_samples)` |
+| `ts_mid` | 滚动中位数 | `rolling_median(windows, min_samples=min_samples)` |
+| `ts_mad` | 滚动 MAD | 内外两层 `rolling_median` 使用相同的 `min_samples` |
+
+> `ts_mad` 计算 `median(|x - rolling_median(x)|) × 1.4826`。常数 1.4826 使其在正态分布下与标准差一致，内外两层滚动中位数共享同一个 `min_samples`。
 
 示例：
 ```python
 cs.sql("ts_mean(close, 5) as ma5")
+cs.sql("ts_mean(close, 20, min_samples=5) as ma20_partial")
 cs.sql("ts_ema(close, 10) as ema10")
+cs.sql("ts_ema(close, 10, min_samples=3) as ema10_warmup")
 cs.sql("ts_std(close, 20) as vol20")
 cs.sql("ts_max(high, 20) as hh20")
-cs.sql("ts_mad(close, 20) as mad20")
+cs.sql("ts_mad(close, 20, min_samples=5) as mad20")
 ```
 
 ### 滞后与差分
@@ -373,6 +375,25 @@ cs = CodeStr(df,
 
 CS 与 TS 的 `partition_by` / `order_by` **刚好交换**，分别实现"按时间分组，沿实体统计"（CS）和"按实体分组，沿时间统计"（TS）。
 
+### 混合窗口规划
+
+TS 与 CS 使用不同分组轴，不能安全地嵌套成一个 Polars window
+expression。`CodeStr.sql()` 会检测窗口祖先链上的域变化，并生成多个
+连续 `with_columns` 阶段：
+
+```text
+ts_mean(cs_moderate(x), 60)
+
+stage 1: internal = cs_moderate(x)
+stage 2: result = ts_mean(internal, 60)
+```
+
+该过程保持 lazy，不会在阶段间调用 `collect()`。同一次 `sql()` 中，
+后续表达式也可以引用前一条表达式创建的别名。
+
+`CodeStr.compile()` 仍返回单个 `pl.Expr`，对混合窗口抛出
+`CompileError`。同域嵌套和并列的 TS/CS 表达式继续正常编译。
+
 ---
 
 ## 自定义算子