SAMBAMBA-SORT(1)

💖 SAMBAMBA-SORT(1) 💖

okay bestie, sit down, grab a strawberry 🍓 — this is sambamba-sort, the tool for sorting BAM files. yes, that one. she's a section 1 manual page and she is lowkey iconic.

✨ SYNOPSIS ✨

sambamba sort OPTIONS <input.bam>

🦋 DESCRIPTION 🦋

so a BAM file can be in one of two sort orders, right? it's either coordinate or qname, and no you don't get to freestyle it.

coordinate means the file is sorted by (integer) reference ID, and then, inside each reference, the reads get sorted by start coordinate. very demure, very orderly. 💅

qname means the reads are sorted lexicographically by their names. alphabetical girlie behavior, we love her.

now here's the tea: sambamba sort does an external stable-type sort on your input file. what does that even mean? it means she reads the source BAM in chunks that fit into memory, sorts each chunk, writes those chunks out to a temporary directory, and then merges them all together. and after the merge? the temporary files get removed automatically. she cleans up after herself. main character energy fr fr. ✨

both sort orders are supported, but the default is coordinate, because that's the one you need for building an index later. iykyk. if you wanna switch over to qname, just use the -n|--sort-by-name flag. easy.

🎀 OPTIONS 🎀

• -m, --memory-limit=LIMIT — sets an upper bound on the memory used. fair warning bestie: this is very approximate, it's giving vibes not precision. the default memory limit is 512MiB. if you raise it, the chunk sizes get bigger and you get fewer I/O seeks, which means the overall performance goes up. slay. LIMIT has to be a number with an optional suffix that says what unit you mean. these endings are recognized: K, KiB, KB, M, MiB, MB, G, GiB, GB.
• --tmpdir=TMPDIR — use TMPDIR for writing out the sorted chunks. default behavior is to use the system temporary directory.
• -o, --out=OUTPUTFILE — the output file name. if you don't provide one, the result gets written to a file with the .sorted.bam extension. she'll name it herself, she's independent like that. 💅
• -n, --sort-by-name — sort by read name instead of doing a coordinate sort. this is the switch that flips you into qname land.
• -l, --compression-level=COMPRESSION_LEVEL — the compression level to use for the sorted BAM, from 0 (known as uncompressed BAM in samtools) all the way up to 9.
• -u, --uncompressed-chunks — write the sorted chunks as uncompressed BAM. default behavior is to write them with compression level 1, because that cuts down the time spent on I/O, but in some cases using this option can give you better speed. BUT. note that the disk space you'll need for sorting will typically be 3-4 times more than without enabling this option. so like, check your disk first, bestie 😭
• -p, --show-progress — show a wget-like progressbar in STDERR. and actually it's two of them, one after another — the first one for sorting, and then another one for merging. double the bars, double the serotonin 🌈
• -t, --nthreads=NTHREADS — number of threads to use. go forth and parallelize 🧚

👑 SEE ALSO 👑

for more info on the original samtools SORT behavior, check out the samtools documentation at http://samtools.sourceforge.net/samtools.shtml. go read it, i'll wait 🫶

💀 BUGS 💀

at the moment, the memory is used quite ineffectively for really large files. not me exposing her flaws on main, but transparency is important bestie 🙈

okay that's the whole page! this was brought to you by SAMBAMBA-SORT(1), dated February 2015 — yeah she's an older queen but she still ate and left no crumbs. mwah 💖✨