somic520/hemusci-skills/r-soil-scientific-figures

R 土壤与相关学科科研绘图

坚守科学含义

先保证研究设计、统计量和空间含义正确，再优化外观。

1. 不改变、隐藏、补造或选择性突出数据来强化结论。保留原始数据、排除规则、缺失/低于检出限编码、变换、聚合、归一化、平滑、分箱和随机种子。
2. 先确定实验单位和独立重复。技术重复、同一样地的多层深度、同一土柱的多时点、区组内样点和像元不得冒充独立 n。
3. 图形结构必须对应设计和模型。配对数据连线；重复测量显示个体轨迹或模型化轨迹；嵌套设计区分观测、实验重复和组级估计；空间数据保留位置关系。
4. 明确估计量与不确定性。区分 SD、SE、CI、预测区间、可信区间、分位数范围和克里金方差；说明置信水平、计算层级和有效 n。
5. 不把显著性字母、星号或 P 值当作分析替代品。只有在已有、可复核的模型与比较结果支持时才标注，并同时给出效应量或区间。
6. 柱高/面积通常从零基线编码；点线图可在有充分上下文时使用非零范围。不得用双轴、截断轴、透视 3D、面积/半径混淆或不一致面板尺度制造差异。
7. 地图必须记录 CRS、投影、基准面、空间分辨率、范围、分类断点、插值/预测方法、掩膜和训练/验证支持域。面积和距离不能在经纬度或 Web Mercator 中直接计算。
8. 预测地图原则上同时给出不确定性或适用域；不得把插值表面表现为实测真值，不得隐藏无数据区和外推区。
9. 颜色映射按语义选择定性、顺序、发散或循环色板，并用形状、线型、直接标注或分面提供冗余编码。不要默认使用彩虹色板。
10. 不推断期刊当前要求。确定期刊、文章类型、投稿阶段和图宽后，从官方页面实时核对；本 skill 的尺寸仅是起点。

任务涉及统计解释或发布结论时读取 references/integrity-and-statistics.md；涉及空间、遥感或数字土壤制图时必须读取其中的空间章节和 references/soil-domain-atlas.md 对应部分。

判定任务类型

将请求归入一个或多个类型：

• 选图：从研究问题、设计和数据结构提出 1 个主方案及必要备选。
• 识图/复现：从截图、图注或论文链接识别图形家族、统计层与 R 实现。
• 作图：生成可运行 R 代码和真实图形文件。
• 升级：在不改变分析结论的前提下重构已有图。
• 审计：只报告统计表达、视觉编码、可访问性、导出和期刊风险；用户未授权时不改文件。
• 图谱检索：查找图名、别名、用途、包、函数、成熟度和证据来源。

先运行目录状态检查：

python3 scripts/figure_catalog.py status

目录未通过验证时不要基于目录声称覆盖范围。

使用 314 个实测模板库

本 skill 的目录不是仅列图名。references/figure-catalog.tsv 有 314 个条目，assets/r-engine/ 提供共享校验、字体、排版、渲染和审计引擎，命名图的深度实现分布在多个 override 模块。先检查：

python3 scripts/figure_catalog.py validate
python3 scripts/tests/audit_recipe_distinctness.py --help
Rscript scripts/tests/render_all_recipes.R . outputs/all-recipes-qa

需要生成每图独立、可移动的复现包时运行：

python3 scripts/build_all_recipe_bundles.py \
  --output outputs/R土壤学科研绘图Skill_314图 \
  --tested-render-dir outputs/all-recipes-qa/png \
  --overwrite

每个 recipes/<id>/ 必须包含可运行 figure.R、标准 data/input.csv、input-schema.tsv、配置、独立引擎、依赖安装脚本和 QA 指针。不得用同一张基础图改名冒充多个模板；完全重复渲染是失败，近似图必须人工证明其统计或领域语义不同。最终质量基线见 references/final-quality-assurance.md。

R 本体、系统字体和系统级组件只在用户明确授权安装时变更；用户要求可直接运行的独立代码时，代码本身必须显式检测所用 CRAN 包，并尝试安装缺失包：

python3 scripts/check_r_environment.py --profiles core,publication --install-missing

macOS 和 Windows 的独立入口分别为 assets/install/install_macos.command 与 assets/install/install_windows.ps1。若 R 不存在，安装器可引导或调用平台包管理器；若字体缺失，使用可记录的回退，不伪称命中宋体或 Times New Roman。Windows 脚本可在 macOS 上做静态检查，但运行认证只能在真实 Windows 主机完成。

建立图形规格

优先从现有数据、分析代码、模型对象、论文图注和期刊要求中提取信息。只有缺失项会实质改变图形时才询问。

记录：

• 科学问题、预期比较和读者要看出的关系；
• 变量含义、类型、单位、尺度、零值、负值、检出限和缺失机制；
• 实验单位、样本量、技术/生物重复、区组、配对、嵌套、深度、时间和空间结构；
• 已完成的分析、估计量、对比、变换和不确定性定义；
• 数据量、离群点处理、聚合和是否需要显示原始观测；
• 目标载体、期刊、栏宽、颜色模式、文件格式和可访问性需求；
• 源数据、脚本、模型和输出的稳定路径。

不得从图形外观反推未提供的统计检验或数据处理。

从目录选图

按问题检索，不要只按图名检索：

python3 scripts/figure_catalog.py search "土壤 深度 重复测量"
python3 scripts/figure_catalog.py recommend --task comparison --design nested --domain soil-biology
python3 scripts/figure_catalog.py show soil-profile-sketch
python3 scripts/figure_catalog.py families

选择时依次判断：

1. 任务：分布、比较、关系、变化、组成、空间、层级、流、网络、不确定性或模型诊断。
2. 数据：变量类型、维数、样本量、稀疏性、闭合组成、空间/时间分辨率。
3. 设计：独立、配对、重复、嵌套、区组、裂区、梯度、剖面、时空或多组学。
4. 统计：描述、模型估计、预测、因果、排序、地统计、分类或多元分析。
5. 载体：静态论文图优先可打印编码；交互图另交付静态后备。

主方案应直接回答问题。只有备选图表达不同的科学侧面时才提供备选。读取：

• 通用选择逻辑与图形家族：references/figure-taxonomy.md
• 土壤及相关学科问题到图形的映射：references/soil-domain-atlas.md
• 详细可检索条目：references/figure-catalog.tsv
• 新兴/近期图形及成熟度：references/emerging-figures.md

使用合适的 R 生态

默认以 ggplot2 图形语法实现常规统计图，但不要强迫所有图进入 ggplot2。对象和语义优先：

• 土壤剖面与土体：aqp、soilDB、sharpshootR；
• 质地/组成：soiltexture、ggsoiltexture、ggtern、compositions；
• 群落生态与排序：vegan，需要整洁绘图时再提取公开 accessor 的 scores；
• 微生物组/系统发育：phyloseq、microViz、MicrobiotaProcess、metacoder、ggtree；
• 空间矢量/栅格：sf、terra、stars、tmap；地统计用 gstat 等模型包；
• 复杂热图：ComplexHeatmap；树与多组学对齐使用 ggtree、aplot 或 ggalign；
• 多面板：优先 patchwork，复杂对齐按对象选择 cowplot、grid 或领域包；
• 大数据：先聚合/栅格化/密度化并保留统计语义，按需使用 ggrastr、scattermore、ggpointdensity；
• 交互与动画：plotly、ggiraph、leaflet、mapview、gganimate，但论文仍输出静态版本。

读取 references/r-package-map.md 获取按领域整理的包、函数入口、状态和替代方案。先用 requireNamespace() 检查依赖。交互分析不静默改环境；独立交付脚本必须包含清晰可见的“检测→从 CRAN 安装缺失包→再次验证→失败即停止”代码块，不依赖另一个 setup_packages.R。不要依赖未记录的开发分支、包的内部对象或易变的图层内部结构。

编写可复现代码

用户要求简洁、可直接运行的单图交付时，从 assets/standalone-examples/ 的最接近示例复制起点；需要完整可追溯审计工程时再使用 assets/figure-template.R 或 314 图引擎。模板只是结构参考，必须按真实指标、实验设计、语言和期刊版面改写。代码按以下顺序组织：

1. 参数与依赖；
2. 读取不可变源数据；
3. 校验列、类型、单位、范围、主键、重复和缺失；
4. 显式转换与统计；
5. 构造单图；
6. 组合面板和标签；
7. 导出；
8. 写会话、图形规格与来源记录。

每个图层都要能回答“它代表观测、摘要、模型还是注释”。统计图层若由 ggplot2::stat_*() 隐式计算，仍要在图注或记录中说明。将因子顺序、颜色映射、随机种子、分箱、带宽、平滑方法、插值和坐标变换写入代码。

对用户数据生成图时必须实际运行代码。若环境不能运行，明确标为未执行代码，不得声称文件已生成。

每张正式图必须交付两份功能完全一致的脚本：<图形名称>.R 不含教学性注释，<图形名称>_中文注释版.R 含分节、详细且自然的中文注释。无注释版应由注释版机械去除整行注释后生成，并进行解析和执行一致性检查。图形名称及文件名服从用户语言；中文图使用中文名，英文图使用英文名，用户可明确覆盖。

识别和复刻用户图片

先运行 scripts/image_probe.py 提取像素尺寸、色域、面板边界、候选轴区、背景与主色，再将观察到的图层写成明确规格。复刻顺序是：图形家族与面板结构、坐标和比例、几何/统计层、图例、字体与颜色、最终版面。可用 scripts/compare_images.py 对参考图与重绘图做尺寸、边缘和感知差异检查。

截图没有原始数据时，只复刻可观察的视觉结构并生成标准输入表；不得把目测点位、网络边、显著性、模型曲线或误差区间包装成真实研究数据。用户提供数据或模型后再做科学含义一致的复现。

土壤领域专项规则

• 连续深度剖面：土壤性质放横轴，深度放纵轴且向下增加；显示层界、采样区间和不规则厚度；同一剖面或样品的多深度测量不得当作独立样本。
• 深度区间柱状图：不得把深度退化为普通横轴分类柱图。默认用水平分组柱，土壤性质放横轴，深度区间放纵轴并由浅到深向下；处理只作组内比较。先在独立样品内汇总区间，再使用与重复测量、区组或嵌套结构一致的模型；显著性字母放在每根柱和全部原始点/误差线之外。
• 土壤硬度/贯入阻力：记录测定时含水状态、仪器/探头和测量支持；可把含水量纳入模型。2.0 MPa 只能作为可配置参考线并在图注声明，不得当作所有土壤的统一临界阈值。
• 质地三角图：确认砂/粉/黏定义、粒径体系、单位和闭合到 100%；明确分类体系版本；不同体系不可混用边界。
• 水分/传输曲线：保留压力头/吸力符号和对数尺度定义；区分实测点、拟合曲线和预测区间；说明模型形式。
• 培养/通量/时间序列：显示真实时间间隔和重复结构；不要跨缺测时段默认连线；累积量与瞬时速率不可共用未解释的轴。
• 多元排序：报告方法、距离/变换、约束、解释率或 NMDS stress；箭头缩放和 site/species scaling 必须可追溯。
• 微生物组组成：组成数据、测序深度和零值处理要与分析一致；堆叠相对丰度不能表达绝对丰度；稀有类合并规则要记录。
• 数字土壤制图：成对审查观测支持、预测、误差/不确定性、外推/适用域和空间验证；分级图给出断点和闭区间规则。
• 遥感/高光谱：标注传感器、产品级别、波段/波长、空间与时间分辨率、云掩膜、缩放和重采样；光谱曲线不能混合未校正的 DN 与反射率。

更多任务映射见 references/soil-domain-atlas.md。

规范轴标签与单位

• 中文轴标签默认写成 指标名称/ (单位)，例如 土壤有机碳/ (g kg⁻¹)：中文名称与 / 之间不留空格，/ 后留一个半角空格。
• 英文轴标签默认写成 Variable / (unit)，例如 Soil organic carbon / (g kg⁻¹)：/ 两侧各留一个半角空格。
• 复合英文单位用半角空格分隔，如 g kg⁻¹、mg L⁻¹、kg N ha⁻¹；除非目标期刊或领域标准明确要求，不用居中点代替该空格。
• 用真正的上标、负号、希腊字母和化学式排版，不把 kg^-1、CO2 等 ASCII 占位形式直接交付到成图。
• 中英文混排轴标签要分别使用已解析的中文和英文字体，保持正常字重；不得因给整个标签指定宋体而让英文单位失去 Times 系字体，也不得因指定 Times 而造成汉字缺字。
• 中文版图形的全部读者可见分类、图例、轴名和注释使用中文；中文片段用宋体兼容字体，英文、拉丁单位和数字用 Times New Roman 兼容字体。英文版图形全部使用英文，并以 Times New Roman 兼容字体为默认起点。
• 连续响应变量的表头、纵轴和图例标题从用户数据的真实指标与单位生成，不得在正式交付中统一写成 Value、测定值 或 数值。例如用户数据明确为土壤有机碳且单位为 g kg⁻¹，标准表数值列表头与纵轴均写 土壤有机碳/ (g kg⁻¹)；若用户未提供单位，不得猜测或擅自补单位。
• 离散分组标签已经清楚表达横轴时，底部横轴总标题默认隐藏。只有用户明确要求、分类含义不清或复杂布局确需公共轴标题时才显示；显示时必须使用真实变量含义，如“处理”“时间”“土层”“品种”或“地点”，不得固定写死。
• 无量纲量不机械添加 / (1)；百分数、pH、比值、对数变换和标准化量按其科学定义显式标注。
• 字号不得写死为某个“万能值”。先确定最终物理宽高，再根据有效面板宽、面板数、类别数、标签长度、图例密度和目标期刊上下限计算基础字号；如果仍拥挤，优先改方向、换行、分面或画布，不以无限缩小字体解决。
• 常规笛卡尔科研图默认采用四周完整 panel.border，并关闭重复的 axis.line；图内总标题默认隐藏，文件名和独立中文图注承担图名与说明。网络、树、地图、三角图等无坐标框图形按语义例外处理。
• 目标期刊明确采用其他轴标签样式时，以实时核对的官方要求为准，并把偏离本默认格式的决定写入 manifest。

共享引擎的 value_axis_label() 默认识别中英文并实施上述间距，可通过 options(r_soil.axis_unit_style = "parentheses") 为已核实要求切换为括号式。详细排版见 references/publication-and-export.md。

设计多面板论文图

先给每个面板定义角色：研究设计/位置、原始证据、主要估计、机制或诊断。删除不能推进叙事的面板。

• 在可比较面板间保持共同尺度、颜色含义、因子顺序和单位；必须改变尺度时醒目标注。
• 共享图例和公共轴只在语义完全一致时使用。
• 面板标签按阅读顺序生成，不把统计结果塞进面板标题。
• 地图含必要的比例、方向或坐标信息；是否需要北箭头/比例尺取决于地图用途和投影，不机械添加。
• 显微/遥感影像保留原图，说明全图调整、裁剪、配准和增强；比例尺来源于校准信息而非目测。

用户要求分面柱状图、柱形均值图或带显著性括号的分组柱状图时，读取 references/faceted-bar-significance.md。连续响应变量默认保留原始观测点，并明确柱高、误差线、比较模型和多重校正；不得把只有汇总柱和未校正星号的参考代码直接作为论文结果。

导出用户可直接运行的最小图形包

单图交付默认在一个文件夹中只保留 7 个正式文件：

1. <图形名称>.R；
2. <图形名称>_中文注释版.R；
3. 标准输入表格.xlsx；
4. <图形名称>.pdf；
5. <图形名称>.png；
6. <图形名称>.tiff；
7. <图形名称>_中文注释.txt。

除非用户明确要求完整审计工程，否则不得把 config.json、README、lib/、data/、outputs/、statistics/、checksums、run 脚本、独立安装脚本、manifest、session-info、重复统计表或 QA 中间件塞进交付文件夹。314 图模板库内部的 recipe 工程不受此最小目录限制，但导出给用户时仍执行本契约。完整规则与土壤硬度深度示例见 references/minimal-standalone-delivery.md 和 assets/standalone-examples/soil-hardness-depth/。

标准输入表格.xlsx 是把用户提供的数据做字段映射、类型统一和结构整理后的代码直接运行表，不是“未经处理的原始表”。只保留 R 代码实际读取的列和记录；单指标数值列使用真实指标名，源数据提供单位时将单位写入同一表头，未提供单位时不猜。R 代码读取该表后直接进行缺失、重复键、数值类型、实验设计、统计和绘图校验，不再输出内容重复的“分析就绪表”。工作表只对实际有内容的区域画完整细框；不得给空白行列加框。列宽逐列以本列最长内容为基准并留边距，设置合理上限，超长表头换行。中文使用宋体兼容字体，英文、数字和单位使用 Times New Roman 兼容字体。

中文图注 .txt 默认写成一段可直接放入论文的中文文字，定义图形比较、轴和单位、观测点、估计量、误差/区间、模型、显著性或多重校正、参考线、样本量和必要限制；不得只写图名。

三种图形格式缺一不可：PDF 为矢量主文件；PNG 为 600 dpi RGB；TIFF 为 600 dpi RGB 并使用 LZW 压缩。三者默认均为不透明白底，主题的 panel.background 与 plot.background 也必须为白色。只有用户或目标载体明确要求时才额外生成透明 PNG；透明版不得替换白底默认文件。SVG、EPS、统计表、manifest 和压缩包只按需增加。

尺寸以最终版面物理宽度为准；DPI 只对栅格层有意义。优先保留矢量文字和线条，对超密散点、栅格、影像或阴影进行有意的局部栅格化。读取 references/publication-and-export.md。

检查实际输出

生成后运行：

python3 scripts/audit_figure_bundle.py \
  --script figure.R \
  --figure outputs/figure-1.pdf \
  --manifest outputs/figure-manifest.json

随后将 PDF/SVG 渲染为最终尺寸的 PNG，逐页/逐面板查看。自动审计不能证明统计正确、可访问或符合期刊要求。人工至少检查：

• 数据点、层位、样点、面板和图例数量；
• 轴范围、单位、变换、断点、方向和缺失；
• 字体、上下标、希腊字母、化学式、物种名和空间标注；
• 颜色含义、灰度可辨性和非颜色冗余编码；
• 标签重叠、裁切、线宽、点尺寸、比例尺和最终缩放；
• 主图、图注、图数据、代码和清单的一致性；
• 目标期刊当前官方要求。

最小包还必须检查：无注释版与注释版去除整行注释后完全一致；两份脚本均可解析，至少无注释版从 标准输入表格.xlsx 独立复跑成功；PNG 无 alpha；TIFF 为 LZW；PDF 页面物理尺寸正确；文件夹恰有上述 7 个正式文件且没有 ._ 或其他隐藏副本。

审计任务只报告证据支持的问题。作图任务应修复问题、重新运行并再次检查。

维护图谱

“所有图形”没有封闭全集：图名存在别名，组合图可以无限生成，领域方法持续出现。本 skill 将覆盖目标定义为图形家族与科学任务的近全覆盖，而不是收集受版权保护的论文图片。

新增条目时：

1. 确认它是独立编码/统计结构、领域专用变体还是纯样式别名；
2. 优先核对原始方法论文、R/CRAN/Bioconductor 官方文档和维护者文档；
3. 记录中英文名、别名、家族、任务、数据/设计、R 包/函数、风险、成熟度和来源键；
4. 将近期条目标记为 emerging、recent-method 或 recent-domain-use，不得把“近期流行”误称为新发明；
5. 运行 python3 scripts/figure_catalog.py validate。

来源分级、检索日期、现有公开 skills 的比较和更新协议见 references/sources.md。