alterlab-rnaseq-quant

Files (11)

• SKILL.md
• evals.json · evals/
• decoy_index.md · references/
• kallisto_kb.md · references/
• salmon_quant.md · references/
• single_cell_alevin.md · references/
• tool_versions.md · references/
• tximport_handoff.md · references/
• build_tx2gene.py · scripts/
• import_quant.py · scripts/
• make_decoys.py · scripts/

SKILL.md (first lines)

# RNA-seq Quantification — salmon & kallisto Transcript Abundance

The command-line quantification entry point for bulk RNA-seq: take raw FASTQ
reads plus a reference transcriptome and produce transcript-level abundance
estimates (counts + TPM) with **salmon** (selective alignment) or **kallisto**
(pseudoalignment via kb-python), then aggregate to the gene level with
`tximport`/`tximeta` and hand off to `alterlab-pydeseq2` for differential
expression. It is the raw-data-to-count-matrix pipeline that the repo's Python
analysis skills assume already ran.

## Quick Start

```
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
```

→ Build a **decoy-aware** index once, run `salmon quant` (or `kb count`) per
sample, then run `scripts/build_tx2gene.py` + `scripts/import_quant.py` to make
the `tximport` gene matrix and route it to `alterlab-pydeseq2`.

---

## When to Use This Skill

Use this skill when the request is about **getting from FASTQ to transcript or
gene abundance** with a lightweight quantifier:

- "Quantify my RNA-seq with salmon / kallisto."
- "Build a decoy-aware salmon index (gentrome + decoys.txt)."
- "Run selective alignment with `--gcBias`." / "Use salmon's `--sketch` mode."
- "I have `quant.sf` files — make me a gene-level count matrix for DESeq2."
- "Set up `tximport` / `tximeta` with a tx2gene map."
- "Use kb-python / `kb count` to pseudoalign these reads."

### Does NOT Trigger — route these to the right sibling

| The request is really about… | Route to |
|------------------------------|----------|
| Differential expression on a **count matrix** (DESeq2 Wald tests, FDR, volcano) | `alterlab-pydeseq2` |
| **Single-cell** RNA-seq quantification (was `salmon alevin`) | piscem + alevin-fry — see [references/single_cell_alevin.md](references/single_cell_alevin.md); downstream → `alterlab-scanpy` / `alterlab-scvi-tools` |
| **FASTQ-to-VCF** germline/somatic variant calling | `alterlab-nf-core-sarek` |
| **16S/ITS amplicon** (microbiome) FASTQ-to-feature-table | `alterlab-qiime2-amplicon` |
| **Spatial** transcriptomics (Visium/Xenium) neighborhood analysis | `alterlab-squidpy-spatial` |
| Loading/manipulating the resulting matrix as an **AnnData** object | `alterlab-anndata` |
| BLAST/DIAMOND **sequence similarity search** | `alterlab-blast` |
| Quick gene/transcript **ID lookups & reference fetch** (Ensembl/RefSeq) | `alterlab-gget` |
| Aligned **BAM** manipulation, coverage, read counting from alignments | `alterlab-pysam` |

This skill stops at the **count/abundance matrix**. It does not call DEGs, does
not handle single-cell barcodes, and does not align to a genome for variant
calling.

---

## Two Critical Correctness Traps (read before quantifying)

These are the three failures most outdated RNA-seq instructions get wrong now that
salmon has moved to **2.x** (a from-scratch Rust rewrite; bioconda 2.7.0). All are
confirmed in the upstream `MIGRATION.md` (see
[references/tool_versions.md](references/tool_versions.md)).

1. **salmon 2.0 cannot read a C++ (pufferfish) index.** The index format changed
   with the rewrite. Loading an old index — or pointing old salmon at a 2.x index —
   is detected and rejected with a clear error, so this fails loudly rather than
   silently. **Rebuild every index** with the same salmon version you quantify with.
   `quant.sf` and the bootstrap/Gibbs outputs are unchanged, so tximport, tximeta,
   fishpond and swish keep working on 2.x output with no changes.

2. **`--validateMappings` no longer does anything.** Selective alignment is the
   default (and only) alignment mode in 2.x, so the flag parses and logs a warning.
   Copying it from a 2019-era tutorial is harmless but misleading; drop it. Several
   other C++ flags now **error out**: `--mimicBT2`, `--mimicStrictBT2`,
   `--minAssignedFrags`, `--numBiasSamples`, `--alternativeInitMode`.

3. **`salmon alevin` was REMOVED.** Single-cell quantification is no longer part of
   salmon; `salmon alevin …` prints a redirect and exits. Use the
   **piscem + alevin-fry** ecosystem instead. If the user has single-cell / droplet
   data, route per the table above and see
   [references/single_cell_alevin.md](references/single_cell_alevin.md).

If you genuinely need the old behavior, the final C++ release (salmon 1.12.0) lives
on the upstream `cpp` branch and is packaged separately as `salmon-cpp`.

---

## Pipeline (salmon, the default path)

### 1. Build a decoy-aware gentrome index (once per reference)

A **decoy-aware** index lets salmon distinguish reads that align better to the
genome than the transcriptome, reducing spurious assignments. You build a
"gentrome" = transcripts FASTA **concatenated with the genome FASTA**, plus a
`decoys.txt` listing the genome sequence names as decoys.

```bash
# 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` is the default k-mer; lower it only for very short reads.
- The helper `scripts/make_decoys.py` writes `decoys.txt` and `gentrome.fa` for
  you and refuses to proceed if the genome names are absent from the transcript
  FASTA (a common silent mistake). See [references/decoy_index.md](references/decoy_index.md).

### 2. Quantify each sample

From AlterLab-IEU/AlterLab-Academic-Skills, MIT.

More from AlterLab-IEU/AlterLab-Academic-Skills