收益率

上游序列的逐期收益率。method = simple 给百分比变化；method = log 给对数收益。Edge-first 且可链。连到多个 Price Factor 时按标的 fan out 为 by_symbol。

怎么用

1. 连一个上游价格序列。
2. 选择 method = simple | log。
3. 输出 series 可喂动量 / z-score / 风险构件。

核心公式

simple:  r_t = P_t / P_{t-1} − 1
log:     r_t = ln(P_t / P_{t-1})
r_0 = None ;  当 P_{t-1} == 0 或 NaN 时 r_t = None

假设与适用性

假设：等间隔周期；log 收益要求价格 > 0；正序序列。

适用：任意资产类别 / 频率；≥ 2 个观测。

不适用：总回报 / 分红调整、货币换算。

已知局限

1. 首位为 None（无上一期）。
2. simple 与 log 不可互换 —— 需刻意选择。
3. 上一期价格为 0 → 该步为 None。
4. 区别于 growth_rate_series（倒序 + abs 分母、无 log）。

参考

Campbell, Lo & MacKinlay (1997), The Econometrics of Financial Markets, 第 1 章。

Golden 测试

tests/golden/fixtures/tier1/compute_returns/ —— 1e-12 绝对、独立 numpy 参照、2026-05-25 passing。

变更记录

• 1.0.0（2026-05-25）—— Draft → Active；补 golden；补齐必填字段。