guzhujushi
6eab0babde
实现（用户本人写）： - 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 个口径
150 lines
13 KiB
Markdown
150 lines
13 KiB
Markdown
# 更新日志
|
||
|
||
格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
|
||
版本号参考 [语义化版本](https://semver.org/lang/zh-CN/)。
|
||
|
||
## [Unreleased]
|
||
|
||
### Added
|
||
- 仓库骨架：`src/mcm_toolkit/` 7 个包（core / data / stats / models / solve / decision / viz）
|
||
- 顶层 `__init__.py` 只导出 7 个子包 + 8 个快捷函数，`__all__` 即公开 API 清单
|
||
- `core.Result`：唯一的结果对象（替代原建议里的 5 个 Result 类）
|
||
- `docs/01-suggestion-review.md`：对 ChatGPT 建库建议的审查与精简（14 包 → 7 包，~250 函数 → ~40）
|
||
- `docs/02-architecture.md`：包边界、`Result` / RNG / `fit-predict-score` 协议、依赖分层
|
||
- `docs/03-roadmap.md`：L0/L1/L2 分级 + **永久不做清单**
|
||
- `docs/04-environment.md`：conda / venv 配置与三个已踩的坑
|
||
- `docs/dev/function-card-template.md`：S 档算法的函数卡片模板
|
||
- `.venv`（基于 Anaconda base，`--system-site-packages`）+ 可编辑安装 —— 10.5 MB，离线可用
|
||
- conda 环境 `mcm-toolkit`（`D:\anaconda\envs\mcm-toolkit`）—— Python 3.13.15，含 SALib / pymoo / pyright
|
||
- `scripts/setup-conda.ps1` / `scripts/setup-venv.ps1` / `scripts/doctor.ps1`
|
||
- `environment.yml`：需联网时的精确复现方案
|
||
- `pyproject.toml`：核心依赖只 4 个，其余走 extras
|
||
- `docs/02-architecture.md` §4.7「类型约定」：注解要写全、numpy 标量的判断写法、
|
||
非法类型必须抛 `TypeError`。配套在 `docs/03-roadmap.md` 的开发纪律里加了指针。
|
||
- `docs/dev/personal-pitfalls.md`：个人易错点清单，**只追加、不通读**
|
||
- `data.clean`：四个函数落地（**由用户本人实现**）——`clean_missing`（L0 第 4 项）、
|
||
`impute_missing` / `detect_outliers` / `winsorize`（原属 L1，顺手写了）。
|
||
- `tests/test_data.py`：新增 13 条 clean 行为测试，覆盖 `clean_missing` 的阈值语义与轴向、
|
||
`impute_missing` 的 mean/ffill/mode 与全 NaN 列、`winsorize` 的分位点与异常类型。
|
||
- `tests/test_data.py`：另加 7 条 `xfail`，把**已知但未修的契约**钉在测试报告里（见 Notes）。
|
||
- `docs/algorithms/detect_outliers.md`：**第一张 S 档函数卡片**（roadmap §3.1 要求
|
||
约 15 张，这是第 1 张）。除模板九节外，额外记了三条容易踩的判断：为什么不返回 `Result`、
|
||
非数值列恒 `False` 的两条备选路各错在哪、以及 `ddof` 口径与 `stats.zscore` 不一致。
|
||
- `examples/01_clean_and_describe.py`：`load_table` / `save_table` / `clean_missing` /
|
||
`impute_missing` / `detect_outliers` / `winsorize` 六个函数的最小用法，实测跑通（exit 0）；
|
||
末尾留 `TODO(L0)` 等 `stats.describe`。
|
||
- `tests/test_data.py`：`data` 的 transform 段 **18 条用例** —— `normalize` 的三种 method、
|
||
`feature_range` 区间与两条校验、常量列不出 nan、docstring 那个 Examples 的精确值、按列语义；
|
||
`standardize` 的按列与 `ddof`（用解析关系钉住：`ddof=1` 时结果的 std = `sqrt((n-1)/n)`）；
|
||
`log_transform` 的定义域平移；`one_hot_encode` 的自动识别、`drop_first`、列不存在报错。
|
||
其中两条是把原先挂着的 `skip` 转为实跑（见坑 9 / 个人易错点 9）。
|
||
|
||
### Changed
|
||
- `core.get_rng` / `core.set_seed`：实现（L0 第 2 项）。`get_rng` 收 `int` / `np.integer` /
|
||
`Generator` / `None`，其余类型抛 `TypeError`；无参调用复用同一个会推进的共享生成器。
|
||
`set_seed` 同时覆盖 numpy 旧全局状态，让 sklearn / statsmodels 也可复现。
|
||
- `core.Result`：补上 `__repr__` 与 `summary()` 实现（L0 第 1 项落地）。
|
||
`repr` 紧凑单行且不打印 `data` 内容；`summary()` 输出可直接贴进论文的 Markdown 表格。
|
||
- `data.load_table`：实现（L0 第 3 项）。按扩展名分派 `.csv` / `.xlsx` / `.xls`；
|
||
`.csv` 默认做编码探测（utf-8 → utf-8-sig → gbk → gb18030），显式传 `encoding=` 时不再探测；
|
||
`na_values` 默认吃下空串 / `NA` / `N/A` / `#N/A` / `null` / `-`。
|
||
- `data.save_table`：实现（原属 L1，顺手落地）。按扩展名分派，父目录不存在时自动创建，
|
||
返回实际写入的 `Path`。
|
||
- `data.load_table` / `data.save_table`：docstring 补 `Parameters` / `Raises`
|
||
（`docs/02-architecture.md` §4.7 对每个公开函数的硬要求）。
|
||
- `data.load_table` 的返回注解 `Any` → `pd.DataFrame`，与 docstring 的承诺对齐。
|
||
- `data.clean`：docstring 按 `docs/02-architecture.md` §4.7 补全 Parameters / Returns / Raises
|
||
（Codex 代写，与 io.py 同一套 numpydoc 格式）。
|
||
- `data.clean`：ruff 从 6 条清到 1 条——导入分组（I001）、elif 链改 if 加末尾无条件 return
|
||
（RET505 / RET503）、去掉多余 f 前缀（F541）、删掉只会被覆盖的 mask 初始化（死代码）、
|
||
去掉行尾空白（W293）。
|
||
- `pyright` 报"无法解析导入 numpy / pandas"（17 errors）的原因：分析器会去 PATH 上找 python，
|
||
本机 PATH 上只有 Codex 运行时的 3.14 shim（无科学栈），且 pyright 不认
|
||
`pyvenv.cfg` 的 `include-system-site-packages`。
|
||
改为 `[tool.pyright]` 指定 `venvPath = "."` / `venv = ".venv"` /
|
||
`pythonVersion = "3.13"`，并让 `scripts/setup-venv.ps1` 往 `.venv` 里写一个
|
||
指向 base site-packages 的 `.pth`。pyright 17 errors → **0**。
|
||
详见 `docs/04-environment.md` 坑 7。
|
||
- `tests/test_data.py`：`df["b"].isna().all()` 的类型是 `Series | bool`，
|
||
直接当断言条件 pyright 会报"条件操作数无效"，外面套 `bool()`；
|
||
两条故意传错类型的用例加 `# type: ignore[arg-type]`。
|
||
- `data.save_table` 的后缀校验排在 `path.parent.mkdir(...)` **之后**，传 `.txt` 会先留下一个
|
||
空目录再抛 `ValueError`。改为**先校验、后副作用**，并加回归测试。
|
||
- `data/io.py` 里 `__all__` 与下一个 `def` 之间只有 1 个空行（PEP 8 要 2 个）。
|
||
- `tests/test_data.py` 顶上的**模块级** `pytestmark = pytest.mark.skip(...)` 会连带跳过同文件里
|
||
已经写好的函数，导致 `load_table` 零覆盖。改为逐条 skip 未实现的算法，并补 8 条 io 测试
|
||
（编码探测、NA 归一、后缀校验、缺文件报错、往返读写、类型校验）。测试数 31 → **39 passed**。
|
||
- 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，"），已修。
|
||
- `data.detect_outliers` 收尾（2026-10-02，**由用户本人实现**）：统计量（`quantile` /
|
||
`mean` / `std`）与掩码写入**都**收窄到数值列，含文本列的赛题表不再崩；
|
||
非数值列在掩码里恒 `False`（用户本人定的语义，见决策 32）。docstring `Notes` 补上这条语义。
|
||
- `data.detect_outliers` 里 `data=data.copy()` 是死代码：下面的 `to_frame()` / `pd.DataFrame()`
|
||
本来就返回新对象，函数全程也没原地改过 `data`，白白复制一份数据；而且它排在类型分派
|
||
**之前**，会把错误入参的报错从 `ValueError` 变成 `AttributeError`。已删。
|
||
- `data.detect_outliers`：删掉那行死代码后 pyright 反而报了 1 个真错 ——
|
||
`df[Index]` 被类型存根当成 `Series`，`.std()` 于是被判成标量、`std.replace(...)` 非法。
|
||
在取列子表处用 `cast(pd.DataFrame, ...)` 按运行时真值收窄。详见 `docs/04-environment.md` 坑 8。
|
||
- `tests/test_data.py`：`test_detect_outliers_survives_text_columns` 摘掉 xfail 并加强断言
|
||
（文本列必须恒 `False`）；新增 `test_detect_outliers_all_text_frame_returns_all_false`
|
||
钉住"整表没有数值列"这条边界。测试 **58 passed / 2 xfailed → 60 passed / 1 xfailed**。
|
||
- `docs/dev/personal-pitfalls.md`：追加第 8 条（限制掩码 ≠ 限制统计量）。
|
||
- `data.impute_missing` 的 mode 分支改为**返回新表**（原先 `data[col] = ...` 会就地改调用方的
|
||
DataFrame，另外四支都返回新对象）。最后一条 `xfail` 随之转正，**测试里 `xfail` 清零**。
|
||
- `data.detect_outliers` 补**入参类型校验**（§4.7：非法类型抛 `TypeError`，不静默兜底）：
|
||
接受 `DataFrame` / `Series` / `list` / `tuple` / `ndarray`。`tuple` 同时补进 `is_ld_array`，
|
||
与 `list` 同等对待；`dict` 不再被接受（以前靠 `pd.DataFrame()` 碰巧能过，见决策 33）。
|
||
- `tests/test_data.py`：摘掉最后一条 `xfail`（mode 就地改）并加强断言；新增 3 条
|
||
（非法类型抛 `TypeError`、元组按一维数组型处理、全 NaN 列与单元素列不抛异常）。
|
||
测试 **60 passed / 1 xfailed → 64 passed / 0 xfailed**。
|
||
- `data.transform` 四个函数实现（**由用户本人写**）：`normalize`（minmax / vector / max，均按列）、
|
||
`standardize`（按列，`ddof` 真的传下去）、`log_transform`（`offset=None` 时自动取 `1 - min(x)`）、
|
||
`one_hot_encode`。`data/` 下的 L0 至此结清。
|
||
- `data.transform`：Codex 清掉 5 条 ruff —— RET503（`normalize` 末尾缺无条件 `return`）、
|
||
F541（无占位符的 f-string）、RET504（多余的 `result` 中转）、RET505（`return` 后的 `elif`）、
|
||
SIM108（`log_transform` 的 if/else 改三元）。
|
||
- `data.transform.normalize`：`supported_method` 与 `feature_range` 的校验提到 `np.asarray` **之前**
|
||
（§4.7 的"守卫集中在开头"）；并修掉说反的报错文案 —— 条件是要求下界 < 上界，
|
||
原文却写"上界必须小于下界"，且 `TypeError` 那条用了无占位符 f-string。
|
||
- `data.transform.one_hot_encode`：自动识别类别列时显式加上 `'str'` / `'string'`。
|
||
原来只写 `['object', 'category']`，在 pandas 3 上是**已弃用路径**（每次调用发 `Pandas4Warning`），
|
||
未来会变成一列都选不中的**静默错误**。详见坑 9。
|
||
- 测试计数：**64 passed → 82 passed**（新增 18 条，另两条 skip 转为实跑），skip 42 → 40。
|
||
|
||
|
||
### Notes
|
||
- `detect_outliers` 原有的三个 bug 加一处设计空白**已全部收口**：`threshold` 范围校验挪进
|
||
`clean_missing`、`is_series` / `is_ld_array` 提到类型转换**之前**、统计量与掩码都限制在数值列、
|
||
非数值列恒 `False`（决策 32）、入参类型校验补上（决策 33）。
|
||
S 档卡片与 `examples/` 用法也已落地 —— `detect_outliers` 这条线**结清**。
|
||
- `transform.py` 还有 **4 个口径待定**，所以四个函数的 docstring 里 `Parameters` / `Returns` /
|
||
`Raises` 都还空着（§4.7 硬要求）：① 三个函数的入参类型策略不一致 —— `normalize` 没有守卫，
|
||
`normalize('abc')` 抛 numpy 的 `ValueError`、`normalize(None)` **静默返回 NaN**；
|
||
② 要不要收 `DataFrame`（`normalize` 收但丢列名、`standardize` 直接 `TypeError`）；
|
||
③ 显式 `offset` 没校验，`log_transform(x, offset=-10.0)` 静默返回 NaN；
|
||
④ 常量列行为已被测试钉住（决策 34）但没写进 docstring。见 `STATUS.md`「下一步」第 1/2 条。
|
||
- 已实现函数的 `examples/` 最小用法仍不全：`00_quickstart.py` 要等 `stats` / `viz`，
|
||
`Result` 的用法届时并进去。见 `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 顺序填实现。
|
||
- 已知缺口：`SALib`（Sobol/Morris）、`pymoo`、`pyright` 已装进 conda 环境 `mcm-toolkit`，`.venv` 里没有。
|
||
|
||
## [0.0.1] - 2026-10-01
|
||
|
||
### Added
|
||
- 项目初始化，包结构落盘（实现为空）。
|