fix(stats): correlation_matrix 修硬 bug，两处 pyright 报错按坑 8/10 正经修（无 ignore）
用户报的是"63 行 p 值赋值报错"。查下来：63 行运行完全正常（p 是 np.float64），
pyright 那条是 scipy 存根的缺陷。但顺着看发现了真正跑不起来的第 41 行。
correlation_matrix:
- 硬 bug: `if numeric_cols == 0` 拿 Index 和标量比 -> 得到布尔数组。
0 列时静默不报错、1 列时碰巧能跑、>=2 列直接 ValueError 崩（而 >=2 列正是常见情况）。
改成 len(numeric_cols) == 0，并加回归用例
- pyright 两处报错都不是运行时问题，且一处 # type: ignore 都没挂:
- data[numeric_cols] 是坑 8 的 DataFrame | Series 重载 -> cast 收窄
- `_, p = stats.pearsonr(...)` 解包退化成 object（scipy 的返回值是 _make_tuple_bunch
运行时拼的类，存根里没有 pvalue）-> 新增 _pvalue(result: Any) -> float 小助手统一取，
后面 t_test / anova / chi_square_test 可复用
- method 校验提到最前；add_stars 的 elif 链改 if；清掉 3 条 F541 与 1 条 I001，ruff 归零
- 顺带记录两处待定：对角线被标了 ***；含 NaN 时 corr 成对删失而 pearsonr 不删，r 与 p 对不上
tests:
- test_correlation_matrix_diagonal_is_one 由 skip 改成 xfail(strict=False)（决策 30）:
契约要数值矩阵、实现返回带星标字符串表，口径待拍板
- 新增 2 条：多列数值表能跑通、非法输入报错
验证: pytest 105 passed / 38 skipped / 1 xfail；ruff All checks passed；pyright 0 errors。
docs: STATUS.md（correlation_matrix 进行中 + 决策 40 + 下一步 A/B/C 选项）；CHANGELOG；
personal-pitfalls 追加第 13 条（Index == 标量 得到布尔数组）；
docs/04-environment.md 追加坑 10（scipy 检验结果的存根缺陷）
This commit is contained in:
guzhujushi committed
1 parent
cfc1be31ca
commit
3432bf3e50
6 files changed
+215
-24
No files matched your search
@@ -154,13 +154,27 @@
|
||||
决策 26 说的就是这个，实现写完了却零覆盖），改成逐条 skip 未实现的 5 条，
|
||||
并新写 20 条 describe / zscore / 变异系数用例
|
||||
- [x] `examples/01_clean_and_describe.py`：填掉末尾的 `TODO(L0)`，加一段 `describe` 输出
|
||||
- [ ] 剩余 4 项：`correlation_matrix` `bootstrap_ci` `monte_carlo` `save_figure`
|
||||
- [ ] `stats/inference.py` 的 `correlation_matrix`（L0 第 9 项，**进行中**；**由用户本人实现**，Codex 审查 + 代修）
|
||||
- **硬 bug**：`if numeric_cols == 0:` 拿 `Index` 和标量比，得到的是布尔**数组** ——
|
||||
0 列时静默不报错、1 列时碰巧能跑、**≥2 列直接 `ValueError` 崩**；
|
||||
而"≥2 个数值列"正是最常见的情况，等于整个函数不可用。改成 `len(numeric_cols) == 0`（易错点 13）
|
||||
- pyright 的报错也都不是运行时问题：`data[numeric_cols]` 是坑 8 的 `DataFrame | Series` 重载
|
||||
（`cast` 收窄）；`_, p = stats.pearsonr(...)` 解包会退化成 `object` —— scipy 的返回值是
|
||||
`_make_tuple_bunch` 运行时拼的类、存根里看不到 `pvalue`（见 `docs/04-environment.md` 坑 10）。
|
||||
加了 `_pvalue(result: Any)` 小助手统一取 p 值，**一处都没挂 `# type: ignore`**
|
||||
- `method` 校验提到最前、清掉 3 条 F541 / 1 条 RET505 / I001，ruff 归零
|
||||
- **L0 契约待拍板**：返回值现在是**带星标的字符串表**（`1.000***`），
|
||||
而 docstring 契约与 L0 用例都要求**数值矩阵**（对角 = 1.0）；
|
||||
该用例已按决策 30 从 `skip` 改成 `xfail(strict=False)`，见「下一步」第 1 条
|
||||
- 另两处待确认：**对角线也被标了 `***`**（自己和自己相关不该有显著性星标）；
|
||||
`df_num` 含 NaN 时 `corr` 走成对删失、而 `pearsonr` 不删 → r 与 p 对不上
|
||||
- [ ] 剩余 3 项：`bootstrap_ci` `monte_carlo` `save_figure`
|
||||
|
||||
### 验证结果
|
||||
|
||||
| 检查 | venv | conda `mcm-toolkit` |
|
||||
|---|---|---|
|
||||
| `pytest` | 见下（单列） | **103 passed, 39 skipped（0 xfail）** |
|
||||
| `pytest` | 见下（单列） | **105 passed, 38 skipped（1 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` | 跑通 | — |
|
||||
@@ -170,13 +184,13 @@
|
||||
（修配置之前是 17 errors，全是"无法解析导入 numpy / pandas"，见决策 29 与
|
||||
`docs/04-environment.md` 坑 7）
|
||||
- base 亦已复核：numpy 2.4.6 / scipy 1.18.1 / pandas 3.0.6（与两套环境一致）
|
||||
- **142 条用例：103 passed / 39 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` 26、
|
||||
- **144 条用例：105 passed / 38 skipped / 1 xfail**。收集数按文件：`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` 28、
|
||||
`test_models.py` 5
|
||||
- **`xfail` 清零**：累计 7 条"契约已写进 docstring、实现没跟上"的用例全部转正，
|
||||
决策 30 那套信号（XPASS → 摘 mark）跑完了一个完整闭环
|
||||
- 目前 **1 条 xfail**：`test_correlation_matrix_diagonal_is_one` —— 契约（数值矩阵）与实现（带星标字符串表）冲突，口径待拍板
|
||||
- 上一轮那 7 条 xfail 已全部转正，决策 30 那套信号（XPASS → 摘 mark）跑完过一个完整闭环
|
||||
- `examples/01_clean_and_describe.py` 实测跑通（exit 0）；`00_quickstart.py` 仍等 `stats` / `viz`
|
||||
- 39 条 skip 是等实现的算法（`train_test_split`、`describe`、`bootstrap_ci`、`monte_carlo` 等）
|
||||
- 38 条 skip 是等实现的算法（`train_test_split`、`describe`、`bootstrap_ci`、`monte_carlo` 等）
|
||||
- **本轮回归（已修）**：`transform.py` 上一版有 3 处真 bug —— 修前 **7 failed / 75 passed**，
|
||||
且 pyright 在同一处报 `reportArgumentType`。**不是静态误报**：pyright CLI 复现 + 测试真红。
|
||||
结论：见到红线先跑 CLI 与 `pytest`，**不许直接挂 `# type: ignore`**（见个人易错点 10）
|
||||
@@ -247,19 +261,26 @@
|
||||
| 38 | `coefficient_of_variation` 用 `σ / |mean|`（**用户本人改的**） |
|
||||
均值为负时 `σ/μ` 会给出负值，容易被读成"波动更小"，其实只是符号跟着均值走。取绝对值后 CV 恒非负。可比性仍只在均值远离 0 的比率尺度数据上成立（已写进 docstring 的 Notes） |
|
||||
| 39 | 工作约定：**语义 / 非法输入口径由用户拍板，Codex 只列选项与影响、不代选**；**ruff、`STATUS.md`、`CHANGELOG.md`、`tests/`、docstring 这类与算法无关的工程事务，Codex 顺手补掉** |
|
||||
| 40 | scipy 的检验结果统一走 `_pvalue(result: Any) -> float` 助手取 p 值，不逐处挂 `# type: ignore` |
|
||||
`PearsonRResult` / `SignificanceResult` 是 `_make_tuple_bunch` 在**运行时**拼出来的类，存根里没有 `pvalue` 字段：解包会退化成 `object`、属性访问会报"未知"。运行时完全正常（实测三个函数返回的都是 `np.float64`）。收成 `Any` 是**一处**收窄，调用点仍然干净；`# type: ignore` 要挂在每一处，且会连带关掉该行后面的检查。见 `docs/04-environment.md` 坑 10 |
|
||||
用户 2026-10-03 明确：没考虑到的非法情况"告诉我我自己改"——因为那是设计决策，得由写实现的人形成判断；而 lint / 进度板 / 测试这类机械活再由用户动手只是浪费。这条与决策 25 / 31 配套：25 定"谁写 src"，31 定"Codex 可改的 bug 范围"，39 定"非算法事务的默认归口" |
|
||||
docstring 与 `test_describe_reports_expected_keys` 早就写死了这个方向，实现里多做的 `.T` 是净负担 —— 且不是"风格不同"那么轻：转置后 `.loc[指标名] = <按变量索引的 Series>` 与列名零交集，pandas **不报错**、把四行整行填成 NaN。方向约定以"能按列名对齐"为准，见易错点 11 |
|
||||
原码写的是 `if offset > 0: raise`，把唯一合法的用例（正 offset 正好抬定义域）全拒了，报错文案却是"offset 必须大于 0"，自相矛盾。改成校验真正的前提：`log` 要求自变量取正。`offset=0` 对全正数据合法（`offset=None` 的自动分支本来就取 0）。**Codex 代选、待用户确认** —— 若原意是"只收正 offset"，改回即可 |
|
||||
## 下一步
|
||||
|
||||
1. **`correlation_matrix` 是 L0 里下一个该写的**（A 档，`stats/inference.py`）——
|
||||
写法和 `describe` 一样：先想"替代了哪段手写代码" → 先写一条会红的测试 → 再实现
|
||||
→ 补 `examples/` 一行（`docs/03-roadmap.md` §3.2）。
|
||||
2. 之后按 L0 剩余顺序推进：`bootstrap_ci`（**S 档，要写函数卡片**）→ `monte_carlo`（**S 档**）
|
||||
→ `save_figure`（A）。
|
||||
1. **`correlation_matrix` 的返回契约待你拍板**（这是 L0 第 9 项唯一还没定的地方）：
|
||||
现在返回的是**带星标的字符串表**（`1.000***`），方便直接贴论文；
|
||||
但 docstring 的契约与 L0 用例要的是**数值矩阵**（对角 = 1.0），两者只能留一个。
|
||||
三个选项：
|
||||
- **A（推荐）**：返回数值矩阵，另给一个 `correlation_table(corr, p)` 出星标字符串表
|
||||
—— 数值矩阵能做的事（挑高相关对、喂给聚类/PCA、画热力图）字符串表都做不了，
|
||||
而反过来随时能格式化。代价：多一个函数。
|
||||
- **B**：就返回字符串表，把 docstring 契约改掉、L0 用例改成断言 `1.000`。代价：丢数值能力。
|
||||
- **C**：返回数值矩阵，星标表挂到 `df.attrs["display"]` 之类的地方。代价：藏得深，不显式。
|
||||
顺带两处一并定了：**对角线不该带 `***`**；`df_num` 含 NaN 时 `corr` 成对删失但 `pearsonr` 不删，
|
||||
r 与 p 会对不上（要不要先 `dropna` 成对再算 p）。
|
||||
2. 之后 L0 剩余：`bootstrap_ci`（**S 档，要写函数卡片**）→ `monte_carlo`（**S 档**）→ `save_figure`（A）。
|
||||
3. L0 跑通后，找一道真题（建议 2025 C）走完整流程，反向沉淀函数。
|
||||
4. **三处口径已拍板**（2026-10-03）：
|
||||
- `log_transform` 的显式 `offset`：**按现状**（定义域前提校验，决策 35）✓
|
||||
- 非数值列：`describe` / `zscore` **默认丢掉**，与 `detect_outliers` 的"保留列、掩码恒 False"
|
||||
**不统一** —— 两者输出契约不同，理由见决策 37 ✓
|
||||
- 变异系数：已改用 `σ / |μ|`（决策 38）✓
|
||||
4. 已拍板的旧口径（留档）：`log_transform` 的 `offset` 维持现状（决策 35）；
|
||||
`describe` / `zscore` 默认丢掉非数值列（决策 37）；变异系数用 `σ / |μ|`（决策 38）；
|
||||
分工见决策 39。
|
||||
Reference in new issue
Block a user