Quantifies bulk RNA-seq transcript abundance with salmon (v1.11.4 selective alignment) and kallisto (v0.52.0, kb-python workflow), builds a decoy-aware gentrome index, runs quant with --validateMappings --gcBias -l A, then imports estimates via tximport/tximeta with a tx2gene map and hands differential expression to alterlab-pydeseq2. Warns that salmon's index format changed to SSHash (rebuild pre-v1.11.2 indices) and that 'salmon alevin' was REMOVED (single-cell now uses piscem + alevin-fry). Use when quantifying RNA-seq transcript abundance, running salmon or kallisto, building a decoy-aware index, or wiring tximport to DESeq2; for differential expression use alterlab-pydeseq2, for FASTQ-to-VCF variant calling use alterlab-nf-core-sarek. Part of the AlterLab Academic Skills suite.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Quantifies bulk RNA-seq transcript abundance with salmon (v1.11.4 selective alignment) and kallisto (v0.52.0, kb-python workflow), builds a decoy-aware gentrome index, runs quant with --validateMappings --gcBias -l A, then imports estimates via tximport/tximeta with a tx2gene map and hands differential expression to alterlab-pydeseq2. Warns that salmon's index format changed to SSHash (rebuild pre-v1.11.2 indices) and that 'salmon alevin' was REMOVED (single-cell now uses piscem + alevin-fry). Use when quantifying RNA-seq transcript abundance, running salmon or kallisto, building a decoy-aware index, or wiring tximport to DESeq2; for differential expression use alterlab-pydeseq2, for FASTQ-to-VCF variant calling use alterlab-nf-core-sarek. Part of the AlterLab Academic Skills suite.
Requires the salmon and/or kallisto CLI on PATH (conda/bioconda or a container). salmon v1.11.4 and kallisto v0.52.0 are the versions this skill targets; the tximport/tx2gene helper runs under `uv run python` with pure stdlib (no pandas needed). No API key or account required; all work is local.
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 --validateMappings --gcBias."
"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)
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 two failures most outdated RNA-seq instructions get wrong as of
salmon v1.11.4 (released 2026-03-11). Both are confirmed in the upstream
release notes (see references/tool_versions.md).
The salmon index format changed to SSHash. salmon switched from the
colored compacted de Bruijn graph index to a new SSHash-based k-mer index.
The release notes state all previously built indices must be rebuilt
before using v1.11.2+. If you reuse a pre-v1.11.2 index you will get an error
or silently wrong results — always rebuild the index with the same salmon
version you quantify with.
salmon alevin was REMOVED. Single-cell quantification is no longer part
of salmon. The release notes direct former alevin users to the
piscem + alevin-fry pipeline. Do not write salmon alevin commands.
If the user has single-cell / droplet data, route per the table above and see
references/single_cell_alevin.md.
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.
# 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 for v1.11.4 — 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.
-l A — auto-detect library type (strandedness). Let salmon infer it
unless you have a documented protocol; verify the inferred type in
lib_format_counts.json.
--validateMappings — enables selective alignment (the accurate default
mode; scores mappings rather than trusting raw pseudo-mappings).
--gcBias — corrects fragment-level GC bias; recommended for DE and cheap
to enable. Add --seqBias for 5'/3' sequence-specific bias if needed.
For single-end reads, pass -r reads.fastq.gz instead of -1/-2.
Each sample produces quants/<sample>/quant.sf (transcript-level estimates) and
quants/<sample>/lib_format_counts.json (the inferred library type). See
references/salmon_quant.md for the full flag map
and per-sample QC checks.
3. Aggregate to gene level with tximport
Build a transcript→gene map (tx2gene) from your annotation, then summarize the
per-sample quant.sf files into a gene-level matrix that pydeseq2 consumes.
# 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 produces an integer-rounded gene × sample count matrix plus a
gene × sample TPM matrix, the inputs alterlab-pydeseq2 expects. It implements
tximport's makeCountsFromAbundance(..., "lengthScaledTPM") at the transcript
level (scale each transcript's TPM by its sample-averaged effective length, then
rescale each sample column back to its mapped-read library size) and sums to
genes — so the counts are length-corrected and library-size-scaled, not raw
summed NumReads. The canonical R route is the tximport / tximeta
Bioconductor packages with countsFromAbundance = "lengthScaledTPM"; the Python
helper here reproduces that computation so you can stay in uv (differing only
in integer rounding and the absence of tximeta provenance). See
references/tximport_handoff.md for the exact
semantics, the tximeta linkedTxome metadata option, and when to prefer the R
path.
4. Hand off to differential expression
Pass gene_counts.tsv (+ a sample/condition sheet) to alterlab-pydeseq2.
This skill does not call DEGs — that is pydeseq2's job (size-factor
normalization, dispersion, Wald tests, BH-FDR, volcano/MA plots).
Pipeline (kallisto, the pseudoalignment path)
kallisto (standalone v0.52.0) and the kb-python wrapper (kb) give a
faster pseudoalignment route. kb-python drives kallisto | bustools and writes
tidy outputs.
# 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 outputs abundance.tsv / abundance.h5; feed these to tximport
(type="kallisto") the same way as salmon's quant.sf.
Long reads: kb-python exposes lr-kallisto via the --long flag (and
k>31 k-mers) — use it for ONT/PacBio cDNA. See
references/kallisto_kb.md.
kallisto does not use the decoy/gentrome construction; that is salmon-specific.
Turnkey alternative — nf-core/rnaseq
For an end-to-end, provenance-tracked pipeline (trimming → alignment →
quantification → QC), nf-core/rnaseq v3.26.0 runs --aligner star_salmon by
default: STAR maps to the genome, projects onto the transcriptome, and Salmon
does the quantification. Reach for it when the user wants a reproducible
Nextflow pipeline rather than hand-run commands; this skill covers the
direct-salmon/kallisto path and the tximport handoff. See
references/tool_versions.md.
Offload note
Indexing and per-sample quantification are CPU/IO-heavy but fully offline. On a
local workstation these are good candidates to run directly (e.g. overnight)
rather than streaming large FASTQs through an API session. Build the index once;
quantify samples in a loop.
Self-Check Before Reporting
Did you rebuild the salmon index with the v1.11.4 you quantified with
(SSHash format — trap #1)? Never reuse a pre-v1.11.2 index.
Is the index decoy-aware (gentrome + decoys.txt) for salmon? Confirm the
genome names made it into decoys.txt.
Did you let -l A infer strandedness, and did you sanity-check the inferred
type in lib_format_counts.json?
Is the data actually single-cell? If so you must NOT use this path —
salmon alevin is gone; route to piscem + alevin-fry (trap #2).
Did you stop at the count matrix and hand DE off to alterlab-pydeseq2
rather than calling DEGs here?
References
references/tool_versions.md — pinned versions
(salmon v1.11.4, kallisto v0.52.0, kb-python, nf-core/rnaseq v3.26.0) and the
upstream release-note facts (SSHash index change, alevin removal).
references/decoy_index.md — decoy-aware gentrome
index construction, gotchas, and the make_decoys.py helper.
