| BAMSORT(1) | General Commands Manual | BAMSORT(1) |
bamsort - sort BAM files by coordinate or query name
bamsort [options]
bamsort reads a BAM, SAM or CRAM file, sorts it by 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 and writes the sorted file in BAM, SAM or CRAM format.
Lexicographical order denotes that pairs (a,b) and (c,d) will be ordered such that (a,b) < (c,d) if either a < c or a = c and b < d. For coordinates this means that the alignments are first grouped by reference sequence id (i.e. all alignments for one chromosome appear in one block) and within the block for each reference sequence the alignments are ordered by the start position on this sequence.
The order by query name decomposes the read names into parts containing numbers and such 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 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 random number) for each read name and order 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.
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
level=<-1|0|1|9|11>: set compression level of the output BAM file. Valid values are
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
verbose=<1>: Valid values are
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
md5=<0|1>: md5 checksum creation for output file. This option can only be given if outputformat=bam. Then valid values are
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
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 in 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 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.
Written by German Tischler.
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.
| September 2017 | BIOBAMBAM |