samtools-reference(1)

✨ NAME ✨

okay so bestie, this page is samtools-reference(1) — the samtools reference command literally extracts an embedded reference from a CRAM file. it’s giving reference-rescue main character energy 💅

---

🌸 SYNOPSIS 🌸

samtools reference [-q] [-r region] [-o out.fa] in.cram

---

🦋 DESCRIPTION 🦋

so here’s the tea: this creates the reference from aligned data using either the MD:Z auxiliary tags or an embedded reference in a CRAM file. the output is a FASTA file. periodt.

for the embedded reference mode (-e) this operation is fast, but it only works on CRAMs produced using --output-fmt-option embed_ref=1. note that this may not be the complete reference used. each CRAM slice will hold the entire reference that spans the slice coordinates, but gaps in coverage can lead to gaps between slices. however, this reference should be suitable for passing into a CRAM decode (samtools view -T ref.fa). 🫶

for SAM/BAM files or CRAMs without reference, using the MD:Z tag may also produce an incomplete reference. unlike embedded reference, this reference may not be sufficient for decoding a CRAM file, because the CRAM slice headers store the MD5sum of the portion of reference that spans that slice, but the slice may not have 100% coverage — leading to Ns in the computed reference. however, it should still be possible to decode such CRAMs by ignoring the md5 mismatches using e.g. samtools view --input-fmt-option ignore_md5=1. no cap, that’s the loophole 😭

---

🎀 OPTIONS 🎀

• -e — enable CRAM embedded reference mode. iconic. ✨
• -q — enables quiet mode and will produce no output. by default, a line per reference is reporting, describing the percentage with non-N bases. lowkey useful unless you want silence 🤫
• -r region — specifies a single region to produce the reference from. if specified, an index file must be present.
• -o FILE — write the FASTA records to FILE. by default this is sent to stdout.
• -@ INT — the number of BAM/CRAM decompression threads to use in addition to the main thread [0].

note this does not multi-thread the main reference generation steps, so scaling may be capped by 2 or 3 threads, depending on the data. it will also not affect the -e option for CRAM embedded reference, although this is already the fastest method. so yeah, don’t expect infinite thread slay here 💀

---

👑 AUTHOR 👑

written by James Bonfield from the Sanger Institute.

---

🌈 SEE ALSO 🌈

• samtools(1)
• Samtools website: <http://www.htslib.org/>

---

made with 💖 and reference-reconstruction vibes — source/version samtools-1.24, dated 9 July 2026. bye bestie, go extract that reference! 🫶🎀