Skip to content

分析流程 › RNA-seq › 10 可重現性

可重現性與疑難排解 (Reproducibility & Troubleshooting) ​

整理 RNA-seq project 的環境、路徑、版本、log 與常見錯誤。這些內容不是形式問題,而是 RNA-seq 結果能否重現與被正確解讀的基礎。

可重現性 ​

建議專案目錄:

text
project/
├── data/
│   ├── raw/
│   ├── reference/
│   └── metadata/
├── results/
│   ├── fastqc/
│   ├── trimming/
│   ├── alignment/
│   ├── counts/
│   ├── de/
│   └── enrichment/
├── scripts/
├── logs/
└── README.md

應保存:

ItemWhy
Software versionsSTAR/HISAT2/Salmon/featureCounts/edgeR/DESeq2 版本會影響結果
Conda environment讓 command-line tools 可重建
R sessionInfo()保存 Bioconductor 與 annotation package 版本
renv.lockR package environment lock
Container對長期重現最穩
Random seedPCA label jitter、bootstrap、simulation、GSEA permutation 需固定
Relative paths避免專案搬移後失效
LogsFastQC、fastp、STAR、HISAT2、featureCounts、DE scripts
Gitscript versioning 與 review
Metadatasample sheet、batch、RIN、library prep、sequencing run
Reference genome versionFASTA、GTF、transcriptome、tx2gene 來源與 release

Conda 範例:

bash
conda create -n rnaseq -c conda-forge -c bioconda \
  fastqc multiqc fastp star hisat2 salmon kallisto samtools subread r-base
conda activate rnaseq

R session:

r
writeLines(capture.output(sessionInfo()), "results/sessionInfo.txt")

renv:

r
install.packages("renv")
renv::init()
renv::snapshot()

Workflow manager 的價值是把步驟依賴、版本、重跑條件與平行化管理起來;但本教學故意以 Bash/R/Python 分段呈現,讓讀者先理解每個分析步驟本身。

疑難排解 ​

ProblemSymptomLikely causeCheck / Fix
FASTQ incompletegzip EOF、行數非 4 倍數下載中斷或傳輸錯誤md5sum、重新下載
Paired-end reads 不成對aligner 報 read pair mismatchR1/R2 混樣或排序錯比對 read id,重新取得 pairs
Adapter 未移除FastQC adapter content 高insert 短、read-throughfastp/Cutadapt trimming
Reference/GTF 不一致mapping 或 counting 異常assembly release 混用檢查 release、chrom names
chr1 vs 1featureCounts assign 很低chromosome naming style 不同統一 FASTA/GTF/BAM naming
Mapping rate 低STAR/HISAT2 uniquely mapped 低污染、錯物種、低品質、短 readsFastQC、Kraken/FastQ Screen、reference check
rRNA reads 高exonic protein-coding reads 低rRNA depletion 失敗RSeQC/Picard RNA metrics
Strandness 設錯featureCounts 幾乎無 reads assigned-s 或 library type 錯RSeQC infer_experiment.py
featureCounts no assignmentUnassigned_NoFeatures 高GTF/FASTA/BAM 不一致或 intronic readscheck annotation, strandedness, RNA type
Metadata 順序錯group signal 混亂count columns 未對齊 sample tableidentical(colnames(counts), metadata$sample_id)
Count matrix 含小數DESeq2 報錯或 silent roundingtranscript estimated counts用 tximport 正確匯入或 round only when appropriate
TPM 直接跑 edgeR/DESeq2結果模型假設錯TPM 不是 count回到 raw/estimated counts
Biological replicate 太少dispersion 不穩、power 低n 不足增加 biological replicates
Group/batch confoundeddesign not full rank實驗安排完全重疊無法統計修正,需新資料
PCA outlier單一樣本遠離QC、batch、sample swap 或真實 biology多圖與 lab record 一起查
Gene ID 無法轉換annotation 大量 NAversion suffix、物種 DB 錯去 suffix、確認 OrgDb/biomaRt dataset
ORA background 錯pathway 過度顯著用全基因組當 universe使用實際 tested genes
Technical replicate 當 biologicalp-value 過小pseudo-replication合併 technical replicate 或正確建模

驗證狀態 ​

各腳本的實跑狀態見 README:驗證狀態。

重跑範例 ​

bash
cd biology/genomics/workflows/rna-seq          # 從 notebook 根目錄

# 重新產生本教學的模擬資料與圖。
python scripts/simulate_rnaseq_demo.py --outdir .

# 有真實 FASTQ 時。
bash scripts/fastq_qc.sh data/raw results/01_fastq_qc
bash scripts/fastp_trim.sh data/sample_metadata.csv . results/02_fastp_trim

# 有 reference 時。
THREADS=12 READ_LENGTH=101 bash scripts/star_alignment.sh reference/genome.fa reference/genes.gtf results/02_fastp_trim/fastq results/03_star
bash scripts/featurecounts_gene_counting.sh reference/genes.gtf results/03_star/bam results/06_featurecounts

可再擴充的方向:

  • 加入真實公開資料集的 end-to-end 範例。
  • 補 single-end、stranded/unstranded 三種 library 的對照結果。
  • 加入 RSeQC gene body coverage 與 read distribution 實際圖。
  • 加入 Salmon decoy-aware index 建立完整範例。
  • 加入 batch correction、SVA/RUVSeq 與 time-course DE。
  • 補充 transcript usage、alternative splicing 與 fusion analysis。