本文详解如何使用 Polars 的 join_asof 实现按 Symbol 分组、基于日期的“向后匹配最近事件”逻辑，即每个事件仅匹配一次，且 fr 中每行关联到 events 中 Earnings_Date ≤ 当前行 Date 的最大日期对应事件。
本文详解如何使用 polars 的 `join_asof` 实现按 symbol 分组、基于日期的“向后匹配最近事件”逻辑，即每个事件仅匹配一次，且 fr 中每行关联到 events 中 earnings_date ≤ 当前行 date 的最大日期对应事件。
在时间序列分析与金融数据处理中，常需将离散事件（如财报发布日）对齐到连续交易日数据上——要求：每个事件最多被匹配一次，且匹配目标为 fr 中首个 ≥ 事件日期的日期（即“next available date”）。Polars 提供了高效、原生支持的 join_asof 方法，但默认行为是“左表每行都匹配右表中 ≤ 其键的最大值”，这会导致同一事件被多次复用（如多个交易日都匹配到同一个财报日）。要实现“事件仅消耗一次”的语义，需结合 over 窗口和去重逻辑。
以下是完整、可运行的解决方案：
import polars as pl
# 构建示例数据
fr = pl.DataFrame({
'Symbol': ['A'] * 5,
'Date': ['2010-08-29', '2010-09-01', '2010-09-05', '2010-11-30', '2010-12-02']
}).with_columns(pl.col('Date').str.to_date('%Y-%m-%d')).with_row_index().set_sorted("Date")
events = pl.DataFrame({
'Symbol': ['A'] * 3,
'Earnings_Date': ['2010-06-01', '2010-09-01', '2010-12-01'],
'Event': [1, 4, 7]
}).with_columns(pl.col('Earnings_Date').str.to_date('%Y-%m-%d')).set_sorted("Earnings_Date")
# ✅ 步骤 1：标准 asof join（按 Symbol 分组，左键 Date，右键 Earnings_Date）
result = (
fr
.join_asof(
events,
left_on="Date",
right_on="Earnings_Date",
by="Symbol", # 关键：按 Symbol 分别执行 asof 匹配
)
)
# ✅ 步骤 2：限制每个事件仅匹配一次（去重逻辑）
# 原理：对每个 Symbol 窗口内，仅保留首次出现的 (Earnings_Date, Event) 组合，其余置空
final = result.with_columns(
pl.when(
pl.col("Earnings_Date").is_first_distinct() &
pl.col("Event").is_first_distinct()
)
.then(pl.col("Earnings_Date"))
.alias("Earnings_Date")
.over("Symbol"),
pl.when(
pl.col("Earnings_Date").is_first_distinct() &
pl.col("Event").is_first_distinct()
)
.then(pl.col("Event"))
.alias("Event")
.over("Symbol")
)
print(final)
输出结果如下（关键特征：事件 Event=4 仅在 Date=2010-09-01 处生效；后续日期不再重复匹配）：
shape: (5, 5) ┌───────┬────────┬────────────┬───────────────┬───────┐ │ index ┆ Symbol ┆ Date ┆ Earnings_Date ┆ Event │ │ --- ┆ --- ┆ --- ┆ --- ┆ --- │ │ u32 ┆ str ┆ date ┆ date ┆ i64 │ ╞═══════╪════════╪════════════╪═══════════════╪═══════╡ │ 0 ┆ A ┆ 2010-08-29 ┆ 2010-06-01 ┆ 1 │ │ 1 ┆ A ┆ 2010-09-01 ┆ 2010-09-01 ┆ 4 │ │ 2 ┆ A ┆ 2010-09-05 ┆ null ┆ null │ │ 3 ┆ A ┆ 2010-11-30 ┆ null ┆ null │ │ 4 ┆ A ┆ 2010-12-02 ┆ 2010-12-01 ┆ 7 │ └───────┴────────┴────────────┴───────────────┴───────┘
⚠️ 注意事项：
- join_asof 要求左右表对应列已排序（使用 .set_sorted() 显式声明，而非仅 .sort()），否则性能下降甚至结果错误；
- by="Symbol" 是实现分组匹配的核心，确保不同股票间事件不交叉干扰；
- is_first_distinct().over("Symbol") 是实现“事件单次消耗”的关键技巧：它在每个 Symbol 分区内标记首次出现的事件组合，后续重复匹配自动置为 null；
- 若需严格“前向填充至下一个可用日期”（即 Earnings_Date >= Date 而非
该方案兼具性能（底层 Rust 实现）、可读性与生产可靠性，适用于百万级时序数据的实时对齐任务。
