1 .TH samtools 1 "6 July 2009" "samtools-0.1.5" "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 tview aln.sorted.bam ref.fasta
25 Samtools is a set of utilities that manipulate alignments in the BAM
26 format. It imports from and exports to the SAM (Sequence Alignment/Map)
27 format, does sorting, merging and indexing, and allows to retrieve reads
28 in any regions swiftly.
30 Samtools is designed to work on a stream. It regards an input file `-'
31 as the standard input (stdin) and an output file `-' as the standard
32 output (stdout). Several commands can thus be combined with Unix
33 pipes. Samtools always output warning and error messages to the standard
34 error output (stderr).
36 Samtools is also able to open a BAM (not SAM) file on a remote FTP
37 server if the BAM file name starts with `ftp://'. Samtools checks the
38 current working directory for the index file and will download the index
39 upon absence. Samtools achieves random FTP file access with the `REST'
40 ftp command. It does not retrieve the entire alignment file unless it is
43 .SH COMMANDS AND OPTIONS
47 samtools import <in.ref_list> <in.sam> <out.bam>
49 Since 0.1.4, this command is an alias of:
51 samtools view -bt <in.ref_list> -o <out.bam> <in.sam>
55 samtools sort [-n] [-m maxMem] <in.bam> <out.prefix>
57 Sort alignments by leftmost coordinates. File
59 will be created. This command may also create temporary files
60 .I <out.prefix>.%d.bam
61 when the whole alignment cannot be fitted into memory (controlled by
68 Sort by read names rather than by chromosomal coordinates
71 Approximately the maximum required memory. [500000000]
76 samtools merge [-n] <out.bam> <in1.bam> <in2.bam> [...]
78 Merge multiple sorted alignments. The header of
82 and the headers of other files will be ignored.
88 The input alignments are sorted by read names rather than by chromosomal
94 samtools index <aln.bam>
96 Index sorted alignment for fast random access. Index file
102 samtools view [-bhuHS] [-t in.refList] [-o output] [-f reqFlag] [-F
103 skipFlag] [-q minMapQ] [-l library] [-r readGroup] <in.bam>|<in.sam> [region1 [...]]
105 Extract/print all or sub alignments in SAM or BAM format. If no region
106 is specified, all the alignments will be printed; otherwise only
107 alignments overlapping the specified regions will be output. An
108 alignment may be given multiple times if it is overlapping several
109 regions. A region can be presented, for example, in the following
110 format: `chr2', `chr2:1000000' or `chr2:1,000,000-2,000,000'. The
111 coordinate is 1-based.
117 Output in the BAM format.
120 Output uncompressed BAM. This option saves time spent on
121 compression/decomprssion and is thus preferred when the output is piped
122 to another samtools command.
125 Include the header in the output.
128 Output the header only.
131 Input is in SAM. If @SQ header lines are absent, the
136 This file is TAB-delimited. Each line must contain the reference name
137 and the length of the reference, one line for each distinct reference;
138 additional fields are ignored. This file also defines the order of the
139 reference sequences in sorting. If you run `samtools faidx <ref.fa>',
140 the resultant index file
150 Only output alignments with all bits in INT present in the FLAG
151 field. INT can be in hex in the format of /^0x[0-9A-F]+/ [0]
154 Skip alignments with bits present in INT [0]
157 Skip alignments with MAPQ smaller than INT [0]
160 Only output reads in library STR [null]
163 Only output reads in read group STR [null]
168 samtools faidx <ref.fasta> [region1 [...]]
170 Index reference sequence in the FASTA format or extract subsequence from
171 indexed reference sequence. If no region is specified,
173 will index the file and create
175 on the disk. If regions are speficified, the subsequences will be
176 retrieved and printed to stdout in the FASTA format. The input file can
183 samtools pileup [-f in.ref.fasta] [-t in.ref_list] [-l in.site_list]
184 [-iscgS2] [-T theta] [-N nHap] [-r pairDiffRate] <in.bam>|<in.sam>
186 Print the alignment in the pileup format. In the pileup format, each
187 line represents a genomic position, consisting of chromosome name,
188 coordinate, reference base, read bases, read qualities and alignment
189 mapping qualities. Information on match, mismatch, indel, strand,
190 mapping quality and start and end of a read are all encoded at the read
191 base column. At this column, a dot stands for a match to the reference
192 base on the forward strand, a comma for a match on the reverse strand,
193 `ACGTN' for a mismatch on the forward strand and `acgtn' for a mismatch
194 on the reverse strand. A pattern `\\+[0-9]+[ACGTNacgtn]+' indicates
195 there is an insertion between this reference position and the next
196 reference position. The length of the insertion is given by the integer
197 in the pattern, followed by the inserted sequence. Similarly, a pattern
198 `-[0-9]+[ACGTNacgtn]+' represents a deletion from the reference. The
199 deleted bases will be presented as `*' in the following lines. Also at
200 the read base column, a symbol `^' marks the start of a read segment
201 which is a contiguous subsequence on the read separated by `N/S/H' CIGAR
202 operations. The ASCII of the character following `^' minus 33 gives the
203 mapping quality. A symbol `$' marks the end of a read segment.
207 is applied, the consensus base, consensus quality, SNP quality and RMS
208 mapping quality of the reads covering the site will be inserted between
209 the `reference base' and the `read bases' columns. An indel occupies an
210 additional line. Each indel line consists of chromosome name,
211 coordinate, a star, the genotype, consensus quality, SNP quality, RMS
212 mapping quality, # covering reads, the first alllele, the second allele,
213 # reads supporting the first allele, # reads supporting the second
214 allele and # reads containing indels different from the top two alleles.
221 Print the mapping quality as the last column. This option makes the
222 output easier to parse, although this format is not space efficient.
226 The input file is in SAM.
230 Only output pileup lines containing indels.
234 The reference sequence in the FASTA format. Index file
241 Cap mapping quality at INT [60]
245 List of reference names ane sequence lengths, in the format described
248 command. If this option is present, samtools assumes the input
250 is in SAM format; otherwise it assumes in BAM format.
254 List of sites at which pileup is output. This file is space
255 delimited. The first two columns are required to be chromosome and
256 1-based coordinate. Additional columns are ignored. It is
257 recommended to use option
261 as in the default format we may not know the mapping quality.
265 Call the consensus sequence using MAQ consensus model. Options
271 are only effective when
279 Generate genotype likelihood in the binary GLFv3 format. This option
280 suppresses -c, -i and -s.
284 The theta parameter (error dependency coefficient) in the maq consensus
289 Number of haplotypes in the sample (>=2) [2]
293 Expected fraction of differences between a pair of haplotypes [0.001]
297 Phred probability of an indel in sequencing/prep. [40]
303 samtools tview <in.sorted.bam> [ref.fasta]
305 Text alignment viewer (based on the ncurses library). In the viewer,
306 press `?' for help and press `g' to check the alignment start from a
307 region in the format like `chr10:10,000,000'. Note that if the region
308 showed on the screen contains no mapped reads, a blank screen will be
309 seen. This is a known issue and will be improved later.
315 samtools fixmate <in.nameSrt.bam> <out.bam>
317 Fill in mate coordinates, ISIZE and mate related flags from a
318 name-sorted alignment.
322 samtools rmdup <input.srt.bam> <out.bam>
324 Remove potential PCR duplicates: if multiple read pairs have identical
325 external coordinates, only retain the pair with highest mapping quality.
328 works with FR orientation and requires ISIZE is correctly set.
334 samtools rmdupse <input.srt.bam> <out.bam>
336 Remove potential duplicates for single-ended reads. This command will
337 treat all reads as single-ended even if they are paired in fact.
343 samtools fillmd [-e] <aln.bam> <ref.fasta>
345 Generate the MD tag. If the MD tag is already present, this command will
346 give a warning if the MD tag generated is different from the existing
353 Convert a the read base to = if it is identical to the aligned reference
354 base. Indel caller does not support the = bases at the moment.
360 SAM is TAB-delimited. Apart from the header lines, which are started
361 with the `@' symbol, each alignment line consists of:
367 Col Field Description
369 1 QNAME Query (pair) NAME
371 3 RNAME Reference sequence NAME
372 4 POS 1-based leftmost POSition/coordinate of clipped sequence
373 5 MAPQ MAPping Quality (Phred-scaled)
374 6 CIAGR extended CIGAR string
375 7 MRNM Mate Reference sequence NaMe (`=' if same as RNAME)
376 8 MPOS 1-based Mate POSistion
377 9 ISIZE Inferred insert SIZE
378 10 SEQ query SEQuence on the same strand as the reference
379 11 QUAL query QUALity (ASCII-33 gives the Phred base quality)
380 12 OPT variable OPTional fields in the format TAG:VTYPE:VALUE
384 Each bit in the FLAG field is defined as:
392 0x0001 the read is paired in sequencing
393 0x0002 the read is mapped in a proper pair
394 0x0004 the query sequence itself is unmapped
395 0x0008 the mate is unmapped
396 0x0010 strand of the query (1 for reverse)
397 0x0020 strand of the mate
398 0x0040 the read is the first read in a pair
399 0x0080 the read is the second read in a pair
400 0x0100 the alignment is not primary
401 0x0200 the read fails platform/vendor quality checks
402 0x0400 the read is either a PCR or an optical duplicate
408 Unaligned words used in bam_import.c, bam_endian.h, bam.c and bam_aux.c.
410 CIGAR operation P is not properly handled at the moment.
414 Heng Li from the Sanger Institute wrote the C version of samtools. Bob
415 Handsaker from the Broad Institute implemented the BGZF library and Jue
416 Ruan from Beijing Genomics Institute wrote the RAZF library. Various
417 people in the 1000Genomes Project contributed to the SAM format
422 Samtools website: http://samtools.sourceforge.net
projects / samtools.git / blob