1 .TH samtools 1 "2 October 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 -C50 -agf 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 [-aug] [-C coef] [-r reg] [-f in.fa] [-l list] [-M capMapQ] [-Q minBaseQ] [-q minMapQ] in.bam [in2.bam [...]]
254 Generate BCF or pileup for one or multiple BAM files. Alignment records
255 are grouped by sample identifiers in @RG header lines. If sample
256 identifiers are absent, each input file is regarded as one sample.
262 Perform HMM realignment to compute base alignment quality (BAQ). Base
263 quality will be capped by BAQ.
266 Compute genotype likelihoods and output them in the binary call format (BCF).
271 except that the output is uncompressed BCF, which is preferred for pipeing.
274 Coefficient for downgrading mapping quality for reads containing
275 excessive mismatches. Given a read with a phred-scaled probability q of
276 being generated from the mapped position, the new mapping quality is
277 about sqrt((INT-q)/INT)*INT. A zero value disables this
278 functionality; if enabled, the recommended value is 50. [0]
281 The reference file [null]
284 File containing a list of sites where pileup or BCF is outputted [null]
287 Minimum mapping quality for an alignment to be used [0]
290 Minimum base quality for a base to be considered [13]
293 Only generate pileup in region
300 samtools reheader <in.header.sam> <in.bam>
302 Replace the header in
306 This command is much faster than replacing the header with a
307 BAM->SAM->BAM conversion.
311 samtools sort [-no] [-m maxMem] <in.bam> <out.prefix>
313 Sort alignments by leftmost coordinates. File
315 will be created. This command may also create temporary files
316 .I <out.prefix>.%d.bam
317 when the whole alignment cannot be fitted into memory (controlled by
324 Output the final alignment to the standard output.
327 Sort by read names rather than by chromosomal coordinates
330 Approximately the maximum required memory. [500000000]
335 samtools merge [-h inh.sam] [-nr] <out.bam> <in1.bam> <in2.bam> [...]
337 Merge multiple sorted alignments.
338 The header reference lists of all the input BAM files, and the @SQ headers of
340 if any, must all refer to the same set of reference sequences.
341 The header reference list and (unless overridden by
347 and the headers of other files will be ignored.
355 as `@' headers to be copied to
357 replacing any header lines that would otherwise be copied from
360 is actually in SAM format, though any alignment records it may contain
364 Attach an RG tag to each alignment. The tag value is inferred from file names.
367 The input alignments are sorted by read names rather than by chromosomal
373 samtools index <aln.bam>
375 Index sorted alignment for fast random access. Index file
381 samtools idxstats <aln.bam>
383 Retrieve and print stats in the index file. The output is TAB delimited
384 with each line consisting of reference sequence name, sequence length, #
385 mapped reads and # unmapped reads.
389 samtools faidx <ref.fasta> [region1 [...]]
391 Index reference sequence in the FASTA format or extract subsequence from
392 indexed reference sequence. If no region is specified,
394 will index the file and create
396 on the disk. If regions are speficified, the subsequences will be
397 retrieved and printed to stdout in the FASTA format. The input file can
404 samtools fixmate <in.nameSrt.bam> <out.bam>
406 Fill in mate coordinates, ISIZE and mate related flags from a
407 name-sorted alignment.
411 samtools rmdup [-sS] <input.srt.bam> <out.bam>
413 Remove potential PCR duplicates: if multiple read pairs have identical
414 external coordinates, only retain the pair with highest mapping quality.
415 In the paired-end mode, this command
417 works with FR orientation and requires ISIZE is correctly set. It does
418 not work for unpaired reads (e.g. two ends mapped to different
419 chromosomes or orphan reads).
425 Remove duplicate for single-end reads. By default, the command works for
426 paired-end reads only.
429 Treat paired-end reads and single-end reads.
434 samtools calmd [-eubS] <aln.bam> <ref.fasta>
436 Generate the MD tag. If the MD tag is already present, this command will
437 give a warning if the MD tag generated is different from the existing
438 tag. Output SAM by default.
444 Convert a the read base to = if it is identical to the aligned reference
445 base. Indel caller does not support the = bases at the moment.
448 Output uncompressed BAM
451 Output compressed BAM
454 The input is SAM with header lines
459 SAM is TAB-delimited. Apart from the header lines, which are started
460 with the `@' symbol, each alignment line consists of:
466 Col Field Description
468 1 QNAME Query (pair) NAME
470 3 RNAME Reference sequence NAME
471 4 POS 1-based leftmost POSition/coordinate of clipped sequence
472 5 MAPQ MAPping Quality (Phred-scaled)
473 6 CIAGR extended CIGAR string
474 7 MRNM Mate Reference sequence NaMe (`=' if same as RNAME)
475 8 MPOS 1-based Mate POSistion
476 9 ISIZE Inferred insert SIZE
477 10 SEQ query SEQuence on the same strand as the reference
478 11 QUAL query QUALity (ASCII-33 gives the Phred base quality)
479 12 OPT variable OPTional fields in the format TAG:VTYPE:VALUE
483 Each bit in the FLAG field is defined as:
491 0x0001 p the read is paired in sequencing
492 0x0002 P the read is mapped in a proper pair
493 0x0004 u the query sequence itself is unmapped
494 0x0008 U the mate is unmapped
495 0x0010 r strand of the query (1 for reverse)
496 0x0020 R strand of the mate
497 0x0040 1 the read is the first read in a pair
498 0x0080 2 the read is the second read in a pair
499 0x0100 s the alignment is not primary
500 0x0200 f the read fails platform/vendor quality checks
501 0x0400 d the read is either a PCR or an optical duplicate
507 Unaligned words used in bam_import.c, bam_endian.h, bam.c and bam_aux.c.
509 In merging, the input files are required to have the same number of
510 reference sequences. The requirement can be relaxed. In addition,
511 merging does not reconstruct the header dictionaries
512 automatically. Endusers have to provide the correct header. Picard is
515 Samtools paired-end rmdup does not work for unpaired reads (e.g. orphan
516 reads or ends mapped to different chromosomes). If this is a concern,
517 please use Picard's MarkDuplicate which correctly handles these cases,
518 although a little slower.
522 Heng Li from the Sanger Institute wrote the C version of samtools. Bob
523 Handsaker from the Broad Institute implemented the BGZF library and Jue
524 Ruan from Beijing Genomics Institute wrote the RAZF library. Various
525 people in the 1000 Genomes Project contributed to the SAM format
530 Samtools website: <http://samtools.sourceforge.net>
projects / samtools.git / blob