bulk-rnaseq

Bulk RNA-seq

概述

此技能编排完整且经得起审查的 Bulk RNA-seq 差异表达研究，从原始测序读段到富集通路和图表。它是一个路由器，而非重新实现：此仓库中的大多数阶段已有专门技能，此技能会按正确顺序将它们串联起来，填补唯一真正的空缺（原始读段 → 基因层级计数矩阵），并落实决定最终结果是否可信的设计与质控决策。

“经得起审查”贯穿始终，包含三方面：

• 可复现 — 固定流水线和工具版本，尽可能使用容器，记录参数，固定随机种子。
• 设置质量门槛 — 在定量前、期间和之后检查并处理质控结果，而不是跳过。
• 统计严谨 — 重复数充足，设计符合生物学实际，正确处理计数，并控制 FDR。

流水线为：FastQC/修剪 → 比对/定量（STAR/Salmon）→ 计数 → 差异表达（pydeseq2）→ 富集（pathway-enrichment）→ 图表。

何时使用此技能

当用户希望执行以下操作时，请使用此技能：

• 从 FASTQ 文件（或一次测序运行）开始，获得差异表达基因和通路。
• 运行或配置 nf-core/rnaseq，或使用 STAR、Salmon 或 featureCounts 进行比对/定量。
• 将 Salmon/STAR/featureCounts 输出转换为适用于 DESeq2/PyDESeq2 的计数矩阵。
• 在投入计算资源前，设计或检查 Bulk RNA-seq 实验（重复、批次、链特异性）。
• 规划端到端 RNA-seq 分析，并决定要串联哪些工具和技能。

这是Bulk RNA-seq（样本 = 生物学标本）。对于单细胞/细胞核数据，请使用 scanpy；仅需进行差异表达统计时，请使用 pydeseq2；仅需进行富集分析时，请使用 pathway-enrichment。

流水线一览

flowchart TD
    fastq["Raw FASTQ + samplesheet"] --> qc["FastQC + MultiQC"]
    qc --> trim["Trim: fastp / Trim Galore"]
    trim --> align["Align + quant: STAR and/or Salmon"]
    align --> counts["Gene-level counts matrix"]
    counts --> de["Differential expression"]
    de --> enrich["Pathway / GSEA enrichment"]
    de --> fig["Figures"]
    enrich --> fig
    nfcore["nf-core/rnaseq via nextflow skill"] -.->|"path A"| align
    manual["Standalone recipes (this skill)"] -.->|"path B"| align
    bridge["build_counts_matrix.py (this skill)"] -.-> counts
    pydeseq2skill["pydeseq2 skill"] -.-> de
    pwskill["pathway-enrichment skill"] -.-> enrich
    vizskill["scientific-visualization skill"] -.-> fig

两条上游路径 — 选择其一

读段 → 计数阶段有两种运行方式。两者生成等效的基因计数；请根据具体情况选择，然后沿用该路径。

在以下情况下使用 路径 A — nf-core/rnaseq：	在以下情况下使用 路径 B — 独立工具：
你希望使用业界标准、经过审查且可引用的流水线，只需一条命令	样本较少，并希望了解/检查每个步骤
样本较多，或准备扩展至 HPC/云端	没有 Nextflow/容器，或环境受限
可复现性和完整的 MultiQC 报告最重要	你需要流水线未提供的非标准步骤
→ 通过 nextflow 技能运行	→ 按照 references/upstream-manual.md 操作

不确定时，请优先选择路径 A：nf-core/rnaseq 已将 FastQC → 修剪 → STAR/Salmon → 定量 → tximport → MultiQC 串联起来，并采用合理且经过审查的默认设置，这是最经得起审查的方案。路径 B 适用于需要透明度或环境受限的情况。

两条路径最终都会得到基因层级计数矩阵，之后的工作流完全相同。

设置

# This skill's glue (bridge + handoffs) — Python
uv pip install pytximport pandas

# Downstream skills install their own deps:
#   pydeseq2 skill           -> uv pip install pydeseq2
#   pathway-enrichment skill -> uv pip install gseapy gprofiler-official

# Path A (nf-core): only Nextflow + a container engine are needed — see the `nextflow` skill.

# Path B (standalone tools): install via bioconda. Pin versions for reproducibility.
conda create -n rnaseq -c bioconda -c conda-forge \
  fastqc fastp trim-galore "star=2.7.11b" "salmon=1.10.3" subread multiqc

记录所用的准确版本（流水线修订版、工具版本、参考基因组及注释版本）——这些信息应写入方法部分，并使分析可复现。

快速入门

路径 A — nf-core/rnaseq（推荐）

# 0. Validate the samplesheet first (catches the most common failures early)
python scripts/validate_samplesheet.py --samplesheet samplesheet.csv

# 1. Smoke-test the environment with tiny bundled data
nextflow run nf-core/rnaseq -r 3.26.0 -profile test,docker --outdir test_results

# 2. Real run: pin the revision, pick an aligner, pass a samplesheet + reference
nextflow run nf-core/rnaseq -r 3.26.0 \
  -profile docker \
  --input samplesheet.csv \
  --genome GRCh38 \
  --aligner star_salmon \
  --outdir results \
  -resume

nf-core/rnaseq 会在内部运行 tximport，因此输出的基因计数已经合并——无需桥接脚本。使用 results/star_salmon/salmon.merged.gene_counts_length_scaled.tsv 进行差异表达分析。样本表格式、比对器选择和输出：references/upstream-nfcore.md。有关运行引擎/HPC/云端/容器的详情，请使用 nextflow 技能。

路径 B — 独立 STAR/Salmon（简略版）

fastqc -o qc/ reads/*.fastq.gz                      # 1. QC raw reads
fastp -i s1_R1.fq.gz -I s1_R2.fq.gz \
      -o s1_R1.trim.fq.gz -O s1_R2.trim.fq.gz \
      --thread 4 -j s1.fastp.json                   # 2. Trim adapters/low-quality
salmon quant -i salmon_index -l A \
      -1 s1_R1.trim.fq.gz -2 s1_R2.trim.fq.gz \
      --gcBias --seqBias -p 8 -o quant/s1            # 3. Quantify (per sample)

完整操作指南（FastQC、fastp/Trim Galore、STAR 索引+比对+--quantMode GeneCounts、Salmon decoy 感知索引、featureCounts、链特异性）：references/upstream-manual.md。

计数 → 差异表达 → 富集（两条路径均适用）

# Path B only: assemble a gene x sample counts matrix + metadata template for PyDESeq2
python scripts/build_counts_matrix.py --from salmon \
  --quant-dir quant/ --tx2gene tx2gene.tsv --output-dir counts/

# Then hand off (see the dedicated skills):
#   pydeseq2:           counts.csv + metadata.csv -> DE table (log2FC, padj, stat)
#   pathway-enrichment: rank by `stat` (GSEA) or padj+|LFC| hit list (ORA)
#   scientific-visualization / matplotlib: volcano, MA, heatmap, PCA, enrichment dotplot

分阶段工作流

按从上到下的顺序进行。每个阶段都会指出负责相关细节的技能或文件。不要跳过设计和 QC 阶段——bulk RNA-seq 研究最常在这些环节出错。

1. 设计与样本表。 确认每组至少有 3 个生物学重复，识别批次和混杂因素，并选择比较组。构建样本表，并使用 scripts/validate_samplesheet.py 验证。设计依据与规则：references/design-and-qc.md。
2. 原始读段 QC。 对每个文件运行 FastQC；使用 MultiQC 汇总。检查每个碱基的质量、接头含量、重复率和过度表示情况。阈值：references/design-and-qc.md。
3. 剪切。 去除接头和低质量末端（使用 fastp 或 Trim Galore）。重新运行 FastQC 进行确认。操作方案：references/upstream-manual.md（Path A 会自动完成这一步）。
4. 比对 / 定量。 使用 STAR（基因组比对 + --quantMode GeneCounts）和/或 Salmon（转录本准比对，考虑诱饵序列）。确定链特异性——这很容易弄错，并会导致计数在不知情的情况下减半。详情：references/upstream-manual.md；流程参数：references/upstream-nfcore.md。
5. 构建计数矩阵。 将定量输出转换为基因 × 样本的整数矩阵和元数据模板（scripts/build_counts_matrix.py）。估算计数和基因 ID 映射的注意事项见 references/counts-and-handoff.md。
6. 差异表达 → pydeseq2 技能。 加载 counts.csv + metadata.csv，设置设计公式（例如 ~batch + condition），拟合模型，并使用 FDR 控制进行检验。检查 PCA 和 p 值直方图，作为 QC。
7. 富集分析 → pathway-enrichment 技能。 对于 GSEA，按 DESeq2 的 stat 对完整基因列表排序；对于 ORA，传入经过阈值筛选的命中列表（padj < 0.05，可选 |log2FC| > 1）。先将基因 ID 映射为符号。
8. 绘图 → scientific-visualization 技能。 绘制火山图、MA 图、样本距离热图、PCA 和富集点图，并附上 MultiQC 报告作为 QC 说明。

计数 → DE 桥接环节（关键衔接）

这是唯一没有上游 / 下游技能的阶段，因此由本技能负责。scripts/build_counts_matrix.py 会将定量输出转换为 pydeseq2 所需的格式：

• Salmon（--from salmon）：使用 pytximport 将每个样本的 quant.sf 汇总到基因层级，参数为 counts_from_abundance="length_scaled_tpm"（这是进行基因层级 DE 的正确选择），并需要 tx2gene 映射表。
• STAR（--from star）：读取每个 ReadsPerGene.out.tab，并根据 --strandedness（unstranded/forward/reverse）选择对应列。
• featureCounts（--from featurecounts）：解析合并后的 featureCounts 矩阵。

该脚本会生成 counts.csv（基因 × 样本，整数）和 metadata_template.csv（每个样本一行），供你填写。Salmon/RSEM 计数是估算值（非整数）；由于 PyDESeq2 要求计数为整数，因此会将其四舍五入为整数——关于使用 length_scaled_tpm 时这样做为何可接受，以及它与基于 offset 的 DESeq2+tximport 流程有何不同，请参阅 references/counts-and-handoff.md。该参考文件还介绍了 Ensembl → 符号映射（富集分析前需要进行）以及 PyDESeq2 所需的确切数据方向。

常见陷阱

以下问题最常导致大规模 RNA-seq 结果错误或无法复现：

1. 重复数过少。 每组少于 3 个生物学重复时，统计效能几乎为零，离散度估计也不稳定。增加重复数比加深测序更有效。
2. 批次与条件混杂。 如果所有处理组样本都在与对照组不同的日期或测序通道上处理，就无法挽回这种影响。请进行随机化，并对已知批次建模（~batch + condition）。参见 references/design-and-qc.md。
3. 链特异性设置错误。 选择错误的 STAR 列，或错误设置 featureCounts -s/Salmon 文库类型，会在无提示的情况下丢弃约一半 reads。使用 Salmon -l A 或推断链特异性，并核实分配到的 reads 比例。
4. 将 TPM/FPKM 输入 DESeq2。 DESeq2 需要原始（或按长度缩放的）计数，绝不能使用 TPM/FPKM/归一化值。桥接程序会处理此问题。
5. 计数不是整数。 PyDESeq2 要求整数；请对 Salmon 估算值进行四舍五入（桥接程序会执行此操作）。
6. 用于富集分析的基因 ID 不匹配。 DESeq2 输出通常是 Ensembl ID；Enrichr/MSigDB 需要基因符号。在运行 pathway-enrichment 前映射 ID，否则就会出现“没有显著结果”。
7. 跳过定量后的 QC。 在相信差异表达（DE）结果前，务必查看 PCA 和样本距离热图——它们能揭示标签互换、离群值和隐藏批次。
8. 不同样本混用比对工具。 所有样本都必须使用相同的工具、版本、参考数据和参数进行定量。
9. 版本未固定。 使用“latest”流水线/基因组会导致结果无法复现；请固定 -r、工具版本以及基因组/注释版本。

与其他技能集成

• 上游执行： nextflow（运行 nf-core/rnaseq，路径 A；HPC/云端/容器）。
• 参考数据 / 基因 ID： gget（使用 gget ref 获取基因组+GTF，使用 gget info/gget search 进行 ID 映射）、database-lookup（Ensembl/NCBI）、biopython/pysam（FASTA/BAM 处理）。
• 差异表达： pydeseq2（本技能将计数交给它作为 DE 引擎）。
• 富集分析： pathway-enrichment（ORA + GSEA；其 scripts/run_enrichment.py 可直接读取 DESeq2 结果 CSV）。
• 图表与报告： scientific-visualization、matplotlib、seaborn；使用 scientific-writing 撰写方法/结果叙述。
• 相关但不同： scanpy（单细胞）、statistical-analysis（深入了解多重检验）。

参考文件

需要深入了解时，请阅读相关文件——每个文件都可独立阅读：

• references/upstream-nfcore.md — 路径 A：样本表格式、--aligner/--pseudo_aligner 选择、关键参数、salmon.merged.gene_counts*.tsv 输出、MultiQC，以及交给 pydeseq2 的内容。
• references/upstream-manual.md — 路径 B：FastQC、fastp/Trim Galore、STAR 基因组索引 + 比对 + --quantMode GeneCounts、Salmon decoy-aware 索引 + quant、featureCounts，以及如何确定链特异性。
• references/counts-and-handoff.md — 将定量输出转换为 PyDESeq2 所需的 counts.csv/metadata.csv（pytximport、STAR 列选择、featureCounts）、整数/估算计数的细节、Ensembl→符号映射，以及 DE→富集分析的排序/命中列表方案。
• references/design-and-qc.md — 实验设计（重复、批次、混杂、设计公式）和 QC 指标解读（比对率、重复率、rRNA、复杂度、PCA/离群值）——构建可辩护流水线的基础。

资源

• nf-core/rnaseq：https://nf-co.re/rnaseq · STAR：https://github.com/alexdobin/STAR · Salmon：https://salmon.readthedocs.io
• fastp：https://github.com/OpenGene/fastp · Trim Galore：https://github.com/FelixKrueger/TrimGalore · MultiQC：https://multiqc.info
• pytximport：https://pytximport.complextissue.com · featureCounts (Subread)：https://subread.sourceforge.net
• 方法背景：Love et al. 2014 (DESeq2) DOI 10.1186/s13059-014-0550-8 · Soneson et al. 2015 (tximport) DOI 10.12688/f1000research.7563.2

相关技能

• pydeseq2：使用 PyDESeq2（DESeq2 的 Python 移植版）对批量 RNA-seq 计数数据进行差异表达分析。
• pathway-enrichment：对基因列表或排序后的基因数据进行通路和基因集富集分析，然后解读结果。
• nextflow：端到端构建、运行和调试 Nextflow 数据管道及 nf-core 工作流。