Provided by: samtools_1.17-1_amd64 bug

NAME

       samtools-sort - sorts SAM/BAM/CRAM files

SYNOPSIS

       samtools  sort [-l level] [-u] [-m maxMem] [-o out.bam] [-O format] [-M] [-K kmerLen] [-n]
       [-t tag] [-T tmpprefix] [-@ threads] [in.sam|in.bam|in.cram]

DESCRIPTION

       Sort alignments by leftmost coordinates, or by read name when -n is used.  An  appropriate
       @HD-SO sort order header tag will be added or an existing one updated if necessary.

       The  sorted  output  is  written  to  standard output by default, or to the specified file
       (out.bam) when -o is used.  This command will also create temporary files tmpprefix.%d.bam
       as  needed when the entire alignment data cannot fit into memory (as controlled via the -m
       option).

       Consider using samtools collate instead if you need name  collated  data  without  a  full
       lexicographical sort.

       Note  that  if  the  sorted  output file is to be indexed with samtools index, the default
       coordinate sort must be used.  Thus the -n and -t options are incompatible  with  samtools
       index.

OPTIONS

       -K INT     Sets the kmer size to be used in the -M option. [20]

       -l INT     Set  the  desired  compression  level for the final output file, ranging from 0
                  (uncompressed) or 1 (fastest but minimal compression) to  9  (best  compression
                  but slowest to write), similarly to gzip(1)'s compression level setting.

                  If -l is not used, the default compression level will apply.

       -u         Set the compression level to 0, for uncompressed output.  This is a synonym for
                  -l 0.

       -m INT     Approximately the maximum required memory per thread, specified either in bytes
                  or with a K, M, or G suffix.  [768 MiB]

                  To  prevent  sort from creating a huge number of temporary files, it enforces a
                  minimum value of 1M for this setting.

       -M         Sort unmapped reads (those in  chromosome  "*")  by  their  sequence  minimiser
                  (Schleimer  et  al., 2003; Roberts et al., 2004), also reverse complementing as
                  appropriate.  This has the effect of  collating  some  similar  data  together,
                  improving  the  compressibility  of  the unmapped sequence.  The minimiser kmer
                  size is adjusted using the -K option.  Note data compressed in this manner  may
                  need to be name collated prior to conversion back to fastq.

                  Mapped sequences are sorted by chromosome and position.

       -n         Sort  by  read  names  (i.e.,  the  QNAME  field)  rather  than  by chromosomal
                  coordinates.

       -t TAG     Sort first by the value in the alignment tag TAG, then by position or name  (if
                  also using -n).

       -o FILE    Write the final sorted output to FILE, rather than to standard output.

       -O FORMAT  Write the final output as sam, bam, or cram.

                  By  default,  samtools  tries  to  select  a  format  based  on the -o filename
                  extension; if output is to standard output or no format can be deduced, bam  is
                  selected.

       -T PREFIX  Write  temporary  files  to  PREFIX.nnnn.bam,  or if the specified PREFIX is an
                  existing  directory,  to  PREFIX/samtools.mmm.mmm.tmp.nnnn.bam,  where  mmm  is
                  unique to this invocation of the sort command.

                  By  default,  any  temporary  files  are  written alongside the output file, as
                  out.bam.tmp.nnnn.bam, or if output  is  to  standard  output,  in  the  current
                  directory as samtools.mmm.mmm.tmp.nnnn.bam.

       -@ INT     Set  number  of  sorting  and  compression  threads.   By default, operation is
                  single-threaded.

       --no-PG    Do not add a @PG line to the header of the output file.

       --template-coordinate
                  Sorts by template-coordinate, whereby the sort order (@HD SO) is unsorted,  the
                  group order (GO) is query, and the sub-sort (SS) is template-coordinate.

       Ordering Rules

       The following rules are used for ordering records.

       If  option -t is in use, records are first sorted by the value of the given alignment tag,
       and then by position or name (if using -n).  For example, “-t RG” will make read group the
       primary sort key.  The rules for ordering by tag are:

       •   Records that do not have the tag are sorted before ones that do.

       •   If  the  types of the tags are different, they will be sorted so that single character
           tags (type A) come before array tags (type B), then string tags (types H and Z),  then
           numeric tags (types f and i).

       •   Numeric  tags  (types  f  and  i)  are  compared  by  value.  Note that comparisons of
           floating-point values are subject to issues of rounding and precision.

       •   String tags (types H and Z) are compared based on the binary contents of the tag using
           the C strcmp(3) function.

       •   Character tags (type A) are compared by binary character value.

       •   No  attempt  is made to compare tags of other types — notably type B array values will
           not be compared.

       When the -n option is present, records are sorted by name.  Names are compared  so  as  to
       give  a  “natural”  ordering — i.e. sections consisting of digits are compared numerically
       while all other sections are compared based on their binary  representation.   This  means
       “a1”  will  come  before “b1” and “a9” will come before “a10”.  Records with the same name
       will be ordered according to the values of the READ1 and READ2 flags (see flags).

       When the --template-coordinate option is in use, the reads are sorted by:

       1. The earlier unclipped 5' coordinate of the template.

       2. The higher unclipped 5' coordinate of the template.

       3. The library (from the read group).

       4. The molecular identifier (MI tag if present).

       5. The read name.

       6. If unpaired, or if R1 has the lower coordinates of the pair.

       When none of the above options are in use, reads are sorted by reference (according to the
       order  of  the  @SQ  header  records),  then by position in the reference, and then by the
       REVERSE flag.

       Note

       Historically samtools sort also accepted a less flexible way of specifying the  final  and
       temporary output filenames:

              samtools sort [-f] [-o] in.bam out.prefix

       This  has  now  been  removed.   The  previous out.prefix argument (and -f option, if any)
       should be changed to an appropriate combination of -T PREFIX and -o FILE.  The previous -o
       option should be removed, as output defaults to standard output.

AUTHOR

       Written by Heng Li from the Sanger Institute with numerous subsequent modifications.

SEE ALSO

       samtools(1), samtools-collate(1), samtools-merge(1)

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