BAMSORT(1)

📦
version 2.0.185 · 2 versions
  • 2.0.185 · debian bookworm, debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
  • 2.0.183 · ubuntu jammy
, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 BAMSORT(1) 🌸

okay bestie, welcome to bamsort from section 1 of the General Commands Manual 💖 this one sorts BAM files by coordinate or by query name, and honestly? it's giving main character energy 👑

🦋 SYNOPSIS 🦋

bamsort [options]

💜 DESCRIPTION 💜

okay so here's the tea ☕: bamsort reads a BAM, SAM or CRAM file, sorts it, and writes the sorted file back out in BAM, SAM or CRAM format ✨ and it can sort by literally so many things:

  • coordinate — lexicographical by reference sequence id and position on reference sequence
  • query name — possibly including the HI aux tag, for ordering alignments featuring the same query name
  • hash value — computed for the query name or an aux tag value

now let's talk about what "lexicographical order" even means, because the way that word gets thrown around... 😭 so lexicographical order means pairs (a,b) and (c,d) get ordered such that (a,b) < (c,d) if either a < c, or a = c and b < d. For coordinates this means the alignments are first grouped by reference sequence id (so like, all the alignments for one chromosome show up in one block 🌈) and within the block for each reference sequence, the alignments get ordered by the start position on that sequence. periodt.

the order by query name decomposes the read names into parts containing numbers and parts containing no number 👀 a read name A15_30_C50 will for instance be split into the components A, 15, _, 30, _C and 50. the comparison of read names is then performed lexicographically along this decomposition, where number fields are compared as numbers. as an example we have A15<B12 as A<B, and A9<A12 as A=A and 9<12 (where 9 and 12 are considered as numbers and not as the sequences of their digits 🧠).

the order by hash value computes a hash value (effectively a random number 🎲) for each read name and orders the alignments by this number in increasing order. alignments assigned the same hash value are ordered by query name.

the order by aux tag compares alignments by the value of a given aux field storing a string value. this string comparison follows the same order used for comparing query names stated above. alignments with the same aux value are sorted by coordinate order.

⚠️ if the memory buffer given is not sufficiently large to process the input file, then the program writes intermediate results to a temporary file. this file can be large and depending on the compression of the input file, larger than the input itself 😳 so plan accordingly bestie.

the following key=value pairs can be given 💅

  • SO=<coordinate|queryname|hash|tag|tagonly|queryname_HI|queryname_lexicographic> — set the sort order. valid values are:
    • coordinate — sort alignments by coordinate
    • queryname — sort alignments by query name
    • hash — sort alignments by (Murmur3) hash of query name. this effectively puts them in a random order 🎲
    • tag — sort alignments by string aux field. the tag of the aux fields needs to be provided using the sorttag key. entries with identical tag are sorted by coordinate.
    • tagonly — sort alignments by string aux field. the tag of the aux fields needs to be provided using the sorttag key. entries with identical tag are left in the same order as they were in the input 👑
    • queryname_HI — sort alignments by query name. alignments with identical query name are sorted by the value of their HI aux field.
    • queryname_lexicographic — sort alignments by query name using a purely lexicographic comparison instead of the more sophisticated version described above.
  • level=<-1|0|1|9|11> — set compression level of the output BAM file. valid values are:
    • -1 — zlib/gzip default compression level
    • 0 — uncompressed
    • 1 — zlib/gzip level 1 (fast) compression
    • 9 — zlib/gzip level 9 (best) compression

if libmaus has been compiled with support for igzip (see https://software.intel.com/en-us/articles/igzip-a-high-performance-deflate-compressor-with-optimizations-for-genomic-data) then an additional valid value is:

  • 11 — igzip compression 🔥
  • verbose=<1> — valid values are:
    • 1 — print progress report on standard error
    • 0 — do not print progress report
  • blockmb=<1024> — set size of the internal memory sorting buffer in megabytes. the default buffer size is one gigabyte 🐘
  • tmpfile=<filename> — set the prefix for temporary file names
  • disablevalidation=<0|1> — sets whether input validation is performed. valid values are:
    • 0 — validation is enabled (default)
    • 1 — validation is disabled
  • md5=<0|1> — md5 checksum creation for output file. this option can only be given if outputformat=bam. then valid values are:
    • 0 — do not compute checksum. this is the default.
    • 1 — compute checksum. if the md5filename key is set, then the checksum is written to the given file. if md5filename is unset, then no checksum will be computed.
  • md5filename — file name for md5 checksum if md5=1.
  • index=<0|1> — compute BAM index for output file. this option can only be given if outputformat=bam. then valid values are:
    • 0 — do not compute BAM index. this is the default.
    • 1 — compute BAM index. if the indexfilename key is set, then the BAM index is written to the given file. if indexfilename is unset, then no BAM index will be computed.
  • indexfilename — file name for output BAM index if index=1.
  • inputformat=<bam> — input file format. all versions of bamsort come with support for the BAM input format. if the program in addition is linked to the io_lib package, then the following options are valid:
  • outputformat=<bam> — output file format. all versions of bamsort come with support for the BAM output format. if the program in addition is linked to the io_lib package, then the following options are valid:
  • I=<[stdin]> — input filename, standard input if unset.
  • O=<[stdout]> — output filename, standard output if unset.
  • inputthreads=<[1]> — input helper threads, only valid for inputformat=bam.
  • sortthreads=<[1]> — number of threads used for sorting.
  • outputthreads=<[1]> — output helper threads, only valid for outputformat=bam.
  • reference=<[]> — reference FastA file for inputformat=cram and outputformat=cram. an index file (.fai) is required 📎
  • range=<> — input range to be processed. this option is only valid if the input is a coordinate sorted and indexed BAM file.
  • fixmates=<0|1> — fix mate information as bamfixmateinformation would do. input is assumed to be collated by query name (no changes will be applied to mates which are not adjacent in the input stream). by default this option is disabled.
  • calmdnm=<0|1> — calculate the MD and NM fields as a side effect. by default the fields are not calculated. calculation is only performed if sorting is performed by coordinate. if calmdnm=1, then the parameter calmdnmreference is required. the supported file formats can be found in the manual page for bammdnm.
  • calmdnmreference=<[]> — name of reference sequence file if calmdnm=1.
  • calmdnmrecompindetonly=<0|1> — compute MD/NM fields in the presence of indeterminate (N) bases only. this option is only relevant if calmdnm=1. by default the fields are computed for all mapped alignments if calmdnm=1.
  • calmdnmwarnchange=<0|1> — warn if MD/NM field which was computed is differing from a previously existing field. by default no warnings are produced.
  • adddupmarksupport=<0|1> — add information required for streaming duplicate marking in the aux fields MS and MC. input is assumed to be collated by query name. this option is ignored unless fixmates=1. by default it is disabled.
  • markduplicates=<[0]> — mark duplicate read pairs and reads. this option can only be used when a name collated file (all reads for a name are consecutive in the input) is sorted into coordinate order. in addition the input is required not to contain orphan reads (pair ends such that the other end of the pair is not contained in the file) 🚨 setting markduplicates=1 implies adddupmarksupport=1. the temporarily added auxiliary fields are removed during output generation. the markduplicates option is disabled by default.
  • rmdup=<[0]> — remove the duplicates marked by the markduplicates option. as this requires markduplicates=1, the requirements stated for markduplicates also apply for rmdup.
  • tag=<tag> — name of auxiliary field storing tag information for duplicate marking in string form. read fragments or pairs with different tags will not be considered as duplicates, even if they would be according to their mapping coordinates. for pairs the tag field information of the first and second mate are concatenated to obtain the tag of the pair.
  • nucltag=<tag> — this option works like the tag option but is restricted to sequences of nucleotides (A,C,G or T) as tags. the length of each tag sequence is not allowed to exceed 15 bases. all tags are required to have the same length. each non nucleotide symbol is mapped to A. in contrast to the tag option, nucltag uses less memory for processing and can be expected to be faster ⚡
  • M=<stderr> — name of the metrics file for duplicate marking (metrics are written to standard error if not set)
  • streaming=<0|1> — do not open input file(s) multiple times if set to 1. when given multiple input files bamsort concatenates the files on the fly and computes a merged header before starting the data processing. computing the header of the output file requires opening each input file. if each input file can only be opened once (as it may take the form of a pipe or socket connection), then bamsort will keep all the files open at the same time. otherwise the files will be opened only as needed to keep the number of open file descriptors lower.
  • sorttag= — tag of aux field used for comparison when SO=tag.
  • hash=<crc32prod> — hash used for producing bamseqchksum type header fields in sorted output.

✍️ AUTHOR ✍️

written by German Tischler 💖

🐛 REPORTING BUGS 🐛

report bugs to <germant@miltenyibiotec.de> 📬

Copyright © 2009-2016 German Tischler, © 2011-2014 Genome Research Limited. License GPLv3+: GNU GPL version 3 <http://gnu.org/licenses/gpl.html>

this is free software: you are free to change and redistribute it. there is NO WARRANTY, to the extent permitted by law 🙈

okay bestie that's the whole thing, you're officially a bamsort girlie now 💅 this page is from BIOBAMBAM, dated September 2017, and it's BAMSORT(1) — go forth and sort, no cap 🎀✨🦋

📦 where this page comes from