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 后端）
75 lines
2.0 KiB
Python
75 lines
2.0 KiB
Python
"""图表导出。
|
||
|
||
工具箱的最终消费者是**论文**，所以这一层不是"附赠功能"，
|
||
而是原建议里最被低估的部分（它只给了一句 `save_figure`）。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from pathlib import Path
|
||
from typing import Any
|
||
|
||
__all__ = ["save_figure", "save_table"]
|
||
|
||
|
||
def save_figure(
|
||
fig: Any,
|
||
path: str | Path,
|
||
dpi: int = 300,
|
||
formats: tuple[str, ...] = ("png", "pdf"),
|
||
bbox_inches: str = "tight",
|
||
transparent: bool = False,
|
||
) -> list[Path]:
|
||
"""保存图，默认同时出 PNG（预览用）和 PDF（LaTeX 插图用）。
|
||
|
||
Parameters
|
||
----------
|
||
formats:
|
||
美赛论文如果用 LaTeX 排版，**矢量图（PDF/EPS）比 PNG 清晰得多**，
|
||
所以默认两种都出。
|
||
|
||
Returns
|
||
-------
|
||
实际写出的文件路径列表。
|
||
|
||
Notes
|
||
-----
|
||
建议配合项目的 figure 目录约定：`figures/fig{序号}_{短名}.pdf`，
|
||
图号与正文引用一一对应，最后核对时不容易错位。
|
||
"""
|
||
# TODO(L0)
|
||
raise NotImplementedError
|
||
|
||
|
||
def save_table(
|
||
df: Any,
|
||
path: str | Path,
|
||
fmt: tuple[str, ...] = ("csv", "latex", "markdown"),
|
||
caption: str | None = None,
|
||
label: str | None = None,
|
||
float_format: str = "%.4f",
|
||
index: bool = True,
|
||
) -> list[Path]:
|
||
r"""导出结果表，默认同时出 CSV + LaTeX + Markdown。
|
||
|
||
这是**节省时间最多的一个函数**：`compare_models`、`parameter_sweep`、
|
||
`topsis` 的结果都能直接 `save_table(r.data, "tab3_model_compare")`，
|
||
然后把 LaTeX 片段粘进论文，不用手工敲表格。
|
||
|
||
Parameters
|
||
----------
|
||
caption / label:
|
||
写进 LaTeX 的 `\caption{}` 与 `\label{}`，
|
||
表号与正文 `\ref{}` 的对应关系就不会断。
|
||
|
||
Returns
|
||
-------
|
||
实际写出的文件路径列表。
|
||
|
||
Examples
|
||
--------
|
||
>>> paths = save_table(df, "tables/tab2", caption="模型对比") # doctest: +SKIP
|
||
"""
|
||
# TODO(L1)
|
||
raise NotImplementedError
|