172 lines
8.7 KiB
Markdown
172 lines
8.7 KiB
Markdown
|
# detect_outliers
|
|||
|
|
|
|||
|
|
| 项 | 内容 |
|
|||
|
|
|---|---|
|
|||
|
|
| 模块 | `mcm_toolkit.data.clean` |
|
|||
|
|
| 档位 | S |
|
|||
|
|
| 参考来源 | Tukey (1977) *Exploratory Data Analysis*（1.5·IQR 围栏的出处）；3σ 准则见 NIST/SEMATECH e-Handbook §1.3.5.17；实现直接调用 `pandas.DataFrame.quantile` / `mean` / `std` |
|
|||
|
|
| 实现状态 | 已实现（2026-10-02），`tests/test_data.py` 中 9 条用例覆盖 |
|
|||
|
|
|
|||
|
|
## 1. 数学定义
|
|||
|
|
|
|||
|
|
设某列数值样本 `x_1..x_n`，记 `Q_1 = quantile(0.25)`、`Q_3 = quantile(0.75)`，
|
|||
|
|
四分位距 `IQR = Q_3 - Q_1`。对每个 `x_i` 给出布尔判定：
|
|||
|
|
|
|||
|
|
**IQR 法**（默认）：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
m_i = (x_i < Q_1 - k·IQR) or (x_i > Q_3 + k·IQR) 默认 k = 1.5
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**z-score 法**：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
z_i = (x_i - x̄) / s s 为样本标准差（ddof = 1）
|
|||
|
|
m_i = |z_i| > t 默认 t = 3.0
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
输入：一张表（`DataFrame`）或一维序列；输出：**与原数据同形的布尔掩码**，
|
|||
|
|
`True` 表示该位置是离群点。数学上它是逐元素定义的二值函数，不依赖行与行之间的关系。
|
|||
|
|
|
|||
|
|
## 2. 适用场景
|
|||
|
|
|
|||
|
|
**用**：
|
|||
|
|
|
|||
|
|
- 数据录入错误（身高 260 cm、年龄 −10）这类"明显不可能"的点，先标出来给人看。
|
|||
|
|
- 建模前的敏感性分析：删与不删各跑一遍，看结论动不动 —— 这比直接删更有说服力。
|
|||
|
|
- 论文要交代"异常值怎么处理"时，这是最容易被评审接受的判据（有文献、可复现、无随机性）。
|
|||
|
|
|
|||
|
|
**不用**：
|
|||
|
|
|
|||
|
|
- **别拿它当自动清洗**。偏态、幂律、小样本（`n < 20`）时 IQR 围栏会误杀 ——
|
|||
|
|
重尾数据里"离群"常常就是信号本身。
|
|||
|
|
- z-score 法**前提是近似正态**。右偏数据（收入、人口、成绩分布）用它会把整片上尾标红。
|
|||
|
|
- 时间序列里的"离群"可能来自趋势或季节项，应先去趋势/差分再判，否则会把拐点当异常。
|
|||
|
|
- 多变量离群（单变量看都正常、组合起来才异常）它看不出来，那要用马氏距离或 `IsolationForest`。
|
|||
|
|
|
|||
|
|
## 3. 参数与返回值
|
|||
|
|
|
|||
|
|
| 参数 | 类型 | 默认 | 含义 | 取值影响 |
|
|||
|
|
|---|---|---|---|---|
|
|||
|
|
| `data` | `DataFrame` / `Series` / `list` / `tuple` / `ndarray` | 必填 | 待判数据 | 非数值列不参与统计，掩码里恒 `False`（见下） |
|
|||
|
|
| `method` | `"iqr"` / `"zscore"` | `"iqr"` | 判据 | IQR 对重尾稳健；zscore 只在近似正态时可靠 |
|
|||
|
|
| `k` | `float` | `1.5` | 仅 IQR：围栏倍数 | 1.5 是 Tukey 的 "outlier"、3.0 是 "far outlier"；调小 → 标出更多 |
|
|||
|
|
| `threshold` | `float` | `3.0` | 仅 zscore：\|z\| 阈值 | 3.0 ≈ 正态下的 0.27%；调小 → 标出更多 |
|
|||
|
|
|
|||
|
|
`k` 与 `threshold` 通过 `**kwargs` 传入，**传错了不会报错**（`k` 只在 iqr 分支被读）。
|
|||
|
|
|
|||
|
|
### 为什么它不返回 `Result`
|
|||
|
|
|
|||
|
|
模板里"返回 `Result`"这一节对它**不适用**，这是刻意的：`Result` 承载的是"一次计算的
|
|||
|
|
参数 + 指标 + 数据"，而 `detect_outliers` 不改数据、不产生标量指标，它只是一个逐元素的
|
|||
|
|
布尔判断。包成 `Result` 会多一层壳，调用方反而要写 `r.data` 才能拿到掩码。
|
|||
|
|
|
|||
|
|
返回值按输入形状分派：
|
|||
|
|
|
|||
|
|
| 输入 | 输出 |
|
|||
|
|
|---|---|
|
|||
|
|
| `DataFrame` | 同形布尔 `DataFrame` |
|
|||
|
|
| `Series` | 布尔 `Series`，**列名保留** |
|
|||
|
|
| 一维 `list` / `tuple` / `ndarray` | 一维布尔 `ndarray` |
|
|||
|
|
| 二维 `ndarray` | 同形布尔 `DataFrame` |
|
|||
|
|
|
|||
|
|
### 非数值列为什么恒 `False`
|
|||
|
|
|
|||
|
|
两条备选路都被否掉了：
|
|||
|
|
|
|||
|
|
- **跳过**（把非数值列从掩码里去掉）→ docstring 承诺的"与原数据同形"就是假话，
|
|||
|
|
形状对不上，也就没法按位置把掩码和原表对回去；
|
|||
|
|
- **报错** → 一张带 `city` 列的真题表直接不可用，而 `city` 列本来就不该影响数值列判定。
|
|||
|
|
|
|||
|
|
`False` 的读法是"这一列没有离群点"，对文本列而言这是最不坏的解释，
|
|||
|
|
而且让整表能一次跑完。**但要注意**：这只是"不报错"，
|
|||
|
|
不代表文本列可以当数值列进模型 —— 编码是 `one_hot_encode` 的事。
|
|||
|
|
|
|||
|
|
## 4. 复杂度
|
|||
|
|
|
|||
|
|
- 时间：`O(n·p)`（n 行、p 列；分位数和均值各扫一遍，比较再扫一遍）。
|
|||
|
|
- 空间：`O(n·p)` —— 掩码与原表同形，这是主要开销。
|
|||
|
|
- **什么时候会跑不完**：单机几千万行以上时，同形掩码会把内存吃满
|
|||
|
|
（1e7 行 × 20 列 `float64` 约 1.6 GB，掩码再来一份 `bool` 约 0.2 GB，
|
|||
|
|
但 `quantile` 内部还会再复制）。真到那一步应该分块流式处理，而不是加内存。
|
|||
|
|
|
|||
|
|
## 5. 数值稳定性
|
|||
|
|
|
|||
|
|
- **`std == 0`（整列同值）**：代码里先 `std.replace(0, np.nan)`，让该列 z 全为 NaN、
|
|||
|
|
一律判 `False`。少这一步会得到 `inf` / `0/0` 并伴随 RuntimeWarning。
|
|||
|
|
- **NaN**：比较结果是 `False`，所以缺失值**不会**被标成离群。这是有意的 ——
|
|||
|
|
缺失归 `clean_missing` / `impute_missing` 管，两件事不该混。
|
|||
|
|
- **`n = 1`**：`std` 是 NaN、分位数等于该值本身，掩码全 `False`。小样本别指望它。
|
|||
|
|
- **边界值**：`x_i` 恰好等于围栏值时**不算**离群（用的是严格 `<` / `>`）。
|
|||
|
|
这是刻意选的：边界值不该被当异常。
|
|||
|
|
- **`ddof` 口径**：本函数用 pandas 的 `Series.std()`，默认 `ddof = 1`（样本标准差），
|
|||
|
|
而 `numpy.std` 默认 `ddof = 0`（总体标准差）。小样本下差别不小：`[1,2,3,4,1000]` 的
|
|||
|
|
std 是 446.1（ddof=1）对 399.0（ddof=0），z 值直接差一成。**本项目 `stats.zscore` 的默认
|
|||
|
|
也是 `ddof = 0`**，两处口径不一致是已知问题 —— 论文里报 |z| 时必须写明用的哪一个。
|
|||
|
|
（分位数这边反而没问题：pandas `quantile` 与 `numpy.percentile` 默认都是线性插值，结果一致。）
|
|||
|
|
|
|||
|
|
## 6. 常见错误
|
|||
|
|
|
|||
|
|
1. 把返回值当筛选结果：`df = detect_outliers(df)` → 表变成布尔掩码。
|
|||
|
|
正确做法是 `mask = detect_outliers(df)`，然后**自己决定**删不删。
|
|||
|
|
2. 对含文本列的真题表直接调用 → 老版本在 `quantile()` 上崩。现在非数值列恒 `False`，
|
|||
|
|
但要记得"不崩"不等于"文本列进了模型"。
|
|||
|
|
3. 用 z-score 判右偏数据 → 整片上尾被标红，删完结论就变了。先画分布再选方法。
|
|||
|
|
4. 看到离群就删 → 论文里没有交代、评审必问。先报告个数与占比，再做删/不删对照。
|
|||
|
|
5. 只报"删了 5 个" → 没给比例、没给判据、没给 `k`。论文里这三个数缺一不可。
|
|||
|
|
6. 以为要设 seed → 本函数**不含随机成分**；但后续若用 bootstrap 比较"删前后"的差异，
|
|||
|
|
那条链必须 `set_seed`，否则"可复现"是假的。
|
|||
|
|
|
|||
|
|
## 7. 最小示例
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
import numpy as np
|
|||
|
|
import pandas as pd
|
|||
|
|
|
|||
|
|
from mcm_toolkit.data import detect_outliers
|
|||
|
|
|
|||
|
|
df = pd.DataFrame({"city": list("abcd"), "v": [1.0, 2.0, 3.0, 1000.0]})
|
|||
|
|
|
|||
|
|
mask = detect_outliers(df) # IQR，默认 k=1.5；只标不删
|
|||
|
|
print(mask)
|
|||
|
|
# city v
|
|||
|
|
# 0 False False
|
|||
|
|
# 1 False False
|
|||
|
|
# 2 False False
|
|||
|
|
# 3 False True
|
|||
|
|
|
|||
|
|
print(np.asarray(mask).sum()) # 1
|
|||
|
|
print(detect_outliers(df["v"]).tolist()) # Series 进 Series 出
|
|||
|
|
# [False, False, False, True]
|
|||
|
|
|
|||
|
|
# 想改成更激进的判定：k 调小
|
|||
|
|
print(np.asarray(detect_outliers(df, k=0.5)).sum())
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 8. 单元测试要点
|
|||
|
|
|
|||
|
|
| 测什么 | 期望 |
|
|||
|
|
|---|---|
|
|||
|
|
| 埋 3 个远离主体的点（IQR 默认） | 正好命中 3 个，且位置对得上 |
|
|||
|
|
| 埋 1 个点（zscore 默认 t=3） | 正好命中 1 个 |
|
|||
|
|
| 返回形状 | 与输入同形；Series 进 Series 出且列名保留；一维数组进一维布尔出 |
|
|||
|
|
| 含文本列的表 | 不崩，文本列恒 `False`，数值列照常判定 |
|
|||
|
|
| 整表没有数值列 | 不崩，返回全 `False` 掩码 |
|
|||
|
|
| `method="bogus"` | `ValueError`，报错信息里带方法名 |
|
|||
|
|
| `data = 42 / 3.14 / "123" / None / dict` | `TypeError`（§4.7：非法类型不静默兜底） |
|
|||
|
|
| 全 NaN 列、单元素列 | 全 `False`，不抛异常 |
|
|||
|
|
| 元组入参 | 按一维数组型处理，结果与传 list 一致 |
|
|||
|
|
|
|||
|
|
## 9. MCM/ICM 用法
|
|||
|
|
|
|||
|
|
- **哪类题**：所有要写"数据预处理"小节的题（几乎全部）。评价类与预测类尤其要做，
|
|||
|
|
因为离群点对均值、回归系数的影响最大。
|
|||
|
|
- **论文里怎么表述**：
|
|||
|
|
"采用 Tukey (1977) 的 1.5×IQR 围栏识别异常值：记 Q1、Q3 为第一、三四分位数，
|
|||
|
|
凡落在 [Q1 − 1.5·IQR, Q3 + 1.5·IQR] 之外者标为可疑点，共 N 个（占 x%）。
|
|||
|
|
我们保留全部原始数据，并给出剔除/不剔除两版对照结果（见附录 B）。"
|
|||
|
|
- **图**：箱线图（标出被标红的点）+ 直方图叠围栏竖线；用 `viz.plot(kind="box")`
|
|||
|
|
与 `viz.plot(kind="hist")`，保存用 `viz.save_figure`。
|
|||
|
|
- **踩坑提醒**：评审最可能追问三件事 ——
|
|||
|
|
① 为什么是 1.5 而不是 3？② 删了多少、删完结论变了吗？③ 这些点是"错误"还是"真实极端值"？
|
|||
|
|
三个问题都要在论文里先答，别等被问。
|