samtools-cat(1)

💅 samtools-cat(1) — the "Bioinformatics tools" girlies' concatenation station 🎀

okay so real talk, bestie: this is samtools cat, and it lives in the Bioinformatics tools manual family (yes, that's the manual name, we're not copying the whole header line, iykyk). It glues files together. It's giving arts-and-crafts but for BAMs. ✨

---

🌸 NAME 🌸

samtools cat — concatenate files together 🫶

---

✨ SYNOPSIS ✨

samtools cat [-b list] [-h header.sam] [-o out.bam] in1.bam in2.bam [ ... ]

---

🦋 DESCRIPTION 🦋

Concatenate BAMs or CRAMs. And like, yes it works on either BAM or CRAM — iconic, flexible, we love her — but all input files must be the same format as each other. No mixing. That's the vibe check.

Also: the sequence dictionary of each input file must be identical. But this command does not check this 😭 so bestie please check it yourself, she's trusting you fr fr.

This command uses a similar trick to reheader which enables fast BAM concatenation. Lowkey genius, highkey fast. ⚡

---

💖 OPTIONS 💖

• -b FOFN — Read the list of input BAM or CRAM files from FOFN. These are concatenated prior to any files specified on the command line. And you can pass multiple -b FOFN options to concatenate multiple lists of BAM/CRAM files. Stack 'em up, queen 👑
• -h FILE — Uses the SAM header from FILE. By default the header is taken from the first file to be concatenated. So if you don't say anything, file #1 is the main character 🩷
• -o FILE — Write the concatenated output to FILE. By default this is sent to stdout. (Which is fine, but like, save it somewhere, she deserves it.)
• -q — [CRAM only] Query the number of containers in the CRAM file. The output is the filename, the number of containers, and the first and last container number as an inclusive range, with one file per line. 🍓

Note this works in conjunction with the -r RANGE option, in which case the 3rd and 4th columns become useful for identifying which containers span the requested range. iykyk 👀

• -r RANGE — [CRAM only] Filter the CRAM file to a specific RANGE. This can be the usual chromosome:start-end syntax, or "*" for unmapped records at the end of alignments. 🧚

If the range is of the form "#:start-end" then the start and end coordinates are interpreted as inclusive CRAM container numbers, starting at 0 and ending 1 less than the number of containers reported by -q. For example -r "#:0-9" is the first 10 CRAM containers of data. Cute, numbered, precise 💅

All range types filter data in as fast a manner as possible, using operating system read/write loops where appropriate. She's speedy, no cap. 🔥

• -p A/B — [CRAM only] Filter the CRAM file using a specific fraction. The file is split into B approximately equal parts and returns element A where A is between 1 and B inclusive. If there are more parts specified than CRAM containers then some of the output will be empty CRAMs. (Empty CRAMs are still CRAMs, bestie. They showed up. 💀)

This can also be combined with the range option above to operate of parts of that range. For example -r chr2 -p 1/10 returns the first 1/10th of data aligned against chromosome 2. Slicing a slice. Obsessed. 🎀

• -f — [CRAM only] Enable fast mode. When filtering by chromosome range with -r we normally do careful recoding of any containers that overlap the start and end of the range so the record count precisely matches that returned by a samtools view equivalent. Fast mode does no filtering, so may return additional alignments in the same container but outside of the requested region. It's fast but it's messy — you've been warned, bestie 🙈
• --no-PG — Do not add a @PG line to the header of the output file. If you don't want the paper trail, this is your girl. 🌈

---

🌟 EXAMPLES 🌟

• Extract a specific chromosome from a CRAM file, outputting to a new CRAM. (Snipping out the one chromosome you actually care about, we've all been there 💜)

samtools cat -o chr10.cram -r chr10 in.cram

• Split a CRAM file up into separate files, each containing at most 123 containers. (123 specifically. Not 124. Don't ask, she said 123. 👑)

set -- $(samtools cat -q in.cram); nc=$2; s=0
while [ $s -lt $nc ]
do
    e=`expr $s + 123`
    if [ $e -ge $nc ]
    then
        e=$nc
    fi
    r="$s-`expr $e - 1`"; echo $r
    fn=/tmp/_part-`printf "%08d" $s`.cram
    samtools cat -o $fn in.cram -r "#:$r"
    s=$e
done

• Split any unaligned data from a (potentially aligned) CRAM file into 10 approximately equal sized pieces. (Ten little pieces. Balanced. Beautiful. 🦋)

for i in `seq 1 10`
do
   samtools cat in.cram -r "*" -p $i/10 -o part-`printf "%02d" $i`.cram
done

---

🫶 AUTHOR 🫶

Written by Heng Li from the Sanger Institute. Updated for CRAM by James Bonfield (also Sanger Institute). Kings. Both of them. 👑👑

---

⭐ SEE ALSO ⭐

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

---

and that's the whole page, bestie — no notes 🧚 samtools-1.24, dated 9 July 2026. Go concatenate something iconic. 💅✨