---
name: bi-distribution-analysis
description: 分析观测数据在不同区间维度上的分布特征。触发条件：当任务强调数据分布特征分析时调用，如出现“数据分布”、“分布情况”等词时触发。
---

# bi-distribution-analysis

观察数据在不同区间的分布特征，计算均值、标准差、中位数等统计信息，用于刻画集中趋势与离散程度。

## 执行步骤

### Step 0：检查数据以及确定区间维度与计算指标

1. 明确分析对象：明确区间维度，以及相应具体数据列。例如，分析“不同国家用户数的分布情况”，区间维度为“国家”，具体数据列为“用户数”；
2. 数据以 CSV 格式保存，且数据中已包含区间维度信息以及关键数据列。如

```csv
date,访问用户数,国家
20250101,10000,英国
20250102,10500,法国
20250103,9800,德国
```

### Step 1：计算数据分布特征

对用于分析的数值序列 \(x_1,\ldots,x_n\)，计算以下数据分布特征：

| 指标       | 说明 |
| ---------- | -------- |
| **均值** | \(\bar{x} = \frac{1}{n}\sum_{i=1}^n x_i\) |
| **标准差** | \(\sigma = \sqrt{\frac{1}{n}\sum_{i=1}^n (x_i-\bar{x})^2}\) |
| **中位数** | 数值序列中位数 |
| **top 5 的维度** | 数据值最大的 5 个维度 ｜
| **top 5 维度各数值占比** | 数值最大的 5 个维度，每个维度对应数值占所有维度数值和的比例 |
| **频率分布（按累计占比分桶）** | 将各维度按数值从大到小排序，逐项累计求和并除以总和得到累计占比 \(r\)，按 \(r\) 落入以下 7 个桶：`<0.5`、`[0.5, 0.6)`、`[0.6, 0.7)`、`[0.7, 0.8)`、`[0.8, 0.9)`、`[0.9, 0.95)`、`>=0.95`。每个桶的值为该桶包含的维度名称列表 |

使用 `<skill-dir>/scripts/distribution_stats.py` 脚本，计算上述 6 个数值分布特征（数值类指标计算结果保留小数点后 5 位）。

```bash
python <skill-dir>/scripts/distribution_stats.py --input_file "<输入数据文件路径 (CSV)>" --value_col "<数值列名>" --dimension_col "<区间维度取值列>"
```

**参数说明**：

| 参数              | 说明                  | 默认值   |
| ---------------- | -------------------- | ------- |
| --input_file     | 输入数据文件路径 (.csv) | (必填) |
| --value_col      | 区间各维度对应数值列名   | (必填) |
| --dimension_col  | 区间维度值列           | (必填) |

## fallback（指引模式）

无脚本环境时按以下计算方式手动计算，不可遗漏任何指标计算。

对用于分析的数值序列 \(x_1,\ldots,x_n\)，计算以下数据分布特征：

| 指标       | 计算方式 |
| ---------- | -------- |
| **均值** | \(\bar{x} = \frac{1}{n}\sum_{i=1}^n x_i\) |
| **标准差** | \(\sigma = \sqrt{\frac{1}{n}\sum_{i=1}^n (x_i-\bar{x})^2}\) |
| **中位数** | 1. 将数据进行从小到大排序；2. n 是奇数，中位数为第 \(\frac{n+1}{2}\) 个数；n 是偶数，中位数为第 \(\frac{n}{2}\) 位和第 \(\frac{n+1}{2}\) 为数的平均数 |
| **top 5 的维度** | 数据最大的 5 个维度 ｜
| **top 5 维度各数值占比** | 数值最大的 5 个维度，每个维度对应数值占所有维度数值和的比例 |
| **频率分布（按累计占比分桶）** | 1. 将所有维度按数值 \(x_i\) 从大到小排序；2. 计算总和 \(S=\sum_i x_i\)；3. 依次计算累计和 \(C_k=\sum_{i=1}^{k} x_i\) 与累计占比 \(r_k = C_k / S\)；4. 按 \(r_k\) 将第 \(k\) 个维度名归入对应的桶：`<0.5`（\(r_k<0.5\)）、`[0.5, 0.6)`、`[0.6, 0.7)`、`[0.7, 0.8)`、`[0.8, 0.9)`、`[0.9, 0.95)`、`>=0.95`（\(r_k \ge 0.95\)）；5. 输出为 dict，key 为桶名，value 为该桶包含的维度名称列表 |

## 输出要求

输出上述全部数值分布特征的计算结果，不要遗失任何计算结果，包括 NaN 值。`频率分布` 中即使某个桶没有任何维度，也需保留为空列表 `[]`。