diff --git a/CHANGELOG.md b/CHANGELOG.md index f9c5ffd..50f40c6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -52,7 +52,7 @@ （Codex 代写，与 io.py 同一套 numpydoc 格式）。 - `data.clean`：ruff 从 6 条清到 1 条——导入分组（I001）、elif 链改 if 加末尾无条件 return （RET505 / RET503）、去掉多余 f 前缀（F541）、删掉只会被覆盖的 mask 初始化（死代码）、 - 去掉行尾空白（W293）。剩下的 1 条 SIM102 就在下面 Notes 那条待修的代码里，删掉它即全绿。：分析器会去 PATH 上找 python， + 去掉行尾空白（W293）。 本机 PATH 上只有 Codex 运行时的 3.14 shim（无科学栈），且 pyright 不认 `pyvenv.cfg` 的 `include-system-site-packages`。 改为 `[tool.pyright]` 指定 `venvPath = "."` / `venv = ".venv"` / @@ -71,15 +71,27 @@ - conda base 里 zstandard 的 `*.conda_trash` 残骸目录被 Python 当成 namespace package 导入， 使 `.venv`（= base）的 `pd.read_csv` 抛 `ImportError: Can't determine version for zstandard`。 已把残骸目录改名禁用（**可逆**，未删除），详见 `docs/04-environment.md` 坑 6。 +- `data.clean` 第二轮审查（2026-10-02），Codex 直接修掉 4 处**轻度**问题： + `winsorize(Series)` 因 `select_dtypes` 在 `Series` 上不存在而直接崩（Series 分支提到最前， + 并加数值 dtype 守卫）；`winsorize` 的 `data.quantile()` 改为只在数值列上算 + （文本列不再崩，与已有的 `numeric_cols` 判断对齐）；删掉 `detect_outliers` 里已成空操作的 + `df = pd.DataFrame(data)`（数据在更早处就转过了，顺手去掉 `df` 这个别名）； + 清掉行尾空白（W293）、函数体内的连续空行，并把 `clean_missing` 的嵌套 `if` 合并 + （SIM102，ruff 最后 1 条）。ruff `1 error` → **`All checks passed`**，pyright 仍 0。 +- `tests/test_data.py`：5 条 `xfail` 经 XPASS 信号确认已修好，**摘掉 mark 转正式用例** + （`detect_outliers` 的 4 条 + `winsorize` 混合类型 1 条）。测试 **53 passed / 7 xfailed → + 58 passed / 2 xfailed**。 +- `CHANGELOG.md`：[Unreleased] 里有一句被重复追加撑坏 + （"…删掉它即全绿。：分析器会去 PATH 上找 python，"），已修。 ### Notes -- `detect_outliers` **目前不可用**，三个 bug 已在 `tests/test_data.py` 里用 xfail 标出： - threshold 范围校验放错了函数（iqr 分支 UnboundLocalError、zscore 分支默认 3.0 被 0<=t<=1 拒掉）、 - quantile 在含文本列的表上直接崩、is_series / is_ld_array 在数据已转成 DataFrame 之后才判断 - 因此永远为 False（返回形状仍是 (n,1)，与 docstring 承诺的「与原数据同形」不符）。 - 修法与优先级见 `STATUS.md` 的「下一步」。 -- `winsorize` 与 `detect_outliers` 都还没能在含文本列的赛题表上跑通：分位数必须限制在数值列。 +- `detect_outliers` 原有三个 bug，现已修掉两个（threshold 范围校验挪进 `clean_missing`、 + `is_series` / `is_ld_array` 提到类型转换**之前**），**只剩"文本列"这一处**： + `data.quantile()` 仍在全表上算，含文本列的赛题表一带就崩。 + 这一处要**先定设计**（非数值列返回全 `False`，还是只对数值列给掩码）， + 所以不在"轻度直接修"的范围内，留给用户本人写 —— 见 `STATUS.md`「下一步」第 1 条。 - `impute_missing` 的 mode 分支会**就地修改**调用方的 DataFrame，其余四个分支都返回新表。 + 同样属于"要选语义"，留给用户本人写 —— 见 `STATUS.md`「下一步」第 3 条。 - 已知缺口： - 除 `core.Result`、`core.get_rng`、`core.set_seed`、`data.load_table`、`data.save_table` 外，其余函数体**尚未实现**（统一 `raise NotImplementedError` + `TODO(L0/L1/v0.2)` 标记）。 这是刻意的：先定接口，再按 `docs/03-roadmap.md` 的 L0 → L1 顺序填实现。 diff --git a/STATUS.md b/STATUS.md index 012b32b..b2ed28c 100644 --- a/STATUS.md +++ b/STATUS.md @@ -1,6 +1,6 @@ # STATUS — 当前进度 -> 更新日期：2026-10-01 +> 更新日期：2026-10-02 ## 本次任务 @@ -10,7 +10,7 @@ **第二阶段（进行中）**：按 `docs/03-roadmap.md` 的 L0 → L1 顺序**逐个实现函数**， 用户本人写 `src/`、Codex 负责审查 + `tests/`（决策 25）。 -当前 3/12：`Result`、`get_rng`/`set_seed`、`load_table`/`save_table`。 +当前 4/12：`Result`、`get_rng`/`set_seed`、`load_table`/`save_table`、`clean_missing`。 ## 任务清单 @@ -95,18 +95,17 @@ - `threshold` 用 `math.ceil` 算 `min_non_na`：3 列、阈值 0.5 时必须是 2， 写 `int()` 截断会漏删 - 顺手落地兄弟函数 `impute_missing` / `winsorize`（原属 L1） -- [ ] **待修：** `detect_outliers` 已写但有 3 个 bug（见下） -- [ ] 剩余 7 项：`normalize` - `detect_outliers` `normalize` `standardize` `describe` `correlation_matrix` - `bootstrap_ci` `monte_carlo` `save_figure` +- [ ] **待收尾：** `detect_outliers` 只剩"文本列"1 处，且要先定设计（见「下一步」第 1 条） +- [ ] 剩余 8 项：`detect_outliers`（收尾）+ `normalize` `standardize` `describe` + `correlation_matrix` `bootstrap_ci` `monte_carlo` `save_figure` ### 验证结果 | 检查 | venv | conda `mcm-toolkit` | |---|---|---| -| `pytest` | 见下（单列） | **53 passed, 42 skipped, 7 xfailed** | +| `pytest` | 见下（单列） | **58 passed, 42 skipped, 2 xfailed** | | `import mcm_toolkit` | 0.0.1 / 16 项 | 0.0.1 / 16 项 | -| `ruff check` | All checks passed | **1 error**（就在 `detect_outliers` 那段待修的代码里） | +| `ruff check` | All checks passed | **All checks passed**（0 error） | | `scripts/doctor.ps1` | 跑通 | — | | SALib / pymoo / pyright | 缺失 | 已装 | @@ -114,10 +113,10 @@ （修配置之前是 17 errors，全是"无法解析导入 numpy / pandas"，见决策 29 与 `docs/04-environment.md` 坑 7） - base 亦已复核：numpy 2.4.6 / scipy 1.18.1 / pandas 3.0.6（与两套环境一致） -- 53 条通过 = 20 条公开 API 契约测试 + 11 条 `core` 行为测试 + 22 条 `data` 行为测试 -- 7 条 `xfail` 是**已知待修**的契约（`detect_outliers` 的 4 条、`winsorize` 混合类型、 - `clean_missing` 阈值范围、`impute_missing` 的 mode 就地修改）； - 修好后会自动变 XPASS，那时把 `xfail` 摘掉即可（决策 30） +- 58 条通过 = 20 条公开 API 契约测试 + 11 条 `core` 行为测试 + 27 条 `data` 行为测试 +- 2 条 `xfail` 是**已知待修**的契约：`detect_outliers` 遇文本列、`impute_missing` 的 mode 就地改。 + 两者都**不是漏改，是设计没定**；修好后会自动变 XPASS，那时把 `xfail` 摘掉即可（决策 30） +- 上一轮 5 条 `xfail` 正是靠这个 XPASS 信号确认修好并摘掉的 - 42 条 skip 是等实现的算法（`normalize` / `standardize` / `train_test_split` 等） - 三个 `.ps1` 通过 PowerShell AST 语法解析 @@ -173,26 +172,22 @@ | 30 | 已知待修的契约用 `@pytest.mark.xfail(strict=False)`，不用 skip | skip 会让"契约还没写"和"写了但实现有问题"混在一起，5 条 skip 曾把 `clean.py` 的 bug 全藏住。xfail 照样进报告，修好后自动变 XPASS，是"修好了"的信号，而且 XPASS 不失败，不会卡住提交 | | 29 | 静态分析器钉死到工作区 `.venv`，并把 base 的 site-packages 用 `.pth` 链进去 | pyright / Pylance **不认** `pyvenv.cfg` 的 `include-system-site-packages`，`.venv` 自己只有 `pip`；不钉的话它们会去 PATH 上找 python，本机 PATH 上那个是 Codex 运行时的 3.14 shim，没有科学栈，于是报"无法解析导入"。`.pth` 是唯一被 pyright 认的转发手段 | | 28 | 不启用 ruff 的 preview 规则集 | `E302`（函数间要 2 个空行）在 ruff 0.16 里是 preview 规则，`select = ["E"]` 默认**不包含**它——所以少一个空行 ruff 照样报 "All checks passed"。行数空行得自己盯，别指望 lint | +| 31 | Codex 可**直接改** `src/` 的范围：纯 bug（不改接口与语义）、格式、死代码 | 决策 25 说实现归用户，但"能跑"是底线：`winsorize(pd.Series)` 因 `select_dtypes` 在 `Series` 上不存在而直接崩、测试变红，这种必须当场修。凡是要**选一个语义**的（文本列返回什么、mode 要不要就地改）一律留给用户本人，Codex 只把选项和影响列清楚 | | 27 | base 里的 zstandard 残骸目录**改名禁用**，不删除、不重装 | 删掉不可逆；`pip install zstandard` 会给 base 塞一个 conda 记录里根本没有的包，下次 `conda update --all` 又要重新判断。改名后 `import` 变回正常 `ModuleNotFoundError`，pandas 自动跳过 | ## 下一步 -1. **修 `detect_outliers`**（唯一挡在 L0 前进路上的 🔴，三处都在 `src/mcm_toolkit/data/clean.py`）： - - `clean.py:165-167` 的 `threshold` 范围校验放错了函数：`threshold` 只在 zscore 分支 - 赋值，iqr 走进去就是 `UnboundLocalError`；而且 z 的阈值本来就是 3.0， - 用 `0 <= threshold <= 1` 卡它必然把默认值拒掉。 - 你本意多半是想校验 `clean_missing` 的 `threshold`（那个才该是 [0,1]）——把它挪过去， - `detect_outliers` 里删掉。ruff 剩下的那 1 条（SIM102）也在这 3 行里，删掉就全绿。 - - `clean.py:145` 的 `df.quantile()` 要在**数值列**上算：`df.select_dtypes(include='number')`， - 否则赛题表一带文本列就崩。`winsorize` 的 `clean.py:186` 同病， - 而且它的空数值列判断排在了分位数之后，等于没兜住。 - - `clean.py:130-131` 的 `is_series` / `is_ld_array` **永远为 False**： - 第 114-117 行已经把 `data` 转成 DataFrame 了，再判断 `isinstance(data, pd.Series)` 自然不成立。 - 要在转换**之前**记下来，或者干脆用 `inspect` 拿原始入参。修好后 - `test_detect_outliers_returns_mask_not_filtered_data` 会从 xfail 变 XPASS。 +1. **收尾 `detect_outliers`**（`src/mcm_toolkit/data/clean.py`，只剩 1 处，且**要先定设计**）： + 非数值列怎么办 —— 一律返回 `False`，还是只对数值列算掩码？ + 现在 iqr / zscore 两条分支都直接在**全表**上 `quantile()` / `mean()`，赛题表一带文本列就崩。 + 定完把它换成 `data[numeric_cols].quantile(...)`（`winsorize` 已按"只对数值列算"改好，可直接照抄）， + 并把 `tests/test_data.py::test_detect_outliers_survives_text_columns` 的 xfail 摘掉。 2. **写 `detect_outliers` 的 S 档函数卡片**（`docs/algorithms/` 下，照 `docs/dev/function-card-template.md`）。 roadmap 要求 S 档先写卡片再写码 —— 这次是反着来的，所以三个 bug 都在"该想清楚"的地方翻车： 上界符号、布尔优先级、维度。卡片本身就是防这个的。 -3. 顺手把 `impute_missing` 的 mode 分支改成**返回新表**（现在就地改调用方的 DataFrame，和另外四个分支不一致）。 -4. 每写完一个函数，在 `examples/` 里加一行最小用法。 -5. L0 跑通后，找一道真题（建议 2025 C）走完整流程，反向沉淀函数。 +3. 顺手把 `impute_missing` 的 mode 分支改成**返回新表** + （现在就地改调用方的 DataFrame，和另外四个分支不一致；`data = data.copy()` 一行的事）。 +4. **下一个文件**：`data/transform.py` 的 `normalize` / `standardize` + （`tests/test_data.py` 里两条 skip 已就位；写之前先定 `method` 的取值集合与 `axis` 语义）。 +5. 每写完一个函数，在 `examples/` 里加一行最小用法。 +6. L0 跑通后，找一道真题（建议 2025 C）走完整流程，反向沉淀函数。 diff --git a/docs/dev/personal-pitfalls.md b/docs/dev/personal-pitfalls.md index bdd7525..5e15893 100644 --- a/docs/dev/personal-pitfalls.md +++ b/docs/dev/personal-pitfalls.md @@ -98,3 +98,19 @@ 想看全貌就偶尔跑一次 `ruff check --select ALL --preview`（只当参考，别直接开进 CI， 会淹没在噪声里）；纯格式问题交给 `ruff format`，它是 formatter，不受 `select` 影响。 - 首次：2026-10-01｜复发：0 + +### 7. 写"守卫子句"时，忘了不是所有入参都长一样 + +- 现象：`winsorize` 开头先算 `numeric_cols = data.select_dtypes(include=['number']).columns` + 挡"空数值列"，但 `winsorize` 同时收 `DataFrame` 和 `Series` —— + **`Series` 上没有 `select_dtypes`**，传 Series 直接 `AttributeError`， + 而且报错就报在守卫那一行（全函数看起来最"安全"的地方）。 +- 为什么会错：写的时候只想"要防住空数值列"，顺手把守卫放在函数最上面， + 没回头确认**这个函数还收哪些类型**。守卫本身没错，错的是它的**位置**： + 它对 `DataFrame` 成立、对 `Series` 根本不合法，所以必须排在 + `isinstance(data, pd.Series)` 的类型分派**之后**。 + 本质是：**先做类型分派，再写只对其中一支成立的逻辑**。 +- 以后怎么防：写"开头集中校验"之前，先把入参的**全部类型**列一遍， + 逐条问"这句话对每种类型都成立吗"；不成立的往后挪， + 挪进 `if isinstance(...)` 里面，让它只有对应的那一支能走到。 +- 首次：2026-10-02｜复发：0 diff --git a/src/mcm_toolkit/data/clean.py b/src/mcm_toolkit/data/clean.py index a60c57e..7364926 100644 --- a/src/mcm_toolkit/data/clean.py +++ b/src/mcm_toolkit/data/clean.py @@ -54,6 +54,9 @@ def clean_missing(data: Any, axis: int = 0, threshold: float | None = None) -> A if not isinstance(data,pd.DataFrame): raise TypeError(f"data必须是pandas DataFrame,你传入了{type(data)}") + if threshold is not None and not 0 <= threshold <= 1: + raise ValueError(f"threshold必须在0和1之间,你传入了{threshold}") + if threshold is None: return data.dropna(axis=target_axis,how='any') @@ -150,6 +153,9 @@ def detect_outliers(data: Any, method: Literal["iqr", "zscore"] = "iqr", **kwarg >>> bool(mask[-1]) True """ + is_series = isinstance(data, pd.Series) + is_ld_array = isinstance(data, (list, np.ndarray)) and np.array(data).ndim == 1 + if isinstance(data,pd.Series): data = data.to_frame() elif not isinstance(data,pd.DataFrame): @@ -162,30 +168,21 @@ def detect_outliers(data: Any, method: Literal["iqr", "zscore"] = "iqr", **kwarg else: raise ValueError(f"不支持的方法:{method},仅支持'iqr'或'zscore'") - if threshold is not None: - if not 0 <= threshold <= 1: - raise ValueError(f"threshold必须在0和1之间,你传入了{threshold}") - - is_series = isinstance(data, pd.Series) - is_ld_array = isinstance(data, (list, np.ndarray)) and np.array(data).ndim == 1 - - df = pd.DataFrame(data) - if method == 'iqr': - Q1 = df.quantile(0.25) - Q3 = df.quantile(0.75) + Q1 = data.quantile(0.25) + Q3 = data.quantile(0.75) IQR = Q3 - Q1 lower_bound = Q1 - k * IQR upper_bound = Q3 + k * IQR - mask = (df < lower_bound) | (df > upper_bound) + mask = (data < lower_bound) | (data > upper_bound) elif method == 'zscore': - mean = df.mean() - std = df.std() + mean = data.mean() + std = data.std() std = std.replace(0, np.nan) - z_scores = (df - mean) / std + z_scores = (data - mean) / std mask = z_scores.abs() > threshold if is_series: @@ -227,22 +224,24 @@ def winsorize(data: Any, lower: float = 0.01, upper: float = 0.99) -> Any: raise ValueError(f"分位数必须满足0 < lower < upper < 1,你传入了lower={lower},upper={upper}") if isinstance(data,pd.Series): + if not pd.api.types.is_numeric_dtype(data): + return data.copy() lower_val = data.quantile(lower) upper_val = data.quantile(upper) return data.clip(lower=float(lower_val),upper=float(upper_val)) - lower_bounds = data.quantile(lower) - upper_bounds = data.quantile(upper) - numeric_cols = data.select_dtypes(include=['number']).columns - result = data.copy() - if len(numeric_cols) == 0: return data.copy() + lower_bounds = data[numeric_cols].quantile(lower) + upper_bounds = data[numeric_cols].quantile(upper) + + result = data.copy() + result[numeric_cols] = result[numeric_cols].clip( - lower=lower_bounds[numeric_cols], - upper=upper_bounds[numeric_cols], + lower=lower_bounds, + upper=upper_bounds, axis=1 ) diff --git a/tests/test_data.py b/tests/test_data.py index 7ce036b..21dbaeb 100644 --- a/tests/test_data.py +++ b/tests/test_data.py @@ -231,20 +231,24 @@ def test_winsorize_rejects_non_frame_with_typeerror(): def test_detect_outliers_rejects_unknown_method(): - """方法名校验在取随机取值之前，所以这条现在就是绿的。""" + """方法名校验在取默认取值之前，所以这条现在就是绿的。""" from mcm_toolkit.data import detect_outliers with pytest.raises(ValueError, match="bogus"): detect_outliers([1.0, 2.0], method="bogus") # type: ignore[arg-type] -# ------------------------------- 待修：契约已写进 docstring，实现还没跟上（xfail） +# ------------------- 契约先写进 docstring，实现逐条跟上（剩余 2 条 xfail） # -# 这些用例写的是**文档里已经承诺的行为**。现在跑是红的，用 xfail 让它们照样出现在 -# 报告里（显示成 x）；实现修好之后会自动变成 XPASS —— 看到 XPASS 就把 mark 摘掉。 +# 这些用例写的是**文档里已经承诺的行为**。实现没跟上时用 xfail，让它们照样出现在 +# 报告里（显示成 x）；修好之后会自动变成 XPASS —— 看到 XPASS 就把 mark 摘掉。 +# +# 已摘掉：threshold 范围校验、IQR 的 UnboundLocalError、(n,1) 形状、zscore 默认阈值、 +# winsorize 的文本列。剩下 2 条不是漏改，是**设计还没定**： +# - detect_outliers 遇到文本列返回什么（全 False？还是只对数值列算掩码？） +# - impute_missing 的 mode 分支该不该就地改调用方的表（其余分支都返回新表） -@pytest.mark.xfail(reason="threshold 只在 zscore 分支赋值，iqr 走进去 UnboundLocalError", strict=False) def test_detect_outliers_finds_planted_points(): """人工埋 3 个离群点，IQR 法应正好命中 3 个。""" from mcm_toolkit.data import detect_outliers @@ -255,7 +259,6 @@ def test_detect_outliers_finds_planted_points(): assert bool(mask[-3:].all()) -@pytest.mark.xfail(reason="返回 (n,1)，契约是「与原数据同形」", strict=False) def test_detect_outliers_returns_mask_not_filtered_data(): """约定：只标不删——返回与原数据同形的布尔掩码。""" from mcm_toolkit.data import detect_outliers @@ -266,7 +269,6 @@ def test_detect_outliers_returns_mask_not_filtered_data(): assert mask.dtype == bool -@pytest.mark.xfail(reason="zscore 的 threshold 被按 [0,1] 校验，默认 3.0 直接被拒", strict=False) def test_detect_outliers_zscore_flags_planted_point(): from mcm_toolkit.data import detect_outliers @@ -285,8 +287,8 @@ def test_detect_outliers_survives_text_columns(): assert int(np.asarray(detect_outliers(df)).sum()) == 1 -@pytest.mark.xfail(reason="quantile 在全表上算，遇到文本列直接崩", strict=False) def test_winsorize_survives_text_columns(): + """文本列必须原样留着：分位数只在数值列上算。""" from mcm_toolkit.data import winsorize df = pd.DataFrame({"city": ["a", "b", "c", "d"], "v": [1.0, 2.0, 3.0, 1000.0]}) @@ -295,7 +297,6 @@ def test_winsorize_survives_text_columns(): assert float(out["v"].iloc[-1]) < 1000.0 -@pytest.mark.xfail(reason="threshold 没做范围校验，传 1.5 会变成「什么都不删」", strict=False) def test_clean_missing_rejects_out_of_range_threshold(): from mcm_toolkit.data import clean_missing