refactor(core): 统一入口 as_array —— 六处手抄的入参处理收成一处（决策 44/45）
## 新增 - `core.validate.as_array(x, *, numeric_only=True, dtype=float, ndim=None) -> (arr, kind)`： 一次做完"类型白名单 + 转 ndarray + 报告原来是什么容器"。`kind` 是 `"frame"` / `"series"` / `"array"`。 - **还原不代做**（用户拍的板）：`describe` / `correlation_*` / `confidence_interval` / `t_test` 的 输出天生与输入不同形，统一还原只会重演易错点 14；所以只报告 `kind`，调用方自己手写三行。 - `core/__init__.py` 导出 `as_array`；`check_array`（L1 未实现）的 docstring 注明实现时复用它。 - 入口三条硬规矩：**默认绝不摊平**（要摊平显式 `ndim=1`）；**不删缺失值**； `numeric_only` 按"输出是否与输入同形"选，不按喜好选。 ## 去重 - `normalize` / `standardize` / `log_transform` / `zscore` / `confidence_interval` / `t_test` 六处手抄的 `isinstance(x, pd.DataFrame)` / `select_dtypes` / `np.asarray` 全部删掉，各剩 1 行入口。 - `data/transform.py` 的 `_NUMERIC_TYPES` 白名单连同 3 份副本一起删除 —— 这类判断原来散在 **5 个文件 31 处**。 - `transform` 的三个函数走 `numeric_only=False`：它们的输出必须与输入同形，跳过非数值列会少列。 ## 修掉 - `zscore` / `normalize` / `standardize` / `log_transform` 的 Series 分支**补回 `name`** —— 此前 `pd.Series(result, index=...)` 会把 `name` 丢掉，管道里 `concat` 会变成无名列。 - "容器对、内容转不成 float"的错误类型，由 numpy 的 `ValueError` 统一成 `TypeError`（决策 45，**待确认**）。 ## 测试与文档 - `tests/test_core.py` 新增 `TestAsArray` 8 条：五种容器的 kind、默认只取数值列、 `numeric_only=False` 遇文本报错、默认不摊平、`ndim=2` 只校验不重塑、白名单外一律 TypeError、 **保留 NaN**、`dtype=None` 保持原 dtype；`tests/test_stats.py` 新增 1 条（Series 保住 index/name）。 - 全量 **171 条：134 passed / 37 skipped / 0 xfail**；ruff 0，pyright 0；`examples/01` 跑通（exit 0）。 - `docs/02-architecture.md` 新增 §4.8「入口只有一个：`core.validate.as_array`」，目录树补 `as_array`； `docs/03-roadmap.md` 的 L1 表下补说明；`docs/dev/personal-pitfalls.md` 新增第 16 条并把索引补到 16。 - `STATUS.md`：决策 44 / 45，E 节记 as_array，「下一步」第 7 条列 3 个待拍板口径。 ## 待用户拍板（Codex 一律未代选） - `int` / `float` 标量是否继续留在白名单（现在会产出 0 维数组，`axis=0` 的算法照样炸）。 - "内容转不成 float" 该用 `TypeError`（现状）还是 `ValueError`。 - 要不要让 `as_array` 顺带返回选中的列（改三元组），省掉 `frame` 分支重写 `select_dtypes`。
This commit is contained in:
guzhujushi committed
1 parent
f95fbd2726
commit
b70a96dd0c
12 files changed
+356
-101
No files matched your search
@@ -193,13 +193,25 @@
|
||||
- 测试 `tests/test_stats.py`：**+10 条（36 → 46）**，含把原先挂着 skip 的 `test_confidence_interval_matches_scipy` 转正；
|
||||
对照一律用解析式（z 公式、Welch `df` 公式、`t = (mean − value)/(s/√n)`），不拿实现对自己
|
||||
- ⚠️ **`t_test` 还有 3 个口径待用户拍板**（Codex 未改，见「下一步」第 6 条）
|
||||
- [x] **`core/validate.py` 的 `as_array`**（统一入口，2026-10-03 落地）
|
||||
- 用户提出"每个函数都抄一遍入口/校验/交换太麻烦"。结论：**入口能统一，出口不能一刀切** ——
|
||||
还原要求"输出与输入同形"，而 `describe` / `correlation_*` / `confidence_interval` / `t_test`
|
||||
的输出形状天生和输入不同，硬套只会重演易错点 14。
|
||||
- 契约：`as_array(x, *, numeric_only=True, dtype=float, ndim=None) -> (arr, kind)`，
|
||||
`kind` 是 `"frame"` / `"series"` / `"array"`（**只报告原类型，还原由调用方手写**，用户拍的板）。
|
||||
- 覆盖掉重复：原先 `select_dtypes` / `isinstance(..., pd.DataFrame|Series)` 散在 **5 个文件 31 处**；
|
||||
现在 `normalize` / `standardize` / `log_transform` / `zscore` / `confidence_interval` / `t_test`
|
||||
各只剩 1 行入口。`data/transform.py` 的 `_NUMERIC_TYPES` 白名单连同 3 份副本一起删掉。
|
||||
- 两条硬规矩：**默认绝不摊平**（要摊平显式 `ndim=1`）；**不删缺失值**（删缺失是各函数的语义，
|
||||
见决策 45 与易错点 15）。`numeric_only` 按"输出是否与输入同形"选，不按喜好选（决策 44）。
|
||||
- `check_array`（L1，未实现）实现时直接复用 `as_array`，一份实现两张脸
|
||||
- [ ] 剩余 3 项：`bootstrap_ci` `monte_carlo` `save_figure`
|
||||
|
||||
### 验证结果
|
||||
|
||||
| 检查 | venv | conda `mcm-toolkit` |
|
||||
|---|---|---|
|
||||
| `pytest` | 见下（单列） | **125 passed, 37 skipped（0 xfail）** |
|
||||
| `pytest` | 见下（单列） | **134 passed, 37 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` | 跑通 | — |
|
||||
@@ -209,13 +221,14 @@
|
||||
（修配置之前是 17 errors，全是"无法解析导入 numpy / pandas"，见决策 29 与
|
||||
`docs/04-environment.md` 坑 7）
|
||||
- base 亦已复核：numpy 2.4.6 / scipy 1.18.1 / pandas 3.0.6（与两套环境一致）
|
||||
- **162 条用例：125 passed / 37 skipped / 0 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` 46、
|
||||
- **171 条用例：134 passed / 37 skipped / 0 xfail**。收集数按文件：`test_data.py` 52、`test_api_surface.py` 20、
|
||||
`test_core.py` 23、`test_solve.py` 9、`test_viz.py` 8、`test_decision.py` 7、`test_stats.py` 47、
|
||||
`test_models.py` 5
|
||||
- **`xfail` 再次清零**：`correlation_matrix` 的契约冲突已按方案 A 解决（决策 41），那条用例转正
|
||||
- 上一轮那 7 条 xfail 已全部转正，决策 30 那套信号（XPASS → 摘 mark）跑完过一个完整闭环
|
||||
- `examples/01_clean_and_describe.py` 实测跑通（exit 0）；`00_quickstart.py` 仍等 `stats` / `viz`
|
||||
- 37 条 skip 是等实现的算法（`train_test_split`、`bootstrap_ci`、`monte_carlo`、`anova`、`fit_distribution` 等）
|
||||
- 37 条 skip 是等实现的算法（`train_test_split`、`bootstrap_ci`、`monte_carlo`、`anova`、`fit_distribution` 等）；
|
||||
`TestValidate` 的 4 条仍挂着 —— `check_*` 还是 `NotImplementedError`，但它们实现时应当直接复用 `as_array`
|
||||
- **本轮回归（已修）**：`transform.py` 上一版有 3 处真 bug —— 修前 **7 failed / 75 passed**，
|
||||
且 pyright 在同一处报 `reportArgumentType`。**不是静态误报**：pyright CLI 复现 + 测试真红。
|
||||
结论：见到红线先跑 CLI 与 `pytest`，**不许直接挂 `# type: ignore`**（见个人易错点 10）
|
||||
@@ -293,6 +306,10 @@
|
||||
原码把三种 method 的区间**无条件**夹进 `[0, 1]`，且 `min` / `max` 参数写反（见易错点 15），实测把身高均值区间下界压成 `0.0`。均值区间的量纲本来就不在 `[0, 1]` 里；只有比例 `p ± z·√(p(1−p)/n)` 的边界才有意义。**Codex 代改、待用户确认** —— 若原意是"什么区间都夹"，改回 `_clip` 一行即可 |
|
||||
| 43 | scipy 检验结果的**统计量**也走 `_statistic(result: Any) -> float` 助手，与决策 40 的 `_pvalue` 成对 |
|
||||
`TtestResult` 与 `PearsonRResult` 同源（`_make_tuple_bunch` 运行时拼类），存根里 `.statistic` / `.pvalue` 都没有。用户报的「307 / 308 行报错」就是这两处，**不是真 bug**（探针实测取值正常）。见 `docs/04-environment.md` 坑 10 |
|
||||
| 44 | 所有收数值的函数**统一从 `core.validate.as_array` 进**；**还原不代做**，调用方按返回的 `kind` 自己手写 |
|
||||
用户 2026-10-03 提"每个函数都抄一遍入口/校验/交换太麻烦"。能统一的只有**入口**：出口要求"输出与输入同形"，而 `describe` / `correlation_*` / `confidence_interval` / `t_test` 天生不同形，硬套会重演易错点 14。用户明确"不要三个函数""转换回去自己手打"，所以 `as_array` 只返回 `(arr, kind)`，`ArraySpec` / `restore` 都不做。`numeric_only` 默认 `True`（用户拍的板），但**按输出契约选**：同形函数必须显式 `False` |
|
||||
| 45 | `as_array` **不删缺失值**；容器类型/内容转换失败**统一抛 `TypeError`** |
|
||||
删缺失是**语义**（`df.corr` 成对删、`describe` 整列统计、`paired=True` 的 t 检验必须成对删），在入口层删掉就把行对应关系永久丢了 —— 这正是 `t_test` 待拍板的口径之一。错误口径统一为 `TypeError` 是**Codex 代选、待用户确认**：`normalize(含文本列的表)` 原先由 numpy 抛 `ValueError`，现在是 `TypeError`（内容转不成 float）；`describe` 的 `weights` 同类情况目前仍抛 `ValueError`（决策 39 说不统一就列出来） |
|
||||
`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 |
|
||||
@@ -321,3 +338,12 @@ docstring 与 `test_describe_reports_expected_keys` 早就写死了这个方向
|
||||
- **④ `t_test(DataFrame)` 会把所有数值列摊平成一个样本**（已写进 `Notes`）。
|
||||
多列不同量纲（`gdp` + `pop`）会被混在一起，而且**没法**拿"一张表里两列"当两组比。
|
||||
要不要改成：多数值列的 DataFrame 直接 `ValueError`、强制先自己取列？
|
||||
|
||||
7. **`as_array` 落地后留下的 3 个小口径（Codex 没代选，按决策 39）**：
|
||||
- `int` / `float` 标量还在白名单里（为兼容 `normalize` / `standardize` / `log_transform`
|
||||
三个 docstring 写的"数值型标量"）。但标量进来是 **0 维数组**，`axis=0` 的算法照样炸 ——
|
||||
要不要把标量摘掉、同时改三处 docstring？
|
||||
- 内容转不成 float 时统一抛 `TypeError`（决策 45）—— `normalize(含文本列的表)` 原来抛 `ValueError`。
|
||||
要不要改回 `ValueError`（"取值问题"）？
|
||||
- 现在 `kind == "frame"` 时你要自己再写一遍 `x.select_dtypes(include=[np.number]).columns` 取列名。
|
||||
嫌烦的话可以让 `as_array` 顺带把选中的列返回（改成三元组），一句话的事。
|
||||
Reference in new issue
Block a user