用途
本技能是批量 RNA-seq 的命令行定量入口：把原始 FASTQ 读段加参考转录组，转成转录本级丰度估计（counts + TPM），再用 tximport/tximeta 汇总到基因级，交给 alterlab-pydeseq2 做差异表达。它是仓库中 Python 分析技能所假设已经跑完的“原始数据到计数矩阵”流程。
主要能力
- 用 salmon 2.x 构建 decoy-aware 的 gentrome 索引，并逐样本运行 salmon quant（选择性比对为默认模式，可选 --sketch 无比对伪比对）。
- 用 kallisto（独立版 v0.52.0）或 kb-python 包装器（kb）做伪比对定量，kb-python 驱动 kallisto | bustools 并输出整洁结果。
- 通过 scripts/build_tx2gene.py 从 GTF/GFF3 生成 tx2gene 映射，再用 scripts/import_quant.py 把各样本 quant.sf 汇总为基因级计数矩阵与 TPM 矩阵。
- 支持长读长：kb-python 通过 --long 暴露 lr-kallisto（及 k>31 的 k-mer），用于 ONT/PacBio cDNA。
- 提供 nf-core/rnaseq v3.26.0 作为端到端、可追溯的替代方案（默认 --aligner star_salmon）。
使用方式
- 构建 decoy-aware gentrome 索引（每个参考一次）：decoys.txt 为基因组序列名，gentrome = 转录本 FASTA 在前、基因组 FASTA 在后，然后运行 salmon index（-k 31 为默认 k-mer）。辅助脚本 scripts/make_decoys.py 可生成 decoys.txt 与 gentrome.fa，并在基因组名未出现在转录本 FASTA 时拒绝继续。
- 逐样本定量：salmon quant 使用 -l A 自动检测文库类型（链特异性），建议加 --gcBias；2.x 中 --validateMappings 已无作用，选择性比对是默认且唯一模式。单端读段用 -r 而非 -1/-2。每样本输出 quants/<sample>/quant.sf 与 lib_format_counts.json。
- 用 tximport 汇总到基因级：先由注释生成 tx2gene，再运行 import_quant.py 得到整数取整的基因×样本计数矩阵与 TPM 矩阵。该脚本在转录本级实现 tximport 的 makeCountsFromAbundance(..., "lengthScaledTPM")，即按样本平均有效长度缩放每个转录本的 TPM，再把每个样本列重新缩放到其比对读段文库大小，然后求和到基因。
- 交给差异表达：把 gene_counts.tsv（加样本/条件表）传给 alterlab-pydeseq2。本技能不调用 DEG。
kallisto 路径：kallisto index 建索引，kallisto quant 定量，输出 abundance.tsv / abundance.h5，可按 type="kallisto" 喂给 tximport。kb-python 工作流中，kb ref 的 -f1 是 kb 写出的 cDNA FASTA，末尾位置参数依次为基因组 FASTA 和 GTF；kb count 用 -x bulk。kallisto 不使用 decoy/gentrome 构建，那是 salmon 特有的。
适用场景
- “用 salmon / kallisto 定量我的 RNA-seq。”
- “构建 decoy-aware salmon 索引（gentrome + decoys.txt）。”
- “用 --gcBias 跑选择性比对”或“使用 salmon 的 --sketch 模式”。
- “我有 quant.sf 文件——帮我生成用于 DESeq2 的基因级计数矩阵。”
- “用 tx2gene 映射设置 tximport / tximeta。”
- “用 kb-python / kb count 对这些读段做伪比对。”
不触发的情况（应路由到对应技能）：计数矩阵上的差异表达 → alterlab-pydeseq2；单细胞 RNA-seq 定量（原 salmon alevin）→ piscem + alevin-fry，下游 → alterlab-scanpy / alterlab-scvi-tools；FASTQ 到 VCF 的胚系/体细胞变异检测 → alterlab-nf-core-sarek；16S/ITS 扩增子 → alterlab-qiime2-amplicon；空间转录组 → alterlab-squidpy-spatial；把结果矩阵作为 AnnData 加载/操作 → alterlab-anndata；BLAST/DIAMOND 序列相似性搜索 → alterlab-blast；基因/转录本 ID 查询与参考获取 → alterlab-gget；比对 BAM 操作、覆盖度、从比对计数 → alterlab-pysam。
限制与注意事项
- salmon 2.0 无法读取 C++（pufferfish）索引，索引格式随重写改变；加载旧索引或用旧 salmon 指向 2.x 索引会被检测并明确报错。必须用与定量相同的 salmon 版本重建每个索引。quant.sf 与 bootstrap/Gibbs 输出未变，tximport、tximeta、fishpond、swish 在 2.x 输出上无需改动即可继续工作。
- --validateMappings 在 2.x 中不再起作用，选择性比对是默认且唯一模式，该标志会被解析并记录警告。其他若干 C++ 标志现在会报错：--mimicBT2、--mimicStrictBT2、--minAssignedFrags、--numBiasSamples、--alternativeInitMode。
- salmon alevin 已被移除，单细胞定量不再属于 salmon；salmon alevin … 会打印重定向并退出。单细胞/液滴数据应改用 piscem + alevin-fry 生态。若确需旧行为，最终 C++ 版本（salmon 1.12.0）位于上游 cpp 分支，并单独打包为 salmon-cpp。
- --ignoreTxVersion（2.x 新增）配合 -g/--geneMap 时，匹配转录本 ID 会忽略末尾的 .N，与 tximport 同名选项一致；用于 Ensembl cDNA 索引对 Ensembl GTF。当转录本无法匹配基因映射时，2.x 会把有问题的名称写入 aux_info/genemap_unmatched_txps.json 并只警告一次（带计数），而非 C++ salmon 的每个转录本一次警告；任何使用 -g 的运行后应检查该文件。
- 本技能止于计数/丰度矩阵，不调用 DEG，不处理单细胞条形码，也不为变异检测做基因组比对。
- 索引与逐样本定量是 CPU/IO 密集型但完全离线，适合在本地工作站直接运行（例如过夜），而不是通过 API 会话流式传输大型 FASTQ。索引构建一次，样本循环定量。
报告前自检
- 是否用与定量相同的 2.x 二进制重建了 salmon 索引？C++/pufferfish 索引会被直接拒绝。
- salmon 索引是否为 decoy-aware（gentrome + decoys.txt）？确认基因组名已进入 decoys.txt。
- 是否让 -l A 推断链特异性，并在 lib_format_counts.json 中检查推断类型？
- 数据是否其实是单细胞？若是则绝不能走此路径——salmon alevin 已移除，应路由到 piscem + alevin-fry。
- 是否止于计数矩阵并把 DE 交给 alterlab-pydeseq2，而不是在此调用 DEG？
参考文件
- 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 替代方案。