1 .TH samtools 1 "10 November 2009" "samtools-0.1.7" "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 view aln.sorted.bam chr2:20,100,000-20,200,000
15 samtools merge out.bam in1.bam in2.bam in3.bam
17 samtools faidx ref.fasta
19 samtools pileup -f ref.fasta aln.sorted.bam
21 samtools mpileup -f ref.fasta -r chr3:1,000-2,000 in1.bam in2.bam
23 samtools tview aln.sorted.bam ref.fasta
27 Samtools is a set of utilities that manipulate alignments in the BAM
28 format. It imports from and exports to the SAM (Sequence Alignment/Map)
29 format, does sorting, merging and indexing, and allows to retrieve reads
30 in any regions swiftly.
32 Samtools is designed to work on a stream. It regards an input file `-'
33 as the standard input (stdin) and an output file `-' as the standard
34 output (stdout). Several commands can thus be combined with Unix
35 pipes. Samtools always output warning and error messages to the standard
36 error output (stderr).
38 Samtools is also able to open a BAM (not SAM) file on a remote FTP or
39 HTTP server if the BAM file name starts with `ftp://' or `http://'.
40 Samtools checks the current working directory for the index file and
41 will download the index upon absence. Samtools does not retrieve the
42 entire alignment file unless it is asked to do so.
44 .SH COMMANDS AND OPTIONS
48 samtools import <in.ref_list> <in.sam> <out.bam>
50 Since 0.1.4, this command is an alias of:
52 samtools view -bt <in.ref_list> -o <out.bam> <in.sam>
56 samtools sort [-n] [-m maxMem] <in.bam> <out.prefix>
58 Sort alignments by leftmost coordinates. File
60 will be created. This command may also create temporary files
61 .I <out.prefix>.%d.bam
62 when the whole alignment cannot be fitted into memory (controlled by
69 Sort by read names rather than by chromosomal coordinates
72 Approximately the maximum required memory. [500000000]
77 samtools merge [-h inh.sam] [-n] <out.bam> <in1.bam> <in2.bam> [...]
79 Merge multiple sorted alignments.
80 The header reference lists of all the input BAM files, and the @SQ headers of
82 if any, must all refer to the same set of reference sequences.
83 The header reference list and (unless overridden by
89 and the headers of other files will be ignored.
97 as `@' headers to be copied to
99 replacing any header lines that would otherwise be copied from
102 is actually in SAM format, though any alignment records it may contain
106 The input alignments are sorted by read names rather than by chromosomal
112 samtools index <aln.bam>
114 Index sorted alignment for fast random access. Index file
120 samtools view [-bhuHS] [-t in.refList] [-o output] [-f reqFlag] [-F
121 skipFlag] [-q minMapQ] [-l library] [-r readGroup] <in.bam>|<in.sam> [region1 [...]]
123 Extract/print all or sub alignments in SAM or BAM format. If no region
124 is specified, all the alignments will be printed; otherwise only
125 alignments overlapping the specified regions will be output. An
126 alignment may be given multiple times if it is overlapping several
127 regions. A region can be presented, for example, in the following
128 format: `chr2' (the whole chr2), `chr2:1000000' (region starting from
129 1,000,000bp) or `chr2:1,000,000-2,000,000' (region between 1,000,000 and
130 2,000,000bp including the end points). The coordinate is 1-based.
136 Output in the BAM format.
139 Output uncompressed BAM. This option saves time spent on
140 compression/decomprssion and is thus preferred when the output is piped
141 to another samtools command.
144 Include the header in the output.
147 Output the header only.
150 Input is in SAM. If @SQ header lines are absent, the
155 This file is TAB-delimited. Each line must contain the reference name
156 and the length of the reference, one line for each distinct reference;
157 additional fields are ignored. This file also defines the order of the
158 reference sequences in sorting. If you run `samtools faidx <ref.fa>',
159 the resultant index file
169 Only output alignments with all bits in INT present in the FLAG
170 field. INT can be in hex in the format of /^0x[0-9A-F]+/ [0]
173 Skip alignments with bits present in INT [0]
176 Skip alignments with MAPQ smaller than INT [0]
179 Only output reads in library STR [null]
182 Only output reads in read group STR [null]
187 samtools faidx <ref.fasta> [region1 [...]]
189 Index reference sequence in the FASTA format or extract subsequence from
190 indexed reference sequence. If no region is specified,
192 will index the file and create
194 on the disk. If regions are speficified, the subsequences will be
195 retrieved and printed to stdout in the FASTA format. The input file can
202 samtools pileup [-f in.ref.fasta] [-t in.ref_list] [-l in.site_list]
203 [-iscgS2] [-T theta] [-N nHap] [-r pairDiffRate] <in.bam>|<in.sam>
205 Print the alignment in the pileup format. In the pileup format, each
206 line represents a genomic position, consisting of chromosome name,
207 coordinate, reference base, read bases, read qualities and alignment
208 mapping qualities. Information on match, mismatch, indel, strand,
209 mapping quality and start and end of a read are all encoded at the read
210 base column. At this column, a dot stands for a match to the reference
211 base on the forward strand, a comma for a match on the reverse strand,
212 `ACGTN' for a mismatch on the forward strand and `acgtn' for a mismatch
213 on the reverse strand. A pattern `\\+[0-9]+[ACGTNacgtn]+' indicates
214 there is an insertion between this reference position and the next
215 reference position. The length of the insertion is given by the integer
216 in the pattern, followed by the inserted sequence. Similarly, a pattern
217 `-[0-9]+[ACGTNacgtn]+' represents a deletion from the reference. The
218 deleted bases will be presented as `*' in the following lines. Also at
219 the read base column, a symbol `^' marks the start of a read segment
220 which is a contiguous subsequence on the read separated by `N/S/H' CIGAR
221 operations. The ASCII of the character following `^' minus 33 gives the
222 mapping quality. A symbol `$' marks the end of a read segment.
226 is applied, the consensus base, Phred-scaled consensus quality, SNP
227 quality (i.e. the Phred-scaled probability of the consensus being
228 identical to the reference) and root mean square (RMS) mapping quality
229 of the reads covering the site will be inserted between the `reference
230 base' and the `read bases' columns. An indel occupies an additional
231 line. Each indel line consists of chromosome name, coordinate, a star,
232 the genotype, consensus quality, SNP quality, RMS mapping quality, #
233 covering reads, the first alllele, the second allele, # reads supporting
234 the first allele, # reads supporting the second allele and # reads
235 containing indels different from the top two alleles.
237 The position of indels is offset by -1.
244 Print the mapping quality as the last column. This option makes the
245 output easier to parse, although this format is not space efficient.
249 The input file is in SAM.
253 Only output pileup lines containing indels.
257 The reference sequence in the FASTA format. Index file
264 Cap mapping quality at INT [60]
268 List of reference names ane sequence lengths, in the format described
271 command. If this option is present, samtools assumes the input
273 is in SAM format; otherwise it assumes in BAM format.
277 List of sites at which pileup is output. This file is space
278 delimited. The first two columns are required to be chromosome and
279 1-based coordinate. Additional columns are ignored. It is
280 recommended to use option
284 as in the default format we may not know the mapping quality.
288 Call the consensus sequence using MAQ consensus model. Options
294 are only effective when
302 Generate genotype likelihood in the binary GLFv3 format. This option
303 suppresses -c, -i and -s.
307 The theta parameter (error dependency coefficient) in the maq consensus
312 Number of haplotypes in the sample (>=2) [2]
316 Expected fraction of differences between a pair of haplotypes [0.001]
320 Phred probability of an indel in sequencing/prep. [40]
326 samtools tview <in.sorted.bam> [ref.fasta]
328 Text alignment viewer (based on the ncurses library). In the viewer,
329 press `?' for help and press `g' to check the alignment start from a
330 region in the format like `chr10:10,000,000'.
334 samtools fixmate <in.nameSrt.bam> <out.bam>
336 Fill in mate coordinates, ISIZE and mate related flags from a
337 name-sorted alignment.
341 samtools rmdup <input.srt.bam> <out.bam>
343 Remove potential PCR duplicates: if multiple read pairs have identical
344 external coordinates, only retain the pair with highest mapping quality.
347 works with FR orientation and requires ISIZE is correctly set.
351 samtools rmdupse <input.srt.bam> <out.bam>
353 Remove potential duplicates for single-ended reads. This command will
354 treat all reads as single-ended even if they are paired in fact.
358 samtools fillmd [-e] <aln.bam> <ref.fasta>
360 Generate the MD tag. If the MD tag is already present, this command will
361 give a warning if the MD tag generated is different from the existing
368 Convert a the read base to = if it is identical to the aligned reference
369 base. Indel caller does not support the = bases at the moment.
375 SAM is TAB-delimited. Apart from the header lines, which are started
376 with the `@' symbol, each alignment line consists of:
382 Col Field Description
384 1 QNAME Query (pair) NAME
386 3 RNAME Reference sequence NAME
387 4 POS 1-based leftmost POSition/coordinate of clipped sequence
388 5 MAPQ MAPping Quality (Phred-scaled)
389 6 CIAGR extended CIGAR string
390 7 MRNM Mate Reference sequence NaMe (`=' if same as RNAME)
391 8 MPOS 1-based Mate POSistion
392 9 ISIZE Inferred insert SIZE
393 10 SEQ query SEQuence on the same strand as the reference
394 11 QUAL query QUALity (ASCII-33 gives the Phred base quality)
395 12 OPT variable OPTional fields in the format TAG:VTYPE:VALUE
399 Each bit in the FLAG field is defined as:
407 0x0001 the read is paired in sequencing
408 0x0002 the read is mapped in a proper pair
409 0x0004 the query sequence itself is unmapped
410 0x0008 the mate is unmapped
411 0x0010 strand of the query (1 for reverse)
412 0x0020 strand of the mate
413 0x0040 the read is the first read in a pair
414 0x0080 the read is the second read in a pair
415 0x0100 the alignment is not primary
416 0x0200 the read fails platform/vendor quality checks
417 0x0400 the read is either a PCR or an optical duplicate
423 Unaligned words used in bam_import.c, bam_endian.h, bam.c and bam_aux.c.
425 CIGAR operation P is not properly handled at the moment.
427 In merging, the input files are required to have the same number of
428 reference sequences. The requirement can be relaxed. In addition,
429 merging does not reconstruct the header dictionaries
430 automatically. Endusers have to provide the correct header. Picard is
433 Samtools' rmdup does not work for single-end data and does not remove
434 duplicates across chromosomes. Picard is better.
438 Heng Li from the Sanger Institute wrote the C version of samtools. Bob
439 Handsaker from the Broad Institute implemented the BGZF library and Jue
440 Ruan from Beijing Genomics Institute wrote the RAZF library. Various
441 people in the 1000Genomes Project contributed to the SAM format
446 Samtools website: <http://samtools.sourceforge.net>
projects / samtools.git / blob