---
name: cell-visualization-code
description: >-
  生成、重构或审核科研可视化代码，支持 Python 的 Matplotlib/Seaborn 与 MATLAB。
  适用于用户要求按论文或报告规范编写绘图代码、统一多图样式、改造已有绘图脚本、
  适配 IEEE Transactions 或 Elsevier 等出版版式、校准最终物理尺寸、矢量导出或
  检查代码可复现性。保留数据、统计和科学含义，
  不用于从参考论文反向复现数据图、机制示意图、图片编辑或图像描摹。
metadata:
  compatibility: >-
    需要读取数据和代码、执行所选后端并查看实际输出的宿主。Python 路径通常需要
    Matplotlib；MATLAB 路径需要可用的 MATLAB。配置检查脚本仅依赖 Python 3.10+ 标准库。
  version: "1.1.0"
  language: "zh-CN"
---

# 科研可视化代码规范

把绘图代码做成可复现的科研产物，而不是一次性调图脚本。最终判断基于真实数据、实际运行结果和目标版面中的可读性。

## 路由与边界

先确定任务是新建代码、重构已有代码还是审核代码，并保留用户指定的后端。

- Python/Matplotlib/Seaborn：读取 [Python 规范](references/python-matplotlib.md)。
- MATLAB：读取 [MATLAB 规范](references/matlab.md)。
- 两条路径都读取 [共享代码合同](references/shared-contract.md)；选择字号和尺寸时读取 [版式策略与示例 profile](references/style-profiles.md)；准备交付时读取 [输出与验收](references/output-qa.md)。
- 目标为 IEEE Transactions 或 Elsevier 时，另读 [出版商 Profile](references/publisher-profiles.md)，并以具体期刊 Guide for Authors 覆盖通用值。
- 需要将参考论文图先用参考数据复现、通过门槛后再换用户数据时，改用 `cell-data-figure`。
- 需要生成机制图、图形摘要或概念示意图时，不使用本 Skill。
- 只处理 LaTeX 全文分页、浮动体和投稿材料时，改用 `cell-submission`。

用户只要求审核时不直接改文件；用户要求生成或修改时才写入代码。已有代码能局部修复就不整体换语言、换库或重写分析流程。

## 不可破坏的事实

1. 不改变观测值、分组、样本身份、单位、时间顺序、统计口径和缺失规则来改善外观。
2. 不从图片重建虚假原始点，不用随机数替代缺失实验数据，不复制参考图的 P 值、误差条或效应量。
3. 图中 n、误差、区间、显著性和比较对象必须能回到真实输入或已核验计算；设计信息不足时只做有边界的描述性图。
4. 用户提供的已有计算结果默认只可视化；除非任务要求，不在绘图脚本中重新训练模型、重新拟合主分析或隐式改变筛选。
5. 颜色不能成为唯一信息通道；同时使用线型、标记、标签、位置或面板结构。语义相同的对象在同一项目中保持相同编码。
6. 哈希、文件存在、静态配置通过不能证明图正确；必须实际运行并查看输出。

## 工作流程

### 1. 锁定输入和用途

读取真实数据、已有代码、目标图和期刊/报告要求。明确每行数据代表什么、独立单位、配对或重复测量、单位、变换、缺失与筛选规则。确定最终使用场景、单栏/双栏/自定义宽度、需要的格式和是否要求可编辑源文件。

未知期刊尺寸时不要伪造官方要求；使用可说明的项目 profile，并把数字标为项目选择。IEEE `8.89 cm` 等值只在已确认对应模板时使用。

### 2. 建立任务 profile

从 [示例 profile](assets/profile.example.json) 复制到任务工作区并替换为实际值。它记录后端、源画布、文档显示宽度、字体层级、线宽、语义颜色、输入和输出，不记录科研结论。`native_final_size` 的源宽等于显示宽；`scaled_source` 必须在导出后测量实际 PDF 边界并复核缩放后的可见字号，不能把两种策略的数值混用。

```bash
python scripts/check_profile.py path/to/profile.json
```

检查通过只表示 profile 完整且路径安全。已有项目若使用同等配置对象，不要求为迁就本 Skill 重写格式，但必须保留相同信息。

### 3. 编写或重构代码

代码至少分离：输入读取、输入验证、必要计算、绘图、导出和入口。样式常量集中管理，单图代码只定义科学内容与必要布局。使用相对路径、命令行参数或显式配置，不写开发者机器的绝对路径。

随机抖动、抽样或布局算法显式保存种子；无随机过程不为形式添加种子。禁止静默捕获异常后继续输出“成功”图。

可从 [Python 模板](assets/python_plot_template.py) 或 [MATLAB 模板](assets/matlab_plot_template.m) 开始，但必须根据真实字段、设计和目标图修改；模板示例不是用户数据或完成证据。

### 4. 在最终物理尺寸下设计

先确定最终宽高，再设置字体、线宽、标记、图例和子图间距。不要先制作巨大画布再整体缩小，也不要用缩小字体解决布局冲突。单栏和双栏应是独立 profile；复杂多面板从一栏改两栏时重新组织面板，而非简单把宽度乘二。

图例不遮挡数据、科学计数法、误差条或关键区间。自动位置可以作为初值，正式交付前必须实际检查；人工拖动后的坐标要回写代码。

### 5. 实际运行和双层验收

在干净工作目录用交付代码和必要输入实际重跑。先检查图本身，再检查它插入最终论文/报告后的页面。源图在 100% 缩放下好看，不代表缩放到栏宽后可读。

若 `bbox_inches="tight"`、外置色条或轴外文字改变 PDF 页面边界，以导出后的实际尺寸为准。检查字体替换、文字是否仍为文字、线条/图元是否保持矢量，以及栅格层是否具有足够分辨率。

### 6. 交付

交付实际可运行的代码、最少必要输入或输入合同、任务 profile，以及用户或目标期刊要求的图件。MATLAB 在用户需要继续手调时可交 `.fig`；Python 不制造虚假的可编辑工程格式。

内部保留运行命令、软件版本、输入与输出哈希和实际查看记录；不把缓存、测试图、旧版脚本和未采用 profile 混入最终目录。未实际运行所选后端时，只能交待运行代码并明确未完成运行验收。

## 完成条件

- 代码从声明的输入重新生成全部声明输出，不依赖开发者绝对路径或未交付的隐藏文件。
- 数据映射、单位、统计标注、样本量和图注含义一致。
- 最终物理尺寸、字体层级、线宽、面板、图例和颜色编码已经实际查看。
- 矢量与栅格格式符合当前任务要求；扩展名与真实格式一致。
- 同一项目的图使用同一个已确认 profile，确需例外时在代码中说明具体原因。
- 插入目标文档后重新编译或渲染并检查；未完成这一项时不宣称出版版面验收通过。