Spectronaut 报表、QC 与 Pipeline

总述

Report、QC 与 Pipeline

如果分析流程负责把数据分析出来，那么报表、QC 和 Pipeline 负责把结果变成能复核、能交付、能长期运行的体系。附录 8 和 9 则进一步把字段语义和 chromatogram 证据向外打开。

交付层的核心作用

平台化交付需要同时建立 schema、字段词典、QC 历史、pipeline 结果留存与 XIC 回查能力。

交付层的四个重点

看懂对象层级而不是只会导 Excel
理解 QC 历史与样本特异 QC 的关系
把 pipeline 做成可重复执行的 SOP
知道何时回到 XIC 层复核证据

交付层关系图

从分析结果到 schema、字段对象、QC、pipeline 和 XIC 接口的工作链。

报表结构

报表结构由 schema tree、column chooser、filters 与 report preview 四个核心面板构成，分别对应结构、字段、筛选与输出预演。

Report perspective — 报表结构。Normal Report、Run Pivot、PTM report、Grid View report 都从这一层设计与导出。

四块区域怎么理解

Schema tree 定义报表结构，Column chooser 负责选字段，Filters 控制筛选条件，Report preview 对应导出前的结构预演。读取顺序为先对象层、再字段层、再筛选层。

不同报表类型的分工

Normal Report 主要对应统计和数据库入库，Run Pivot 对应人工浏览，PTM Site Report 对位点项目尤其重要，Grid View Report 对应界面视图联动。

报表结构的逻辑

Report Perspective 被定义为“可设计、可定制、可保存复用”的 reporting strategy，而不是一次性导出窗口。schema 一旦保存，就会留在左侧 schema tree 中复用。
Report Perspective 的四个 panels 从左到右依次是 schema tree、column chooser、filters 和 report preview。这个顺序也对应报表搭建顺序：先决定结构，再挑字段，再筛，再预演。
Normal Report 是 long format：每个 reported event 占一行，按 Experiment → Run → Protein Group → Peptide → Elution Group → Fragment Group → Fragment 的层级展开。Columns tree 很深，底部 search field 是找列的常规入口。
Run Pivot Report 则把每个 run 变成一个列。你需要在 Row Labels 中定义行对象，在 Cell Values 中定义单元格值；如果 Row Labels 或 Cell Values 选多个，表的宽度会迅速增加。这里明确区分了 long format 与 wide format 的用途。
若实验采用 PTM workflow，软件还会提供 PTM site report，并把层级改成 Experiment → Run → Protein Group → PTM site。这说明对象层级会随 workflow 类型改变，而不是所有项目都共享同一套报表层。

QC

QC 监控

QC 不只是展示当前结果，而是持续记录成功分析、按 instrument 构建历史，并允许样本特异 QC panel 与 iRT QC 并行存在。

QC perspective — QC 监控。History tree、instrument 分组和多维性能图共同构成长期 QC 监控面板。

QC 监控层的四个重点

每一次成功分析都会写入 QC 历史，这使软件天然具备平台级趋势追踪能力。
如果有多台同型号仪器，应手动命名，以避免历史混淆。
除了 iRT kit，还可以在 Library Perspective 中右键 Enable QC 生成 sample-specific QC panel。
QC Plot History Length 决定历史窗口大小，通常按实验室管理策略统一设置。

QC 的监控层级

QC Perspective 的定义是：基于 iRT kit，对 chromatography、mass spectrometer performance 和 analysis process 做随时间的监控。也就是说，它同时覆盖液相、仪器和分析三层。
每次成功分析都会写入 QC history，并按 instrument 自动分开保存；如果有多台同型号仪器，应手动重命名，以免历史曲线混淆。
QC Plot History Length 控制 plots 中显示多少历史 runs，这意味着 QC 不是“自动无限堆叠”，而是一个需要人为定义观察窗口的监控系统。
除了 iRT QC panel，Library Perspective 里启用 Enable QC 后，还能把特定 spectral library 派生出 sample-specific QC panel。这一步说明 discovery 文件可以反向服务平台质控。

Pipeline

批处理与生产化运行

Spectronaut 更偏向顺序处理多个实验，而不是并行抢占磁盘 IO。Pipeline 的核心是稳定、可复制和批量运行。

Pipeline perspective — Pipeline Queue。多个分析任务进入队列后，软件会按顺序生成 experiments、reports、plots 和 summaries。

Pipeline mode settings — Pipeline Mode Settings。重点是选择 run-based / experiment-based reports、scoring histograms 和是否保存 `.sne`。

队列处理

Pipeline 不是为了替代所有人工 review，而是为了让标准化 discovery 项目进入队列式批处理，减少重复点击与输出不一致。

Pipeline Mode 参数

这一层决定写出哪些 reports、按 run 还是按 experiment 组织、是否导出 scoring histograms，以及是否保留整个实验的 .sne 文件，是平台交付设计的关键开关。

Pipeline、SNE combine 与 SNE merge

Pipeline Perspective 先解决的是 library-based DIA analyses 的 batch processing。顺序处理多个 experiments 比并行更高效，因为磁盘 IO 是瓶颈。
SNE combine workflow 是 Spectronaut 14 引入的大规模方案：可以先分批分析大实验，分别存成 .sne，再在 combine 阶段以 FDR-controlled 方式合并 identification results，并重新做 cross-run normalization、interference correction、protein inference、quantification 和 FDR。
此处的限制条件包括：所有 batches 必须使用同一 spectral library 和 acquisition method；directDIA 的 SNE 当前不支持 combine；regulation analysis、Heatmap 和 Volcano 不能在 SNE combine 中做；最终导出只支持 long format；normalization 仅限 Global Normalization；sample grouping 继承自原始 SNE，不能在 combine 时改写。
SNE merge 则是更小规模的 experiment-level merge，通常对应少于一百个 raw files 的工作流。大实验如果强行 merge，可能超出 RAM 或磁盘空间，应改用 SNE combine 生成 combined reports。
combine 与 merge 并不相同：前者面向 memory scalability 的大规模报告合并，后者面向较小 experiment 的对象级合并。

附录 8

关键报表字段

这一部分把 report 输出从列名列表提升到对象层级语言，可直接作为字段词典起点。

Q-value 字段必须和对象层级一起读

EG.Qvalue 对应 precursor / elution group 层，需要和峰形、iRT 偏移、fragment 干扰一起判断；PG.Qvalue 对应 protein group 层，更接近最终交付对象。两者都叫 q-value，但回答的并不是同一个问题。

q-value 与对象层级 FDR 的报告阅读方式

蛋白层交付边界要把 protein inference 与 single-hit proteins 一起读

Protein group 不是 precursor 结果的自然终点，而是经过 protein inference、shared peptides 处理和单 hit 蛋白策略之后的交付对象。只要这些规则变化，PG.Qvalue、蛋白数和最终可报告边界就会一起变化。

因此蛋白层结果不能只说“我们做了 1% FDR”。更完整的表达应同时说明：蛋白层是如何从 precursor / peptide 汇总而来，single-hit proteins 是否被保留，以及当前设置在 entrapment 或经验验证中落到了什么风险水平。

single-hit protein 的经验验证设置与模板

层级	代表字段	解释重点	主要使用场景
PG	`PG.Quantity`、`PG.Qvalue`、`PG.RunEvidenceCount`	回答蛋白层对象是否可靠、定量值是多少、每个 run 的支持证据有多强。	结果汇报、差异蛋白解释、项目交付
PEP	`PEP.GroupingKey`、`PEP.IsProteinGroupSpecific`、`PEP.UsedForProteinGroupQuantity`	这个肽段如何被定义、是否特异、是否真的参与了蛋白层定量。	定量逻辑理解、蛋白推断理解
EG	`EG.PrecursorId`、`EG.Qvalue`、`EG.Cscore`、`EG.DeltaiRT`、`EG.MeanTailingFactor`	回答这个前体在这个 run 中的鉴定与峰提取到底可信不可信。	峰图 review、质控、排错
FG / F	`FG.TotalPeakArea`、`FG.Quantity`、`F.InterferenceScore`、`F.ExcludeFromQuantification`	说明定量是由哪些 fragment 累积而来，以及哪些离子可能被排除或视为干扰。	碎片离子层排错、labeled / spike-in 项目
PTM	`PTM.Quantity`、`PTM.QuantityPerProtein`、`PTM.Stoichiometry`	把位点项目从有无变化推进到相对蛋白输入的变化和占比解释。	磷酸化、乙酰化等 PTM 项目

交付场景	报告中至少同时读取的字段	报告里必须补充的方法说明	当前可以成立的结论
标准 canonical FASTA、默认 protein inference	`PG.Qvalue`、`PG.RunEvidenceCount`、`PEP.UsedForProteinGroupQuantity`	数据库版本、protein inference 规则、single-hit protein 沿用默认设置	可以进入常规蛋白层结果汇报与差异分析
canonical + non-canonical FASTA	`PG.Qvalue`、`PEP.IsProteinGroupSpecific`、`PEP.GroupingKey`、组别化 precursor 证据	数据库分组结构、`precursor FDR per group`、non-canonical 条目来源	蛋白层结果只能在当前数据库结构内解释，不能直接外推为标准蛋白组结论
保留 single-hit proteins	`PG.Qvalue`、`PG.RunEvidenceCount`、蛋白特异肽支持字段	single-hit protein 保留策略、经验验证方式、protein inference 版本	可以保留探索性蛋白层对象，但必须同步标注风险边界
开放搜索 / peptidomics / PTM probing	`EG.Qvalue`、`PG.Qvalue`、位点或肽段层证据字段	search space 范围、FDR 粒度、对象层级和过滤条件	通常先交付 discovery evidence，再谨慎收敛到蛋白层解释

字段训练要点

PG.Qvalue 是 experiment-wise 的，所以不要把它直接理解成某个单一峰的质量。
PEP.UsedForProteinGroupQuantity 直接说明这个肽会或不会进入蛋白定量。
EG.Cscore、EG.DeltaiRT 和 EG.MeanTailingFactor 应与 XIC 和人工 review 一起讲。
F.InterferenceScore 和 F.ExcludeFromQuantification 说明 fragment 级错误会向上游层级传导。
只要 protein inference 或 single-hit protein 策略改变，PG.Qvalue 的解读边界也会随之改变，因此蛋白层字段必须和 settings 一起回看。

蛋白层结果进入报告前必须固定的四项说明

第一项是数据库结构。只要 FASTA 从标准 canonical proteome 扩展到 canonical + non-canonical、开放搜索或特殊 cleavage 规则，蛋白层对象空间就已经改变。
第二项是 protein inference。蛋白层对象不是 precursor 的自然相加，而是 shared peptides、grouping 和推断规则处理后的结果。
第三项是 single-hit protein 策略。是否保留仅由单条证据支持的蛋白，会直接改变蛋白数、经验错误比例和交付边界。
第四项是对象层级。若当前结论主要站在 precursor、peptide 或 PTM site 层，就不应只拿 PG.Qvalue 包装成统一的蛋白层结论。

Appendix 8 的优先字段顺序

PG.ProteinGroups、PG.ProteinAccessions、PG.Genes、PG.ProteinDescriptions 都依赖 parsing rule，因此蛋白层字段好不好读，前提在于 Databases 里的 FASTA parsing 是否统一好。
PEP.GroupingKey 与 PEP.GroupingKeyType 会告诉你当前 settings 把什么对象当成 peptide，默认通常是 stripped sequence。这直接决定 peptide 层的统计对象定义。
EG.IsUserPeak、EG.IsVerified、EG.Cscore、EG.DeltaiRT、EG.MeanTailingFactor 需要与 review 行为对应起来阅读，因为它们会同时暴露峰是否被手改、峰是否可信以及色谱是否稳定。
FG.Id、FG.TotalPeakArea、FG.Quantity 只在 labeled / spike-in workflows 下尤为关键，说明 fragment group 层并不是所有实验都同等重要。
PTM site headers 中最重要的是 PTM.CollapseKey、PTM.Multiplicity、PTM.QuantityPerProtein 和 PTM.Stoichiometry，因为它们直接把 site collapse、input normalization 和 site stoichiometry 的逻辑写进报表字段里。

Appendix 9

XIC 导出数据库

它让 Spectronaut 不再只是桌面软件，而成为可以和数据库、脚本和算法系统对接的数据接口层。

XIC DB schema — 附录 9。XIC 导出数据库的核心是 `IonTraces`、`RTAxis` 和 `Run` 三张表的关系。

对象	作用	关键点
`FG.XICDBID`	把 report 中的 feature / precursor 行回连到 XIC 数据库对象	它是报表层与色谱证据层之间最关键的桥
`IonTraces`	保存强度轨迹和离子相关索引	峰形证据集中保存在这一层，而不是只停留在 report 的数量列中
`RTAxis`	保存 RT 轴，减少重复存储	说明 XIC 可用数据库方式组织与索引
`Run`	回溯 raw file 元信息	对应项目归档、异常追溯和跨 run 调试

XIC DB 是怎么导出、怎么回查和怎么读回来的

这里给出三个正式导出入口：在 Review perspective 里右键 experiment tab 选择 Export all XIC；在 Settings → Global → Reporting 启用 Automatic XIC Storage；或在 command line 的 Analysis Settings → Pipeline Mode 中启用 Export All XICs。
由于性能考虑，18.7 之后改成每个 raw file 生成一个 SQLite database。这意味着 XIC export 是按 run 拆分管理的，不再是单一 experiment 大库。
IonTraces 是主表，FG.XICDBID 对应其 FGID，并携带 IonRank、MSLevel、IntensityBytes、RTAxis offsets 与 Run_ID；RTAxis 存整段 RT axis，再由 offset / length 截取子区间；Run 负责保存 source raw file 的文件名与索引。
Appendix 9 同时提供了 R 示例代码，说明这套结构不是只给软件内部使用，而是明确鼓励外部脚本把 base64 编码的 intensity 与 RT 数据重新解码后画图或做下游分析。

Skyline Schema

Spectronaut Library .skyr 字段映射

该 .skyr 是 Skyline report schema，用于把 Skyline 中的 precursor、fragment、iRT、修饰序列、蛋白和 decoy 信息导出成 Spectronaut library 可读字段。

ReportSpec

导出对象层级

schema 的 rowsource 指向 Transition，并展开 Results 子列表，因此它不是只导 peptide 列表，而是按 transition / fragment 级别输出 library 所需信息。

<report name="Spectronaut_Library"
  rowsource="...Transition"
  sublist="Results!*">

下载 .skyr

Field Map

关键字段

ProteinId、ModifiedSequence、StrippedSequence、iRT、PrecursorMz、PrecursorCharge、FragmentMz、FragmentCharge、FragmentType、FragmentNumber、RelativeFragmentIntensity、Decoy、IsotopicLabel 和 GeneId 是导出主干。

schema 同时过滤 Protein.Name != Decoys 与 Precursor.IsDecoy != TRUE，避免 decoy 对象进入目标 library 导出。