\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename maffilter.info
@settitle MafFilter Manual 1.1.0
@c documentencoding UTF-8
@afourpaper
@dircategory Science Biology Genetics
@direntry
* maffilter: (maffilter)        MAF Filter.
@end direntry
@c %**end of header


@copying
This is the manual of MafFilter, version 1.1.0.

Copyright @copyright{} 2014 Julien Y. Dutheil
@end copying

@titlepage
@title MafFilter Manual
@author Julien Dutheil
@author @email{julien.dutheil@@univ-montp2.fr}


@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1fill1
@insertcopying
@end titlepage

@c Output the table of contents at the beginning.
@contents

@ifnottex
@node Top, Introduction, (dir), (dir)
@top The MafFilter Manual

@insertcopying
@end ifnottex

@menu
* Introduction::                
* Filters::                     

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* Description::                 
* Run::                         
* General::                     

Filters

* Extracting::                  
* Cleaning::                    
* Analyzing::                   
* Exporting::                   

Extracting data

* Subset::                      
* SelectOrphans::               
* Merge::                       
* Concatenate::                 
* ExtractFeature::              
* SelectChr::                   
* WindowSplit::                 

Cleaning alignment blocks

* MinBlockLength::              
* MinBlockSize::                
* XFullGap::                    
* AlnFilter::                   
* AlnFilter2::                  
* EntropyFilter::               
* MaskFilter::                  
* QualFilter::                  
* FeatureFilter::               

Statistical analysis

* Descriptive::                 
* Phylogenetics::               

Arguments:

* BlockSize::                   
* BlockLength::                 
* SequenceLength::              
* AlnScore::                    
* BlockCounts::                 
* PairwiseDivergence::          
* SiteStatistics::              
* FourSpeciesSitePatternCounts::  
* SiteFrequencySpectrum::       
* PolymorphismStatistics::      
* DiversityStatistics::         
* CountClusters::               
* ModelFit::                    

Phylogenetics

* DistanceEstimation::          
* DistanceBasedPhylogeny::      
* NewOutgroup::                 
* DropSpecies::                 

Exporting blocks and data

* Output::                      
* OutputAlignments::            
* VcfOutput::                   
* OutputCoordinates::           
* OutputTrees::                 

@end detailmenu
@end menu

@c ------------------------------------------------------------------------------------------------------------------

@node Introduction, Filters, Top, Top
@chapter Introduction

MafFilter is a program for post-processing genome alignments in the Multiple Alignment Files (MAF) format.
MAF files consist of a series of "blocks", displaying the alignment of subsequences of the original genomes.
In a typical MAF file, such blocks represent synteny blocks.
See the UCSC website for a detailed description of the file format.

How to obtain MAF files is not covered in this manual. MAF files are typically generated by packages such as BlastZ, MultiZ, Last or Galaxy, and you should refer to the manual of these resources for more detailed help.
These packages also contain tools for manipulating MAF files, which you might find useful in combination to the program described here.

Note that several examples are provided along with the source code of the program, and can serve as good training starts.
This manual intends to provide an exhaustive description of the options used in these examples, as well as to provide general information about the way the program works and its underlying algorithms.

@c ------------------------------------------------------------------------------------------------------------------

         
@menu
* Description::                 
* Run::                         
* General::                     
@end menu

@node Description, Run, Introduction, Introduction
@section Description of the program

The main goal of MafFilter is to apply a series of "filters" to the original input file.
A ``filter'' can be seen as a small program that takes as input one or several maf blocks, and outputs one or several maf block, after performing some actions on them:

@verbatim
                         +--------+
   Alignment block(s)    |        |   Alignment block(s)
------------------------>+ Filter +------------------------>
                         |        |
                         +--------+
@end verbatim

We can roughly distinguish four types of filters:

@itemize @bullet
@item
Filters that take one block as input, and output one single block, possibly after removing some sequences, or even the full block if it did not match a certain criterion,
@item
Filters that take one block as input, and split them into several smaller blocks, for instance of a fixed size,
@item
Filters that take several blocks as input and output a larger one, typically after concatenating the input blocks,
@item
Filters that do not modify the input block and simply forward it, yet after having performed some computations, for instance calculating various statistics.
@end itemize

A run of MafFilter typically consists in a workflow of filters, applied in a serial way, the output of one filter being taken as input as the next one.
In the current version of MafFilter, only linear workflows are possible, without branching:

@verbatim
    +----------+    +----------+    +----------+
    |          |    |          |    |          |
--->+ Filter 1 +--->+ Filter 2 +--->+ Filter 3 +---> Etc.
    |          |    |          |    |          |
    +----------+    +----------+    +----------+
@end verbatim

Branching processes can however be achieved by outputing the alignment blocks at the branching point, and run various instances of MafFilter on the resulting files:

@verbatim
     Run 1
    +----------+    +----------+    +----------+
    |          |    |          |    |          |
--->+ Filter 1 +--->+ Filter 2 +--->+ Filter 3 +---> Etc.
    |          |    |          |    |          |
    +----------+    +----+-----+    +----------+
                         |
                         |    +------------+
                         |    |            |
     Run 2               +--->+ Filter 2.1 +---> Etc.
                              |            |
                              +------------+
@end verbatim

Some filters allow to generate additional data associated to each alignment block, such as phylogenetic trees.
Such data cannot be written to file together with the blocks, as the MAF format does not support this.
These data are however stored in memory by MafFilter together with the block, as ``extra-data''.
Extra-data are associated with a special tag which is used for refering to them, including for writting them in appropriate output files.

The next section describes how to specify the series of filters to be applied, and the next chapter provides an exhaustive list of available filters.

@c ------------------------------------------------------------------------------------------------------------------

@node Run, General, Description, Introduction
@section How to run the program

MafFilter is a program written in C++ with the Bio++ libraries. It is a command line program (that is, without graphical user interface) which uses the Bio++ Options (BppO) syntax. 
This syntax is of type @samp{keys}=@samp{values}, which can be passed directly as arguments of the maffilter program
@verbatim
maffilter option1=value1 option2=value2 ... optionN=valueN
@end verbatim
or more conveniently, stored in an ``options'' file (specified with param=option_file), or a combination of both:
@verbatim
maffilter param=option_file
maffilter param=option_file option1=value1 option2=value2
@end verbatim
See the Bio++ Program Suite (BppSuite) manual for more information.

MafFilter typically takes as input a MAF file and a series of commands which determine the output file(s) that will be written and where.
Additional input files might be specified, such as gene annotation files (typically in GFF/GTF format).
Here is the structure of a minimal option file:

@verbatim
DATA=example.file //A user-defined variable, representing the input maf file, without extension
input.file=$(DATA).maf.gz  //Input maf file, gzipped
input.file.compression=gzip
output.log=$(DATA).maffilter.log //Output log file
maf.filter= //A coma separated list of filters, here empty (the programs only read the input file and exits).
@end verbatim
The list of filters can be split on multiple lines for convenience, providing each line is escaped by a '\' at the end to indicate that the next line is a continuation of the current one:
@verbatim
maf.filter=Filter1,\
           Filter2,\
           Filter3
@end verbatim

Please refer to the Bio++ Program Suite manual for more details, including the use of variables, priority of option values, etc.

@c ------------------------------------------------------------------------------------------------------------------

@node General,  , Run, Introduction
@section General options

@heading Synopsis:

@cartouche
@example
input.file=mydata.maf.gz
input.file.compression=gzip
input.format=Maf
output.log=mydata.maffilter.log
...
@end example

or
@example
input.file=mydata.fasta
input.file.compression=none
input.format=Fasta(zero_based=yes)
output.log=mydata.maffilter.log
...
@end example
@end cartouche

@heading Detailed description of commands:

@table @command

@item input.file=@{path@}
The MAF file to parse

@item input.file.compression=[none|zip|gzip|bzip2]
The compression format of the input file.

@item input.format=@{Maf|Fasta@}
MafFilter takes by default a MAF file. It is, however, possible to use a fasta file as input,
which will lead MafFilter to run in "single sequence" mode.
In this mode, each sequence of the original file is considered as a distinct block.
This mode might be useful to extract annotations and estimate simple statistics.
Fasta files can be compressed in the same way as MAF files.
The sequence names are expected to be of the form Species:Chromosome:start:strand:length, with possible empty fields.
Coordinates are expected to be 0-based (that is, the first nucleotide is position 0). However, passing the @command{zero_based=no} argument to the format name will assume that the first nucleotide is position 1.

@item output.log=@{path@}
The file where to write log messages.

@item maf.filter=@{Filter1, Filter2, ...@}
The main command, specifying the list of filter commands to apply, in the given order (that is, the input of filter 2 will be the output of filter 1).
Filters take a series of arguments, specified within parentheses: @command{Filter(arg1=opt1, arg2=opt2, etc)}.
The next section present all available filters and their corresponding arguments.
@end table

@c ------------------------------------------------------------------------------------------------------------------

@node Filters,  , Introduction, Top
@chapter Filters

@c ------------------------------------------------------------------------------------------------------------------

@menu
* Extracting::                  
* Cleaning::                    
* Analyzing::                   
* Exporting::                   
@end menu

@node Extracting, Cleaning, Filters, Filters
@section Extracting data

@menu
* Subset::                      
* SelectOrphans::               
* Merge::                       
* Concatenate::                 
* ExtractFeature::              
* SelectChr::                   
* WindowSplit::                 
@end menu

@c ------------------------------------------------------------------------------------------------------------------

@node Subset, SelectOrphans, Extracting, Extracting
@subsection Subset: remove sequences from blocks by species name

The @command{Subset} filter allows to filter sequences for each block by keeping only a selection of species.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    Subset(                                 \
        species=(species1, species2, etc),  \
        strict=yes,                         \
        keep=no,                            \
        remove_duplicates=yes),             \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command
@item species=(species1, species2, etc)
A coma separated, within parentheses, list of species. Only sequences corresponding to the selected species will be kept.
Block without sequences from the selection will be discarded.

@item strict=yes/no
If set to yes, only blocks containing at least one sequence from each species in the selection will be kept.
        
@item keep=yes/no
If strict is set to yes, tells if additional sequences should be kept in the block, or remove so that the output blocks only contain species from the selection.
        
@item remove_duplicates=yes/no
If set to yes, only keep blocks for which only one sequence for each species is present. Blocks with paralogous sequences in at least one species will therefore be discarded. 

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node SelectOrphans, Merge, Subset, Extracting
@subsection SelectOrphans: keep only block with the specified species

The @command{SelectOrphans} filter allows to discard all block with species out of the specified range.
This is typically used to extract blocks with no homolog ("orphan").

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    SelectOrphans(                          \
        species=(species1, species2, etc),  \
        strict=yes,                         \
        remove_duplicates=yes),             \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command
@item species=(species1, species2, etc)
A coma separated, within parentheses, list of species.
All block containing at least one species outside this list will be discarded.

@item strict=yes/no
If set to yes, only block containing at least one sequence from each species in the selection will be kept.
        
@item remove_duplicates=yes/no
If set to yes, only keep blocks for which only one sequence for each species is present.
Blocks with paralogous sequences in at least one species will therefore be discarded. 

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node Merge, Concatenate, SelectOrphans, Extracting
@subsection Merging: merge synthenic blocks

The @command{Merge} filter fuses consecutive blocks based on their coordinates.
Blocks will be fused only if the sequences from a specified set of species can be considered as syntenic.
Two sequences are considered as syntenic if:
@itemize @bullet
@item
they are from the same species
@item
they are from the same chromosome
@item
they are from the same strand
@item
they are distant by less than a defined threshold (the start of sequence 2 - the end of sequence 1 < threshold in bp).
@end itemize

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    Merge(                                  \
        species=(species1, species2, etc),  \
        dist_max=0,                         \
        ignore_chr=(Random,Unknown)),       \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command

@item species=(species1, species2, etc)
A coma separated, within parentheses, list of species.
These species only will be used for the synteny check.
Other species will be concatenated in any situation, and their coordinates removed.

@item dist_max=@{int@}
Maximum distance (in nt) to consider sequences as syntenic.
If dist_max is greater than 0, sequences will be filled with 'N' to preserve coordinates when they are fused.

@item ignore_chr=@{none | (list)@}
An optional parenthetic list of chromosomes to ignore (typically "Unknown", or "Random", etc.).
Sequences annotated with such chromosomes will not be checked for synteny and the corresponding block will not be fused.

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node Concatenate, ExtractFeature, Merge, Extracting
@subsection Concatenating: merge consecutive blocks up to a certain size

The @command{Concatenate} filter fuses consecutive blocks until the concatenated block reaches a minimal size.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    Concatenate(minimum_size=10000),        \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command

@item minimum_size=@{int@}
The minimum size for the blocks to be reached.

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node ExtractFeature, SelectChr, Concatenate, Extracting
@subsection Extract features from the alignment

The @command{ExtractFeature} extracts parts of the alignment corresponding to certain features.
The features to extract are typically provided via a GFF file. 

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...]z
    ExtractFeature(                         \
        ref_species=species1,               \
        feature.file=species1.gff3.gz,      \
        feature.file.compression=gzip,      \
        feature.format=GFF,                 \
        feature.type=mRNA,                  \
        compression=gzip,                   \
        complete=yes,                       \
        ignore_strand=no),                  \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command

@item ref_species=@{string@}
The name of the species for which the coordinates of the features are provided.

@item feature.file=@{path@}
The file where the features are described.

@item feature.file.compression=@{none|gzip|zip|bzip2@}
Compression format for the feature file.

@item feature.format=@{GFF|GTF@}
Format for the feature file, currently GFF (v3.0) or GTF only.

@item feature.type=@{all|(list)@}
Specifies which type of feature should be extracted from the feature file, if several are available.

@item compression=@{none|gzip|zip|bzip2@}
Compression format for output file (if file != none).

@item complete=@{yes|no@}
Tell if only complete features should be extracted or if partial extraction is allowed.

@item ignore_strand=@{yes|no@}
If yes, features will be extracted ``as is''. Otherwise, the invert-complement sequence will be returned if it is located on the negative strand.

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node SelectChr, WindowSplit, ExtractFeature, Extracting
@subsection Extract blocks for a given chromosome/contig/scaffold

The @command{SelectChr} filter keeps only block from a given chromosome (or contig or scaffold...) for a given reference species.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    SelectChr(                              \
        ref_species=species1,               \
        chromosome=chr01),                  \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command

@item ref_species=@{string@}
The species name for which chromosomes should be extracted.

@item chromosome=@{string@}
The name of the chromosome/contig/scaffold to be filtered.

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node WindowSplit,  , SelectChr, Extracting
@subsection Split alignment blocks into smaller parts

The @command{WindowSplit} filter subdivides blocks into smaller ones of a regular size, typically for window-based analyses.
It is possible to generate overlapping windows.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    WindowSplit(                            \
        preferred_size=1000,                \
        align=center),                      \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command

@item preferred_size=@{int>0@}
The preferred size for the output windows.

@item align=@{ragged_left|ragged_right|center|adjust@}
Specifies how to align windows on the block:

@table @command
@item ragged_left
@verbatim
Block   |----------------------------|
Windows |----|----|----|----|----|XXXX
@end verbatim

@item ragged_right
@verbatim
Block   |----------------------------|
Windows XXXX|----|----|----|----|----|
@end verbatim

@item center
@verbatim
Block   |----------------------------|
Windows XX|----|----|----|----|----|XX
@end verbatim

@item adjust
@verbatim
Block   |----------------------------|
Windows |-----|-----|-----|-----|----|
@end verbatim
@end table
In the first three case, some parts of the original block (shown with X) will be discarded.
In the last case, the windows will have at least the specified size, but might be larger.
@end table

@c ------------------------------------------------------------------------------------------------------------------

@node Cleaning, Analyzing, Extracting, Filters
@section Cleaning alignment blocks

@c ------------------------------------------------------------------------------------------------------------------

@menu
* MinBlockLength::              
* MinBlockSize::                
* XFullGap::                    
* AlnFilter::                   
* AlnFilter2::                  
* EntropyFilter::               
* MaskFilter::                  
* QualFilter::                  
* FeatureFilter::               
@end menu

@node MinBlockLength, MinBlockSize, Cleaning, Cleaning
@subsection Minumum block length

The @command{MinBlockLength} filter discards blocks with less sites than a given threshold.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    MinBlockLength(min_length=1000),        \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command

@item min_length=@{int>0@}
The minimum length.

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node MinBlockSize, XFullGap, MinBlockLength, Cleaning
@subsection Minumum block size

The @command{MinBlockSize} filter discards blocks with less sequences than a given threshold.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    MinBlockSize(min_size=3),               \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command

@item min_size=@{int>0@}
The minimum size.

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node XFullGap, AlnFilter, MinBlockSize, Cleaning
@subsection Exclude full gap columns

Remove gap-only columns from blocks. This does not modify coordinates and might be necessary after a @command{Subset} filter.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    XFullGap(
        species=(species1,species2,etc)),   \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command

@item species=(species1, species2, etc)
A coma separated, within parentheses, list of species. Any column containing a gap in the specified species will be removed. If other species are present in the block, the corresponding character will be removed, whether it is a gap or not. The coordinates of these species will then be discarded.

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node AlnFilter, AlnFilter2, XFullGap, Cleaning
@subsection Alignment filtering

Split alignment blocks by removing regions with ambiguous alignments.
The local uncertainty in the alignment is determined through a sliding window based approach.
For each window, the number of gap characters and the total entropy are computed. Any window
for which both the entropy and number of gaps exceed the given thresholds will be removed from
the alignment, and the corresponding block split accordingly.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    AlnFilter(                              \
        species=(species1,species2,etc),    \
        window.size=10,                     \
        window.step=1,                      \
        max.gap=9,                          \
        max.ent=0.2,                        \
        missing_as_gap=yes,                 \
        file=data.trash_aln.maf.gz,         \
        compression=gzip),                  \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command

@item species=(species1, species2, etc)
A coma separated, within parentheses, list of species. All calculations will be performed on the sub-alignment corresponding to these species only.

@item window.size=@{int>0@}
The width, in bp, of the sliding window.

@item window.step=@{int>0@}
The step by which the window is moved, in bp.

@item max.gap=@{int>0@}
The maximum number of gaps allowed in each window.

@item max.ent=@{float@}
The maximum entropy allowed in each window.

@item missing_as_gap=@{yes/no@}
Tell if unresolved characters should be counted as gaps.

@item file=@{none|@{path@}@}
An optional file were removed alignment parts will be stored, in the MAF format.
This can be helpful for visual inspection and fine tuning of the filter parameters.

@item compression=@{none|gzip|zip|bzip2@}
Compression format for output file (if file != none).

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node AlnFilter2, EntropyFilter, AlnFilter, Cleaning
@subsection Alignment filtering 2

This is another algorithm for cleaning alignment blocks (see AlnFilter), using sliding windows.
The number of gaps in each alignment column in the window is counted, and the column is masked if it contains more than a given threshold of gaps. consecutive patterns in the window are only counted ones. In the follwing 10nt window:
@verbatim
AATCGGGCGT
AA---GCGGA
AA---CGGGT
CA---CGGGA
@end verbatim
positions 3, 4 and 5 will be masked if the maximum number of gaps allowed is 2 or less. The three columns will however count as only one indel event.
The window is then discarded if it contains more than a given number of indel events.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    AlnFilter2(                             \
        species=(species1,species2,etc),    \
        window.size=10,                     \
        window.step=1,                      \
        max.gap=1,                          \
        max.pos=1,                          \
        missing_as_gap=yes,                 \
        file=data.trash_aln.maf.gz,         \
        compression=gzip),                  \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command

@item species=(species1, species2, etc)
A coma separated, within parentheses, list of species. All calculations will be performed on the sub-alignment corresponding to these species only.

@item window.size=@{int>0@}
The width, in bp, of the sliding window.

@item window.step=@{int>0@}
The step by which the window is moved, in bp.

@item max.gap=@{int>0@}
The maximum number of gaps allowed in each site.

@item max.pos=@{int>0@}
The maximum number of positions with gaps (``indel events'').

@item missing_as_gap=@{yes/no@}
Tell if unresolved characters should be counted as gaps.

@item file=@{none|@{path@}@}
An optional file were removed alignment parts will be stored, in the MAF format.
This can be helpful for visual inspection and fine tuning of the filter parameters.

@item compression=@{none|gzip|zip|bzip2@}
Compression format for output file (if file != none).

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node EntropyFilter, MaskFilter, AlnFilter2, Cleaning
@subsection Entropy filtering

This filter removes highly variable regions and split the blocks accordingly.
It uses a sliding windows, and compute the entropy for each site in the window.
The window is then discarded if it containes more than 'p' sites with an entropy higher that a user-specified threshold. The alignment block is then split into separate block accordingly.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    EntropyFilter(                          \
        species=(species1,species2,etc),    \
        window.size=10,                     \
        window.step=1,                      \
        max.ent=0.2,                        \
        max.pos=3,                          \
        missing_as_gap=yes,                 \
        ignore_gaps=yes,                    \
        file=data.trash_ent.maf.gz,         \
        compression=gzip),                  \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command

@item species=(species1, species2, etc)
A coma separated, within parentheses, list of species. All calculations will be performed on the sub-alignment corresponding to these species only.

@item window.size=@{int>0@}
The width, in bp, of the sliding window.

@item window.step=@{int>0@}
The step by which the window is moved, in bp.

@item max.ent=@{float@}
The maximum entropy allowed at each site.

@item max.pos=@{int>0@}
The maximum number of positions with an entropy higher than the given threshold.

@item missing_as_gap=@{yes/no@}
Tell if unresolved characters should be counted as gaps.

@item ignore_gaps=@{yes/no@}
Tell if gaps should not be counted in entropy calculation. If no, then gaps are counted as a ``fifth'' state.

@item file=@{none|@{path@}@}
An optional file were removed alignment parts will be stored, in the MAF format.
This can be helpful for visual inspection and fine tuning of the filter parameters.

@item compression=@{none|gzip|zip|bzip2@}
Compression format for output file (if file != none).

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node MaskFilter, QualFilter, EntropyFilter, Cleaning
@subsection Masked sequences filtering

The @command{MaskFilter} split alignment blocks by removing regions with too many masked positions (typically showing repeat-content), using sliding windows.
A masked position is identified by a lower case letter in the original sequence.
Windows with more than a given amount of lower case characters will be discarded, and the corresponding block split.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    MaskFilter(                             \
        species=(species1,species2,etc),    \
        window.size=10,                     \
        window.step=1,                      \
        max.masked=2,                       \
        file=data.trash_msk.maf.gz,         \
        compression=gzip),                  \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command

@item species=(species1, species2, etc)
A coma separated, within parentheses, list of species. All calculations will be performed on the sub-alignment corresponding to these species only.

@item window.size=@{int>0@}
The width, in bp, of the sliding window.

@item window.step=@{int>0@}
The step by which the window is moved, in bp.

@item max.masked=@{int>0@}
The maximum number of lower-case characters allowed in each window.

@item file=@{none|@{path@}@}
An optional file were removed alignment parts will be stored, in the MAF format.
This can be helpful for visual inspection and fine tuning of the filter parameters.

@item compresion=@{none|gzip|zip|bzip2@}
Compression format for output file (if file != none).

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node QualFilter, FeatureFilter, MaskFilter, Cleaning
@subsection Quality filtering

The @command{QualFilter} split alignment blocks by removing regions with too low quality score.
Windows with an average quality below a given threshold will be discarded, and the corresponding block split.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    QualFilter(                             \
        species=(species1,species2,etc),    \
        window.size=10,                     \
        window.step=1,                      \
        min.qual=0.8,                       \
        file=data.trash_qual.maf.gz,        \
        compression=gzip),                  \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command

@item species=(species1, species2, etc)
A coma separated, within parentheses, list of species. All calculations will be performed on the sub-alignment corresponding to these species only. The corresponding sequences must have a quality score line in the original file.

@item window.size=@{int>0@}
The width, in bp, of the sliding window.

@item window.step=@{int>0@}
The step by which the window is moved, in bp.

@item min.qual=@{double@}
The minimum average quality allowed for each window.

@item file=@{none|@{path@}@}
An optional file were removed alignment parts will be stored, in the MAF format.
This can be helpful for visual inspection and fine tuning of the filter parameters.

@item compression=@{none|gzip|zip|bzip2@}
Compression format for output file (if file != none).

@end table

@c ------------------------------------------------------------------------------------------------------------------
@node FeatureFilter,  , QualFilter, Cleaning
@subsection Remove sequences from features from the alignment

The @command{FeatureFilter} remove parts of the alignment corresponding to certain features.
The features to extract are typically provided via a GFF file. See @command{ExtractFeature}
in order to keep only the feature parts.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    FeatureFilter(                          \
        ref_species=species1,               \
        feature.file=species1.gff3,         \
        feature.file.compression=none,      \
        feature.format=GFF,                 \
        feature.type=(mRNA,tRNA),           \
        file=data.trash_features.maf.gz,    \
        compression=gzip),                  \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command

@item ref_species=@{string@}
The name of the species for which the coordinates of the features are provided.

@item feature.file=@{path@}
The file where the features are described.

@item feature.file.compression=@{none|gzip|zip|bzip2@}
Compression format for the feature file.

@item feature.format=@{GFF|GTF@}
Format for the feature file, currently GFF (v3.0) or GTF only.

@item feature.type=@{all|(list)@}
Specifies which type of feature should be extracted from the feature file, if several are available.

@item file=@{none|@{path@}@}
An optional file were extracted features will be stored, in the MAF format.

@item compression=@{none|gzip|zip|bzip2@}
Compression format for output file (if file != none).

@end table

@c ------------------------------------------------------------------------------------------------------------------


@c ------------------------------------------------------------------------------------------------------------------
@c ------------------------------------------------------------------------------------------------------------------
@c ------------------------------------------------------------------------------------------------------------------
@c ------------------------------------------------------------------------------------------------------------------
@c ------------------------------------------------------------------------------------------------------------------

@node Analyzing, Exporting, Cleaning, Filters
@section Statistical analysis

@menu
* Descriptive::                 
* Phylogenetics::               
@end menu

@node Descriptive, Phylogenetics, Analyzing, Analyzing
@subsection Descriptive statistics

The section describes how to compute simple statistics for each alignment block.
For the sake of computer efficiency, several statistics can be computed simultaneously on each alignment block.
The results are written in a text file, with one line per block and one column per statistics.
In addition, the coordinates of the block will be reported according to a specified reference species.
The choice of statistics is specified by the user. Some of them output several results, which will appear each in a column in the output file.

Descriptive statistics are computed through the @command{SequenceStatistics} filter, which takes the following arguments:

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    SequenceStatistics(                     \
        statistics=(\                       \
            BlockLength,                    \
            AlnScore,                       \
            BlockCounts),                   \
        ref_species=species1,               \
        file=data.statistics.csv),          \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command

@item statistics=@{list of statistics functions@}
See below for the list of possible functions and their detailed description.

@item ref_species=@{string@}
The species to use to report block coordinates in the output file. For block where the reference species is missing, NA will be output.

@item file=@{path@}
A file path for the output file.

@end table

The statistics to compute take the form of functions (just like filters themselves), which can potentially take arguments.
Here is the list of currently available statistical functions:

@menu
* BlockSize::                   
* BlockLength::                 
* SequenceLength::              
* AlnScore::                    
* BlockCounts::                 
* PairwiseDivergence::          
* SiteStatistics::              
* FourSpeciesSitePatternCounts::  
* SiteFrequencySpectrum::       
* PolymorphismStatistics::      
* DiversityStatistics::         
* CountClusters::               
* ModelFit::                    
@end menu

@node BlockSize, BlockLength, Descriptive, Descriptive
@subsubsection Size of alignment blocks
The @command{BlockSize} statistics reports the number of sequences in the block.

(No argument)

@node BlockLength, SequenceLength, BlockSize, Descriptive
@subsubsection Length of alignment blocks
The @command{BlockLength} statistics reports the number of sites in the block.

(No argument)

@node SequenceLength, AlnScore, BlockLength, Descriptive
@subsubsection Length of sequence for a species
The @command{SequenceLength} statistics computes the length (in bp) of the sequence of one species. It returns 0 if no sequence for this species is found in the current block.
It will send an error however if the block has more than one sequence for this species (be sure to use the @command{Subset} filter before, if needed).

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],                                   
    SequenceStatistics(                     \
        statistics=(\                       \
            [...],                                                    
            SequenceLength(                 \
                species=species1),          \
            [...]),                         \
        ref_species=species1,               \
        file=data.statistics.csv),          \
    [...]
@end example
@end cartouche

@heading Arguments:
@table @command
@item species=@{string@}
The species for which lengths should be reported.
@end table

@node AlnScore, BlockCounts, SequenceLength, Descriptive
@subsubsection Alignment score
The @command{AlnScore} statistics reports the alignment score associated to the block, if any.

(No argument)

@node BlockCounts, PairwiseDivergence, AlnScore, Descriptive
@subsubsection Character frequencies
The @command{BlockCounts} statistics reports the count of each character found in the block.

(No argument)

@node PairwiseDivergence, SiteStatistics, BlockCounts, Descriptive
@subsubsection Pairwise divergence
The @command{PairwiseDivergence} computes the divergence (percentage of mistmatch) between two species.
If at least one of the species is missing, NaN is returned.
It will send an error however if the block has more than one sequence for this species (be sure to use the @command{Subset} filter before, if needed).

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],                                   
    SequenceStatistics(                     \
        statistics=(\                       \
            [...],                                                    
            PairwiseDivergence(             \
                species1=species1,          \
                species2=species1),         \
            [...]),                         \
        ref_species=species1,               \
        file=data.statistics.csv),          \
    [...]
@end example
@end cartouche

@heading Arguments:
@table @command
@item species1=@{string@}
The first species for which divergence should be reported.
@item species2=@{string@}
The second species for which divergence should be reported.
@end table

@node SiteStatistics, FourSpeciesSitePatternCounts, PairwiseDivergence, Descriptive
@subsubsection Site statistics
@command{SiteStatistics} computes site-wise statistics, including:
@itemize
@item
Number of sites without gap,
@item
Number of complete sites (no gap, no unresolved character),
@item
Number of parsimony-informative sites.
@end itemize
The statistics are computed for a given subset of species (typically forming a ingroup).

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],                                   
    SequenceStatistics(                     \
        statistics=(\                       \
            [...],                                                    
            SiteStatistics(                 \
                species=species1),          \
            [...]),                         \
        ref_species=species1,               \
        file=data.statistics.csv),          \
    [...]
@end example
@end cartouche

@heading Arguments:
@table @command
@item species=@{list@}
A list of species to be considered in the statistics calculations.
@end table

@node FourSpeciesSitePatternCounts, SiteFrequencySpectrum, SiteStatistics, Descriptive
@subsubsection Counts of parsimony informative sites for a species quartet
The @command{FourSpeciesSitePatternCounts} computes the frequency of each type of informative sites.
With four species, 3 types are expected: 1100, 0110 and 1010. On entry will be output for each of these types.
The remaining sites will be pulled in a column called ``Ignored''.
 
@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],                                   
    SequenceStatistics(                     \
        statistics=(\                       \
            [...],                                                    
            FourSpeciesSitePatternCounts(   \
                species1=sp1,               \
                species2=sp2,               \
                species3=sp3,               \
                species4=sp4                \
            [...]),                         \
        ref_species=sp1,                    \
        file=data.statistics.csv),          \
    [...]
@end example
@end cartouche

@heading Arguments:
@table @command
@item species1=species
First species to consider (resp. second, third and fourth).

@end table

@node SiteFrequencySpectrum, PolymorphismStatistics, FourSpeciesSitePatternCounts, Descriptive
@subsubsection Site frequency spectrum
The @command{SiteFrequencySpectrum} computes the site frequency spectrum for each block.
Only ``doubletons'' sites are considered, that is, positions in the alignment with only two states.
The proportions of doubletons are then computed by bins.
Lets consider the following example with 7 sequences:
@verbatim
ACGT
ACTT
AGTT
AGTT
TCTT
TCTT
TCTT
@end verbatim
It contains one site with 4/7 (eq 3/7), one site with 2/7 (eq 5/7), one site with 1/7 (eq 6/7) and one site 0/7 (eq 7/7).
With seven sequences, there are actually 4 possibles frequencies: 1/7, 2/7, 3/7 and 4/7 (plus the 0/7 frequency, corresponding to a site with no-mutation).
It is possible to compute all these frequencies individually by settingthe @command{bounds} parameter to
@verbatim
SiteFrequencySpectrum(bounds=(-0.5,0.5,1.5,2.5,3.5,4.5), ...)
@end verbatim
which will output the number of site with 0, 1, 2, 3 or 4 minor states. Sites with more than 2 states are always ocounted separately, as well as sites containing unresolved characters.
If one want to count only constant sites for instance, one can simply type
@verbatim
SiteFrequencySpectrum(bounds=(-0.5,0.5), ...)
@end verbatim
The remaining sites will be pulled in a column called ``Ignored''.
 
@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],                                   
    SequenceStatistics(                     \
        statistics=(\                       \
            [...],                                                    
            SiteFrequencySpectrum(          \
                bounds=(-0.5, 0.5, 1.5),    \
                ingroup=(pop1, pop2, pop3), \
                outgroup=species2,          \
            [...]),                         \
        ref_species=pop1,                   \
        file=data.statistics.csv),          \
    [...]
@end example
@end cartouche

@heading Arguments:
@table @command
@item bounds=@{list of double@}
The bounds delimiting the bins of the spectrum to be computed.

@item ingroup=@{list@}
A list of species forming the ingroup and on which the statistics should be calculated.

@item outgroup=species
A species name saying which sequence should be used to determine the ancestral state. If non-empty, the unfolded frequency spectrum will be computed.
If empty, the folded frequency spectrum will be returned (1/5 and 4/5 frequences will be pulled, so that the maximum frequency will be 1/2).

@end table

@node PolymorphismStatistics, DiversityStatistics, SiteFrequencySpectrum, Descriptive
@subsubsection Polymorphism statistics
Compute various statistics describing sequence polymorphism. Two aligned sets of ``species'' are compared, and the number of polymorphic / fixed sites are computed: 
@table @command
@item F
Number of sites fixed in the two sets
@item FF
Number of sites fixed in the two sets, yet with a distinct state
@item P
Number of sites that are polymorphic in the two sets
@item FP
Number of sites that are fixed in set 1 but polymorhic in set 2
@item PF
Number of sites that are fixed in set 2 but polymorphic in set 1
@end table

Positions containing a gap or an unresolved character in one set are considered ambiguous.
Such positions are counted separately in the following quantities:
@table @command
@item X
Number of sites unresolved in the two sets
@item FX
Number of sites fixed in set 1 and unresolved in set 2
@item XF
Number of sites fixed in set 2 and unresolved in set 1
@item PX
Number of sites polymorphic in set 1 and unresolved in set 2
@item XP
Number of sites polymorphic in set 2 and unresolved in set 1
@end table

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],                                   
    SequenceStatistics(                     \
        statistics=(\                       \
            [...],                                                    
            SiteFrequencySpectrum(          \
                bounds=(-0.5, 0.5, 1.5),    \
                ingroup=(pop1, pop2, pop3), \
                outgroup=species2,          \
            [...]),                         \
        ref_species=pop1,                   \
        file=data.statistics.csv),          \
    [...]
@end example
@end cartouche

@heading Arguments:
@table @command
@item species1=@{list@}
A list of species for set 1.
@item species2=@{list@}
A list of species for set 2.
@end table

Note that the ``species'' terminology relates to multispecies alignments, as originally implemented in the MultiZ aligner. These statistics will however be most relevant when the aligned sequences are actually from individuals from the same population / species. The term ``species'' is here therefore to be taken in terchnical terms (a sequence id in the alignment), and not biological. 

@node DiversityStatistics, CountClusters, PolymorphismStatistics, Descriptive
@subsubsection Sequence diversity statistics
@command{DiversityStatistics} computes sequence diversity statistics, including:
@itemize
@item
Number of seggregating sites,
@item
Watterson's theta.
@end itemize

@heading Synopsis:

@cartouche
@example
maf.filter=                                   \
    [...],                                   
    SequenceStatistics(                       \
        statistics=(\                         \
            [...],                                                    
            DiversityStatistics(              \
                ingroup=(samp1, samp2, samp3),\
            [...]),                           \
        ref_species=samp1,                    \
        file=data.statistics.csv),            \
    [...]
@end example
@end cartouche

@heading Arguments:
@table @command
@item ingroup=@{list@}
A list of sequences to be considered in the statistics calculations.
@end table


@node CountClusters, ModelFit, DiversityStatistics, Descriptive
@subsubsection Number of sequence clusters.
@command{CountClusters} counts the number of sequence clusters. This requires that a clustering tree was previously computed (see below).

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],                                   
    SequenceStatistics(                     \
        statistics=(\                       \
            [...],                                                    
            CountClusters(                  \
                tree=bionj,                 \
                threshold=0.001),           \
            [...]),                         \
        ref_species=species1,               \
        file=data.statistics.csv),          \
    [...]
@end example
@end cartouche

@heading Arguments:
@table @command

@item tree=@{string@}
The tag name used to store the previously computed tree.

@item threshold=@{double@}
The threshold to use in order to compute clusters. A threshold of 0.001 for instance means that sequences within each cluster will be divergent by maximum 0.001, while sequences in distinct clusters will be divergent by at least 0.001.
 
@end table

@c ------------------------------------------------------------------------------------------------------------------

@node ModelFit,  , CountClusters, Descriptive
@subsubsection Fit a substitution model and estimate parameters

@command{ModelFit} fits a substitution model to the input block, given a phylogenetic tree.
All nucleotide homogeneous models can be used, with or without rate across sites variation.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],                                   
    SequenceStatistics(                     \
        statistics=(\                       \
            [...],                                                    
            ModelFit(                       \
                model=HKY85(                \
                     kappa=1,               \
                     theta=0.5,             \
                     theta1=0.5,            \
                     theta2=0.5),           \
                rate_distribution=Gamma(    \
                     n=4,                   \
                     alpha=0.5),            \
                tree=BioNJ,                 \
                parameters_output=(         \
                     HKY85.theta,           \
                     HKY85.theta1,          \
                     HKY85.theta2,          \
                     HKY85.kappa),          \
                fixed_parameters=(),        \
                reestimate_brlen=yes,       \
                max_freq_gaps=0.3,          \
                gaps_as_unresolved=yes)),   \
            [...]),                         \
        ref_species=species1,               \
        file=data.statistics.csv),          \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command
@item model=@{string@}
Substitution model to use. See the Bio++ Program Suite manual for an extensive description of available models.
All nucleotide models can be used.

@item rate_distribution=@{string@}
The distribution for rates across sites. See the Bio++ Program Suite manual for all available distributions.

@item root_freqs=@{None|Full|GC@}
Allow root frequencies to be different (non-stationary model). Root frequencies can be fully parametrized, or parametrized with GC content.

@item tree=@{string@}
The property name under which trees are stored for each block.

@item parameters_output=@{list@}
A list of parameter names to output as statistics.

@item fixed_parameters=@{list@}
A list of parameters which should not be optimized, but fixed to their initila values.

@item reestimate_brlen=@{boolean@}
Tell if the branches of the tree should be reestimated for each block together with other model parameters.

@item max_freq_gaps=@{float@}
The maximum proportion of gaps for a site to be included in the analysis.

@item gaps_as_unresolved=@{yes/no@}
Tell if remaining gaps should be converted to 'N' before likelihood computation. This should be 'yes' unless you specify a substitution model which explicitely allows for gaps.

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node Phylogenetics,  , Descriptive, Analyzing
@subsection Phylogenetics

@c ------------------------------------------------------------------------------------------------------------------

@menu
* DistanceEstimation::          
* DistanceBasedPhylogeny::      
* NewOutgroup::                 
* DropSpecies::                 
@end menu

@node DistanceEstimation, DistanceBasedPhylogeny, Phylogenetics, Phylogenetics
@subsubsection Distance matrix estimation

Estimates a pairwise distance matrix.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    DistanceEstimation(                     \
        method=count,                       \
        gap_option=no_double_gap,           \
        unresolved_as_gap=no),               \
    [...]
@end example
or
@example
maf.filter=                                 \
    [...],
    DistanceEstimation(                     \
        method=ml,                          \
        model=K80(kappa=2),                 \
        rate=Gamma(n=4, alpha=0.5),         \
        parameter_estimation=initial,       \
        max_freq_gaps=0.33,                 \
        gaps_as_unresolved=yes,             \
        profiler=none,                      \
        message_handler=none),              \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command
@item method=@{count|ml@}
Method used to estimate distance, either observed count or maximum likelihood estimate.
@end table

Further arguments for the observed counts:
@table @command
@item gap_option=@{string@}
Specifies how to deal with gaps:
@table @command
@item all
All positions are used. Gaps are considered as a fifth character.
@item no_full_gap
Positions only made of gaps in the alignment block are ignored. Alternatively, a gap in the two sequences is ocnsidered as a match (gap are a ``fifth'' charcater).
@item no_double_gap
For each pairwise comparison, positions where a gap is found in both sequences are ignored.
@item no_gap
For each pairwise comparison, any gap-containing position is ignored. This is the recommended option for building phylogenies.
@end table

@item unresolved_as_gap=@{yes|no@}
Tell is unresolved characters should be treated as gaps (usually in order to be ignored).

@end table

Further arguments for the ML method:
@table @command
@item model=@{substitution model description@}
See the Bio++ Program Suite manual for a description of substitution models available. Only nucleotide models can be used.
@example
model=JC
model=K80(kappa=2)
model=T92(kappa=2, theta=0.5)
model=GTR
@end example

@item rate=@{rate distribution description@}
See the Bio++ Program Suite manual for a description of available options.
@example
rate=Constant
rate=Gamma(n=4, alpha=0.5)
@end example

@item profiler=@{none|std|@{path@}@}
Where to print optimization steps (nowhere, standard output or to a given file).

@item message_handler=@{none|std|@{path@}@}
Where to log optimization (nowhere, standard output or to a given file).

@item parameter_estimation=@{initial|pairwise@}
How to estimate substitution process parameters (for instance kappa and alpha).
Available options are either to leave them to their initial values, or to estimate them for each pair of sequences.

@item max_freq_gaps=@{float@}
The maximum proportion of gaps for a site to be included in the analysis.

@item gaps_as_unresolved=@{yes/no@}
Tell if remaining gaps should be converted to 'N' before likelihood computation. This should be 'yes' unless you specify a substitution model which explicitely allows for gaps.
@end table


@heading Extra-data:

@table @command
@item CountDistance or MLDistance
The estimated pairwise distance matrix.
@end table

@c ------------------------------------------------------------------------------------------------------------------

@node DistanceBasedPhylogeny, NewOutgroup, DistanceEstimation, Phylogenetics
@subsubsection Hierarchical clustering based on distances

Performs hierarchical clustering from a previously computed distance matrix.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    DistanceBasedPhylogeny(                 \
        method=bionj,                       \
        dist_mat=MLDistance),               \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command
@item method=@{string@}
Method to use for reconstructing the tree:
@table @command
@item upgma
Unweighted pair group method using arithmetic means
@item wpgma
Weighted pair group method using aritmetic means
@item nj
Neighbor-Joining (Saitou and Nei, 1987)
@item bionj
BioNJ method (Gascuel, 1997)
@end table

@item dist_mat=@{string@}
The tag name of the distance matrix to use.
@end table

@heading Extra-data:

@table @command
@item UPGMA|WPGMA|NJ|BioNJ
The resulting tree.
@end table

@c ------------------------------------------------------------------------------------------------------------------

@node NewOutgroup, DropSpecies, DistanceBasedPhylogeny, Phylogenetics
@subsubsection Root trees

The @command{NewOutgroup} filter takes an input tree and (re)root it according to a given species name.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    NewOutgroup(                            \
        tree_input=BioNJ,                   \
        tree_output=NioNJ_rooted,           \
        outgroup=outgroupSpecies),          \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command
@item tree_input=@{string@}
The tag name of the tree to reroot.
@item tree_output=@{string@}
The tag name to use to store the rerooted tree. If the same as @command{tree_input}, the rerooted tree will replace the old one.
@item outgroup=@{string@}
The name of the species to use as outgroup. One and only one sequence for this species should be present in each block for which rerooting is to be performed.
@end table

@heading Extra-data:

@table @command
@item (user-defined tag)
A rooted tree.
@end table

@c ------------------------------------------------------------------------------------------------------------------

@node DropSpecies,  , NewOutgroup, Phylogenetics
@subsubsection Remove a species from a tree

The @command{DropSpecies} removes a leaf from a tree.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    DropSpecies(                            \
        tree_input=BioNJ,                   \
        tree_output=BioNJ_subtree,          \
        species=species1),                  \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command
@item tree_input=@{string@}
The tag name of the tree to edit.
@item tree_output=@{string@}
The tag name to use to store the edited tree. If the same as @command{tree_input}, the edited tree will replace the old one.
@item species=@{string@}
The name of the species to remove. All leaves in the tree, if any, corresponding to a sequence for this species will be removed.
@end table

@heading Extra-data:

@table @command
@item (user-defined tag)
An edited tree.
@end table

@c ------------------------------------------------------------------------------------------------------------------
@c ------------------------------------------------------------------------------------------------------------------
@c ------------------------------------------------------------------------------------------------------------------
@c ------------------------------------------------------------------------------------------------------------------
@c ------------------------------------------------------------------------------------------------------------------
@node Exporting,  , Analyzing, Filters
@section Exporting blocks and data

@menu
* Output::                      
* OutputAlignments::            
* VcfOutput::                   
* OutputCoordinates::           
* OutputTrees::                 
@end menu

@node Output, OutputAlignments, Exporting, Exporting
@subsection Write alignment blocks to a MAF file

The @command{Output} filter writes all blocks to a MAF file.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    Output(                                 \
        file=data.filtered.maf.gz,          \
        compression=gzip,                   \
        mask=yes),                          \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command
@item file=@{none|@{path@}@}
A file path where to write alignment blocks, in the MAF format.

@item compression=@{none|gzip|zip|bzip2@}
Compression format for output file.

@item mask=@{yes|no@}
Tell if sequences should be masked (if a mask annotation is available), or if masking information should be ignored.

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node OutputAlignments, VcfOutput, Output, Exporting
@subsection Write alignment blocks to an external alignment file.

The @command{OutputAlignments} filter writes all blocks to an external alignment file, potentially losing some information such as coordinates and scores.
Sequence names will be formated following the Ensembl convention.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    OutputAlignments(                       \
        file=data.filtered.aln,             \
        compression=none,                   \
        format=Clustal,                     \
        mask=no),                           \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command
@item file=@{none|@{path@}@}
A file path where to write alignment blocks. If the file name contains the %i code, one alignment file per block will be generated, where %i will be replaced by the block index.

@item format=@{string@}
One of the alignment format supported by Bio++ (this includes Fasta, Mase and Clustal, see the Bio++ Program suite reference manual for a complete list of formats and options).

@item compression=@{none|gzip|zip|bzip2@}
Compression format for output file.

@item mask=@{yes|no@}
Tell if sequences should be masked (if a mask annotation is available), or if masking information should be ignored.

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node VcfOutput, OutputCoordinates, OutputAlignments, Exporting
@subsection Call SNPs from alignment blocks and export to VCF file

The @command{VcfOutput} filter call SNPs from each block and output them to a VCF file.
Only substitutions are called for now.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    VcfOutput(                              \
        file=snp.vcf.gz,                    \
        compression=gzip,                   \
        reference=Ref,                      \
        genotypes=(sample1,sample2)),       \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command
@item file=@{none|@{path@}@}
A file path for the output VCF file.

@item compression=@{none|gzip|zip|bzip2@}
Compression format for output file.

@item reference=@{species name@}
A species name corresponding to the sequence to use as reference.

@item genotypes=@{list of species@}
A list of species for which genotypes informations should be written. If not, void, a 'FORMAT' column will be added to the output, as well as oneextra column per species to genotype.
If the species is not present in this particular, or if a N or Gap is present, adot ('.') will be written in the column.
Please note that species should be unique in each block, otherwise an error will occur.

@end table

@c ------------------------------------------------------------------------------------------------------------------

@node OutputCoordinates, OutputTrees, VcfOutput, Exporting
@subsection Output coordinates of a set of species for each block.

The @command{OutputCoordinates} takes as input a list of species and output the coordinates of each of the corresponding sequences in each block.
This filter only works if no more than one sequence per species are present, otherwise an error is casted. If some species are missing in some blocks, NA are produced in the output file.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    OutputCoordinates(                      \
        file=coordinates.txt.gz,            \
        compression=gzip,                   \
        species=(species1,species2))        \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command
@item file=@{none|@{path@}@}
A file path for the output text file.

@item compression=@{none|gzip|zip|bzip2@}
Compression format for output file.

@item species=@{list of species@}
A list of species for which coodinates should be written.

@end table

@c ------------------------------------------------------------------------------------------------------------------


@node OutputTrees,  , OutputCoordinates, Exporting
@subsection Write trees to a file.

The @command{OutputTrees} filter writes trees associated to blocks to a file, in the Newick format. All trees will be stored in the same file, one per line.

@heading Synopsis:

@cartouche
@example
maf.filter=                                 \
    [...],
    OutputTrees(                            \
        tree=BioNJ,                         \
        file=data.trees.dnd,                \
        compression=gzip),                  \
    [...]
@end example
@end cartouche

@heading Arguments:

@table @command
@item tree=@{string@}
The tag used to store previously computed trees.

@item file=@{none|@{path@}@}
A file path where to write trees, in the Newick format.

@item compression=@{none|gzip|zip|bzip2@}
Compression format for output file.

@end table

@c ------------------------------------------------------------------------------------------------------------------

@c end of document

@c @node Index,  , Reference, Top
@c @unnumbered Index
@c
@c @printindex cp


@bye
