alterlab-rnaseq-quant

RNA-seq 定量——salmon 和 kallisto 转录本丰度

用于 bulk RNA-seq 的命令行定量入口：输入原始 FASTQ reads 和参考转录组，使用 salmon（选择性比对）或 kallisto（通过 kb-python 进行伪比对）生成转录本水平的丰度估计（counts + TPM），然后通过 tximport/tximeta 汇总到基因水平，并交由 alterlab-pydeseq2 进行差异表达分析。这是从原始数据生成 count 矩阵的流水线；仓库中的 Python 分析技能假定该流程已运行。

快速开始

Quantify these RNA-seq FASTQs with salmon and a decoy-aware index
Build a salmon gentrome index from this transcriptome + genome
Run kallisto / kb count on my paired-end reads
Turn my salmon quant.sf files into a gene-level count matrix for DESeq2

→ 构建一次包含诱饵序列的索引，然后对每个样本运行 salmon quant（或 kb count），接着运行 scripts/build_tx2gene.py + scripts/import_quant.py，生成 tximport 基因矩阵并将其交给 alterlab-pydeseq2。

---

何时使用此技能

当请求涉及使用轻量级定量工具从 FASTQ 获取转录本或基因丰度时，请使用此技能：

• “用 salmon / kallisto 对我的 RNA-seq 进行定量。”
• “构建包含诱饵序列的 salmon 索引（gentrome + decoys.txt）。”
• “使用 --gcBias 运行选择性比对。” / “使用 salmon 的 --sketch 模式。”
• “我有 quant.sf 文件——帮我生成用于 DESeq2 的基因水平 count 矩阵。”
• “使用 tx2gene 映射设置 tximport / tximeta。”
• “使用 kb-python / kb count 对这些 reads 进行伪比对。”

不会触发——请将这些请求转交给对应的同类技能

请求的实际内容是……	转交给
对count 矩阵进行差异表达分析（DESeq2 Wald 检验、FDR、火山图）	alterlab-pydeseq2
单细胞 RNA-seq 定量（以前使用 salmon alevin）	piscem + alevin-fry——请参阅 references/single_cell_alevin.md；下游分析 → alterlab-scanpy / alterlab-scvi-tools
FASTQ 到 VCF 的胚系/体细胞变异检测	alterlab-nf-core-sarek
16S/ITS 扩增子（微生物组）FASTQ 到特征表	alterlab-qiime2-amplicon
空间转录组学（Visium/Xenium）邻域分析	alterlab-squidpy-spatial
将生成的矩阵加载为 AnnData 对象或对其进行操作	alterlab-anndata
BLAST/DIAMOND 序列相似性搜索	alterlab-blast
快速查询基因/转录本 ID 并获取参考数据（Ensembl/RefSeq）	alterlab-gget
已比对 BAM 的操作、覆盖度，以及从比对结果中进行 reads 计数	alterlab-pysam

此技能止于计数/丰度矩阵。它不会进行 DEG 检测，不处理单细胞条形码，也不会为变异检测而比对到基因组。

---

两个关键正确性陷阱（量化前请阅读）

如今 salmon 已升级到 2.x（从头使用 Rust 重写；bioconda 版本为 2.7.0），许多过时的 RNA-seq 说明中最常见的三个错误如下。上游 MIGRATION.md 已确认这些问题（参见 references/tool_versions.md）。

1. salmon 2.0 无法读取 C++（pufferfish）索引。 重写后索引格式已更改。加载旧索引，或使用旧版 salmon 加载 2.x 索引时，程序会检测到并明确报错，因此会显式失败，不会静默出错。请使用与量化时相同版本的 salmon 重建所有索引。 quant.sf 和 bootstrap/Gibbs 输出均未更改，因此 tximport、tximeta、fishpond 和 swish 无需任何更改即可继续处理 2.x 输出。

2. --validateMappings 不再起作用。 selective alignment 是 2.x 中默认且唯一的比对模式，因此该标志虽然可以解析，但会记录一条警告。从 2019 年的教程中照搬它无伤大雅，但容易造成误导；请删除它。其他几个 C++ 标志现在会直接报错：--mimicBT2、--mimicStrictBT2、--minAssignedFrags、--numBiasSamples、--alternativeInitMode。

3. salmon alevin 已移除。 单细胞量化不再属于 salmon；运行 salmon alevin … 会打印重定向提示并退出。请改用 piscem + alevin-fry 生态系统。如果用户有单细胞 / 液滴数据，请按上表进行路由，并参见 references/single_cell_alevin.md。

如果确实需要旧版行为，最终的 C++ 版本（salmon 1.12.0）位于上游 cpp 分支，并作为独立软件包 salmon-cpp 发布。

---

工作流（salmon，默认路径）

1. 构建能识别诱饵序列的 gentrome 索引（每个参考序列构建一次）

能识别诱饵序列的索引可让 salmon 区分哪些 reads 与基因组的比对效果优于与转录组的比对效果，从而减少错误分配。构建“gentrome”时，将转录本 FASTA 与基因组 FASTA 拼接，并创建一个列出基因组序列名称作为诱饵的 decoys.txt。

# 1. decoys.txt = the genome's sequence (chromosome) names, one per line
grep "^>" genome.fa | sed 's/^>//; s/ .*//' > decoys.txt

# 2. gentrome = transcripts FIRST, then genome (order matters)
cat transcripts.fa genome.fa > gentrome.fa

# 3. build the index (rebuild under salmon 2.x — see trap #1)
salmon index \
  -t gentrome.fa \
  -d decoys.txt \
  -i salmon_index \
  -k 31 \
  -p 8

• -k 31 是默认 k-mer 长度；仅在 reads 非常短时才调低。
• 辅助脚本 scripts/make_decoys.py 会为你生成 decoys.txt 和 gentrome.fa；如果基因组名称未出现在转录本 FASTA 中（这是常见的隐蔽错误），脚本会拒绝继续。参见 references/decoy_index.md。

2. 量化每个样本

salmon quant \
  -i salmon_index \
  -l A \
  -1 sampleA_R1.fastq.gz -2 sampleA_R2.fastq.gz \
  --gcBias \
  -p 8 \
  -o quants/sampleA

• -l A — 自动检测文库类型（链特异性）。除非你有已记录的实验方案，否则让 salmon 自动推断，并在 lib_format_counts.json 中确认推断出的类型。
• Selective alignment 是 salmon 2.x 中的默认模式 — 没有开启该模式的标志（--validateMappings 会被接受，但会被忽略）。--sketch 会选择退出该模式，改用速度更快的无比对 pseudoalignment；如果量化结果用于差异表达分析，请优先使用默认模式；只有在速度优先的超大规模筛查中才使用 --sketch。
• --gcBias — 校正片段级别的 GC 偏差；推荐用于差异表达分析，且启用成本低。如有需要，可添加 --seqBias，校正 5'/3' 序列特异性偏差。
• --ignoreTxVersion（2.x 新增）— 与 -g/--geneMap 搭配使用时，匹配转录本 ID 时忽略末尾的 .N，其行为与 tximport 中同名选项相同。将 Ensembl cDNA 索引与 Ensembl GTF 搭配使用时需要此选项。如果转录本无法与基因映射表匹配，2.x 会将不匹配的名称写入 aux_info/genemap_unmatched_txps.json，并只发出一次警告，其中包含不匹配数量；而 C++ salmon 会对每个转录本分别发出警告 — 任何使用了 -g 的运行结束后，都请检查该文件。
• 对于单端 reads，请传入 -r reads.fastq.gz，而不是 -1/-2。

每个样本会生成 quants/<sample>/quant.sf（转录本级别的估计值）和 quants/<sample>/lib_format_counts.json（推断出的文库类型）。有关完整的标志说明和逐样本 QC 检查，请参见 references/salmon_quant.md。

3. 使用 tximport 汇总到基因层级

根据注释构建转录本→基因映射（tx2gene），然后将每个样本的 quant.sf 文件汇总为 pydeseq2 使用的基因层级矩阵。

# tx2gene from a GTF/GFF3 (transcript_id -> gene_id)
uv run python scripts/build_tx2gene.py annotation.gtf --out tx2gene.tsv

# import + summarize to gene level (tximport "lengthScaledTPM" counts)
uv run python scripts/import_quant.py \
  --quants quants \
  --tx2gene tx2gene.tsv \
  --out-counts gene_counts.tsv \
  --out-tpm gene_tpm.tsv

import_quant.py 会生成一个整数取整后的基因 × 样本计数矩阵，以及一个 基因 × 样本 TPM 矩阵，这些正是 alterlab-pydeseq2 需要的输入。它在转录本层级实现了 tximport 的 makeCountsFromAbundance(..., "lengthScaledTPM")（将每个转录本的 TPM 乘以其样本平均有效长度，然后将每个样本列重新缩放到其比对读取文库大小），再汇总到 基因层级，因此计数经过长度校正并按文库大小缩放，并非直接对 NumReads 求和。标准的 R 路径是使用 tximport / tximeta Bioconductor 软件包，并设置 countsFromAbundance = "lengthScaledTPM"；这里的 Python 辅助工具复现了该计算，因此你可以继续使用 uv（区别仅在于整数取整方式不同， 且不包含 tximeta 来源信息）。有关确切语义、tximeta 的 linkedTxome 元数据选项，以及 何时优先使用 R 路径，请参阅 references/tximport_handoff.md。

4. 移交至差异表达分析

将 gene_counts.tsv（以及样本/条件表）传给 alterlab-pydeseq2。 此技能不会调用 DEGs——这是 pydeseq2 的工作（大小因子 标准化、离散度估计、Wald 检验、BH-FDR、火山图/MA 图）。

---

流程（kallisto，伪比对路径）

kallisto（独立版本 v0.52.0）和 kb-python 封装器（kb）提供了 更快的伪比对路径。kb-python 会调用 kallisto | bustools 并写出整洁的输出。

# build a kallisto index from the transcriptome
kallisto index -i kallisto_index.idx transcripts.fa

# quantify a paired-end sample
kallisto quant -i kallisto_index.idx -o quants_kallisto/sampleA \
  sampleA_R1.fastq.gz sampleA_R2.fastq.gz

# OR the kb-python workflow (bulk)
# -f1 is the cDNA FASTA kb WRITES; trailing positionals are genome FASTA THEN GTF
kb ref -i index.idx -g t2g.txt -f1 cdna.fa genome.fa annotation.gtf
kb count -i index.idx -g t2g.txt -x bulk -o quants_kb/sampleA \
  sampleA_R1.fastq.gz sampleA_R2.fastq.gz

• kallisto 输出 abundance.tsv / abundance.h5；将这些文件交给 tximport （type="kallisto"），用法与 salmon 的 quant.sf 相同。
• 长读长： kb-python 通过 --long 标志（以及 k>31 的 k-mer）提供 lr-kallisto—— 用于 ONT/PacBio cDNA。请参阅 references/kallisto_kb.md。
• kallisto 不使用 decoy/gentrome 构建；这是 salmon 专用的。

---

一站式替代方案——nf-core/rnaseq

对于端到端、可追溯来源的流程（修剪 → 比对 → 定量 → QC），nf-core/rnaseq v3.26.0 默认运行 --aligner star_salmon： STAR 将读取比对到基因组，再投射到转录组，由 Salmon 进行定量。当用户需要可复现的 Nextflow 流程，而不是手动运行命令时，可使用此方案；此技能涵盖 直接使用 salmon/kallisto 的路径及 tximport 移交。请参阅 references/tool_versions.md。

---

卸载说明

索引构建和逐样本定量会占用大量 CPU/IO，但完全可以离线完成。在本地 工作站上，这些任务适合直接运行（例如过夜），而不是通过 API 会话流式传输大型 FASTQ 文件。 索引只需构建一次；在循环中对样本进行定量。

---

报告前自检

• 你是否使用定量时相同的 2.x 二进制文件重新构建了 salmon 索引 （陷阱 #1）？C++/pufferfish 索引会被直接拒绝。
• salmon 使用的索引是否包含 decoy（gentrome + decoys.txt）？请确认 基因组名称已写入 decoys.txt。
• 你是否让 -l A 推断链特异性，并在 lib_format_counts.json 中检查了推断的 类型是否合理？
• 数据是否确实为单细胞？如果是，则不得使用此路径—— salmon alevin 已不可用；请改用 piscem + alevin-fry（陷阱 #2）。
• 你是否停留在计数矩阵这一步，并将差异表达分析移交给 alterlab-pydeseq2， 而不是在此处调用 DEGs？

---

参考资料

• references/tool_versions.md — 固定版本 （salmon 2.x、kallisto v0.52.0、kb-python、nf-core/rnaseq）以及上游发行说明中的事实（2.0 重写和索引不兼容、移除 alevin）。
• references/decoy_index.md — decoy-aware gentrome 索引构建、注意事项和 make_decoys.py 辅助脚本。
• references/salmon_quant.md — salmon quant 标志映射、 文库类型推断和逐样本 QC。
• references/kallisto_kb.md — kallisto / kb-python 工作流、--long（lr-kallisto）和输出处理。
• references/tximport_handoff.md — tximport / tximeta 汇总、tx2gene、countsFromAbundance 以及与 pydeseq2 的交接。
• references/single_cell_alevin.md — 移除 salmon alevin 的原因，以及 piscem + alevin-fry 替代方案。

属于 AlterLab Academic Skills 套件。