1 .TH samtools 1 "11 July 2010" "samtools-0.1.8" "Bioinformatics tools"
4 samtools - Utilities for the Sequence Alignment/Map (SAM) format
7 samtools view -bt ref_list.txt -o aln.bam aln.sam.gz
9 samtools sort aln.bam aln.sorted
11 samtools index aln.sorted.bam
13 samtools idxstats aln.sorted.bam
15 samtools view aln.sorted.bam chr2:20,100,000-20,200,000
17 samtools merge out.bam in1.bam in2.bam in3.bam
19 samtools faidx ref.fasta
21 samtools pileup -f ref.fasta aln.sorted.bam
23 samtools mpileup -f ref.fasta -r chr3:1,000-2,000 in1.bam in2.bam
25 samtools tview aln.sorted.bam ref.fasta
29 Samtools is a set of utilities that manipulate alignments in the BAM
30 format. It imports from and exports to the SAM (Sequence Alignment/Map)
31 format, does sorting, merging and indexing, and allows to retrieve reads
32 in any regions swiftly.
34 Samtools is designed to work on a stream. It regards an input file `-'
35 as the standard input (stdin) and an output file `-' as the standard
36 output (stdout). Several commands can thus be combined with Unix
37 pipes. Samtools always output warning and error messages to the standard
38 error output (stderr).
40 Samtools is also able to open a BAM (not SAM) file on a remote FTP or
41 HTTP server if the BAM file name starts with `ftp://' or `http://'.
42 Samtools checks the current working directory for the index file and
43 will download the index upon absence. Samtools does not retrieve the
44 entire alignment file unless it is asked to do so.
46 .SH COMMANDS AND OPTIONS
50 samtools view [-bhuHS] [-t in.refList] [-o output] [-f reqFlag] [-F
51 skipFlag] [-q minMapQ] [-l library] [-r readGroup] [-R rgFile] <in.bam>|<in.sam> [region1 [...]]
53 Extract/print all or sub alignments in SAM or BAM format. If no region
54 is specified, all the alignments will be printed; otherwise only
55 alignments overlapping the specified regions will be output. An
56 alignment may be given multiple times if it is overlapping several
57 regions. A region can be presented, for example, in the following
58 format: `chr2' (the whole chr2), `chr2:1000000' (region starting from
59 1,000,000bp) or `chr2:1,000,000-2,000,000' (region between 1,000,000 and
60 2,000,000bp including the end points). The coordinate is 1-based.
66 Output in the BAM format.
69 Output uncompressed BAM. This option saves time spent on
70 compression/decomprssion and is thus preferred when the output is piped
71 to another samtools command.
74 Include the header in the output.
77 Output the header only.
80 Input is in SAM. If @SQ header lines are absent, the
85 This file is TAB-delimited. Each line must contain the reference name
86 and the length of the reference, one line for each distinct reference;
87 additional fields are ignored. This file also defines the order of the
88 reference sequences in sorting. If you run `samtools faidx <ref.fa>',
89 the resultant index file
99 Only output alignments with all bits in INT present in the FLAG
100 field. INT can be in hex in the format of /^0x[0-9A-F]+/ [0]
103 Skip alignments with bits present in INT [0]
106 Skip alignments with MAPQ smaller than INT [0]
109 Only output reads in library STR [null]
112 Only output reads in read group STR [null]
115 Output reads in read groups listed in
122 samtools tview <in.sorted.bam> [ref.fasta]
124 Text alignment viewer (based on the ncurses library). In the viewer,
125 press `?' for help and press `g' to check the alignment start from a
126 region in the format like `chr10:10,000,000' or `=10,000,000' when
127 viewing the same reference sequence.
131 samtools pileup [-f in.ref.fasta] [-t in.ref_list] [-l in.site_list]
132 [-iscgS2] [-T theta] [-N nHap] [-r pairDiffRate] <in.bam>|<in.sam>
134 Print the alignment in the pileup format. In the pileup format, each
135 line represents a genomic position, consisting of chromosome name,
136 coordinate, reference base, read bases, read qualities and alignment
137 mapping qualities. Information on match, mismatch, indel, strand,
138 mapping quality and start and end of a read are all encoded at the read
139 base column. At this column, a dot stands for a match to the reference
140 base on the forward strand, a comma for a match on the reverse strand,
141 `ACGTN' for a mismatch on the forward strand and `acgtn' for a mismatch
142 on the reverse strand. A pattern `\\+[0-9]+[ACGTNacgtn]+' indicates
143 there is an insertion between this reference position and the next
144 reference position. The length of the insertion is given by the integer
145 in the pattern, followed by the inserted sequence. Similarly, a pattern
146 `-[0-9]+[ACGTNacgtn]+' represents a deletion from the reference. The
147 deleted bases will be presented as `*' in the following lines. Also at
148 the read base column, a symbol `^' marks the start of a read segment
149 which is a contiguous subsequence on the read separated by `N/S/H' CIGAR
150 operations. The ASCII of the character following `^' minus 33 gives the
151 mapping quality. A symbol `$' marks the end of a read segment.
155 is applied, the consensus base, Phred-scaled consensus quality, SNP
156 quality (i.e. the Phred-scaled probability of the consensus being
157 identical to the reference) and root mean square (RMS) mapping quality
158 of the reads covering the site will be inserted between the `reference
159 base' and the `read bases' columns. An indel occupies an additional
160 line. Each indel line consists of chromosome name, coordinate, a star,
161 the genotype, consensus quality, SNP quality, RMS mapping quality, #
162 covering reads, the first alllele, the second allele, # reads supporting
163 the first allele, # reads supporting the second allele and # reads
164 containing indels different from the top two alleles.
166 The position of indels is offset by -1.
172 Print the mapping quality as the last column. This option makes the
173 output easier to parse, although this format is not space efficient.
176 The input file is in SAM.
179 Only output pileup lines containing indels.
182 The reference sequence in the FASTA format. Index file
188 Cap mapping quality at INT [60]
191 Filter reads with flag containing bits in
199 reads in the pileup for indel calling for speed up. Zero for unlimited. [0]
202 List of reference names ane sequence lengths, in the format described
205 command. If this option is present, samtools assumes the input
207 is in SAM format; otherwise it assumes in BAM format.
210 List of sites at which pileup is output. This file is space
211 delimited. The first two columns are required to be chromosome and
212 1-based coordinate. Additional columns are ignored. It is
213 recommended to use option
217 as in the default format we may not know the mapping quality.
220 Call the consensus sequence using SOAPsnp consensus model. Options
226 are only effective when
233 Generate genotype likelihood in the binary GLFv3 format. This option
234 suppresses -c, -i and -s.
237 The theta parameter (error dependency coefficient) in the maq consensus
241 Number of haplotypes in the sample (>=2) [2]
244 Expected fraction of differences between a pair of haplotypes [0.001]
247 Phred probability of an indel in sequencing/prep. [40]
252 samtools mpileup [-r reg] [-f in.fa] in.bam [in2.bam [...]]
254 Generate pileup for multiple BAM files. Consensus calling is not
261 Only generate pileup in region
266 The reference file [null]
271 samtools reheader <in.header.sam> <in.bam>
273 Replace the header in
277 This command is much faster than replacing the header with a
278 BAM->SAM->BAM conversion.
282 samtools sort [-no] [-m maxMem] <in.bam> <out.prefix>
284 Sort alignments by leftmost coordinates. File
286 will be created. This command may also create temporary files
287 .I <out.prefix>.%d.bam
288 when the whole alignment cannot be fitted into memory (controlled by
295 Output the final alignment to the standard output.
298 Sort by read names rather than by chromosomal coordinates
301 Approximately the maximum required memory. [500000000]
306 samtools merge [-h inh.sam] [-nr] <out.bam> <in1.bam> <in2.bam> [...]
308 Merge multiple sorted alignments.
309 The header reference lists of all the input BAM files, and the @SQ headers of
311 if any, must all refer to the same set of reference sequences.
312 The header reference list and (unless overridden by
318 and the headers of other files will be ignored.
326 as `@' headers to be copied to
328 replacing any header lines that would otherwise be copied from
331 is actually in SAM format, though any alignment records it may contain
335 Attach an RG tag to each alignment. The tag value is inferred from file names.
338 The input alignments are sorted by read names rather than by chromosomal
344 samtools index <aln.bam>
346 Index sorted alignment for fast random access. Index file
352 samtools idxstats <aln.bam>
354 Retrieve and print stats in the index file. The output is TAB delimited
355 with each line consisting of reference sequence name, sequence length, #
356 mapped reads and # unmapped reads.
360 samtools faidx <ref.fasta> [region1 [...]]
362 Index reference sequence in the FASTA format or extract subsequence from
363 indexed reference sequence. If no region is specified,
365 will index the file and create
367 on the disk. If regions are speficified, the subsequences will be
368 retrieved and printed to stdout in the FASTA format. The input file can
375 samtools fixmate <in.nameSrt.bam> <out.bam>
377 Fill in mate coordinates, ISIZE and mate related flags from a
378 name-sorted alignment.
382 samtools rmdup [-sS] <input.srt.bam> <out.bam>
384 Remove potential PCR duplicates: if multiple read pairs have identical
385 external coordinates, only retain the pair with highest mapping quality.
386 In the paired-end mode, this command
388 works with FR orientation and requires ISIZE is correctly set. It does
389 not work for unpaired reads (e.g. two ends mapped to different
390 chromosomes or orphan reads).
396 Remove duplicate for single-end reads. By default, the command works for
397 paired-end reads only.
400 Treat paired-end reads and single-end reads.
405 samtools calmd [-eubS] <aln.bam> <ref.fasta>
407 Generate the MD tag. If the MD tag is already present, this command will
408 give a warning if the MD tag generated is different from the existing
409 tag. Output SAM by default.
415 Convert a the read base to = if it is identical to the aligned reference
416 base. Indel caller does not support the = bases at the moment.
419 Output uncompressed BAM
422 Output compressed BAM
425 The input is SAM with header lines
430 SAM is TAB-delimited. Apart from the header lines, which are started
431 with the `@' symbol, each alignment line consists of:
437 Col Field Description
439 1 QNAME Query (pair) NAME
441 3 RNAME Reference sequence NAME
442 4 POS 1-based leftmost POSition/coordinate of clipped sequence
443 5 MAPQ MAPping Quality (Phred-scaled)
444 6 CIAGR extended CIGAR string
445 7 MRNM Mate Reference sequence NaMe (`=' if same as RNAME)
446 8 MPOS 1-based Mate POSistion
447 9 ISIZE Inferred insert SIZE
448 10 SEQ query SEQuence on the same strand as the reference
449 11 QUAL query QUALity (ASCII-33 gives the Phred base quality)
450 12 OPT variable OPTional fields in the format TAG:VTYPE:VALUE
454 Each bit in the FLAG field is defined as:
462 0x0001 p the read is paired in sequencing
463 0x0002 P the read is mapped in a proper pair
464 0x0004 u the query sequence itself is unmapped
465 0x0008 U the mate is unmapped
466 0x0010 r strand of the query (1 for reverse)
467 0x0020 R strand of the mate
468 0x0040 1 the read is the first read in a pair
469 0x0080 2 the read is the second read in a pair
470 0x0100 s the alignment is not primary
471 0x0200 f the read fails platform/vendor quality checks
472 0x0400 d the read is either a PCR or an optical duplicate
478 Unaligned words used in bam_import.c, bam_endian.h, bam.c and bam_aux.c.
480 In merging, the input files are required to have the same number of
481 reference sequences. The requirement can be relaxed. In addition,
482 merging does not reconstruct the header dictionaries
483 automatically. Endusers have to provide the correct header. Picard is
486 Samtools paired-end rmdup does not work for unpaired reads (e.g. orphan
487 reads or ends mapped to different chromosomes). If this is a concern,
488 please use Picard's MarkDuplicate which correctly handles these cases,
489 although a little slower.
493 Heng Li from the Sanger Institute wrote the C version of samtools. Bob
494 Handsaker from the Broad Institute implemented the BGZF library and Jue
495 Ruan from Beijing Genomics Institute wrote the RAZF library. Various
496 people in the 1000 Genomes Project contributed to the SAM format
501 Samtools website: <http://samtools.sourceforge.net>
projects / samtools.git / blob