Provided by: biobambam2_2.0.185+ds-1_amd64 bug

NAME

       bamsort - sort BAM files by coordinate or query name

SYNOPSIS

       bamsort [options]

DESCRIPTION

       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

       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 need 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 need 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:

       bam:   BAM (see http://samtools.sourceforge.net/SAM1.pdf)

       sam:   SAM (see http://samtools.sourceforge.net/SAM1.pdf)

       cram:  CRAM (see http://www.ebi.ac.uk/ena/about/cram_toolkit)

       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:

       bam:   BAM (see http://samtools.sourceforge.net/SAM1.pdf)

       sam:   SAM (see http://samtools.sourceforge.net/SAM1.pdf)

       cram:  CRAM  (see  http://www.ebi.ac.uk/ena/about/cram_toolkit).  This   format   is   not
              advisable for data sorted by query name.

       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.

AUTHOR

       Written by German Tischler.

REPORTING BUGS

       Report bugs to <germant@miltenyibiotec.de>

COPYRIGHT

       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.