guzhujushi
5319589dfd
审查并精简 ChatGPT 的建库建议后落地的第一版骨架，只定接口不写实现。 - 建议审查：14 个包 → 7 个；约 250 个函数 → 约 40 个；5 个 Result 类 → 1 个 （docs/01-suggestion-review.md） - docs/：架构、路线图（含永久不做清单）、环境、Git 工作流、函数卡片模板 - src/mcm_toolkit/：core / data / stats / models / solve / decision / viz 共 23 个模块，均为签名 + docstring + NotImplementedError - tests/：9 个文件，其中 test_api_surface.py 已通过（20 passed） - examples/ problems/ notebooks/ figures/ tables/ 骨架 - pyproject.toml（核心依赖 4 个 + 6 组 extras）、environment.yml - scripts/：setup-venv.ps1（ASCII + LF）、setup-conda.ps1、doctor.ps1 - 环境：.venv（system-site-packages）与 conda 环境 mcm-toolkit 均已建好， 数值栈版本与 base 完全对齐（numpy 2.4.6 / scipy 1.18.1 / pandas 3.0.6，MKL 后端）
80 lines
2.6 KiB
Python
80 lines
2.6 KiB
Python
"""绘图。
|
||
|
||
`plot` 是一个通用入口，按 `kind` 分派；三个专用图有真实的额外逻辑
|
||
（显著性星标、残差诊断、收敛曲线），所以单独保留。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from typing import Any
|
||
|
||
__all__ = ["plot", "plot_convergence", "plot_correlation_matrix", "plot_residuals"]
|
||
|
||
|
||
def plot(
|
||
x: Any = None,
|
||
y: Any = None,
|
||
kind: str = "line",
|
||
ax: Any = None,
|
||
labels: Any = None,
|
||
title: str | None = None,
|
||
xlabel: str | None = None,
|
||
ylabel: str | None = None,
|
||
**kwargs: Any,
|
||
) -> Any:
|
||
"""通用绘图入口。
|
||
|
||
Parameters
|
||
----------
|
||
kind:
|
||
`"line"` / `"scatter"` / `"hist"` / `"box"` / `"bar"` / `"heatmap"` / `"pie"`。
|
||
ax:
|
||
传入已有 axes 就在上面画（多子图场景）；`None` 时新建 figure。
|
||
|
||
Returns
|
||
-------
|
||
符合"创建—绘制—保存"三段的 `(fig, ax)`，交给 :func:`save_figure`。
|
||
|
||
Examples
|
||
--------
|
||
>>> fig, ax = plot([1, 2, 3], [1, 4, 9], kind="line") # doctest: +SKIP
|
||
"""
|
||
# TODO(L1)
|
||
raise NotImplementedError
|
||
|
||
|
||
def plot_correlation_matrix(data: Any, method: str = "pearson", annot: bool = True, significance: bool = True) -> Any:
|
||
"""相关矩阵热图。
|
||
|
||
`significance=True` 时在不显著的格子（`p > 0.05`）上打叉。
|
||
这比只画颜色有意义得多——**不显著的相关性画出来是误导**。
|
||
"""
|
||
# TODO(L1)
|
||
raise NotImplementedError
|
||
|
||
|
||
def plot_residuals(y_true: Any, y_pred: Any, n_features: int | None = None) -> Any:
|
||
"""残差诊断四联图：残差-拟合值、Q-Q 图、直方图、残差-序。
|
||
|
||
拟合完模型**第一件事就是看这个**：
|
||
* 残差-拟合值有漏斗形 → 异方差，考虑加权最小二乘或对数变换；
|
||
* Q-Q 图偏离直线 → 正态性假设不成立，区间估计要改用 bootstrap；
|
||
* 残差有周期性 → 漏了时间/结构项。
|
||
|
||
这三个诊断结论是论文"模型检验"一节的素材，比只报一个 R² 有说服力。
|
||
"""
|
||
# TODO(L1)
|
||
raise NotImplementedError
|
||
|
||
|
||
def plot_convergence(history: Any, ax: Any = None, labels: Any = None, log: bool = False, reference: float | None = None) -> Any:
|
||
"""收敛曲线。
|
||
|
||
`history` 可以是迭代轨迹数组、也接受 `Result.extras["history"]`
|
||
（`simulated_annealing` 与 `monte_carlo` 都会填这个字段）。
|
||
`reference` 传入解析解时会把真值画成虚线，
|
||
用于"MC 积分误差随 n 收敛"这类图——这是证明 `n` 选得合理的标准做法。
|
||
"""
|
||
# TODO(L1)
|
||
raise NotImplementedError
|