bi-ltv-analysis

name	bi-ltv-analysis
description	评估单个用户或用户群体在生命周期内创造的收益。触发条件：当需要用户生命周期价值计算与分析时触发，如对话中涉及“LTV”、“LTV 分析”、“用户生命周期价值”、“人均收益测算”等等相近词语时调用。

bi-ltv-analysis

评估单个用户或用户群体在整个生命周期内创造的收入（或利润），典型用途。

执行步骤

Step 1：准备数据

根据分析任务需求与所给数据结构，明确 LTV 分析涉及的指标，即分析粒度（用户级 / 群体级）、收益口径（如购买、升级等行为产生的收入、利润等）以及生命周期（如时间窗口、某阶段流失率等），将取数结果保存为 CSV。

整理数据为 CSV 格式，采用“分组（用户/群体） × N天（生命周期与收益数据）”，数据应至少包括分析粒度对应的对象列、收益口径对应的收入数据列以及生命周期对应的数据列。

例如，对于用户级的 LTV 分析，分析数据示例如下，

用户ID,事件时间a,收入金额a,事件时间b,收入金额b
1,2025-04-25,26.0,2025-04-26,6.5
2,2025-04-25,6.5,NaN,NaN

对于群体级的 LTV 分析，数据示例如下，

群体类别,a阶段流失率,a阶段收入金额,b阶段流失率,b阶段收入金额
group_1,0.366,26.0,0.121,6.5
group_2,0.253,6.5,0.754,2.0

若上游步骤已产出可用汇总表则直接使用，否则按口径从明细聚合（按用户求和、按队列求和等）。

注意：若数据包含留存率、流失率等指标可以用于 LTV 分析，则统一使用流失率进行计算，若数据中仅包含留存率，则转化为流失率进行 LTV 计算和分析，一般情况，流失率=1-留存率。

Step 2：计算 LTV

LTV 计算公式一：

(LTV = ARPU \times 生命周期)

LTV 计算公式二：

(LTV = ARPU \times \frac{1}{流失率})

ARPU（Average Revenue Per User）：单位用户在指定统计范围内的平均收入。若 CSV 中收入列为阶段合计、且另有用户数列，则脚本按 (ARPU = 收入 / 用户数) 计算；若收入列已是人均口径，则无需 --users-col。

群体多阶段（含多列「阶段流失率 + 阶段收入金额」）：按阶段顺序，用存活率对收入加权求和：

[ LTV = \sum_{j} 收入_j \times \prod_{k<j}(1 - 流失率_k) ]

方式一：使用脚本

使用 <skill-dir>/scripts/ltv_calc.py 计算 LTV。结果写入 --output-file 指定的 CSV：第一列为输入中的分析对象列（--object-col），第二列为 LTV（默认列名 ltv）。

用户级（观测窗口内各阶段收入累计）：

python <skill-dir>/scripts/ltv_calc.py \
  --input-file "<输入 CSV 路径>" \
  --object-col "用户ID" \
  --revenue-cols "收入金额a" "收入金额b" \
  --output-file "<输出 CSV 路径>"

群体级（多阶段流失率 + 收入）：

python <skill-dir>/scripts/ltv_calc.py \
  --input-file "<输入 CSV 路径>" \
  --object-col "群体类别" \
  --revenue-cols "a阶段收入金额" "b阶段收入金额" \
  --churn-cols "a阶段流失率" "b阶段流失率" \
  --output-file "<输出 CSV 路径>"

公式一（单列收入 + 生命周期 T）：

python <skill-dir>/scripts/ltv_calc.py \
  --input-file "<输入 CSV 路径>" \
  --object-col "群体类别" \
  --revenue-col "a阶段收入金额" \
  --users-col "用户数" \
  --lifecycle 12 \
  --formula lifecycle \
  --output-file "<输出 CSV 路径>"

公式二（单列收入 + 单列流失率）：

python <skill-dir>/scripts/ltv_calc.py \
  --input-file "<输入 CSV 路径>" \
  --object-col "群体类别" \
  --revenue-col "a阶段收入金额" \
  --churn-col "a阶段流失率" \
  --formula churn \
  --output-file "<输出 CSV 路径>"

若数据列为留存率而非流失率，增加 --rate-is-retention（按 流失率 = 1 − 留存率 转换）。

参数说明：

参数	说明	默认值
--input-file	输入数据文件路径（CSV）	（必填）
--object-col	分析对象列名（用户 ID、群体类别等）	（必填）
--output-file	输出 CSV 路径（两列：分析对象、LTV）	（必填）
--ltv-col	输出中 LTV 列名	ltv
--formula	cumulative / lifecycle / churn / stage_weighted；省略时按其它参数自动推断	自动推断
--revenue-cols	多阶段收入列名（可多个）	—
--churn-cols	多阶段流失率列名，与 --revenue-cols 顺序一一对应	—
--revenue-col	单列收入（公式一、二）	—
--churn-col	单列流失率（公式二）	—
--lifecycle	生命周期数值 T（公式一）	—
--users-col	用户数列（收入为合计时计算 ARPU）	—
--rate-is-retention	将流失率列按留存率处理并转换为流失率	否