[meta]
name = "samtools"
category = "alignment"
description = "Suite of programs for interacting with high-throughput sequencing data in SAM/BAM/CRAM format"
tags = ["bam", "sam", "cram", "alignment", "ngs", "sequencing", "indexing", "sorting"]
author = "oxo-call built-in"
source_url = "http://www.htslib.org/doc/samtools.html"

[context]
concepts = [
    "SAM is plain text, BAM is binary (smaller/faster), CRAM is reference-compressed (smallest). Use BAM for most workflows.",
    "BAM files MUST be coordinate-sorted (samtools sort) BEFORE indexing (samtools index). Random-access region queries require both steps.",
    "Use -@ N to enable N extra threads; -o FILE to write to a file instead of stdout; use -b flag to output BAM.",
    "samtools view filters reads: -F N excludes reads with flag N set; -f N keeps only reads with flag N set. Common flags: 4=unmapped, 256=secondary, 2048=supplementary.",
    "CRAM output requires --reference /path/to/ref.fa because it stores differences from the reference.",
    "Many subcommands (view, sort, flagstat) accept a region like chr1:1000-2000 to limit output.",
]

pitfalls = [
    "Without -o, samtools writes to stdout — pipe carefully or always use -o output.bam.",
    "CRAM output (-C flag in view, or -O cram in sort) requires --reference; omitting it causes an error.",
    "samtools index on an unsorted BAM will appear to succeed but region queries will give wrong results.",
    "samtools view without -b or -O bam outputs SAM text, not BAM — the file will be much larger.",
    "samtools sort -n sorts by read name (needed before fixmate/markdup); the default is coordinate sort.",
    "Piping samtools sort to samtools index does not work — sort must complete and write a file first.",
]

[[examples]]
task = "sort a BAM file by genomic coordinates"
args = "sort -@ 4 -o sorted.bam input.bam"
explanation = "-@ 4 uses 4 threads; -o writes BAM file; coordinate sort is the default"

[[examples]]
task = "create an index for a sorted BAM file"
args = "index sorted.bam"
explanation = "creates sorted.bam.bai; must be run on a coordinate-sorted BAM"

[[examples]]
task = "filter to keep only properly paired primary alignments"
args = "view -b -f 2 -F 256 -F 2048 -o proper_paired.bam input.bam"
explanation = "-f 2 keeps properly paired; -F 256 removes secondary; -F 2048 removes supplementary; -b outputs BAM"

[[examples]]
task = "get alignment statistics (mapped, unmapped, duplicates)"
args = "flagstat input.bam"
explanation = "outputs counts for each alignment category to stdout; redirect with > stats.txt to save"

[[examples]]
task = "convert BAM to FASTQ for paired-end reads"
args = "fastq -@ 4 -1 R1.fastq.gz -2 R2.fastq.gz -0 /dev/null -s /dev/null -n input.bam"
explanation = "-1/-2 for read 1/2; -0 for unpaired; -s for supplementary; -n preserves original read names"

[[examples]]
task = "extract reads mapping to chromosome 1 between 100000 and 200000"
args = "view -b -o region.bam input.bam chr1:100000-200000"
explanation = "region queries require a sorted + indexed BAM; -b outputs BAM"

[[examples]]
task = "mark PCR duplicates"
args = "markdup -@ 4 -f stats.txt input_namesorted.bam output_markdup.bam"
explanation = "input must be name-sorted (samtools sort -n), then fixmate'd; -f writes stats"

[[examples]]
task = "merge multiple BAM files into one"
args = "merge -@ 4 -f merged.bam sample1.bam sample2.bam sample3.bam"
explanation = "-f overwrites output if it exists; all inputs should be sorted"

[[examples]]
task = "compute per-base depth of coverage"
args = "depth -a -o coverage.txt input.bam"
explanation = "-a includes positions with zero coverage; -o writes to file"

[[examples]]
task = "view the BAM header"
args = "view -H input.bam"
explanation = "outputs only the header lines (starting with @) to stdout"
