SQANTI3 实跑，FSM、NIC、NNC 能告诉你什么，又不能证明什么

长读长转录组结果里，经常出现完整剪接匹配、已知位点新组合以及包含新位点等分类。它们看起来像一套从可靠到可疑的质量等级，但实际回答的首先是输入结构与当前参考注释的关系。如果把分类标签直接等同于真假，就容易把重要候选误删，也可能给缺少验证的结果过度背书。

本篇实际安装 SQANTI3 六点一，构造八种可以手工核对的转录本结构，分别对照两套参考注释运行质量注释。我们重点检查剪接类别、端点差异、典型连接和缺失证据，同时记录安装与执行中遇到的问题，让读者能够理解每一列到底来自什么分析。

本次检查的是结构，不是表达发现

输入由人工基因组和手工设计的 GTF 构成，没有真实测序样本。参考注释首先只包含一个三外显子转录本，第二套参考再增加一个跳过中间外显子的模型。两次运行的八条查询结构完全相同。

我们没有提供短读段覆盖、表达矩阵、CAGE 峰、独立多聚腺苷位点或真实全长读段计数，也没有运行 ORF 预测、规则过滤和候选救回。因此，本文结果能够检验结构分类与字段行为，不能证明新的生物学转录本，也不能评估整套发现流程的准确率。

输入直接采用 GTF，所以没有执行序列到基因组的比对。日志还明确说明，这种入口没有计算比对插入缺失信息。后续看到相关字段为空，应先联系实际输入方式，而不是马上推断该转录本没有任何比对错误。

SQANTI3 可以整合多种独立证据，但这种能力只有在相应数据和分析步骤实际存在时才会体现在结果中。配置文件里有一个可选入口，不等于当前项目已经获得了那一类支持。SQANTI3 质量检查说明

八种结构分别控制什么变量

参考的三个外显子分别位于一千零一到一千四百、二千五百零一到二千九百、四千零一到四千四百。所有坐标构造和随机种子都保存在脚本里，方便检查每一种变化。

第一条查询保留全部内部连接，但起点向后移动二十碱基，终点向前移动二十碱基。第二条删除最前面的外显子。第三条跳过中间外显子，只连接第一段和第三段。

第四条把第一外显子的供体延长五十碱基，并在新位置设置典型连接序列。第五条再使用另一个新供体位置，故意设置非典型连接。最后三条分别位于参考的反义链、一个内含子内部和基因间区。

基因间区查询的终点下游二十碱基被全部设为腺嘌呤。这是用于检验字段尺度的人工极端条件，不是我们在真实样本里发现了内部引物起始事件。区分测试构造和生物学观察，能避免实验结论被误读。

安装成功后仍要执行一个小检查

本次容器内质量检查程序实际报告六点一。统一包装入口不接受我们最初尝试的版本参数，质量检查入口可以正常报告版本。先看具体子程序帮助，比只记住软件总名称更可靠。

IMAGE=quay.io/biocontainers/sqanti3@sha256:998119e65224de4cbaa8ef4a43e42e88705d8c76436509ec031b3a9bcac2581f
docker pull "$IMAGE"
docker run --rm "$IMAGE" sqanti3_qc.py --version
docker run --rm "$IMAGE" sqanti3_qc.py --help

第一轮流程在注释格式转换处失败。具体日志显示，内置转换程序请求的库名称不存在，而镜像里已经包含同系列的实际库文件。我们没有修改基础镜像，而是在实验目录中给已有库增加所需别名，只对本次容器调用设置库搜索路径。

gtfToGenePred-linux-x86_64
error while loading shared libraries:
libbz2.so.1: cannot open shared object file

修复后，另一个可选的匹配明细输出触发函数参数数量错误。由于它不属于本实验所需的分类表和连接表，我们去掉该可选开关，在全新结果目录重新执行两组分析，两组均正常退出。

可选参数 --isoform_hits
TypeError: write_isoform_hits() takes 2 positional arguments but 3 were given

附件驱动包含这次固定镜像的局部库兼容处理，并保留原始和修复后的依赖检查结果。这个经验不能推广为遇到库错误就随意建立软链接，应该先核对缺失名称、实际库版本与运行结果。更换镜像后，也要重新确认问题是否仍然存在。

最终实际执行的命令

下面是局部兼容环境准备完成后，容器内执行的核心命令。第二组只把参考文件换成增加跳跃模型的版本，并使用另一个输出目录。完整驱动会自动生成全部输入，不要求读者手工拼接 GTF。

sqanti3_qc.py --isoforms queries.gtf \
  --refGTF reference.gtf --refFasta genome.fa \
  --cpus 2 --report skip \
  --output toy --dir baseline

sqanti3_qc.py --isoforms queries.gtf \
  --refGTF expanded.gtf --refFasta genome.fa \
  --cpus 2 --report skip \
  --output toy --dir expanded

当前版本需要显式开启 ORF 预测，本次没有开启。网页报告也被明确跳过，但分类表和连接表都已生成。报告是否漂亮与底层表格是否正确是两件事，复现时应先核对数据文件。

python3 151-sqanti3/run.py results/sqanti3

FSM 并不要求两个端点完全相同

第一条查询比参考两端各短二十碱基，但内部剪接连接完全一致，实际分类仍是完整剪接匹配。结果中的两项端点差异都为负二十，而查询长度是一千一百六十，参考长度是一千二百。

因此，完整剪接匹配描述的是剪接结构的匹配关系，不能自动解释成整条转录本从起点到终点都与参考完全相同。若研究问题涉及转录起始或终止位置，必须继续检查端点字段和独立证据。

第二条缺少最前面的外显子，被分类为不完整剪接匹配，并标记为三端片段。这个标签说明它覆盖参考的一部分结构，不能单独判定它来自降解，也不能直接证明它是稳定存在的短转录本。

把这两条放在一起看，可以区分剪接链完整程度与端点一致程度。前者完整不代表端点一致，后者不完整也不意味着剩余连接就一定有问题。官方分类说明同样将这些关系分开定义。SQANTI3 结构类别

NIC 与 NNC 的区别落在什么位置

跳过中间外显子的第三条查询，使用的供体和受体都已存在于参考，但二者形成的直接连接不在参考模型中。实际得到 NIC，子类指出这是已有剪接位点的新组合。

第四条查询使用新的供体，尽管连接序列仍为典型组合，也得到 NNC。第五条同样使用新供体，并且连接序列非典型，同样得到 NNC。两者结构类别相同，连接典型性却不同。

由此可见，是否为新位点和是否符合典型连接模式不是同一个维度。不能把所有 NNC 都当成非典型连接，也不能因为一个连接符合常见模式，就把它当作已经被真实样本验证的新结构。

连接表还能把这个差别进一步拆开。第三条查询的连接本身标记为新，但两端位点都标记为已知。第四条则是一端新、一端已知。比起只保留总类别，这种分解更能帮助解释候选到底新在哪里。

反义、内含子和基因间区也不是质量等级

反义链查询被归入反义类别，内含子内部的单外显子查询被归入内含子区域类别，基因间区单外显子查询则归入基因间类别。这些标签首先描述相对于当前参考的位置关系。

单外显子查询没有可检查的剪接连接，因此典型性字段为空。这个空值不能当成非典型，也不能当成已经通过典型连接检查。没有相应对象可计算，与计算后得到某种结果，是不同情况。

实际数据出现这些类别时，应检查注释覆盖程度、链特异信息、比对与表达支持。参考之外的结构可能值得研究，也可能来自技术问题，仅靠位置类别无法完成真假判断。

只加一条参考，NIC 就变成 FSM

第二组没有改动查询序列、结构和基因组，只在参考中增加了第三条查询对应的跳跃模型。该查询从 NIC 变为完整剪接匹配，关联转录本也从新模型标记变成新增的参考名称。

这个变化没有增加任何实验支持。它只改变了查询相对于参考集合的身份。因此，比较不同项目的新转录本比例时，必须同时核对参考版本、纳入的转录本范围和处理流程。

如果一个项目使用更丰富的参考集合，新类别比例可能下降，并不意味着测序数据更保守。反过来，使用较旧或较精简的注释，可能把已有结构重新标记为新。单独比较比例，容易把注释差异讲成生物学差异。

实际归档时，应保存参考文件本身或可核验的版本与摘要，不能只写一个物种名称。后续升级参考，再追踪哪些候选发生类别变化，比直接覆盖旧结果更有助于解释结论演变。

non_coding 可能意味着本次根本没有预测

本实验没有开启 ORF 预测，八条查询的编码字段却全部写成非编码，相关长度、位置和评分字段则为空。日志同时明确写出跳过预测。这是一个不能忽略的结果解释陷阱。

若只按编码列筛选，这八条人工结构都会进入非编码集合。但本次并没有运行能够支持这一判断的编码潜能分析，因此不能把它们报告为经过预测确认的非编码转录本。

这里应该将解释写为本次未评估编码潜能，并保留原始软件字段。下游整理表格时，可以额外增加分析是否执行这一列，把未计算与计算后判定为非编码分开，而不是静默改写原文件。

官方输出说明明确记录了当前版本在未开启预测时的字段行为。这也说明，理解默认值和缺失值同样重要，不能只背字段名称。SQANTI3 输出字段说明

下游全 A 是一个提醒，不是已经发生的伪影

基因间区查询下游被我们设计为二十个腺嘌呤，实际输出的下游 A 比例为一百点零。这个结果说明当前字段按百分比尺度输出，不能不检查范围就把它与零到一的比例阈值直接比较。

真实分析中，富 A 的基因组邻域值得结合端点与引物机制检查。但本实验只有人工基因组和结构，没有真实逆转录或建库过程。因此，这个数值不能证明内部引物起始已经发生。

类似地，本次完整剪接匹配查询还出现了逆转录模板切换相关提示。它来自程序对序列模式的检查，而人工输入根本没有经历逆转录过程。这恰好提醒我们，算法标记的是需要进一步核查的模式，并不是对实验历史的直接观察。

判断候选时，应把结构关系、序列模式、覆盖支持和实验验证分开保存。多个维度一致时，解释会更有根据。单个提示可以帮助安排检查优先级，却不应被包装成独立验证结论。

缺失证据应该如何进入后续表格

本次未提供短读段数据，覆盖相关字段为空。没有全长计数与表达矩阵，对应字段也为空。没有端点峰信息，相关距离和是否落峰的字段同样为空。这些空值不能统一替换成零或否。

例如，零条短读段支持意味着在某个明确检查范围和统计规则下没有观察到支持。根本没有提供短读段数据，则没有完成这项观察。把后者改成零，会让下游筛选把未检查误当成证据不足的实测结果。

整理候选表时，可以同时记录字段值、数据来源和是否实际计算。这样筛选规则就能区分必须具备的证据、可选证据与尚未补充的信息，也更容易解释候选为何进入或离开列表。

SQANTI3 的优点在于把多个结构与质量维度集中到可追溯表格中，便于系统检查。其限制是输出依赖参考集合和提供的外部数据，分类标签无法独自承担生物学验证的任务。把它作为证据整理工具使用，通常比把类别机械排成真假等级更有价值。

重跑时先核对这些具体结果

下载本组三篇的驱动、实测结果与说明。本篇包含两套参考、八种人工结构、局部兼容处理及完整分类和连接表。重跑后先确认两组均完成八条分类，再检查第三条查询是否由 NIC 变为完整剪接匹配。

随后核对第一条两端缩短仍为完整剪接匹配、两条新供体的典型性不同、下游全 A 输出为一百，以及未预测编码潜能时的字段行为。这些检查把命令、输入与解释连在一起，能够直接帮助排查真实项目中的误读。

如果后续需要维护长读长质量检查及多批次注释环境，可了解云生信生物分析服务器服务，统一保存软件版本、参考资料和分析结果。