=head1 NAME

Maq - Mapping and Assembly with Qualities

=head1 SYNOPSIS

B<maq> I<command> [I<options>] I<arguments>

B<maq.pl> I<command> [I<options>] I<arguments>

=head1 DESCRIPTION

Maq is a software that builds mapping assemblies from short reads
generated by the next-generation sequencing machines. It is particularly
designed for Illumina-Solexa 1G Genetic Analyzer, and has a preliminary
functionality to handle AB SOLiD data.

With Maq you can:

=over 2

=item

Fast align Illumina/SOLiD reads to the reference genome. With the
default options, one million pairs of reads can be mapped to the human
genome in about 10 CPU hours with less than 1G memory.

=item

Accurately measure the error probability of the alignment of each
individual read.

=item

Call the consensus genotypes, including homozygous and heterozygous
polymorphisms, with a Phred probabilistic quality assigned to each base.

=item

Find short indels with paired end reads.

=item

Accurately find large scale genomic deletions and translocations with
paired end reads.

=item

Discover potential CNVs by checking read depth.

=item

Evaluate the accuracy of raw base qualities from sequencers and help to
check the systematic errors.

=back

However, Maq can B<NOT>:

=over 2

=item

Do I<de novo> assembly. (Maq can only call the consensus by mapping
reads to a known reference.)

=item

Map shorts reads against themselves. (Maq can only find complete overlap
between reads.)

=item

Align capillary reads or 454 reads to the reference. (Maq cannot align
reads longer than 63bp.)

=back

=head1 MAQ COMMANDS

=head2 Key Commands

=over 11

=item B<fasta2bfa>

B<maq> B<fasta2bfa> F<in.ref.fasta> F<out.ref.bfa>

Convert sequences in FASTA format to Maq's BFA (binary FASTA) format.

=item B<fastq2bfq>

B<maq> B<fastq2bfq> [B<-n> I<nreads>] F<in.read.fastq>
F<out.read.bfq>|F<out.prefix>

Convert reads in FASTQ format to Maq's BFQ (binary FASTQ) format.

B<OPTIONS:>

=over 9

=item B<-n> I<INT>

number of reads per file [not specified]

=back

=item B<map>

B<maq> B<map> [B<-n> I<nmis>] [B<-a> I<maxins>] [B<-c>] [B<-1> I<len1>]
[B<-2> I<len2>] [B<-d> F<adap3>] [B<-m> I<mutrate>] [B<-u> F<unmapped>]
[-e I<maxerr>] [B<-M> c|g] [B<-N>] [B<-H> F<allhits>] [B<-C> I<maxhits>]
F<out.aln.map> F<in.ref.bfa> F<in.read1.bfq> [F<in.read2.bfq>] 2>
F<out.map.log>

Map reads to the reference sequences.

B<OPTIONS:>

=over 9

=item B<-n> I<INT>

Number of maximum mismatches that can always be found [2]

=item B<-a> I<INT>

Maximum outer distance for a correct read pair [250]

=item B<-A> I<INT>

Maximum outer distance of two RF paied read (0 for disable) [0]

=item B<-c>

Map reads in the colour space (for SOLiD only)

=item B<-1> I<INT>

Read length for the first read, 0 for auto [0]

=item B<-2> I<INT>

Read length for the second read, 0 for auto [0]

=item B<-m> I<FLOAT>

Mutation rate between the reference sequences and the reads [0.001]

=item B<-d> F<FILE>

Specify a file containing a single line of the 3'-adapter sequence
[null]

=item B<-u> F<FILE>

Dump unmapped reads and reads containing more than I<nmis> mismatches to
a separate file [null]

=item B<-e> I<INT>

Threshold on the sum of mismatching base qualities [70]

=item B<-H> F<FILE>

Dump multiple/all 01-mismatch hits to I<FILE> [null]

=item B<-C> I<INT>

Maximum number of hits to output. Unlimited if larger than 512. [250]

=item B<-M> c|g

methylation alignment mode. All C (or G) on the forward strand will be
changed to T (or A). This option is for testing only.

=item B<-N>

store the mismatch position in the output file F<out.aln.map>. When this
option is in use, the maximum allowed read length is 55bp.

=back

B<NOTE:>

=over 2

=item

Paired end reads should be prepared in two files, one for each end, with
reads are sorted in the same order. This means the k-th read in the
first file is mated with the k-th read in the second file. The
corresponding read names must be identical up to the tailing `/1' or
`/2'. For example, such a pair of read names are allowed:
`EAS1_1_5_100_200/1' and `EAS1_1_5_100_200/2'. The tailing `/[12]' is
usually generated by the GAPipeline to distinguish the two ends in a
pair.

=item

The output is a compressed binary file. It is affected by the
endianness.

=item

The best way to run this command is to provide about 1 to 3 million
reads as input. More reads consume more memory.

=item

Option B<-n> controls the sensitivity of the alignment. By default, a
hit with up to 2 mismatches can be always found. Higher B<-n> finds more
hits and also improves the accuracy of mapping qualities. However, this
is done at the cost of speed.

=item

Alignments with many high-quality mismatches should be discarded as
false alignments or possible contaminations. This behaviour is
controlled by option B<-e>. The B<-e> threshold is only calculated
approximately because base qualities are divided by 10 at a certain
stage of the alignment. The B<-Q> option in the B<assemble> command
precisely set the threshold.

=item

A pair of reads are said to be correctly paired if and only if the
orientation is I<FR> and the outer distance of the pair is no larger
than I<maxins>. There is no limit on the minimum insert size. This
setting is determined by the paired end alignment algorithm used in
Maq. Requiring a minimum insert size will lead to some wrong alignments
with highly overestimated mapping qualities.

=item

Currently, read pairs from Illumina/Solexa long-insert library have RF
read orientation. The maximum insert size is set by option
B<-A>. However, long-insert library is also mixed with a small fraction
of short-insert read pairs. B<-a> should also be set correctly.

=item

Sometimes 5'-end or even the entire 3'-adapter sequence may be
sequenced. Providing B<-d> renders Maq to eliminate the adapter
contaminations.

=item

Given 2 million reads as input, B<maq> usually takes 800MB memory.

=back

=item B<mapmerge>

B<maq> B<mapmerge> F<out.aln.map> F<in.aln1.map> F<in.aln2.map> [...]

Merge a batch of read alignments together.

B<NOTE:>

=over 2

=item

In theory, this command can merge unlimited number of
alignments. However, as mapmerge will be reading all the inputs at the
same time, it may hit the limit of the maximum number of opening files
set by the OS. At present, this has to be manually solved by endusers.

=item

Command B<mapmerge> can be used to merge alignment files with different
read lengths. All the subsequent analyses do not assume fixed length any
more.

=back

=item B<rmdup>

B<maq> B<rmdup> F<out.rmdup.map> F<in.ori.map>

Remove pairs with identical outer coordinates. In principle, pairs with
identical outer coordinates should happen rarely. However, due to the
amplification in sample preparation, this occurs much more frequently
than by chance. Practical analyses show that removing duplicates helps
to improve the overall accuracy of SNP calling.

=item B<assemble>

B<maq> B<assemble> [B<-sp>] [B<-m> I<maxmis>] [B<-Q> I<maxerr>] [B<-r>
I<hetrate>] [B<-t> I<coef>] [B<-q> I<minQ>] [B<-N> I<nHap>] F<out.cns>
F<in.ref.bfa> F<in.aln.map> 2> F<out.cns.log>

Call the consensus sequences from read mapping.

B<OPTIONS:>

=over 9

=item B<-t> I<FLOAT>

Error dependency coefficient [0.93]

=item B<-r> I<FLOAT>

Fraction of heterozygotes among all sites [0.001]

=item B<-s>

Take single end mapping quality as the final mapping quality; otherwise
paired end mapping quality will be used

=item B<-p>

Discard paired end reads that are not mapped in correct pairs

=item B<-m> I<INT>

Maximum number of mismatches allowed for a read to be used in consensus
calling [7]

=item B<-Q> I<INT>

Maximum allowed sum of quality values of mismatched bases [60]

=item B<-q> I<INT>

Minimum mapping quality allowed for a read to be used in consensus
calling [0]

=item B<-N> I<INT>

Number of haplotypes in the pool (>=2) [2]

=back

B<NOTE:>

=over 2

=item

Option B<-Q> sets a limit on the maximum sum of mismatching base
qualities. Reads containing many high-quality mismatches should be
discarded.

=item

Option B<-N> sets the number of haplotypes in a pool. It is designed for
resequencing of samples by pooling multiple strains/individuals
together. For diploid genome resequencing, this option equals 2.

=back

=item B<glfgen>

B<maq> B<glfgen> [B<-sp>] [B<-m> I<maxmis>] [B<-Q> I<maxerr>] [B<-r>
I<hetrate>] [B<-t> I<coef>] [B<-q> I<minQ>] [B<-N> I<nHap>] F<out.cns>
F<in.ref.bfa> F<in.aln.map> 2> F<out.cns.log>

Calculate log-likelihood for all genotypes and store the results in GLF
format (Genotyping Likelihood Format). Please check MAQ website for
detailed descriptions of the file format and the related utilities.

=item B<indelpe>

B<maq> B<indelpe> F<in.ref.bfa> F<in.aln.map> > F<out.indelpe>

Call consistent indels from paired end reads. The output is TAB
delimited with each line consisting of chromosome, start position, type
of the indel, number of reads across the indel, size of the indel and
inserted/deleted nucleotides (separated by colon), number of indels on
the reverse strand, number of indels on the forward strand, 5' sequence
ahead of the indel, 3' sequence following the indel, number of reads
aligned without indels and three additional columns for filters.

At the 3rd column, type of the indel, a star indicates the indel is
confirmed by reads from both strands, a plus means the indel is hit by
at least two reads but from the same strand, a minus shows the indel is
only found on one read, and a dot means the indel is too close to
another indel and is filtered out.

Users are recommended to run through `maq.pl indelpe' to correct the
number of reads mapped without indels. For more details, see the `maq.pl
indelpe' section.

=item B<indelsoa>

B<maq> B<indelsoa> F<in.ref.bfa> F<in.aln.map> > F<out.indelsoa>

Call potential homozygous indels and break points by detecting the
abnormal alignment pattern around indels and break points. The output is
also TAB delimited with each line consisting of chromosome, approximate
coordinate, length of the abnormal region, number of reads mapped across
the position, number of reads on the left-hand side of the position and
number of reads on the right-hand side. The last column can be ignored.

The output contains many false positives. A recommended filter could be:

  awk '$5+$6-$4 >= 3 && $4 <= 1' in.indelsoa

Note that this command does not aim to be an accurate indel detector,
but mainly helps to avoid some false positives in substitution
calling. In addition, it only works well given deep depth (~40X for
example); otherwise the false negative rate would be very high.

=back

=head2 Format Converting

=over 11

=item B<sol2sanger>

B<maq> B<sol2sanger> F<in.sol.fastq> F<out.sanger.fastq>

Convert Solexa FASTQ to standard/Sanger FASTQ format.

=item B<bfq2fastq>

B<maq> B<bfq2fastq> F<in.read.bfq> F<out.read.fastq>

Convert Maq's BFQ format to standard FASTQ format.

=item B<mapass2maq>

B<maq> B<mapass2maq> F<in.mapass2.map> F<out.maq.map>

Convert obsolete mapass2's map format to Maq's map format. The old
format does not contain read names.

=back

=head2 Information Extracting

=over 11

=item B<mapview>

B<maq> B<mapview> [B<-bN>] F<in.aln.map> > F<out.aln.txt>

Display the read alignment in plain text. For reads aligned before the
Smith-Waterman alignment, each line consists of read name, chromosome,
position, strand, insert size from the outer coorniates of a pair,
paired flag, mapping quality, single-end mapping quality, alternative
mapping quality, number of mismatches of the best hit, sum of qualities
of mismatched bases of the best hit, number of 0-mismatch hits of the
first 24bp, number of 1-mismatch hits of the first 24bp on the
reference, length of the read, read sequence and its quality.
Alternative mapping quality always equals to mapping quality if the
reads are not paired. If reads are paired, it equals to the smaller
mapping quality of the two ends. This alternative mapping quality is
actually the mapping quality of an abnormal pair.

The fifth column, paired flag, is a bitwise flag. Its lower 4 bits give
the orientation: 1 stands for FF, 2 for FR, 4 for RF, and 8 for RR,
where FR means that the read with smaller coordinate is on the forward
strand, and its mate is on the reverse strand. Only FR is allowed for a
correct pair. The higher bits of this flag give further information. If
the pair meets the paired end requirement, 16 will be set. If the two
reads are mapped to different chromosomes, 32 will be set. If one of the
two reads cannot be mapped at all, 64 will be set. The flag for a
correct pair always equals to 18.

For reads aligned by the Smith-Waterman alignment afterwards, the flag
is always 130. A line consists of read name, chromosome, position,
strand, insert size, flag (always 130), position of the indel on the
read (0 if no indel), length of the indels (positive for insertions and
negative for deletions), mapping quality of its mate, number of
mismatches of the best hit, sum of qualities of mismatched bases of the
best hit, two zeros, length of the read, read sequence and its
quality. The mate of a 130-flagged read always gets a flag 18.

Flag 192 indicates that the read is not mapped but its mate is
mapped. For such a read pair, one read has flag 64 and the other has
192.

B<OPTIONS:>

=over 9

=item B<-b>

do not display the read sequence and the quality

=item B<-N>

display the positions where mismatches occur. This flag only works with
a .map file generated by `maq map -N'.

=back

=item B<mapcheck>

B<maq> B<mapcheck> [B<-s>] [B<-m> I<maxmis>] [B<-q> I<minQ>]
F<in.ref.bfa> F<in.aln.map> > F<out.mapcheck>

Read quality check. The mapcheck first reports the composition and the
depth of the reference. After that there is a form. The first column
indicates the position on a read. Following four columns which show the
nucleotide composition, substitution rates between the reference and
reads will be given. These rates and the numbers in the following
columns are scaled to 999 and rounded to nearest integer. The next group
of columns show the distribution of base qualities along the reads at a
quality interval of 10. A decay in quality can usually be observed,
which means bases at the end of read are less accurate. The last group
of columns present the fraction of substitutions for read bases at a
quality interval. This measures the accuracy of base quality
estimation. Idealy, we expect to see 1 in the 3? column, 10 in the 2?
column and 100 in the 1? column.

B<OPTIONS:>

=over 9

=item B<-s>

Take single end mapping quality as the final mapping quality

=item B<-m> I<INT>

Maximum number of mismatahces allowed for a read to be counted [4]

=item B<-q> I<INT>

Minimum mapping quality allowed for a read to be counted [30]

=back

=item B<pileup>

B<maq> B<pileup> [B<-spvP>] [B<-m> I<maxmis>] [B<-Q> I<maxerr>] [B<-q>
I<minQ>] [B<-l> F<sitefile>] F<in.ref.bfa> F<in.aln.map> >
F<out.pileup>

Display the alignment in a `pileup' text format. Each line consists of
chromosome, position, reference base, depth and the bases on reads that
cover this position. If B<-v> is added on the command line, base
qualities and mapping qualities will be presented in the sixth and
seventh columns in order.

The fifth column always starts with `@'. In this column, read bases
identical to the reference are showed in comma `,' or dot `.', and read
bases different from the reference in letters. A comma or a upper case
indicates that the base comes from a read aligned on the forward strand,
while a dot or a lower case on the reverse strand.

This command is for users who want to develop their own SNP callers.

B<OPTIONS:>

=over 9

=item B<-s>

Take single end mapping quality as the final mapping quality

=item B<-p>

Discard paired end reads that are not mapped as correct pairs

=item B<-v>

Output verbose information including base qualities and mapping qualities

=item B<-m> I<INT>

Maximum number of mismatches allowed for a read to be used [7]

=item B<-Q> I<INT>

Maximum allowed number of quality values of mismatches [60]

=item B<-q> I<INT>

Minimum mapping quality allowed for a read to be used [0]

=item B<-l> F<FILE>

File containing the sites at which pileup will be printed out. In this
file the first column gives the names of the reference and the second
the coordinates. Additional columns will be ignored. [null]

=item B<-P>

also output the base position on the read

=back

=item B<cns2fq>

B<maq> B<cns2fq> [B<-Q> I<minMapQ>] [B<-n> I<minNeiQ>] [B<-d>
I<minDepth>] [B<-D> I<maxDepth>] F<in.cns> > F<out.cns.fastq>

Extract the consensus sequences in FASTQ format. In the sequence lines,
bases in lower case are essentially repeats or do not have sufficient
coverage; bases in upper case indicate regions where SNPs can be
reliably called. In the quality lines, ASCII of a character minus 33
gives the PHRED quality.

B<OPTIONS:>

=over 9

=item B<-Q> I<INT>

Minimum mapping quality [40]

=item B<-d> I<INT>

Minimum read depth [3]

=item B<-n> I<INT>

Minimum neighbouring quality [20]

=item B<-D> I<INT>

Maximum read dpeth. >=255 for unlimited. [255]

=back

=item B<cns2snp>

B<maq> B<cns2snp> F<in.cns> > F<out.snp>

Extract SNP sites. Each line consists of chromosome, position, reference
base, consensus base, Phred-like consensus quality, read depth, the
average number of hits of reads covering this position, the highest
mapping quality of the reads covering the position, the minimum
consensus quality in the 3bp flanking regions at each side of the site
(6bp in total), the second best call, log likelihood ratio of the second
best and the third best call, and the third best call.

The 5th column is the key criterion when you judge the reliability of a
SNP. However, as this quality is only calculated assuming site
independency, you should also consider other columns to get more
accurate SNP calls. Script command `B<maq.pl> B<SNPfilter>' is designed
for this (see below).

The 7th column implies whether the site falls in a repetitive region. If
no read covering the site can be mapped with high mapping quality, the
flanking region is possibly repetitive or in the lack of good
reads. A SNP at such site is usually not reliable.

The 8th column roughly gives the copy number of the flanking region in
the reference genome. In most cases, this number approaches 1.00, which
means the region is about unique. Sometimes you may see non-zero read
depth but 0.00 at the 7th column. This indicates that all the reads
covering the position have at least two mismatches. Maq only counts the
number of 0- and 1-mismatch hits to the reference. This is due to a
complex technical issue.

The 9th column gives the neighbouring quality. Filtering on this column
is also required to get reliable SNPs. This idea is inspired by NQS,
although NQS is initially designed for a single read instead of a
consensus.

=item B<cns2view>

B<maq> B<cns2view> F<in.cns> > F<out.view>

Show detailed information at all sites. The output format is identical
to B<cns2snp> report.

=item B<cns2ref>

B<maq> B<cns2ref> F<in.cns> > F<out.ref.fasta>

Extract the reference sequence.

=item B<cns2win>

B<maq> B<cns2win> [B<-w> I<winsize>] [B<-c> I<chr>] [B<-b> I<begin>]
[B<-e> I<end>] [B<-q> I<minQ>] F<in.cns> > F<out.win>

Extract information averaged in a tilling window. The output is TAB
delimited, which consists of reference name, coordinate divided by
1,000,000, SNP rate, het rate, raw read depth, read depth in
approximately unique regions, the average number of hits of reads in the
window and percent GC.

B<OPTIONS:>

=over 9

=item B<-w> I<INT>

Size of a window [1000]

=item B<-c> I<STR>

Destinated reference sequence; otherwise all references will be used
[null]

=item B<-b> I<INT>

Start position, 0 for no constraint [0]

=item B<-e> I<INT>

End position, 0 for no constraint [0]

=item B<-q> I<INT>

Minimum consensus quality of the sites to be used [0]

=back

=back

=head2 Simulation Related

=over 11

=item B<fakemut>

B<maq> B<fakemut> [B<-r> I<mutrate>] [B<-R> I<indelfrac>]
F<in.ref.fasta> > F<out.fakeref.fasta> 2> F<out.fake.snp>

Randomly introduce substitutions and indels to the
reference. Substitutions and sinlge base-pair indels can be added.

B<OPTIONS:>

=over 10

=item B<-r> I<FLOAT>

Mutation rate [0.001]

=item B<-R> I<FLOAT>

Fraction of mutations to be indels [0.1]

=back

=item B<simutrain>

B<maq> B<simutrain> F<out.simupars.dat> F<in.read.fastq>

Estimate/train parameters for read simulation.

=item B<simulate>

B<maq> B<simulate> [B<-d> I<insize>] [B<-s> I<stdev>] [B<-N> I<nReads>]
[B<-1> I<readLen1>] [B<-2> I<readLen2>] [B<-r> I<mutRate>] [B<-R>
I<indelFrac>] [B<-h>] F<out.read1.fastq> F<out.read2.fastq>
F<in.ref.fasta> F<in.simupars.dat>

Simulate paired end reads. File I<in.simupars.dat> determines the read
lengths and quality distribution. It is generated from B<simutrain>, or
can be downloaded from Maq website. In the output read files, a read
name consists of the reference sequence name and the outer coordinates
of the pair of simulated reads. By default, B<simulate> assumes reads
come from a diploid sequence which is generated by adding two different
sets of mutations, including one base-pair indels, to F<in.ref.fasta>.

B<OPTIONS:>

=over 9

=item B<-d> I<INT>

mean of the outer distance of insert sizes [170]

=item B<-s> I<INT>

standard deviation of insert sizes [20]

=item B<-N> I<INT>

number of pairs of reads to be generated [1000000]

=item B<-1> I<INT>

length of the first read [set by F<in.simupars.dat>]

=item B<-2> I<INT>

length of the second read [set by F<in.simupars.dat>]

=item B<-r> I<FLOAT>

mutation rate [0.001]

=item B<-R> I<FLOAT>

fraction of 1bp indels [0.1]

=item B<-h>

add all mutations to F<in.ref.fasta> and generate reads from the single
mutated sequence (haploid mode)

=back

B<NOTE:>

=over 2

=item

Reads generated from this command are independent, which deviates from
the truth. Whereas alignment evaluation is less affected by this,
evaluation on SNP calling should be performed with caution. Error
dependency may be one of the major causes of wrong SNP calls.

=back

=item B<simustat>

B<maq> B<simustat> F<in.simu-aln.map> > F<out.simustat>

Evaluate mapping qualities from simulated reads.

=back

=head2 SOLiD Related

=over 11

=item B<fasta2csfa>

B<maq> B<fasta2csfa> F<in.nucl-ref.fasta> > F<out.colour-ref.fasta>

Convert nucleotide FASTA to colour-coded FASTA. Flag B<-c> should be
then applied to B<map> command. In the output, letter `A' stands for
color 0, `C' for 1, `G' for 2 and `T' for 3. Each sequence in the output
is 1bp shorter than the input.

=item B<csmap2nt>

B<maq> B<csmap2nt> F<out.nt.map> F<in.ref.nt.bfa> F<in.cs.map>

Convert color alignment to nucleotide alignment. The input
F<in.ref.nt.bfa> is the nucleotide binary FASTA reference file. It must
correspond to the original file from which the color reference is
converted. Nucleotide consensus can be called from the resultant
alignment.

=back

=head2 Miscellaneous/Advanced Commands

=over 11

=item B<submap>

B<maq> B<submap> [B<-q> I<minMapQ>] [B<-Q> I<maxSumErr>] [B<-m> I<maxMM>]
[B<-p>] F<out.map> F<in.map>

Filter bad alignments in F<in.map>. Command-line options are described
in the `B<assemble>' command.

=item B<eland2maq>

B<maq> B<eland2maq> [B<-q> I<defqual>] F<out.map> F<in.list> F<in.eland>

Convert eland alignment to maq's .map format. File F<in.list> consists
of the sequence names that appear at the seventh column of the eland
alignment file F<in.eland> and the name you expect to see in maq
alignment. The following is an example:

  cX.fa chrX
  c1.fa chr1
  c2.fa chr2

If you are aligning reads in several batches using eland, it
is important to use the same F<in.list> for the conversion. In addition,
maq will load all the alignments and sort them in the memory. If you
have concatenate several eland outputs into one huge file, you should
separate it into smaller files to prevent maq from eating all your
machine memory.

This command actually aims to show Eland alignment in Maqview. As no
quality information is available, the resultant maq alignment file
should not be used to call consensus genotypes.

=item B<export2maq>

B<maq> B<export2maq> [B<-1> I<read1len>] [B<-2> I<read2len>] [B<-a>
I<maxdist>] [B<-n>] F<out.map> F<in.list> F<in.export>

Convert Illumina's Export format to Maq's F<.map> format. Export format
is a new alignment format since SolexaPipeline-0.3.0 which also
calculates mapping qualities like maq. The resultant file can be used to
call consensus genotypes as most of necessary information is available
for maq to do this accurately.

B<OPTIONS:>

=over 9

=item B<-1> I<INT>

Length of the first read [0]

=item B<-2> I<INT>

Length of the second read [0]

=item B<-a> I<INT>

Maximum outer distance for a correct read pair [250]

=item B<-n>

Retain filtered reads

=back

=back

=head1 MAQ-PERL COMMANDS

=over 11

=item B<demo>

B<maq.pl> B<demo> [B<-h>] [B<-s>] [B<-N> I<nPairs>] [B<-d> I<outDir>]
F<in.fasta> F<in.simudat>

Demonstrate the use of B<maq> and its companion scripts. This command
will simulate reads from a FASTA file F<in.fasta>. The sequence length
and qualities are determined by F<in.simudat> which is generated from
B<maq simutrain> or can be downloaded from Maq website. The simulated
reads will then be mapped with B<maq.pl easyrun>. The alignment accuracy
is evaluated by B<maq simustat>, the consensus accuracy by B<maq
simucns>, and the SNP accuracy by B<maq_eval.pl>.

By default, paired end reads will be simulated and a diploid sequence
will be generated from the input by adding mutations to either haploid
type. The insert size and mutation rate are controlled by B<maq
simulate>.

B<OPTIONS:>

=over 9

=item B<-h>

simulate a haploid sequence instead of a diploid sequence

=item B<-s>

use single-end mode to align reads instead of paired-end mode

=item B<-N> I<INT>

number of pairs of reads to be simulated [1000000]

=item B<-d> I<DIR>

output directory [maqdemo]

=back

B<NOTE:>

=over 2

=item

The output files from B<maq_eval.pl> have not been documented, but you
may make a good guess at some of these files.

=item

This command just demonstrates the use of the maq suite. The accuracy on
real data is almost always lower than what you see from pure simulation.

=back

=item B<easyrun>

B<maq.pl> B<easyrun> [B<-1> I<read1Len>] [B<-d> I<out.dir>] [B<-n>
I<nReads>] [B<-A> F<3adapter>] [B<-e> I<minDep>] [B<-q> I<minCnsQ>]
[B<-p>] [B<-2> I<read2Len>] [B<-a> I<maxIns>] [B<-S>] [B<-N>]
F<in.ref.fasta> F<in1.fastq> [F<in2.fastq>]

Analyses pipeline for small genomes. Easyrun command will run most of
analyses implemented in B<maq>. By default, B<easyrun> assumes all the
input read sequences files are single-end and independent; when B<-p> is
specified, two read sequence files are required, one for each end.

Several files will be generated in I<out.dir>, among which the following
files are the key output:

=over 16

=item F<cns.final.snp>

final SNP calls with low quality ones filtered out

=item F<cns.fq>

consensus sequences and qualities in the FASTQ format

=back

B<OPTIONS:>

=over 9

=item B<-d> I<DIR>

output directory [easyrun]

=item B<-n> I<INT>

number of reads/pairs in one batch of alignment [2000000]

=item B<-S>

apply split-read analysis of short indels (maybe very slow)

=item B<-N> I<INT>

number of haplotypes/strains in the pool (>=2) [2]

=item B<-A> F<FILE>

file for 3'-adapter. The file should contain a single line of sequence
[null]

=item B<-1> I<INT>

length of the first read, 0 for auto [0]

=item B<-e> I<INT>

minimum read depth required to call a SNP (for SNPfilter) [3]

=item B<-q> I<INT>

minimum consensus quality for SNPs in F<cns.final.snp> [30]

=item B<-p>

switch to paired end alignment mode

=item B<-2> I<INT>

length of the second read when B<-p> is applied [0]

=item B<-a> I<INT>

maximum insert size when B<-p> is applied [250]

=back

B<NOTES:>

=over 2

=item

For SNP calling on pooled samples, users should set correct `B<-N>' as
well as `B<-E> 0'.

=item

The input file can be maq's binary format. B<maq.pl> will automatically
detect the file format.

=back

=item B<SNPfilter>

B<maq.pl> B<SNPfilter> [B<-d> I<minDep>] [B<-D> I<maxDep>] [B<-Q>
I<maxMapQ>] [B<-q> I<minCnsQ>] [B<-w> I<indelWinSize>] [B<-n>
I<minNeiQ>] [B<-F> F<in.indelpe>] [B<-f> F<in.indelsoa>] [B<-s>
I<minScore>] [B<-m> I<maxAcross>] [B<-a>] [B<-N> I<maxWinSNP>] [B<-W>
I<densWinSize>] F<in.cns2snp.snp> > F<out.filtered.snp>

Rule out SNPs that are covered by few reads (specified by B<-d>), by too
many reads (specified by B<-D>), near (specified by B<-w>) to a
potential indel, falling in a possible repetitve region (characterized
by B<-Q>), or having low-quality neighbouring bases (specified by
B<-n>). If I<maxWinSNP> or more SNPs appear in any I<densWinSize>
window, they will also be filtered out together.

B<OPTIONS:>

=over 10

=item B<-d> I<INT>

Minimum read depth required to call a SNP [3]

=item B<-D> I<INT>

Maximum read depth required to call a SNP (<255, otherwise ignored) [256]

=item B<-Q> I<INT>

Required maximum mapping quality of reads covering the SNP [40]

=item B<-q> I<INT>

Minimum consensus quality [20]

=item B<-n> I<INT>

Minimum adjacent consensus quality [20]

=item B<-w> I<INT>

Size of the window around the potential indels. SNPs that are close to
indels will be suppressed [3]

=item B<-F> F<FILE>

The B<indelpe> output [null]

=item B<-f> F<FILE>

The B<indelsoa> output [null]

=item B<-s> I<INT>

Minimum score for a soa-indel to be considered [3]

=item B<-m> I<INT>

Maximum number of reads that can be mapped across a soa-indel [1]

=item B<-a>

Alternative filter for single end alignment

=back

=item B<indelpe>

B<maq.pl> B<indelpe> F<in.indelpe> > F<out.indelpe>

Correct the number of reads mapped without indels for homopolymer
tracts. This command modify the 4th, 10th and the last three columns of
F<in.indelpe> and output the result in F<out.indelpe>. After the
correction, the following B<awk> command gives putative homozygous
indels:

  awk '($3=="*"||$3=="+") && $6+$7>=3 && ($6+$7)/$4>=0.75'

and the following gives heterozygotes:

  awk '($3=="*"||$3=="+") && $6+$7>=3 && ($6+$7)/$4<0.75'

Please note that this B<indelpe> command just implements several
heuristic rules. It does not correct for impure homopolymer runs or
di-nucleotide/triplet repeats. Consequently, the two awk commands only
give approximate hom/het indels.

=back

=head1 EXAMPLES

=over 2

=item

Easyrun script:
  maq.pl easyrun -d easyrun ref.fasta part1.fastq part2.fastq

=item

Key commands behind easyrun:
  maq fasta2bfa ref.fasta ref.bfa;
  maq fastq2bfq part1.fastq part1.bfq;
  maq fastq2bfq part2.fastq part2.bfq;
  maq map part1.map ref.bfa part1.bfq;
  maq map part2.map ref.bfa part2.bfq;
  maq mapmerge aln.map part1.map part2.map;
  maq assemble cns.cns ref.bfa aln.map;

=back

=cut

=head1 LICENSE

GNU General Public License, version 3 (GPLv3)

=head1 AVAILABILITY

L<http://maq.sourceforge.net>

=head1 AUTHOR

Heng Li <lh3@sanger.ac.uk>

=cut
