[meta]
name = "kallisto"
category = "rna-seq"
description = "Ultrafast pseudoalignment RNA-seq transcript quantification tool"
tags = ["rna-seq", "quantification", "pseudoalignment", "transcript", "expression", "tpm", "counts"]
author = "oxo-call built-in"
source_url = "https://pachterlab.github.io/kallisto/"

[context]
concepts = [
    "Kallisto uses pseudoalignment to quantify RNA-seq data; it is 20x faster than alignment-based tools with comparable accuracy.",
    "Two-step workflow: (1) kallisto index -i index.idx transcriptome.fa; (2) kallisto quant -i index.idx -o outdir R1.fq R2.fq.",
    "Kallisto requires transcriptome FASTA (cDNA), not genome FASTA.",
    "Output includes abundance.tsv (TPM and estimated counts), run_info.json (run statistics), and abundance.h5 (for sleuth).",
    "Use --bootstrap-samples 100 (-b 100) for bootstrap variance estimation; required for sleuth differential expression.",
    "Strandedness: --rf-stranded for reverse-strand (dUTP), --fr-stranded for forward-strand; default is unstranded.",
    "kb-python (kallisto|bustools) is the modern single-cell extension for scRNA-seq processing.",
]

pitfalls = [
    "Kallisto requires transcriptome cDNA FASTA, NOT genome FASTA — indexing the genome produces wrong results.",
    "Without --bootstrap-samples, downstream differential expression with sleuth cannot estimate variance.",
    "For paired-end, both FASTQ files are passed as positional arguments (no -1/-2 flags) after -o output_dir.",
    "kallisto does not output BAM by default — use kallisto quant --pseudobam for BAM output (if needed).",
    "Forgetting strandedness option for stranded libraries leads to approximately half the reads assigned per strand.",
    "kallisto quant outputs to a directory — make sure the output directory does not already exist or use a fresh path.",
]

[[examples]]
task = "build a kallisto index from a transcriptome FASTA"
args = "index -i transcriptome.idx transcriptome.fa"
explanation = "-i specifies the index output file; transcriptome.fa is the cDNA/transcript FASTA"

[[examples]]
task = "quantify paired-end RNA-seq reads"
args = "quant -i transcriptome.idx -o sample_output -b 100 --threads 8 R1.fastq.gz R2.fastq.gz"
explanation = "-o output directory; -b 100 bootstrap samples for variance; R1 and R2 are positional arguments"

[[examples]]
task = "quantify single-end RNA-seq reads with fragment length parameters"
args = "quant -i transcriptome.idx -o sample_output --single -l 200 -s 20 -b 100 --threads 8 reads.fastq.gz"
explanation = "--single for SE mode; -l mean fragment length; -s fragment length SD; required for SE mode"

[[examples]]
task = "quantify strand-specific reverse-strand paired-end RNA-seq"
args = "quant -i transcriptome.idx -o sample_output --rf-stranded -b 100 --threads 8 R1.fastq.gz R2.fastq.gz"
explanation = "--rf-stranded for dUTP/TruSeq reverse-strand libraries; use --fr-stranded for forward-strand"

[[examples]]
task = "quantify multiple samples in batch"
args = "quant -i transcriptome.idx -o sample1_out -b 50 --threads 4 sample1_R1.fq.gz sample1_R2.fq.gz"
explanation = "run kallisto quant once per sample; loop in shell for batch processing"
