---
name: bi-retention-rate
description: 用户留存率计算，计算用户首次进入产品或首次完成关键行为后，后续回访或持续活跃的比例。触发条件：需计算用户留存率时触发，如观测次日留存率、观测第七日留存率等。
---

# bi-retention-rate

计算用户首次进入产品或首次完成关键行为后，后续回访或持续活跃概率。

## 执行步骤

### Step 0：检查数据以及确定计算指标

1. 留存率计算涉及的指标以及数据列已经明确，如次日留存率计算考虑当日用户数与次日用户数，第七日留存率考虑当日留存用户数与第七日留存用户数；
2. 数据已经保存为 CSV 文件，且包含留存率计算所需关键数据，如当日用户数、次日用户数等。如

```csv
date,当日访问用户数,次日访问用户数
2025-01-01,10000,3000
2025-01-02,10500,1000
2025-01-03,9800,100
```

### Step 1：执行留存率计算

使用 `<skill-dir>/scripts/compute_retention.py` 脚本，计算用户在后续第 n 天的留存率（计算结果保留小数点后 5 位）。

```bash
python <skill-dir>/scripts/compute_retention.py --input_file "<输入数据文件路径 (CSV)>" --metric_name "<指标名称>" --day0_col "<第 0 天用户数列名>" --dayn_col "<第 n 天用户数列名>"
```

**参数说明**：

| 参数              | 说明                                 | 默认值   |
| ---------------- | ------------------------------------ | ------- |
| --input_file     | 输入数据文件路径 (.csv)                 | (必填) |
| --metric_name    | 计算指标名称（如次日留存率、第七日留存率等） | 留存率 |
| --day0_col       | 第 0 天用户数列名                       | (必填) |
| --dayn_col       | 第 n 天用户数列名                       | (必填) |

对于所有需要计算的留存率指标都需调用该脚本计算，不能遗失任何必要的指标计算。

## fallback（指引模式）

无脚本环境时按以下步骤手动计算：

1. 给定留存率计算所需的初始时间点 day0 以及 n 日后的留存率计算时间点 dayn
2. 计算 n 日留存率（保留小数点后 5 位）：
    $\frac{|\{用户 \mid day0新增用户\wedge 用户在dayn活跃 \}|}{|\{用户 \mid day0新增用户 \}|}$

## 输出要求

输出所有需要计算的留存率指标结果，不要遗失任何计算结果，包括 NaN 值。