sam-bam-basics

SAM / BAM File Basics

Hard rules

1. No fabricated citations. Every cited work must resolve to a verifiable
2. No claim without provenance. Every quantitative or factual claim
3. No silent failure. Every script invocation, API call, or tool use must declare its exit status and what to do on non-zero. A skill that silently swallows errors is a violation.

When to use

• Understanding why reads aligned (or didn't).
• Filtering BAMs by FLAG, MAPQ, CIGAR.
• Extracting specific read subsets for downstream tools.
• Converting SAM ↔ BAM and adding custom tags.

When NOT to use

• You need BAM statistics — see bam-statistics skill.
• You need to filter duplicates — see duplicate-handling skill.
• Visualizing alignments — use IGV, samtools tview, or a browser.

Prerequisites

• samtools ≥ 1.19
• For programmatic work: pysam (see pysam-genomics skill)

The SAM line format

QNAME FLAG RNAME POS CIGAR SEQ QUAL TAGS

The canonical optional tags

Common FLAGs (binary decode)

Use samtools flags 99 to decode or encode:

Code patterns

View a BAM as SAM (text)

samtools view -h input.bam | head -20

Convert SAM to BAM

samtools view -bS input.sam > output.bam

Extract mapped reads

samtools view -F 4 -b input.bam > mapped.bam
# -F 4 = exclude FLAG 4 (unmapped)

Extract unmapped reads

samtools view -f 4 -b input.bam > unmapped.bam
# -f 4 = require FLAG 4 (unmapped)

Extract properly paired reads

samtools view -F 4 -f 2 -b input.bam > proper.bam

Extract reads with MAPQ >= 30

samtools view -q 30 -b input.bam > q30.bam

Extract primary alignments only

samtools view -F 256 -b input.bam > primary.bam

Extract alignments to chromosome 1

samtools view -b chr1 input.bam > chr1.bam

Extract reads by read name

samtools view -h input.bam | grep "read_name" | samtools view -bS - > reads.bam

Convert BED to SAM/BAM (via BEDTools if needed)

BEDTools: bedtools bedtobam -bed12 input.bed -g genome.txt > output.bam

Decode a FLAG to readable string

samtools flags 99
# 99 = PAIRED|PROPER_PAIRED|REVERSE|MREVERSE

Sort by name (for fixmate)

samtools sort -n input.bam -o input.name.bam
samtools index input.name.bam

Sort by coordinate (default)

samtools sort -o input.coord.bam input.bam
samtools index input.coord.bam

Build a header from scratch

samtools view -H input.bam
# Shows @HD, @SQ, @RG, @PG lines

Add a read group to the header

samtools addreplacerg -r "@RG\tID:sample1\tSM:sample1\tPL:ILLUMINA" -o out.bam in.bam
samtools index out.bam

Extract strand-specific information

For RNA-seq, the XS tag indicates strand:

samtools view input.bam | awk '$20 ~ /XS:A:[+-]/ {print $20}'

Coordinate systems

Common pitfalls

• 0-based vs 1-based confusion. SAM POS is 1-based. Python slice is 0-based. Convert explicitly.
• CIGAR interpretation. 50M = 50 matches. 10S40M = 10 soft-clipped + 40 matches.
• Primary/secondary alignment. FLAG 256 means secondary (split read aligned elsewhere). Often not what you want.
• Supplementary. FLAG 2048 means supplementary alignment (chimeric).
• Duplicate markings are recommendations, not truth. samtools markdup is the canonical; confirm before filtering.
• MAPQ = 255 from bowtie2 means "aligner can't calculate a good MAPQ" — not "very high confidence".

Validation

• After any filter, use samtools flagstat to check read counts.
• After samtools view -F 4, no reads should have FLAG bit 4.
• Coordinate-sorted BAM must be indexed (samtools index) before samtools tview or region queries.

Open alternatives

References

• SAM spec: https://samtools.github.io/hts-specs/SAMv1.pdf
• samtools manual: http://www.htslib.org/doc/samtools.html
• Companion: ors-bioinformatics-sequence-bam-statistics, ors-bioinformatics-sequence-pysam-genomics

Changelog

• 1.0.0 (2026-06-10): Initial adaptation by Pradyumna Jayaram from bio-sam-bam-basics (bioSkills-main/alignment-files/sam-bam-basics).

Cross-references

Other skills in this category:

• batch-processing
• bowtie2-alignment
• bwa-alignment
• bwa-mem2-alignment
• codon-usage
• compressed-sequence-files
• fastq-quality-scores
• filter-sequences
• format-conversion
• hisat2-alignment
• motif-search
• paired-end-fastq
• pysam-genomics
• read-write-sequences
• reverse-complement
• samtools-bam-processing
• seq-objects
• sequence-properties
• sequence-slicing
• sequence-statistics
• star-alignment
• transcription-translation