STARsolo 只叫出很少细胞？从两份 FASTQ 查到原始计数矩阵

同一份10x Genomics 单细胞文库，测序交付单上写着几千个细胞，STARsolo 的过滤矩阵却只剩几十列。此时直接放宽门槛，可能把没有正确读到条形码的文库画出一张看似正常的聚类图。更省事的排查顺序是先证明两端读段各司其职，然后确认原始矩阵究竟有没有分子，最后才讨论怎样判定细胞。每一步都能留下别人看得懂的中间结果。

下文讨论的是常见的10x 3′基因表达双端文库，一端是转录本序列，另一端携带细胞条形码和分子标签。其他化学体系、5′ 文库或自定义接头可能具有不同的读段结构。先向建库方确认文库类型以及每段序列的位置和长度，再使用下列例子。只知道文件名里含有第一端、第二端，仍然不够。

确认传给程序的第一份文件是什么

普通双端比对命令常把第一端写在前面。STARsolo 对这类输入规定的顺序是转录本端在前，条形码和分子标签端在后。因此常见10x 3′布局使用第二端文件在前、第一端文件在后。对于多个测序泳道，左边列出的所有转录本文件与右边的条形码文件要逐泳道成对。把两边分别按不同的命名规则排序，会造成总读段数看似合理、配对身份却错乱的问题。STARsolo 作者的输入说明与命令示例

先随机选一份文库，看交付单里的建库说明，再人工核对同一泳道首批读段的标识和长度。不同命名软件可能在读段标识末尾附加端号，比较时可去掉成对命名约定中的端号，保留区分测序簇的其余部分。若行首标识本来就不属于同一批簇，先修正配对文件。读长可以提供线索，较长的一端并非在所有实验中都恒定担当转录本端。

# 在包含同一泳道 R1、R2 的目录中运行，先看各自第一条记录
gzip -dc sample_R1.fastq.gz | head -n 4
gzip -dc sample_R2.fastq.gz | head -n 4
# 常见 10x 3′ 文库的输入片段，须并入你自己的 STAR 命令
# --readFilesIn sample_R2.fastq.gz sample_R1.fastq.gz --readFilesCommand zcat

接着检查允许的细胞条形码清单与化学体系是否相符，同时逐项对照细胞条形码和分子标签的起始位置、长度。某个参数写错一个碱基，切出来的条形码长度仍可能完全一致，继续运行也未必报错。一个有辨别力的试验是从同一小批成对记录提取预期位置的条形码，查看它们与该版本白名单的精确匹配状况。它适合比较两种布局谁合理。正式计数还可能纠正部分条形码错配，不能把这个试验的精确匹配率直接当成最终有效率。

用三层统计确定故障发生在哪里

从输出目录中同时找比对日志、选定特征类型下的原始矩阵，以及该类型对应的过滤矩阵。先抄三个量，比对有多少读段能落到参考基因组、原始矩阵里有多少非零分子计数、过滤后留下多少条形码。这三者的分母不同。一个样本的比对率很高，只能说明序列与参考有较好匹配，并不保证它带着可用的细胞条形码，也不保证最终能归入某个基因。

若问题落在第二层，别遗漏“给什么特征计数”这个问题。只统计外显子证据，与允许计入基因范围内含子证据，回答的是不同问题。单核测序中若未剪接转录本较多，这个差别尤其值得先查。记录运行时的 --soloFeatures、选来下游分析的子目录，以及建索引所用的注释版本。把一套参考的基因矩阵和另一套参考的全基因范围矩阵交叉比较，会把计数定义的差异误认为是细胞判定造成的损失。STAR 与 STARsolo 的参数定义

如果有两份化学体系相同、来自同一批次的文库，可以把两份日志的同一项指标横向对齐。只有其中一份条形码识别差，优先回看那份文库的文件与泳道拆分。两份都在同一处掉下去，再查共有的白名单、参考与参数。这种对照不能排除实验问题，但能缩小需要动手重跑的范围。

实跑经验｜故意对调两份 FASTQ，看错误最先出现在哪里

在 Ubuntu 24.04 安装 STAR 2.7.11b，构造一个已知基因、五个条形码及五十六对双端读段。每个分子恰好测两次，按精确 UMI 去重后，五个条形码得到 12、8、5、2、1 个分子，合计二十八，与设计逐项一致。按正确顺序输入时，分子计数全都能对上。只对调两份 FASTQ，第一条读段就触发报错，程序期待二十八个碱基的条形码读段，却读到了五十个碱基的转录本读段，退出码为 104。遇到这种信息时先核实文件身份与长度，关掉长度检查会掩盖这次输入错误。

还实际在原矩阵上单独重做了细胞过滤。在这个固定版本和这组无并列的五个计数上，TopCells 参数取 3 时得到四列，计数为 12、8、5、2，参数取 2 时得到三列，计数为 12、8、5。源代码在降序数组中取相应位置作阈值，保留达到该阈值的条形码。这个实测说明不能把示例参数直接当作输出细胞数。交付时保留原矩阵，核对过滤矩阵的实际列名和阈值处的计数，再写下究竟删除了哪些条形码。本次使用版本的细胞过滤实现

只改细胞判定时，沿用同一份原始矩阵

假设某次检查得到五个教学条形码，各自有一千、八百、六百、十二、八个分子。若方案甲保留前三个，方案乙只保留前两个，两份原始矩阵其实完全一样。应该拿第三个条形码的表达谱回看，检查它与低计数液滴的背景是否类似，以及它能否形成符合组织背景的标记组合。如果两次连原始分子数都变了，就得先回前一步寻找读段归属、参考或分子去重设置上的差异。这个五列例子只演示比较顺序，不能用其中任何数字制定正式阈值。

STARsolo 提供在已有原始计数矩阵上单独运行细胞过滤的模式。把原始目录设为输入，指定新的输出前缀，就能保留最初结论，比较另一种细胞判定得到的结果。官方列出的 EmptyDrops_CR 利用与环境背景的表达差异识别部分低计数条形码。它和简单地截取分子数最高的若干列具有不同含义，核查结果时应列出新增和移除的条形码，而不仅仅报两个总数。

STAR --runMode soloCellFiltering Solo.out/Gene/raw/ check_ \
  --soloCellFilter EmptyDrops_CR

对于两套具有相同原始计数的结果，我会保留三个集合，双方都有、第一次独有、第二次独有。分别查看每个集合的分子数、基因数和已知谱系标记。两套结果即使都报告两千个细胞，也可能各自换掉几百个条形码。若更换的主要是测序较浅的小淋巴细胞，后续细胞比例可能受到影响。若边界上主要是零星表达高丰度环境基因的液滴，就需要在报告中保留这一解释。这样下一位接手的人能确切知道哪些生物学结论需要重看。

正式交付时保存三样东西就能大幅缩短复盘时间，带泳道顺序的输入清单、当时的完整参数，以及变动过的条形码集合。下一批文库表现异常时，先沿着这三个环节定位，再决定是重比对还是仅重做细胞过滤。需要在同一分析环境中持续处理多批原始读段时，可了解云生信的生物信息分析服务器。