return-calculations

收益率计算

核心概念

简单收益率（持有期收益率）

$$R = \frac{V_{end} - V_{begin} + D}{V_{begin}}$$

其中，D = 期间收到的分配（股息、利息）。如果 V_end 已计入再投资的分配，则不要再次加上 D。

均值和对数收益率约定

• 算术平均值 R_a = (1/n) * sum(R_i) — 对预期单期收益率的无偏估计（用于前瞻性输入，例如均值—方差优化）。始终 >= 几何平均值；会高估实际复合增长。
• 几何平均值 R_g = [prod(1 + R_i)]^(1/n) - 1 — 衡量实际多期复合增长的正确指标。低于算术平均值的差距约为 sigma^2 / 2（波动率拖累）。
• 对数收益率 r = ln(V_end / V_begin) — 具有时间可加性（r_total = r_1 + ... + r_n），因此适合统计建模和多期汇总。使用 R_simple = e^r - 1 和 r = ln(1 + R_simple) 进行转换。对数收益率可沿时间相加，但不能跨资产相加。

CAGR（复合年增长率）

$$CAGR = \left(\frac{V_{end}}{V_{begin}}\right)^{1/n} - 1$$

其中，n 以年为单位。表示两个估值之间、没有中间现金流时的年化几何增长率。

时间加权收益率（TWR）

将每次外部现金流之间计算的子期间收益率链式连接，从而消除现金流时机的影响。TWR 衡量投资经理的投资能力，不受投资者存入或提取资金决策的影响，也是 GIPS 规定的经理业绩标准。

$$1 + R_{TWR} = \prod_{i=1}^{n}(1 + R_i), \qquad R_i = \frac{V_{end,i}}{V_{begin,i} + CF_i} - 1$$

精确计算 TWR 需要在每个现金流发生日对投资组合进行估值。

修正 Dietz 收益率

如果无法在每个现金流发生日估值，修正 Dietz 方法会根据各笔外部现金流在期间内所占的天数权重，近似计算期间收益率：

$$R_{MD} = \frac{V_{end} - V_{begin} - CF_{net}}{V_{begin} + \sum_i CF_i \times w_i}, \qquad w_i = \frac{CD - D_i}{CD}$$

其中，CF_net = 外部现金流总额，CD = 期间的日历天数，D_i = 第 i 笔现金流发生的日期（因此 w_i 是该笔资金在期间内处于投资状态的时间占比）。这是一种资金加权的近似方法；将修正 Dietz 子期间收益率链式连接，可近似得到 TWR。当现金流相对于投资组合价值较大，或期间内市场波动较大时，准确性会下降；此时应在大额现金流发生日重新估值。

资金加权收益率（MWR / IRR）

使所有投资者现金流（投入、提取和期末价值）的净现值（NPV）为零的内部收益率：

$$0 = \sum_{t=0}^{T} \frac{CF_t}{(1 + r)^t}$$

MWR 对现金流的时机和金额较为敏感，因此反映了投资者的实际体验。通过数值方法（Newton-Raphson 或二分法）求解。

年化

$$R_{annual} = (1 + R_{period})^{periods_per_year} - 1$$

例如，季度收益率为 2%，年化后为 (1.02)^4 - 1 = 8.24%。

子期间收益率链式连接

$$(1 + R_{total}) = \prod_{i=1}^{n}(1 + R_i)$$

这是 TWR 和 CAGR 背后的基本恒等式。

示例

示例 1：根据 5 年投资计算 CAGR

已知： 一笔 $10,000 的投资在整整 5 年内增长至 $16,105.10，期间没有中间现金流。

计算： 复合年增长率（CAGR）。

解答：

CAGR = (V_end / V_begin)^(1/n) - 1
CAGR = (16,105.10 / 10,000)^(1/5) - 1
CAGR = (1.610510)^(0.2) - 1
CAGR = 1.10 - 1
CAGR = 0.10 = 10%

该投资的年复合增长率为 10%。

验证：$10,000 * (1.10)^5 = $10,000 * 1.61051 = $16,105.10

示例 2：现金流时机不佳时 TWR 与 MWR 的差异

已知： 一只基金的历史如下：

• 第 1 年年初：投资组合价值 = $100,000
• 第 1 年年末：投资组合价值 = $120,000（收益率 = +20%）
• 第 2 年年初：投资者存入 $100,000，投资组合价值增至 $220,000
• 第 2 年年末：投资组合价值 = $198,000（收益率 = -10%）

计算： TWR 和 MWR，并解释两者的差异。

解答：

时间加权收益率（TWR）：

Sub-period 1 return: R_1 = (120,000 - 100,000) / 100,000 = +20%
Sub-period 2 return: R_2 = (198,000 - 220,000) / 220,000 = -10%

TWR (cumulative) = (1 + 0.20) * (1 + (-0.10)) - 1
                  = 1.20 * 0.90 - 1
                  = 1.08 - 1
                  = +8.0%

TWR (annualized) = (1.08)^(1/2) - 1 = 3.92%

资金加权收益率（MWR / IRR）： 从投资者的角度看现金流：

• t=0：-$100,000（初始投资）
• t=1：-$100,000（追加存款）
• t=2：+$198,000（期末价值）

求解：-100,000 + (-100,000)/(1+r) + 198,000/(1+r)^2 = 0

这是关于 x = 1/(1+r) 的二次方程；正根得出 r = -0.66815%（可使用捆绑脚本或任何 IRR 求解器验证）。

r = -0.0066815 时的 NPV 检查：

-100,000 + (-100,000)/0.9933185 + 198,000/0.9933185^2
= -100,000 - 100,672.65 + 200,672.65
= 0.00  (exact)

MWR 约为年化 -0.67%。

解读： 年化 +3.92% 的 TWR 反映了管理者的能力：基金先上涨 20%，再下跌 10%，两年累计收益为 +8%。约为 -0.67% 的 MWR 反映了投资者的实际体验：由于第 2 年的大额存款，亏损年份中承担风险的资金更多，因此投资者按资金加权计算的结果略为负数。这种差异说明了为何评估管理者表现时优先使用 TWR，而 MWR 更能描述特定投资者实际实现的结果。

常见误区

• 混淆算术平均数和几何平均数：算术平均数总是大于或等于几何平均数（AM-GM 不等式）。用算术平均数预测复合增长会高估期末财富。
• 多期复利计算时使用算术平均数：描述多期复合增长时，始终使用几何平均数或 CAGR。
• 将极短周期的收益年化：将每周 2% 的收益年化会得到 (1.02)^52 - 1 = 180%，这会放大噪声并产生误导。年化对至少一年的周期最有意义。
• 在适合使用 TWR 时忽略现金流时机：MWR 会将管理者的能力与投资者的时机选择混为一谈。评估管理者时使用 TWR。
• 重复计算股息：如果期末价值 V_end 已包含再投资的股息，就不要在持有期收益公式中单独加上 D。
• 现金流较大时仍依赖 Modified Dietz：如果单笔现金流超过投资组合价值的大约 10%，应在现金流发生日重新估值，而不是按天加权。

运行脚本

scripts/return_calculations.py 提供了一个 Returns 类，其中包含上述每个公式的静态方法（持有期收益率、TWR、通过牛顿法计算的 MWR/IRR、可由这些方法轻松组合计算的 Modified Dietz、CAGR、年化、收益链接、算术／几何平均数、对数收益率转换）。

• 运行：uv run scripts/return_calculations.py（PEP 723 内联元数据会自动解析 numpy），或在已安装 numpy 的情况下运行 python3 scripts/return_calculations.py。
• 直接运行（或使用 --verify）会打印所有函数的示例，并且断言上述示例的计算结果（示例 1 的 CAGR = 10%，示例 2 的 TWR = 累计 +8.0% / 年化 3.92%，MWR = -0.6682%）；任何不匹配都会以非零状态码退出。
• --help 会列出可用函数和导入用法。
• 如需以编程方式使用，请导入而非运行：from return_calculations import Returns。

交叉引用

• time-value-of-money（核心插件）：NPV、IRR 和折现概念与 MWR 计算重叠；负责项目／贷款 IRR
• statistics-fundamentals（核心插件）：算术和几何平均数、收益分布分析