guzhujushi/MCM-ICM_Toolkit
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c2595b6d077932903ccce4021033b7608393a43e
MCM-ICM_Toolkit/CHANGELOG.md
T
guzhujushi c2595b6d07 feat(data): clean.py 四个函数落地；补测试、docstring 与 ruff 清理 
src 由用户本人写（决策 25），Codex 只做审查、补测试与文档。

实现（用户）：
- clean_missing：按行/列删缺失过多的行，threshold 用 math.ceil 算 min_non_na
  （3 列、阈值 0.5 时必须是 2；写 int() 截断会漏删）
- impute_missing / detect_outliers / winsorize（原属 L1，顺手落地）

Codex 改的轻度项：
- 按 §4.7 给四个函数补 Parameters / Returns / Raises（与 io.py 同一套 numpydoc 格式）
- ruff 6 -> 1：导入分组（I001）、elif 链改 if 加末尾无条件 return（RET505/RET503）、
  去掉多余 f 前缀（F541）、删掉只会被覆盖的 mask 初始化、去掉行尾空白（W293）
- tests/test_data.py：新增 13 条 clean 行为测试 + 7 条 xfail

结果：
- pytest 53 passed / 42 skipped / 7 xfailed（此前 40 / 44 / 0）
- pyright 0 errors, 0 warnings
- ruff 剩 1 条 SIM102，就在 detect_outliers 里那段待修的代码中，删掉即全绿

已知未修（详见 STATUS.md「下一步」）：
- detect_outliers 三个 bug：threshold 范围校验放错函数（iqr 分支 UnboundLocalError、
  zscore 默认 3.0 被 [0,1] 拒掉）、quantile 在含文本列的表上崩、
  is_series / is_ld_array 在 data 已转 DataFrame 之后才判断，因此永远为 False
- winsorize 同样在含文本列的表上崩
- impute_missing 的 mode 分支就地修改调用方的表
2026-10-02 15:04:13 +08:00

92 lines
6.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 更新日志
格式参考 [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
### 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 的承诺对齐。
### Added
- `docs/02-architecture.md` §4.7「类型约定」：注解要写全、numpy 标量的判断写法、
非法类型必须抛 `TypeError`。配套在 `docs/03-roadmap.md` 的开发纪律里加了指针。
- `docs/dev/personal-pitfalls.md`：个人易错点清单，**只追加、不通读**
### Added
- `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）。
### Changed
- `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）。剩下的 1 条 SIM102 就在下面 Notes 那条待修的代码里，删掉它即全绿。：分析器会去 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。
### 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` 都还没能在含文本列的赛题表上跑通：分位数必须限制在数值列。
- `impute_missing` 的 mode 分支会**就地修改**调用方的 DataFrame，其余四个分支都返回新表。
- 已知缺口：
- 除 `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
- 项目初始化，包结构落盘（实现为空）。
Reference in new issue View Git Blame Copy Permalink