Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
samtools-sort(1)	     Bioinformatics tools	      samtools-sort(1)

       samtools	sort - sorts SAM/BAM/CRAM files

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

       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 cre-
       ate temporary files tmpprefix.%d.bam as needed when the	entire	align-
       ment 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.

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

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

       -m INT	  Approximately	the maximum required memory per	thread,	speci-
		  fied 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.

       -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 stan-
		  dard 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	speci-
		  fied	 PREFIX	 is  an	 existing  directory,  to  PREFIX/sam-
		  tools.mmm.mmm.tmp.nnnn.bam, where mmm	is unique to this  in-
		  vocation 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  sam-

       -@ 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.

       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:

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

       o   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

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

       o   String  tags	 (types	H and Z) are compared based on the binary con-
	   tents of the	tag using the C	strcmp(3) function.

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

       o   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 com-
       pared 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 (ac-
       cording 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	speci-
       fying 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  out-
       put defaults to standard	output.

       Written	by  Heng Li from the Sanger Institute with numerous subsequent

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

       Samtools	website: <>

samtools-1.10			6 December 2019		      samtools-sort(1)


Want to link to this manual page? Use this URL:

home | help