X-Git-Url: http://woldlab.caltech.edu/gitweb/?p=samtools.git;a=blobdiff_plain;f=samtools.1;h=98ce9d04d92d3f38c36ef8809962ea155359c38f;hp=e87bef7e788f09d1c0c38219f231062868a010d4;hb=5075acdfc387c56ca8411cde3e419e867da9804d;hpb=016b50ab60e879a0b8f81cb76ce11ea360a03d4a diff --git a/samtools.1 b/samtools.1 index e87bef7..98ce9d0 100644 --- a/samtools.1 +++ b/samtools.1 @@ -1,7 +1,9 @@ -.TH samtools 1 "15 November 2010" "samtools-0.1.10" "Bioinformatics tools" +.TH samtools 1 "05 July 2011" "samtools-0.1.17" "Bioinformatics tools" .SH NAME .PP samtools - Utilities for the Sequence Alignment/Map (SAM) format + +bcftools - Utilities for the Binary Call Format (BCF) and VCF .SH SYNOPSIS .PP samtools view -bt ref_list.txt -o aln.bam aln.sam.gz @@ -23,6 +25,12 @@ samtools pileup -vcf ref.fasta aln.sorted.bam samtools mpileup -C50 -gf ref.fasta -r chr3:1,000-2,000 in1.bam in2.bam .PP samtools tview aln.sorted.bam ref.fasta +.PP +bcftools index in.bcf +.PP +bcftools view in.bcf chr2:100-200 > out.vcf +.PP +bcftools view -vc in.bcf > out.vcf 2> out.afs .SH DESCRIPTION .PP @@ -43,7 +51,7 @@ Samtools checks the current working directory for the index file and will download the index upon absence. Samtools does not retrieve the entire alignment file unless it is asked to do so. -.SH COMMANDS AND OPTIONS +.SH SAMTOOLS COMMANDS AND OPTIONS .TP 10 .B view @@ -137,21 +145,68 @@ viewing the same reference sequence. .TP .B mpileup -samtools mpileup [-Bug] [-C capQcoef] [-r reg] [-f in.fa] [-l list] [-M capMapQ] [-Q minBaseQ] [-q minMapQ] in.bam [in2.bam [...]] +.B samtools mpileup +.RB [ \-EBug ] +.RB [ \-C +.IR capQcoef ] +.RB [ \-r +.IR reg ] +.RB [ \-f +.IR in.fa ] +.RB [ \-l +.IR list ] +.RB [ \-M +.IR capMapQ ] +.RB [ \-Q +.IR minBaseQ ] +.RB [ \-q +.IR minMapQ ] +.I in.bam +.RI [ in2.bam +.RI [ ... ]] Generate BCF or pileup for one or multiple BAM files. Alignment records are grouped by sample identifiers in @RG header lines. If sample identifiers are absent, each input file is regarded as one sample. -.B OPTIONS: +In the pileup format (without +.BR -u or -g ), +each +line represents a genomic position, consisting of chromosome name, +coordinate, reference base, read bases, read qualities and alignment +mapping qualities. Information on match, mismatch, indel, strand, +mapping quality and start and end of a read are all encoded at the read +base column. At this column, a dot stands for a match to the reference +base on the forward strand, a comma for a match on the reverse strand, +a '>' or '<' for a reference skip, `ACGTN' for a mismatch on the forward +strand and `acgtn' for a mismatch on the reverse strand. A pattern +`\\+[0-9]+[ACGTNacgtn]+' indicates there is an insertion between this +reference position and the next reference position. The length of the +insertion is given by the integer in the pattern, followed by the +inserted sequence. Similarly, a pattern `-[0-9]+[ACGTNacgtn]+' +represents a deletion from the reference. The deleted bases will be +presented as `*' in the following lines. Also at the read base column, a +symbol `^' marks the start of a read. The ASCII of the character +following `^' minus 33 gives the mapping quality. A symbol `$' marks the +end of a read segment. + +.B Input Options: .RS -.TP 8 +.TP 10 +.B -6 +Assume the quality is in the Illumina 1.3+ encoding. +.B -A +Do not skip anomalous read pairs in variant calling. +.TP .B -B Disable probabilistic realignment for the computation of base alignment quality (BAQ). BAQ is the Phred-scaled probability of a read base being misaligned. Applying this option greatly helps to reduce false SNPs caused by misalignments. .TP +.BI -b \ FILE +List of input BAM files, one file per line [null] +.TP .BI -C \ INT Coefficient for downgrading mapping quality for reads containing excessive mismatches. Given a read with a phred-scaled probability q of @@ -159,17 +214,62 @@ being generated from the mapped position, the new mapping quality is about sqrt((INT-q)/INT)*INT. A zero value disables this functionality; if enabled, the recommended value for BWA is 50. [0] .TP -.BI -e \ INT -Phred-scaled gap extension sequencing error probability. Reducing +.BI -d \ INT +At a position, read maximally .I INT -leads to longer indels. [20] +reads per input BAM. [250] +.TP +.B -E +Extended BAQ computation. This option helps sensitivity especially for MNPs, but may hurt +specificity a little bit. .TP .BI -f \ FILE -The reference file [null] +The +.BR faidx -indexed +reference file in the FASTA format. The file can be optionally compressed by +.BR razip . +[null] +.TP +.BI -l \ FILE +BED or position list file containing a list of regions or sites where pileup or BCF should be generated [null] +.TP +.BI -q \ INT +Minimum mapping quality for an alignment to be used [0] +.TP +.BI -Q \ INT +Minimum base quality for a base to be considered [13] +.TP +.BI -r \ STR +Only generate pileup in region +.I STR +[all sites] +.TP +.B Output Options: + +.TP +.B -D +Output per-sample read depth .TP .B -g Compute genotype likelihoods and output them in the binary call format (BCF). .TP +.B -S +Output per-sample Phred-scaled strand bias P-value +.TP +.B -u +Similar to +.B -g +except that the output is uncompressed BCF, which is preferred for piping. + +.TP +.B Options for Genotype Likelihood Computation (for -g or -u): + +.TP +.BI -e \ INT +Phred-scaled gap extension sequencing error probability. Reducing +.I INT +leads to longer indels. [20] +.TP .BI -h \ INT Coefficient for modeling homopolymer errors. Given an .IR l -long @@ -180,8 +280,13 @@ is modeled as .IR INT * s / l . [100] .TP -.BI -l \ FILE -File containing a list of sites where pileup or BCF is outputted [null] +.B -I +Do not perform INDEL calling +.TP +.BI -L \ INT +Skip INDEL calling if the average per-sample depth is above +.IR INT . +[250] .TP .BI -o \ INT Phred-scaled gap open sequencing error probability. Reducing @@ -194,22 +299,6 @@ Comma dilimited list of platforms (determined by from which indel candidates are obtained. It is recommended to collect indel candidates from sequencing technologies that have low indel error rate such as ILLUMINA. [all] -.TP -.BI -q \ INT -Minimum mapping quality for an alignment to be used [0] -.TP -.BI -Q \ INT -Minimum base quality for a base to be considered [13] -.TP -.BI -r \ STR -Only generate pileup in region -.I STR -[all sites] -.TP -.B -u -Similar to -.B -g -except that the output is uncompressed BCF, which is preferred for piping. .RE .TP @@ -223,6 +312,16 @@ with the header in This command is much faster than replacing the header with a BAM->SAM->BAM conversion. +.TP +.B cat +samtools cat [-h header.sam] [-o out.bam] [ ... ] + +Concatenate BAMs. The sequence dictionary of each input BAM must be identical, +although this command does not check this. This command uses a similar trick +to +.B reheader +which enables fast BAM concatenation. + .TP .B sort samtools sort [-no] [-m maxMem] @@ -249,7 +348,7 @@ Approximately the maximum required memory. [500000000] .TP .B merge -samtools merge [-nur] [-h inh.sam] [-R reg] [...] +samtools merge [-nur1f] [-h inh.sam] [-R reg] [...] Merge multiple sorted alignments. The header reference lists of all the input BAM files, and the @SQ headers of @@ -266,6 +365,12 @@ and the headers of other files will be ignored. .B OPTIONS: .RS .TP 8 +.B -1 +Use zlib compression level 1 to comrpess the output +.TP +.B -f +Force to overwrite the output file if present. +.TP 8 .BI -h \ FILE Use the lines of .I FILE @@ -277,17 +382,18 @@ replacing any header lines that would otherwise be copied from is actually in SAM format, though any alignment records it may contain are ignored.) .TP +.B -n +The input alignments are sorted by read names rather than by chromosomal +coordinates +.TP .BI -R \ STR Merge files in the specified region indicated by .I STR +[null] .TP .B -r Attach an RG tag to each alignment. The tag value is inferred from file names. .TP -.B -n -The input alignments are sorted by read names rather than by chromosomal -coordinates -.TP .B -u Uncompressed BAM output .RE @@ -355,7 +461,7 @@ Treat paired-end reads and single-end reads. .TP .B calmd -samtools calmd [-eubSr] [-C capQcoef] +samtools calmd [-EeubSr] [-C capQcoef] Generate the MD tag. If the MD tag is already present, this command will give a warning if the MD tag generated is different from the existing @@ -388,142 +494,228 @@ Coefficient to cap mapping quality of poorly mapped reads. See the command for details. [0] .TP .B -r -Compute the BQ tag without changing the base quality. +Compute the BQ tag (without -A) or cap base quality by BAQ (with -A). +.TP +.B -E +Extended BAQ calculation. This option trades specificity for sensitivity, though the +effect is minor. .RE .TP -.B pileup -samtools pileup [-2sSBicv] [-f in.ref.fasta] [-t in.ref_list] [-l -in.site_list] [-C capMapQ] [-M maxMapQ] [-T theta] [-N nHap] [-r -pairDiffRate] [-m mask] [-d maxIndelDepth] [-G indelPrior] -| +.B targetcut +samtools targetcut [-Q minBaseQ] [-i inPenalty] [-0 em0] [-1 em1] [-2 em2] [-f ref] -Print the alignment in the pileup format. In the pileup format, each -line represents a genomic position, consisting of chromosome name, -coordinate, reference base, read bases, read qualities and alignment -mapping qualities. Information on match, mismatch, indel, strand, -mapping quality and start and end of a read are all encoded at the read -base column. At this column, a dot stands for a match to the reference -base on the forward strand, a comma for a match on the reverse strand, -a '>' or '<' for a reference skip, `ACGTN' for a mismatch on the forward -strand and `acgtn' for a mismatch on the reverse strand. A pattern -`\\+[0-9]+[ACGTNacgtn]+' indicates there is an insertion between this -reference position and the next reference position. The length of the -insertion is given by the integer in the pattern, followed by the -inserted sequence. Similarly, a pattern `-[0-9]+[ACGTNacgtn]+' -represents a deletion from the reference. The deleted bases will be -presented as `*' in the following lines. Also at the read base column, a -symbol `^' marks the start of a read. The ASCII of the character -following `^' minus 33 gives the mapping quality. A symbol `$' marks the -end of a read segment. +This command identifies target regions by examining the continuity of read depth, computes +haploid consensus sequences of targets and outputs a SAM with each sequence corresponding +to a target. When option +.B -f +is in use, BAQ will be applied. This command is +.B only +designed for cutting fosmid clones from fosmid pool sequencing [Ref. Kitzman et al. (2010)]. +.RE -If option -.B -c -is applied, the consensus base, Phred-scaled consensus quality, SNP -quality (i.e. the Phred-scaled probability of the consensus being -identical to the reference) and root mean square (RMS) mapping quality -of the reads covering the site will be inserted between the `reference -base' and the `read bases' columns. An indel occupies an additional -line. Each indel line consists of chromosome name, coordinate, a star, -the genotype, consensus quality, SNP quality, RMS mapping quality, # -covering reads, the first alllele, the second allele, # reads supporting -the first allele, # reads supporting the second allele and # reads -containing indels different from the top two alleles. - -.B NOTE: -Since 0.1.10, the `pileup' command is deprecated by `mpileup'. +.TP +.B phase +samtools phase [-AF] [-k len] [-b prefix] [-q minLOD] [-Q minBaseQ] +Call and phase heterozygous SNPs. .B OPTIONS: .RS -.TP 10 -.B -B -Disable the BAQ computation. See the -.B mpileup -command for details. +.TP 8 +.B -A +Drop reads with ambiguous phase. +.TP 8 +.BI -b \ STR +Prefix of BAM output. When this option is in use, phase-0 reads will be saved in file +.BR STR .0.bam +and phase-1 reads in +.BR STR .1.bam. +Phase unknown reads will be randomly allocated to one of the two files. Chimeric reads +with switch errors will be saved in +.BR STR .chimeric.bam. +[null] .TP -.B -c -Call the consensus sequence. Options -.BR -T ", " -N ", " -I " and " -r -are only effective when -.BR -c " or " -g -is in use. +.B -F +Do not attempt to fix chimeric reads. .TP -.BI -C \ INT -Coefficient for downgrading the mapping quality of poorly mapped -reads. See the -.B mpileup -command for details. [0] +.BI -k \ INT +Maximum length for local phasing. [13] .TP -.BI -d \ INT -Use the first -.I NUM -reads in the pileup for indel calling for speed up. Zero for unlimited. [1024] +.BI -q \ INT +Minimum Phred-scaled LOD to call a heterozygote. [40] .TP -.BI -f \ FILE -The reference sequence in the FASTA format. Index file -.I FILE.fai -will be created if -absent. +.BI -Q \ INT +Minimum base quality to be used in het calling. [13] +.RE + +.SH BCFTOOLS COMMANDS AND OPTIONS + +.TP 10 +.B view +.B bcftools view +.RB [ \-AbFGNQSucgv ] +.RB [ \-D +.IR seqDict ] +.RB [ \-l +.IR listLoci ] +.RB [ \-s +.IR listSample ] +.RB [ \-i +.IR gapSNPratio ] +.RB [ \-t +.IR mutRate ] +.RB [ \-p +.IR varThres ] +.RB [ \-P +.IR prior ] +.RB [ \-1 +.IR nGroup1 ] +.RB [ \-d +.IR minFrac ] +.RB [ \-U +.IR nPerm ] +.RB [ \-X +.IR permThres ] +.RB [ \-T +.IR trioType ] +.I in.bcf +.RI [ region ] + +Convert between BCF and VCF, call variant candidates and estimate allele +frequencies. + +.RS .TP -.B -g -Generate genotype likelihood in the binary GLFv3 format. This option -suppresses -c, -i and -s. This option is deprecated by the -.B mpileup -command. +.B Input/Output Options: +.TP 10 +.B -A +Retain all possible alternate alleles at variant sites. By default, the view +command discards unlikely alleles. +.TP 10 +.B -b +Output in the BCF format. The default is VCF. .TP -.B -i -Only output pileup lines containing indels. +.BI -D \ FILE +Sequence dictionary (list of chromosome names) for VCF->BCF conversion [null] .TP -.BI -I \ INT -Phred probability of an indel in sequencing/prep. [40] +.B -F +Indicate PL is generated by r921 or before (ordering is different). +.TP +.B -G +Suppress all individual genotype information. .TP .BI -l \ FILE -List of sites at which pileup is output. This file is space -delimited. The first two columns are required to be chromosome and -1-based coordinate. Additional columns are ignored. It is -recommended to use option +List of sites at which information are outputted [all sites] .TP -.BI -m \ INT -Filter reads with flag containing bits in -.I INT -[1796] +.B -N +Skip sites where the REF field is not A/C/G/T .TP -.BI -M \ INT -Cap mapping quality at INT [60] +.B -Q +Output the QCALL likelihood format .TP -.BI -N \ INT -Number of haplotypes in the sample (>=2) [2] +.BI -s \ FILE +List of samples to use. The first column in the input gives the sample names +and the second gives the ploidy, which can only be 1 or 2. When the 2nd column +is absent, the sample ploidy is assumed to be 2. In the output, the ordering of +samples will be identical to the one in +.IR FILE . +[null] .TP -.BI -r \ FLOAT -Expected fraction of differences between a pair of haplotypes [0.001] +.B -S +The input is VCF instead of BCF. .TP -.B -s -Print the mapping quality as the last column. This option makes the -output easier to parse, although this format is not space efficient. +.B -u +Uncompressed BCF output (force -b). .TP -.B -S -The input file is in SAM. +.B Consensus/Variant Calling Options: +.TP 10 +.B -c +Call variants using Bayesian inference. This option automatically invokes option +.BR -e . .TP -.BI -t \ FILE -List of reference names ane sequence lengths, in the format described -for the -.B import -command. If this option is present, samtools assumes the input -.I -is in SAM format; otherwise it assumes in BAM format. +.BI -d \ FLOAT +When +.B -v +is in use, skip loci where the fraction of samples covered by reads is below FLOAT. [0] +.TP +.B -e +Perform max-likelihood inference only, including estimating the site allele frequency, +testing Hardy-Weinberg equlibrium and testing associations with LRT. +.TP +.B -g +Call per-sample genotypes at variant sites (force -c) +.TP +.BI -i \ FLOAT +Ratio of INDEL-to-SNP mutation rate [0.15] +.TP +.BI -p \ FLOAT +A site is considered to be a variant if P(ref|D)