samtools-collate(1)

✨ samtools-collate ✨

okay bestie, welcome to the samtools-collate page — it's one of the Bioinformatics tools in the samtools fam, and honestly it's giving underrated icon 💅

🌸 NAME 🌸

samtools collate — shuffles and groups reads together by their names 🎀

🦋 SYNOPSIS 🦋

samtools collate [options] in.sam|in.bam|in.cram [<prefix>]

💖 DESCRIPTION 💖

So what does it actually do?? It shuffles and groups reads together by their names. Think of it as the speedier, chiller alternative to a full query name sort — collate makes sure all the reads with the same name end up grouped together in contiguous groups, but it does not promise anything about the order of read names between those groups. No cap, that's the whole deal ✨

The output is meant to be suitable for any operation that needs all the reads from the same template grouped together. Periodt 🫶

Temporary files get written to <prefix>, which you can specify either as the last argument or with the -T option. If you don't give a prefix, one gets derived from the output filename (that's the -o option). And if there's no output file either, then the TMPDIR environment variable is used — and if that's unset too, /tmp is the fallback. Chain of command, bestie 👑

Conversely (love that word), if you do specify a prefix but don't give an output filename, the output goes to <prefix>.<fmt> where <fmt> matches the file format in use (like "bam" or "cram") 🎀

---

⚡ fast mode, aka the -f situation ⚡

Using -f for fast mode outputs only primary alignments that have either the READ1 or READ2 flags set — but not both. Every other alignment record gets filtered out, sorry not sorry. And heads up: the collation only works correctly if there are no more than two reads for any given QNAME after filtering. That's a real caveat, don't skip it 😭

Fast mode keeps a buffer of alignments in memory so it can write out most pairs as soon as it finds them instead of stashing them in temporary files. This lets collate dodge some work and finish faster than standard mode — slay 💅 The number of alignments it holds is controlled by -r: storing more alignments eats more memory but increases the number of pairs that get written early.

⚠️ okay but listen: while collate normally randomises the ordering of read pairs, fast mode does not. Position-dependent biases that would normally get broken up can remain in the fast collate output. So it is not a good idea to use fast mode when you're prepping data for programs that expect randomly ordered paired reads. For example, using fast collate instead of standard mode may lead to significantly different results from aligners that estimate library insert sizes on batches of reads. fr fr, this one matters 💀

✨ OPTIONS ✨

• -O — Output to stdout. This option cannot be used with -o. 💅
• -o FILE — Write output to FILE. This option cannot be used with -O. If it's unspecified and -O isn't set, the temporary file <prefix> is used, appended by the the appropriate file-format suffix.
• -T PREFIX — Use PREFIX for temporary files. This is the same as specifying PREFIX as the last argument on the command line. This option is included for consistency with samtools sort. 🫶
• -u — Write uncompressed BAM output.
• -l INT — Compression level. Default is [1].
• -n INT — Number of temporary files to use. Default is [64].
• -f — Fast mode (primary alignments only). ⚡
• -r INT — Number of reads to store in memory (for use with -f). Default is [10000].
• --no-PG — Do not add a @PG line to the header of the output file. 🙈
• -@, --threads INT — Number of input/output compression threads to use in addition to main thread. Default is [0].

👑 AUTHOR 👑

Written by Heng Li from the Sanger Institute and extended by Andrew Whitwham. Legends, honestly 🌈

🧚 SEE ALSO 🧚

• samtools(1)
• samtools-sort(1)

Samtools website: <http://www.htslib.org/> 🌸

---

and that's the whole page bestie!! this one's samtools-1.24, dated 9 July 2026 — go forth and collate responsibly 💖✨🎀