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.
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.
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.
Sort by read names (i.e., the QNAME field) rather than by chromosomal coordinates.
Sort first by the value in the alignment tag TAG, then by position or name (if also using -n).
Write the final sorted output to FILE, rather than to standard output.
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.
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.
Set number of sorting and compression threads. By default, operation is single-threaded.
Do not add a @PG line to the header of the output file.
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:
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 -n option is not present, 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.
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.
Written by Heng Li from the Sanger Institute with numerous subsequent modifications.
samtools (1), samtools-collate (1), samtools-merge (1)
Samtools website: <http://www.htslib.org/>
Copyright © 2023 Genome Research Limited (reg no. 2742969) is a charity registered in England with number 1021457. Terms and conditions.