feat(data): transform.py 四个函数落地；补 18 条测试、清 5 条 ruff
实现（用户本人写）： - normalize（minmax / vector / max，三种都按列）+ feature_range 校验 + 常量列不出 nan - standardize（按列，ddof 真的传下去）+ 类型守卫 - log_transform（offset=None 时自动取 1 - min(x)，保证 x + offset >= 1）+ 类型守卫 - one_hot_encode（自动识别对象列 / 指定列 / drop_first） - data/ 下的 L0 至此结清（L0 7/12） Codex 的轻度修复（不改接口与语义）： - 清掉 5 条 ruff：RET503 / F541 / RET504 / RET505 / SIM108 - supported_method 与 feature_range 的校验提到 np.asarray 之前（守卫集中开头） - 修掉说反的报错文案（条件是要求下界 < 上界，原文写"上界必须小于下界"） - one_hot_encode 自动识别时显式加上 str / string：只写 object 在 pandas 3 上是弃用路径， 每次调用发 Pandas4Warning，未来会变成"一列都选不中"的静默错误（详见坑 9） 测试： - 新写 18 条（transform 段），其中两条是把原先挂着的 skip 转为实跑 —— normalize / standardize 的实现此前一条测试都没跑到（详见个人易错点 9） - 82 passed / 40 skipped / 0 xfailed；ruff 0；pyright 0 文档： - STATUS.md：E 节 + 验证表（122 条用例分布）+ 下一步重写（transform 待定的 4 个口径）+ 决策 34 - docs/04-environment.md：新增坑 9（pandas 3 的 str dtype 与 select_dtypes 弃用路径，含实测对照表） - docs/dev/personal-pitfalls.md：只追加第 9 条（实现写完但测试还挂 skip，绿灯是假的） - CHANGELOG.md：本轮变更 + 记录 transform 待定的 4 个口径
This commit is contained in:
guzhujushi committed
1 parent
5749e50e83
commit
6eab0babde
6 files changed
+330
-32
No files matched your search
@@ -112,14 +112,26 @@
|
||||
接受 `DataFrame` / `Series` / `list` / `tuple` / `ndarray`，`dict` 不再接受（决策 33）
|
||||
- [x] `examples/01_clean_and_describe.py`：`load_table` / `save_table` / `clean_missing` /
|
||||
`impute_missing` / `detect_outliers` / `winsorize` 六个函数的最小用法，实测可直接跑通
|
||||
- [ ] 剩余 7 项：`normalize` `standardize` `describe` `correlation_matrix`
|
||||
`bootstrap_ci` `monte_carlo` `save_figure`
|
||||
- [x] `data/transform.py` 的四个函数（**由用户本人实现**）：`normalize` / `standardize`（L0 第 6、7 项）、
|
||||
`log_transform` / `one_hot_encode`（原属 L1，顺手写了）
|
||||
- `normalize`：三种 method（`minmax` / `vector` / `max`）都**按列**；`feature_range` 校验下界 < 上界；
|
||||
常量列压到下界而不出 nan（决策 34）
|
||||
- `standardize`：按列，`ddof` 真的传下去 —— 测试用解析关系钉住
|
||||
（`ddof=0` → std 恰为 1；`ddof=1` → `sqrt((n-1)/n)` = 0.866）
|
||||
- `log_transform`：`offset=None` 时自动取 `1 - min(x)`，保证 `x + offset >= 1`
|
||||
- `one_hot_encode`：自动识别的 dtype 集合已显式补上 `'str'` / `'string'`（见坑 9）
|
||||
- Codex 清掉 5 条 ruff（RET503 / F541 / RET504 / RET505 / SIM108），并把 `feature_range`
|
||||
的两条校验提到 `np.asarray` **之前**、修掉说反的报错文案（条件是"下界必须小于上界"）
|
||||
- 测试：**新写 18 条**，其中两条是把原先挂着的 `skip` 转为实跑 —— 见 `tests/test_data.py` 的 transform 段
|
||||
- [ ] **待定：** `transform` 的 4 个口径问题（入参类型策略、要不要收 `DataFrame`、
|
||||
显式 `offset` 的校验、常量列写进 docstring）—— 见「下一步」第 1/2 条
|
||||
- [ ] 剩余 5 项：`describe` `correlation_matrix` `bootstrap_ci` `monte_carlo` `save_figure`
|
||||
|
||||
### 验证结果
|
||||
|
||||
| 检查 | venv | conda `mcm-toolkit` |
|
||||
|---|---|---|
|
||||
| `pytest` | 见下（单列） | **64 passed, 42 skipped（0 xfail）** |
|
||||
| `pytest` | 见下（单列） | **82 passed, 40 skipped（0 xfail）** |
|
||||
| `import mcm_toolkit` | 0.0.1 / 16 项 | 0.0.1 / 16 项 |
|
||||
| `ruff check` | All checks passed | **All checks passed**（0 error） |
|
||||
| `scripts/doctor.ps1` | 跑通 | — |
|
||||
@@ -129,11 +141,13 @@
|
||||
（修配置之前是 17 errors，全是"无法解析导入 numpy / pandas"，见决策 29 与
|
||||
`docs/04-environment.md` 坑 7）
|
||||
- base 亦已复核：numpy 2.4.6 / scipy 1.18.1 / pandas 3.0.6（与两套环境一致）
|
||||
- 64 条通过 = 20 条公开 API 契约测试 + 11 条 `core` 行为测试 + 33 条 `data` 行为测试
|
||||
- **122 条用例：82 passed / 40 skipped**。收集数按文件：`test_data.py` 52、`test_api_surface.py` 20、
|
||||
`test_core.py` 15、`test_solve.py` 9、`test_viz.py` 8、`test_decision.py` 7、`test_stats.py` 6、
|
||||
`test_models.py` 5
|
||||
- **`xfail` 清零**：累计 7 条"契约已写进 docstring、实现没跟上"的用例全部转正，
|
||||
决策 30 那套信号（XPASS → 摘 mark）跑完了一个完整闭环
|
||||
- `examples/01_clean_and_describe.py` 实测跑通（exit 0）；`00_quickstart.py` 仍等 `stats` / `viz`
|
||||
- 42 条 skip 是等实现的算法（`normalize` / `standardize` / `train_test_split` 等）
|
||||
- 40 条 skip 是等实现的算法（`train_test_split`、`describe`、`bootstrap_ci`、`monte_carlo` 等）
|
||||
- 三个 `.ps1` 通过 PowerShell AST 语法解析
|
||||
|
||||
### ⚠️ 需要注意 / 遗留
|
||||
@@ -143,8 +157,9 @@
|
||||
只差 Python 补丁号（3.13.9 vs 3.13.15）。详见 `docs/04-environment.md` §5。
|
||||
- [x] ~~Gitea 远程尚未配置~~ → **已配置并推送完成**，见上面 D 节与决策 19/20。
|
||||
note：仓库当前是 **Public**（匿名 `git ls-remote` 可读），要改私有去 Gitea 仓库设置。
|
||||
- [ ] L0 完成 **5/12**（`Result`、`get_rng`/`set_seed`、`load_table`/`save_table`、`clean_missing`、
|
||||
`detect_outliers`），其余按 `docs/03-roadmap.md` 的 L0 → L1 顺序推进；详情见上面 E 节
|
||||
- [ ] L0 完成 **7/12**（`Result`、`get_rng`/`set_seed`、`load_table`/`save_table`、`clean_missing`、
|
||||
`detect_outliers`、`normalize`、`standardize`），其余按 `docs/03-roadmap.md` 的 L0 → L1 顺序推进；
|
||||
详情见上面 E 节
|
||||
- [ ] 本机 `exec_command` 在沙箱模式下**完全不可用**
|
||||
（`helper_unknown_error: setup refresh had errors`），只有提权
|
||||
（`require_escalated`）模式可用。沙箱模式只允许写 `D:\MCM&ICM_Toolkit`。
|
||||
@@ -188,6 +203,7 @@
|
||||
| 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 |
|
||||
| 34 | 常量列（`max == min`）不定区间也不崩：`normalize` 压到 `feature_range` 下界，`standardize` 给 0 | 除零必须有个确定的答案，不能出 nan / inf。给 0 与 `sklearn` 的 `MinMaxScaler` / `StandardScaler` 一致（sklearn 把常量列的 scale 设为 1，结果就是 0），换库不换结论。行为已由 `test_normalize_constant_column_stays_finite` 与 `test_standardize_constant_column_stays_finite` 钉住 |
|
||||
| 33 | `detect_outliers` 只接受 `DataFrame` / `Series` / `list` / `tuple` / `ndarray`，`dict` 一律 `TypeError` | §4.7 要求非法类型抛 `TypeError` 而非静默兜底。`dict` 以前能"碰巧"被 `pd.DataFrame()` 转成表，但那不是文档承诺的形状，静默接受会让调用方以为传什么都行；`tuple` 则补进文档与 `is_ld_array`，与 `list` 同等对待 |
|
||||
| 32 | `detect_outliers` 对非数值列恒返回 `False`（既不跳过也不报错） | **用户本人在两条路里选的**。跳过会让 docstring 里"与原数据同形"变成谎话（形状对不上，没法按位置对回原表）；报错则让一张带 `city` 列的真题表直接不可用。`False` 的读法是"这一列没有离群点"，对文本列是最不坏的解释，也让整表能一次跑完 |
|
||||
| 31 | Codex 可**直接改** `src/` 的范围：纯 bug（不改接口与语义）、格式、死代码 | 决策 25 说实现归用户，但"能跑"是底线：`winsorize(pd.Series)` 因 `select_dtypes` 在 `Series` 上不存在而直接崩、测试变红，这种必须当场修。凡是要**选一个语义**的（文本列返回什么、mode 要不要就地改）一律留给用户本人，Codex 只把选项和影响列清楚 |
|
||||
@@ -195,17 +211,19 @@
|
||||
|
||||
## 下一步
|
||||
|
||||
1. **`data/transform.py` 的 `normalize` / `standardize`**（用户本人开始写）
|
||||
- 签名已经定好（`normalize(x, method="minmax", feature_range=(0.0, 1.0))`、
|
||||
`standardize(x, ddof=0)`），动手前只需要定两件事：`normalize` 的 `method` 取值集合
|
||||
（默认 `"minmax"`；要不要再放 `"maxabs"` / `"robust"`？YAGNI 的话就只留 `"minmax"`）、
|
||||
以及 `axis` 语义 —— 赛题里几乎总是**按列**，那就明确默认按列，别留模糊。
|
||||
- 注意 `standardize` 的 `ddof=0` 与 `detect_outliers` 里 pandas 默认的 `ddof=1` 不一致，
|
||||
两处都要在 docstring 里写明，否则以后对不上账（见 `docs/algorithms/detect_outliers.md` §5）。
|
||||
- `tests/test_data.py` 里两条 skip 已就位（`test_normalize_minmax_range`、
|
||||
`test_standardize_has_zero_mean_unit_std`）。
|
||||
2. `stats.describe` + `data/transform.py` 的 `log_transform` / `one_hot_encode`
|
||||
（`examples/01_clean_and_describe.py` 末尾的 `TODO(L0)` 就等 `describe`）。
|
||||
3. 补齐 `examples/00_quickstart.py`：它要等 `stats` / `viz`；`Result` 的用法届时一并写进去。
|
||||
4. 每写完一个函数：docstring（§4.7 全套）+ 一条 pytest + `examples/` 一行用法 + 更新 `STATUS.md`。
|
||||
5. L0 跑通后，找一道真题（建议 2025 C）走完整流程，反向沉淀函数。
|
||||
1. **`transform.py` 还剩 4 个口径要你拍板**（都要落到 docstring 的 `Raises` / `Notes` 里）：
|
||||
- **入参类型策略三个函数不一致**：`standardize` / `log_transform` 有守卫，只收
|
||||
`int/float/list/tuple/ndarray/Series`；`normalize` 没有，全靠 `np.asarray` 自己崩 ——
|
||||
`normalize('abc')` 抛 numpy 的 `ValueError`（不是 §4.7 要的 `TypeError`），
|
||||
`normalize(None)` 更糟：**静默返回 NaN**。建议照 `standardize` 的元组抄一份守卫，三处统一。
|
||||
- **要不要收 `DataFrame`**：`normalize(df)` 现在能跑，但返回 ndarray、**列名丢了**；
|
||||
`standardize(df)` 直接 `TypeError`。`load_table` 出来的就是 DataFrame，
|
||||
建议三个函数都收 DataFrame、按列处理、并保持 DataFrame 返回（列名留着才好回填原表）。
|
||||
- **显式 `offset` 没校验**：`log_transform(x, offset=-10.0)` 静默返回 NaN（`np.log` 负数 + RuntimeWarning）。
|
||||
要么校验（`x + offset <= 0` 就抛 `ValueError`），要么在 docstring 里写清"由调用方保证"。
|
||||
- **常量列行为写进 docstring**：行为已被测试钉住（决策 34），但 docstring 还是空白。
|
||||
2. 四个函数的 docstring 都缺 `Parameters` / `Returns` / `Raises`（§4.7 硬要求）。
|
||||
上面 4 点定了之后一次补齐 —— 现在补也会因为口径未定而要返工。
|
||||
3. `stats.describe` + `stats` 其余函数：`examples/00_quickstart.py` 与
|
||||
`examples/01_clean_and_describe.py` 末尾的 `TODO(L0)` 都在等它。
|
||||
4. L0 跑通后，找一道真题（建议 2025 C）走完整流程，反向沉淀函数。
|
||||
Reference in new issue
Block a user