scientific-visualization

科学可视化

在优化外观之前，先构建能够保留科学含义的图形。将通用原则与过时的出版商规则区分开来，保留原始数据和变换过程，冗余地使用颜色，并检查交付的文件，而不是盲目信任绘图默认值。

不可妥协的护栏

• 绝不要为了提高图形效果而更改、隐藏、编造或选择性地增强数据。
• 保留原始表格/图像、排除项、缺失值编码、分析代码、归一化、分箱、图像调整和随机种子。
• 不要推断期刊要求。确定确切的期刊、文章类型、图形类型和投稿阶段；核实其现行的官方指南。
• 不要声称某个调色板、DPI 值、格式或自动化报告能使图形具备可访问性或符合期刊要求。
• 不要静默连接缺失的观测值、压制不便展示的点、将图像上采样得仿佛细节增加，或调整坐标轴/双轴以夸大结论。
• 将交互式输出和静态输出保留为不同的交付物。交互式悬停不能替代标签、替代文本、键盘访问、可访问的数据表或静态回退方案。

阅读 references/publication_guidelines.md 了解欺骗性编码和诚信检查。只有在目标和阶段已知后，才阅读 references/journal_requirements.md。

工作流

1. 定义证据和目的地

记录：

• 受众和媒介：稿件、网页、幻灯片、海报、补充材料；
• 确切的出版商/期刊、文章类型、投稿阶段和预期最终宽度；
• 变量语义、单位、样本/重复结构、缺失/删失值；
• 估计量和不确定性定义；
• 变换：过滤、聚合、归一化、平滑、分箱、图像处理；
• 源数据路径/标识符和输出溯源。

如果要求未知，创建一个临时的通用图形，并将所有出版商选择标记为待核实。

2. 选择诚实的编码

优先使用公共刻度上的位置。在编码之前，检查：

• 条形/面积： 通常包含零，因为长度/面积是从基线开始测量的。
• 点/线： 非零范围可能是有效的；显示上下文并披露截断。
• 不确定性： 指明 SD、SE、CI、百分位数、后验或另一个区间；说明 n 和重复单位。
• 原始观测值： 在可行时显示它们；不要让抖动模糊类别/数值。
• 缺失数据： 区分缺失、零、删失和排除；使用间隙或明确的模型/插值样式。
• 面积/体积： 缩放面积/体积，而不是半径/直径；避免装饰性 3D。
• 对数轴： 标注底数/变换，并声明如何处理零/负值。
• 分箱/平滑： 记录边界、带宽/窗口、方法和敏感性。
• 归一化： 说明公式/参考，并在比较的面板之间保持范围一致。
• 双轴： 优先使用对齐的面板；如果不可避免，说明单位的合理性，并且不要人为制造表观相关性。
• 图像： 保留原始图像，披露全图调整，显示比例尺，并避免裁剪/擦除背景。

3. 在设计阶段就纳入可访问性，而不是事后补救

• 使用颜色加上标记、线型、阴影线、直接标签或面板分隔。
• 根据数据语义选择定性、顺序、发散或循环颜色。
• 在渲染尺寸下审核前景/背景对比度。
• 明确显示缺失值和超出范围的值。
• 为复杂图形提供替代文本、更长的描述，并为网页交付提供底层数据。
• 将 WCAG 2.2 视为网页指南：普通文本 4.5:1，大文本 3:1，理解所必需的图形对象 3:1；颜色不能是唯一的线索。适用性和例外情况很重要。

参见 references/color_palettes.md。灰度屏幕很有用，但不是完整的色觉或可访问性测试。

4. 使用作用域样式实现

使用 Matplotlib 的面向对象 API 和临时样式上下文：

import matplotlib.pyplot as plt

from style_presets import style_context

with style_context("default", palette_name="okabe_ito_on_white"):
    fig, ax = plt.subplots(
        figsize=(89 / 25.4, 60 / 25.4),
        layout="constrained",
    )
    ax.plot(x, y, marker="o", label="Observed")
    ax.set(xlabel="Time (hours)", ylabel="Response (unit)")
    ax.legend()

layout="constrained" 支持颜色条、嵌套 GridSpec、子图和 subplot_mosaic。之后不要调用 tight_layout()；它会禁用受约束布局。

如需精确的物理尺寸，除非有意更改页面尺寸，否则不要使用 bbox_inches="tight"。

颜色归一化

import matplotlib as mpl

norm = mpl.colors.TwoSlopeNorm(vmin=-2, vcenter=0, vmax=5)
cmap = mpl.colormaps["RdBu_r"].with_extremes(bad="#777777")
image = ax.imshow(values, norm=norm, cmap=cmap, interpolation="nearest")
fig.colorbar(image, ax=ax, label="Change (unit)")

仅当 LogNorm、CenteredNorm、SymLogNorm、BoundaryNorm 或 TwoSlopeNorm 的映射符合科学含义时，才使用它们。

Seaborn

Seaborn 0.13.2 使用当前的 errorbar API：

sns.lineplot(
    data=frame,
    x="time",
    y="response",
    hue="treatment",
    style="treatment",
    markers=True,
    errorbar=("ci", 95),
    n_boot=5000,
    seed=20260723,
    ax=ax,
)

坐标轴级函数适用于自定义 Matplotlib 布局；图级函数会创建自己的图形／分面。不要将 Seaborn 的内部绘图元素列表当作稳定 API 来自定义。

Plotly

• 使用 write_html() 实现交互，使用 write_image()／plotly.io.write_images() 生成静态输出。
• Kaleido 1.3.0 需要 Chrome／Chromium；它不再捆绑 Chrome。
• 当前支持的静态格式：PNG、JPEG、WebP、SVG、PDF。EPS 仅支持 Kaleido v0。
• 不要传入已弃用的 engine=，也不要使用 Orca／plotly.io.kaleido.scope。
• width、height 和 scale 控制像素；scale=3 并不天然等于“300 DPI”。
• WebGL 绘图轨迹会在 PDF／SVG 中嵌入栅格内容。
• 若图形引用 MathJax／topojson／瓦片，要实现完全离线导出，必须使用本地外部资源。

5. 明确导出并记录来源信息

from figure_export import export_figure

report = export_figure(
    fig,
    "outputs/figure1",
    formats=["pdf", "png"],
    dpi=600,
    bbox_inches=None,  # preserve figure page dimensions
    provenance={
        "raw_data": "data/source.csv",
        "transformations": ["predeclared QC filter", "group mean"],
        "uncertainty": "95% bootstrap CI; seed 20260723",
        "missing_data": "retained as gaps",
    },
    write_manifest=True,
)

导出器会拒绝隐式覆盖，以原子方式写入，保留嵌入栅格的矢量 DPI，使用 TIFF LZW，并可使用 PDF／PS Type 42 字体。它不会验证科学内容或出版方的验收要求。

要使用可编辑字体：

• PDF／PS Type 42 会嵌入 TrueType 字体。
• svg.fonttype="none" 会保留可编辑／可搜索的文本，但不会嵌入字体；显示效果取决于已安装的字体。
• svg.fonttype="path" 会将字形转换为路径以保留外观，但文本将无法编辑／搜索。

除非需要透明背景，否则请使用明确的不透明背景；与其他背景混合会改变感知对比度。

6. 检查、比较和审阅

1. 检查文件元数据。
2. 审核调色板的对比度／灰度区分度。
3. 与注明日期的出版方快照进行比较。
4. 在稿件／网页环境中按最终尺寸查看。
5. 手动审阅字体、嵌入的栅格图像、裁切、图例、比例尺、图像完整性、说明文字、替代文本和源数据。
6. 上传前立即重新检查目标期刊的实时页面。

固定快照

示例和冒烟测试使用截至 2026-07-23 的直接依赖版本固定项：

uv run --isolated --no-project --python 3.13 \
  --with "matplotlib==3.11.1" \
  --with "seaborn==0.13.2" \
  --with "plotly==6.9.0" \
  --with "kaleido==1.3.0" \
  --with "pillow==12.3.0" \
  --with "pypdf==6.14.2" \
  python your_figure.py

这是注明日期的直接依赖快照，不是传递依赖锁定文件。要精确重现，请使用项目的 uv 锁定文件；此技能不会附带依赖锁定文件。

捆绑的 CLI

所有辅助工具均可确定性运行、无需联网、设有边界限制，并会在相关情况下拒绝符号链接输入／目标；除非明确指定 --force，否则会拒绝覆盖。

检查栅格／矢量元数据

uv run --isolated --no-project --python 3.13 \
  --with "pillow==12.3.0" \
  python scripts/image_metadata.py figure.tiff \
  --format tiff --mode RGB --min-dpi 300 --target-width-mm 85 \
  --alpha-policy forbid

支持栅格图像（Pillow）、SVG、PDF（pypdf）和 EPS／PS。报告尺寸、DPI／有效 DPI、模式、Alpha、ICC 配置文件是否存在、压缩方式、页面尺寸，以及保守检测到的 PDF 首页字体资源。它不会检查矢量容器中的每个嵌入栅格图像。

审核调色板对比度和灰度

uv run --isolated --no-project --python 3.13 \
  python scripts/palette_audit.py \
  --palette okabe_ito_on_white \
  --background FFFFFF \
  --role graphical

报告精确的 WCAG sRGB 对比度，以及成对的 CIE L* 灰度筛查结果。灰度阈值是启发式指标，并非标准。

规划／筛查出版方导出要求

uv run --isolated --no-project --python 3.13 \
  python scripts/export_plan.py \
  --publisher nature \
  --figure-type combination \
  --width single \
  --phase final

添加 --input figure.pdf 可筛查机器可读属性。配置文件是截至 2026-07-23 访问的官方来源快照，并非自动合规规则。

预览样式

uv run --isolated --no-project --python 3.13 \
  --with "matplotlib==3.11.1" \
  python scripts/style_preview.py \
  --output outputs/style-preview \
  --style default \
  --palette okabe_ito_on_white \
  --formats png,svg

检查／写入样式并对导出进行冒烟测试

uv run --isolated --no-project --python 3.13 \
  python scripts/style_presets.py --list
uv run --isolated --no-project --python 3.13 \
  python scripts/style_presets.py --show nature
uv run --isolated --no-project --python 3.13 \
  --with "matplotlib==3.11.1" \
  python scripts/figure_export.py --demo outputs/export-smoke --manifest

资源

• assets/publication.mplstyle：通用印刷起始样式。
• assets/nature.mplstyle：过时的旗舰期刊 Nature 视觉起始样式，不是合规预设。
• assets/presentation.mplstyle：适用于较大投影屏幕的样式。
• assets/color_palettes.py：可导入的 Okabe-Ito 和 Paul Tol 色值及其元数据。
• assets/publisher_profiles.json：带日期、机器可读的规划快照。

Matplotlib 样式文件中的十六进制颜色不带 #，因为在 .mplstyle 解析中，# 表示注释的开头。

参考资料

• references/publication_guidelines.md：诚信、误导性编码、无障碍，以及静态／交互式输出。
• references/color_palettes.md：调色板语义、精确色值、WCAG 对比度、灰度注意事项及色彩管理。
• references/journal_requirements.md：按阶段整理的官方出版方快照。
• references/matplotlib_examples.md：当前可运行的 Matplotlib／Seaborn／Plotly 示例。
• references/sources.md：官方 URL、日期、版本及研究依据。

最终检查清单

• 已保留原始数据／图像及转换代码。
• 已明确说明缺失值、排除项、分箱、归一化及不确定性。
• 基线、刻度、范围以及面积／体积编码均准确呈现。
• 颜色提供了冗余编码，并已检查渲染后的对比度。
• 在适用情况下，图表附有无障碍描述／数据替代形式。
• 导出后已检查物理尺寸、DPI、格式、字体、透明度及文件大小。
• 已针对具体期刊和阶段核实出版方的规则。
• 未将任何自动生成的报告宣称为科学、无障碍或合规认证。

相关技能

• matplotlib：支持全面自定义的底层绘图库。
• academic-plotting：根据研究背景为 ML 论文生成符合出版质量要求的图表。
• seaborn：与 pandas 集成的统计可视化工具。