\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename bppsuite.info
@settitle BppSuite Manual 2.4.0
@documentencoding UTF-8
@afourpaper
@dircategory Science Biology Genetics
@direntry
* bppml: (bppml)                Bio++ Maximum Likelihood.
* bppseqgen: (bppseqgen)        Bio++ Sequence Generator.
* bppancestor: (bppancestor)    Bio++ Ancestral Sequences and Rates reconstruction.
* bppdist: (bppdist)            Bio++ Distance Methods.
* bpppars: (bpppars)            Bio++ Maximum Parsimony.
* bppconsense: (bppconsense)    Bio++ Consensus Trees.
* bppreroot: (bppreroot)        Bio++ Serial Tree Re-rooting.
* bppseqman: (bppseqman)        Bio++ Sequences Manipulation.
* bppalnscore: (bppalnscore)    Bio++ Alignment Scoring.
* bpppopstats: (bpppopstats)    Bio++ Population Genetics.
* bpptreedraw: (bpptreedraw)    Bio++ Tree Drawing.
@end direntry
@c %**end of header

@copying
This is the manual of the Bio++ Program Suite, version 2.4.0.

Copyright @copyright{} 2007-2018 Bio++ development team
@end copying

@titlepage
@title BppSuite Manual
@author Julien Dutheil, Laurent Guéguen
@author @email{dutheil@@evolbio.mpg.de}

@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 Bio++ Program Suite Manual

@insertcopying

@menu
* Introduction::                Introducing the Bio++ Program Suite and this manual.                
* Syntax::                      A general description of the syntax used to communicate with the programs.
* Common::                      Common options shared by several programs.                      
* Reference::                   The exhaustive list of options available for all programs in the Bio++ Program Suite.

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

Common options encountered in several programs.

* Alphabet::                    Alphabets and genetic codes.
* Sequences::                   Loading sequences/alignments.
* Tree::                        Loading trees.
* AlphabetIndex::               Setting biochemical properties and distances. 
* Process::
* Distribution::                Setting of the discrete distributions.
* Estimation::                  Estimating parameters by maximizing a likelihood function.
* WritingSequences::            Writing sequences/alignments to files. 
* WritingTrees::                Writing trees to files. 

Process specification

* Model::
* Non-homogeneity::             Specific declaration of non-homogeneous modelling.
* FrequenciesSet::              Frequencies 
* Rates::                       Rates across sites
* Linking::

Setting up the substitution model

* Nucleotide::                  Nucleotide models
* Protein::                     Protein models
* Miscellaneous::               Miscellaneous models
* Codon::                       Codon models
* Multiple::                    General multiple site models
* Meta::                        Meta models
* Mixture::                     Mixture of models
* Conditioned::                 Models conditioned by events

Bio++ Program Suite Reference

* bppml::                       Bio++ Maximum Likelihood.
* bppseqgen::                   Bio++ Sequence Generator.
* bppancestor::                 Bio++ Ancestral Sequences and Rates reconstruction.
* bppmixedlikelihoods::         Bio++ Site-Likelihoods Inside Mixed Models.
* bppdist::                     Bio++ Distance Methods.
* bpppars::                     Bio++ Maximum Parsimony.
* bppconsense::                 Bio++ Consensus Trees.
* bppreroot::                   Bio++ Serial Tree Re-rooting.
* bppseqman::                   Bio++ Sequences Manipulation.
* bppalnscore::                 Bio++ Alignment Scoring.
* bpppopstats::                 Bio++ Population Genetics Statistics.
* bpptreedraw::                 Bio++ Tree Drawing.

@end detailmenu
@end menu

@end ifnottex
@c ------------------------------------------------------------------------------------------------------------------

@node Introduction, Syntax, Top, Top
@chapter Introduction

The Bio++ Program Suite is a package of programs using the Bio++ libraries and dedicated to Phylogenetics and Molecular Evolution.
All programs are independent, but can be combined to perform rather complex analyses.
These programs use the interface helper tools of the libraries, and hence share the same syntax.
They also have several options in common, which may also be shared by third-party software.
This manual was hence split into three parts: 
@table @emph
@item Bio++ option file syntax
A general description of the language used to interact with the programs.

@item Shared options
A more detailed description about several options that are encountered in several programs.
This includes input/output of data and model specifications.

@item The Bio++ Program Suite reference
Include a reference of all available options for each program in the package.

@end table

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

@node Syntax, Common, Introduction, Top
@chapter Syntax description

@section Calling the programs and writing the option files.

The programs in the Bio++ Program Suite are command line-driven.
Arguments may be passed as @command{parameter=value} options, either directly to the command line or
using an option file:
@cartouche
@example
@{program@} parameter1=value1 parameter2=value2 ... parameterN=valueN
@end example
@end cartouche
or
@cartouche
@example
@{program@} param=option_file
@end example
@end cartouche
where @{program@} is the name of the program to use (bppml, bppseqgen,
etc.). Option files contain @command{parameter=value} lines, with only
one parameter per line. They can be written from scratch using a
regular text editor, but since these files can potentially turn to be
quite complex, it is probably wiser to start with a sample provided
along with the program (if any!).

Extra-space may be included between parameter names, equal sign and value:
@cartouche
@example
first_parameter   = value1
second_parameter  = value2
@end example
@end cartouche
and lines can be broken using the backslash character:
@cartouche
@example
parameter = value1,\
            value2,\
            value3
@end example
@end cartouche

Comment may be included, in either scripting format:
@cartouche
@example
# This is a comment
@end example
@end cartouche
C format:
@cartouche
@example
/* This is a comment
*/
@end example
@end cartouche
or C++ format:
@cartouche
@example
// This is a comment
@end example
@end cartouche
Command line and file options may be combined:
@cartouche
@example
@{program@} param=option_file parameterX=valueX
@end example
@end cartouche
In case @command{parameterX} is specified in both option file and
command line, the command line value will be used. This allows to run
the programs several times by changing a single option, like the name
of the data set for instance.

Option files can be nested, by using @command{param=nestedoptionfile}
within an option file, as with the command line. It is possible to use
this option as often as needed, this will load all the required option
files.

@section Different types of options

The next chapters describe the whole set of options available in BppSuite.
For each parameter, the type of parameter value expected is defined as:
@table @command
@item @{chars@}
A character chain

@item @{path@}
A file path, which may be absolute or related to the current directory

@item @{int@}
An integer

@item @{int@}, @{int>0@}, @{int>=0@}, @{int[2,10]@}
An integer, a positive integer, a positive non-null integer, an
integer falling between 2 and 10

@item @{real@}, @{real>0@}, etc
A real number, a positive real number, etc.

@item @{boolean@}
A Boolean value, which may be one of 'yes', 'no', 'true' or 'false'

@item @{xxx|yyy|zzz@}
A set of allowed values

@item @{list<type>@}
A list of values of specified type, separated by comas.

@end table

If an option availability or choice depends on another parameters, it will be noted as

@example
parameter1=@{xxx|yyy|zzz@}

parameter2=@{chars@} [[parameter1=zzz]]
@end example
meaning that parameter2 is available only if parameter1 is set to 'zzz'.

Any optional argument will be noted within hooks [].

In some cases, the argument value is more complexe and follows the 'keyval'
syntax.
This syntax will be quite familiar for users using languages like R, Python, or
certain LaTeX packages.
A keyval procedure is a name that does no contain any space, together with some
arguments within parentheses.
The arguments take the form @command{key=value}, separated by comas:
@cartouche
@example
parameter=Function(name1=value1, name2=value2)
@end example
@end cartouche
Space characters are allowed around the '=' and ',' ponctuations.

@section Variables

It is possible to recall anywhere the value of an option by using $(parameter).
@cartouche
@example
topo.algo = NNI
topo.algo_nni.method = phyml
output.tree.file = MyData_$(topo.algo)_$(topo.algo_nni.method).dnd
@end example
@end cartouche
You can use this syntax to define global variables:
@cartouche
@example
data=MyData
input.sequence.file=$(data).fasta
input.tree.file=$(data).dnd
output.infos=$(data).infos
@end example
@end cartouche

Important note: it is not possible to use a macro with the 'param' option.
This is because all nested option files are parsed before the variable resolution.
Writing @command{param=$(model1).bpp} will not work, but this allows the user to override variables in nested files, as with the command line.
For instance:
@cartouche
@example
#Option file 1:
param=options2.bpp
input.sequence.file=$(data).fasta
input.sequence.format=Fasta
@end example
@end cartouche
@cartouche
@example
#Option file 2:
data=LSU
#etc
@end example
@end cartouche
 
@c ------------------------------------------------------------------------------------------------------------------

@node Common, Reference, Syntax, Top
@chapter Common options encountered in several programs.

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

@menu
* Alphabet::                    Alphabets and genetic codes.
* Sequences::                   Loading sequences/alignments.
* Tree::                        Loading trees.
* AlphabetIndex::               Setting biochemical properties and distances. 
* Process::
* Distribution::                Setting of the discrete distributions.
* Estimation::                  Estimating parameters by maximizing a likelihood function.
* WritingSequences::            Writing sequences/alignments to files. 
* WritingTrees::                Writing trees to files. 
@end menu

@node Alphabet, Sequences, Common, Common
@section Setting alphabet and genetic code

@table @command
@item alphabet = @{DNA|RNA|Protein|Binary|Word(letter=@{DNA|RNA|Protein@},length=@{int@})|
Codon(letter=@{DNA|RNA@})@}

The alphabet to use when reading sequences. DNA and RNA alphabet can in addition take an argument:

@table @command
@item bangAsgap=@{bool@}
Tell is exclamation mark should be considered as a gap character. The default is to consider it as an unknown character such as 'N' or '?'.
@end table

@item genetic_code = @{translation table@}
The genetic code used for codon alphabet, where 'translation table'
specifies the code to use, either as a text description, or as the
NCBI number. The following table give the currently implemented codes
with their corresponding names:

@multitable @columnfractions 0.5 0.5
@item Standard @tab 1
@item VertebrateMitochondrial @tab 2
@item YeastMitochondrial @tab 3
@item MoldMitochondrial @tab 4
@item InvertebrateMitochondrial @tab 5
@item EchinodermMitochondrial @tab 9
@item AscidianMitochondrial @tab 13
@end multitable

@end table

The states of the alphabets are in alphabetical order. For the proteic
alphabet, the amino-acid are in the order of their 3-letters code
(ALA, ARG, ASN, ...).

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

@node Sequences, Tree, Alphabet, Common
@section Reading sequences

@table @command
@item input.sequence.file=@{path@}
The sequence file to use. Depending on the program, these sequences have or do not have to be aligned.

@item input.sequence.format = @{sequence format description@}
The sequence file format.

@item input.site.selection = @{list of integers@}
Will only consider sites in the given list of positions, in extended
format : positions separated with ",", and "i-j" for all positions
between i and j, included.

@item input.site.selection = @{Sample(n=@{integer@} [, replace=@{true@}])@}
Will consider @{n@} random sites, with optional replacement.

@end table
Since Bio++ Program Suite version 0.4.0, the format description uses
the keyval syntax. The format is a function, with optional parameters:

@table @command

@item Fasta(extended=@{bool@}, strictNames=@{bool@})
The fasta format.
The argument @command{extended}, default to 'no', allows to enable the
HUPO-PSI extension of the format.
The argument @command{strict_names}, default to 'no', specifies that
only the first word in the fasta header is used as a sequence names,
the rest of the header being considered as comments.

@item Mase(siteSelection=@{chars@})
The Mase format (as read by Seaview and Phylo_win for instance), with
an optional site selection name.

@item Phylip(order=@{interleaved|sequential@}, type=@{classic|extended@}, split=@{spaces|tab@})                          

The Phylip format, with several variations. The argument
@command{order} distinguishes between sequential and interleaved
format, while the option @command{type} distinguished between the
plain old Phylip format and the more recent extension allowing for
sequence names longer than 10 characters, as understood by PAML and
PhyML. Finally, the @command{split} argument specifies the type of
character that separates the sequence name from the sequence content.
The conventional option is to use one (classic) or more (extended)
spaces, but tabs can also be used instead.

@item Clustal(extraSpaces=@{int@})
The Clustal format. 
In its basic set up, sequence names do not have space characters, and
one space splits the sequence content from its name. The parser can
however be configured to allow for spaces in the sequence names,
providing a minimum number of space characters is used to split the
content from the name. Setting @command{extraSpaces} to 5 for
instance, the sequences are expected to be at least 6 spaces away for
their names.

@item Dcse()
The DCSE alignment format. The secondary structure annotation will be
ignored.

@item Nexus()
The Nexus alignment format. Only very basic support is provided.

@end table

For programs that do not require the sequences to be aligned, the
following formats are also available:
@table @command

@item GenBank()
Very basic support: only retrieves the sequence content for now, all
features are ignored.

@end table

Basic operations can be performed on the sequences:

@table @command

@item input.sequence.sites_to_use = @{all|nogap|complete@}
This option only works if the program requires an alignment.
Tells which sites to use.
The @option{nogap} option removes all sites containing at least one
gap, and the @option{complete} option removes all sites containing at
least one gap or one generic character, as 'X' for instance.

@item input.sequence.remove_stop_codons = @{boolean@}
This option only works if the alphabet is a codon alphabet. Removes
the sites where there is a stop codon (default: 'yes').

@item input.sequence.max_gap_allowed=100%
This option only works if the program requires an alignment.
Only works when the @option{all} option is selected.
It specifies the maximum amount of gap allowed per site, as a number
of sequence or a percentage.
Sites not matching the criterion will not be included in the analysis, but the
original site numbering will be used in the output files (if relevant).

@item input.sequence.max_unresolved_allowed=100%
This option only works if the program requires an alignment. Only
works when the @option{all} option is selected. It specifies the
maximum amount of unresolved states per site, as a number of sequence
or a percentage. Sites not matching the criterion will not be included
in the analysis, but the original site numbering will be used in the
output files (if relevant).

@end table
 
@c ------------------------------------------------------------------------------------------------------------------

@node Tree, AlphabetIndex, Sequences, Common
@section Reading trees

@table @command
@item input.tree.file = @{path@}
The phylogenetic tree file to use.

@item input.tree.format = @{Newick|Nexus|NHX@}
The format of the input tree file.

@end table

In case the input tree does not specify node identifiers, some will be
generated automatically. Nodes identifiers can be outputed using the
following option:
@table @command
@item output.tree_ids.file = @{@{path@}|none@}
A tree file in newick format, with node ids instead of bootstrap
values, and leaf names with their id as suffix.
@end table
In case it is supported by the program, the use of that option will
cause the program to exit just after producing the tagged tree.

Some programs may require that your file contains several trees. The
corresponding options are then:

@table @command
@item input.trees.file = @{path@}
The file containing multiple trees.

@item input.trees.format = @{Newick|Nexus|NHX@}
The format of the input tree file.

@end table

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

@node AlphabetIndex, Process, Tree, Common
@section Specifying biochemical properties and distances

Some methods require an "alphabet index" to be specified. Alphabet
indexes associate a value with each alphabet state (Index1, e.g. a
biochemical property) or for a pair of states (Index2, e.g. a
biochemical distance). This section describes the supported indexes:

@subsection Index1

@table @command
@item None
If no index should be used.
@item Surface, Mass, Volume, Charge @{AA@}
Basic amino acids properties.
@item GranthamPolarity, GranthamVolume @{AA@}
Grantham's polarity and volume index.
@item KleinCharge @{AA@}
Klein's charge.
@item ChouFasmanAHelix, ChouFasmanBSheet, ChouFasmanTurn @{AA@}
Chou and Fasmani score for secondary structure prediction. 
@item ChenGuHuangHydrophobicity @{AA@}
Hydrophobicity according to Chen, Gu and Huang.
@item SEALow, SEAMedium, SEAHigh @{AA@}
Solvent Exposed Area, percent of amino acids having a SEA below 10,
between 10 and 30, or higher than 30, respectively.
@item User
A user defined Index1, from a file in the AAIndex1 syntax. The input
file is specified using the @command{file=@{path@}} argument.
@command{file}

@end table


@subsection Index2

@table @command
@item None
If no index should be used.
@item Blosum50 @{AA@}
The BLOSUM 50 amino acid distance matrix.
@item Grantham, Miyata @{AA@}
Two biochemical distance matrices. Both accept an optional argument
@command{symmetrical=@{boolean@}} allowing to specify if the matrix
should be symmetric or not. If not, the distance measure will be
signed.
@item Diff
Allow to compute a distance matrix by taking the difference for, each
pair of state, of an Index1 value. The Index1 to use is specified
using the @command{index1=@{Index1 description@}} argument. An
additional argument allow to specify whether the resulting matrix
should be symetric (@command{symmetrical=@{boolean@}}): if so, the
absolute difference will be used. Alternatively, the distance will be
signed and d[i,j] = - d[j,i].
@item User
A user defined Index2, from a file in the AAIndex2 syntax. The input
file is specified using the @command{file=@{path@}} argument. The
@command{symmetrical=@{boolean@}} argument can be used to specify
whether distances should be signed or not.
@end table


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


@node Process, Distribution, AlphabetIndex, Common
@section Process specification

@menu
* Model::
* Non-homogeneity::             Specific declaration of non-homogeneous modelling.
* FrequenciesSet::              Frequencies 
* Rates::                       Rates across sites
* Linking::
@end menu

The substitution model specification over the tree is set up in different parts.
@table @command
@item nonhomogeneous = @{no|one_per_branch|general@}
Set the type of model. The @option{no} option is used for homogeneous
models. The @option{one_per_branch} option is used as a short cut for
setting branch models (for instance Galtier and Gouy 97 for branch GC
content, or PAML branch model), and the @option{general} option for
the more general case, including PAML clade models. In either of the
last two cases, the model is potentially non-stationary, that is,
possibly not at the equilibrium and hence includes the root
frequencies as additional parameters. If the substitution model is not
the same across the tree, then the model is also non-homogeneous.
@end table

In combination with those models, one can also specify a distribution
of site-specific rate.

@node Model, Non-homogeneity, Process, Process
@subsection Setting up the substitution model

@menu
* Nucleotide::                  Nucleotide models
* Protein::                     Protein models
* Miscellaneous::               Miscellaneous models
* Codon::                       Codon models
* Multiple::                    General multiple site models
* Meta::                        Meta models
* Mixture::                     Mixture of models
* Conditioned::                 Models conditioned by events
@end menu

@table @command

@item model = @{model description@}
A description of the substitution model to use, using the keyval syntax.

@end table
From version 0.4.0 of BppSuite, the model specification uses a
completely new syntax, based on the keyval (key = value) scheme. The
old option files will hence not be compatible with new version of the
software. The new syntax however is hopefully more intuitive, and more
generalizable, so that few changes are expected when new models will
be built. The substitution model is a function, potentially including
parameters. The following table lists the set of usable functions, and
their parameters.

Many models have a set of optional parameters denoted here as
"equilibrium frequencies" that are used to initialize the parameters
of the model related with the equilibrium frequencies. These options
are:

@table @command

@item initFreqs=values(@{real]0,1[@},...,@{real]0,1[@})
The equilibrium frequency is set equal (as much as possible) to the
given frequencies. Those frequencies are given in the same order as
the alphabet, and they must sum 1.

@item initFreqs=observed 
The equilibrium frequency is set equal (as much as possible) to the
observed frequencies.

@item initFreqs.observedPseudoCount=@{integer@}
a peusocount integer added to all counts of letters (or words), when
the frequencies are computed from observed data.

@end table

@node Nucleotide, Protein, Model, Model
@subsubsection Nucleotide models

@table @command

@item JC69
The Jukes and Cantor model. This model has no additional parameter.
See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1JCnuc.html#details, Bio++ description, Bio++ description}.

@item K80([kappa=@{real>0@}])
The Kimura 2 parameters model. @var{kappa} is the transition over
transversion ratio. Default: @var{kappa}=1. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1K80.html#details, Bio++ description, Bio++ description}.


@item F84([kappa=@{real>0@}, theta=@{real]0,1[@}, theta1=@{real]0,1[@},theta2=@{real]0,1[@}, "equilibrium frequencies"] )
Felsenstein's 1984 substitution model, with transition/transversion
ratio and 4 distinct equilibrium frequencies, set using three
independent parameters: @var{theta} is the GC content, @var{theta1} is
the proportion of G / (G + C) and @var{theta2} is the proportion of A
/ (A + T or U). See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1F84.html#details, Bio++ description, Bio++ description}.


@item HKY85([kappa=@{real>0@}, theta=@{real]0,1[@}, theta1=@{real]0,1[@}, theta2=@{real]0,1[@}, "equilibrium frequencies"])
Hasegawa, Kishino and Yano 1985's substitution model. The model is
similar to @command{F84}, but with a different implementation. The
@var{kappa} parameter used here is comparable to the one in
@command{K80}. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1HKY85.html#details, Bio++ description, Bio++ description}.


@item T92([kappa=@{real>0@}, theta=@{real]0,1[@} ,"equilibrium frequencies"])
Tamura 1992's model for nucleotides, similar to @command{HKY85}, yet
assuming that the frequencies of A = T/U and G = C. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1T92.html#details, Bio++ description, Bio++ description}.

@item TN93([kappa1=@{real>0@}, kappa2=@{real>0@}, theta=@{real]0,1[@}, theta1=@{real]0,1[@}, theta2=@{real]0,1[@}, "equilibrium frequencies"])
Tamura and Nei 1993's model, similar to @command{HKY85}, but allowing
for two distinct transition/transversion ratios. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1TN93.html#details, Bio++ description, Bio++ description}.


@item GTR([a=@{real>0@}, b=@{real>0@}, c=@{real>0@}, d=@{real>0@}, e=@{real>0@}, theta=@{real]0,1[@}, theta1=@{real]0,1[@}, theta2=@{real]0,1[@} ,"equilibrium frequencies"])
The General Time-Reversible substitution model. Parameters @var{a},
@var{b}, @var{c}, @var{d}, @var{e} are the entries of the
exchangeability matrix. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1GTR.html#details, Bio++ description, Bio++ description}.


@item L95([beta=@{real>0@}, gamma=@{real>0@}, delta=@{real>0@}, theta=@{real]0,1[@}, theta1=@{real]0,1[@}, theta2=@{real]0,1[@} ,"equilibrium frequencies"])
The strand-symmetric model of Lobry 1995, for nucleotides. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1L95.html#details, Bio++ description, Bio++ description}.

@item SSR([beta=@{real>0@}, gamma=@{real>0@}, delta=@{real>0@}, theta=@{real]0,1[@}])
The strand-symmetric reversible model, for nucleotides. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1SSR.html#details, Bio++ description, Bio++ description}.

@item RN95([thetaR=@{real]0,1[@}, thetaC=@{real]0,1[@}, thetaG=@{real]0,1[@}, kappaP=@{real[0,1[@}, gammaP=@{real[0,1[@}, sigmaP=@{real>1@}, alphaP=@{real>1@}])
The model described by Rhetsky and Nei, where the only hypothesis is
that the transversion rates are only dependent of the target
nucleotide. This model is not reversible. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1RN95.html#details,Bio++
description, Bio++ description}.

@item RN95s([thetaA=@{real]0,0.5[@}, gamma=@{real]0,0.5[@}, alphaP=@{real>1@}]) 
The instersection of models RN95 and L95. The two hypotheses are that
the transversion rates are only dependent of the target nucleotide,
and strand symmetry. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1RN95s.html#details,Bio++
description, Bio++ description}.

@end table

@node Protein, Miscellaneous, Nucleotide, Model
@subsubsection Protein models

@table @command

@item JC69
The Jukes and Cantor model. This model has no additional parameter. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1JCprot.html#details, Bio++ description, Bio++ description}.


@item DSO78
Protein substitution model, using the dcmutt implementation of Kosiol
and Goldman 2005. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1DSO78.html#details, Bio++ description, Bio++ description}.


@item JTT92
Protein substitution model, using the dcmutt implementation of Kosiol
and Goldman 2005. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1JTT92.html#details, Bio++ description, Bio++ description}.


@item WAG01
Protein substitution model, from Whelan & Goldman 2001. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1WAG01.html#details, Bio++ description, Bio++ description}.


@item LG08
Protein substitution model, from Le & Gascuel 2008. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1LG08.html#details, Bio++ description, Bio++ description}.


@item LLG08_EX2([relrate1=@{real]0,1[@}, relproba1=@{real]0,1[@}])
Protein substitution model, from Le, Lartillot & Gascuel 2008.
@xref{Mixture}, for the meaning of the variables. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1LLG08__EX2.html#details,
Bio++ description, Bio++ description}.


@item LLG08_EX3([relrate1=@{real]0,1[@}, relrate2=@{real]0,1[@}, relproba1=@{real]0,1[@}, relproba2=@{real]0,1[@}])
Protein substitution model, from Le, Lartillot & Gascuel 2008. @xref{Mixture}, for the meaning of the variables. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1LLG08__EX3.html#details, Bio++ description, Bio++ description}.


@item LLG08_EHO([relrate1=@{real]0,1[@}, relrate2=@{real]0,1[@}, relproba1=@{real]0,1[@}, relproba2=@{real]0,1[@}])
Protein substitution model, from Le, Lartillot & Gascuel 2008. @xref{Mixture}, for the meaning of the variables. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1LLG08__EHO.html#details, Bio++ description, Bio++ description}.


@item LLG08_UL2([relrate1=@{real]0,1[@}, relproba1=@{real]0,1[@}])
Protein substitution model, from Le, Lartillot & Gascuel 2008. @xref{Mixture}, for the meaning of the variables. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1LLG08__UL2.html#details, Bio++ description, Bio++ description}.


@item LLG08_UL3([relrate1=@{real]0,1[@}, relrate2=@{real]0,1[@}, relproba1=@{real]0,1[@}, relproba2=@{real]0,1[@}])
Protein substitution model, from Le, Lartillot & Gascuel 2008. @xref{Mixture}, for the meaning of the variables. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1LLG08__UL3.html#details, Bio++ description, Bio++ description}.

@item LGL08_CAT(nbCat=@{[10,20,30,40,50,60]@}, [relrate1=@{real]0,1[@}, relrate2=@{real]0,1[@}, ..., relproba1=@{real]0,1[@}, relproba2=@{real]0,1[@}, ...] ))
CAT protein substitution model, from Le, Gascuel & Lartillot 2008, with a
given number (@var{nbCat}) of profiles. @xref{Mixture}, for the meaning
of the variables. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1LGL08__CAT.html#details,
Bio++ description, Bio++ description}.

@item LGL08_CAT_C@{[1,...,nbCat]@}(nbCat=@{[10,20,30,40,50,60]@})
Submodel of a given CAT Protein substitution model, from Le, Gascuel &
Lartillot 2008, with a given number (@var{nbCat}) of profiles. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1LGL08__CAT.html#details,
Bio++ description, Bio++ description}.

@item DSO78+F([theta=@{real]0,1[@}, theta1=@{real]0,1[@}, theta2=@{real]0,1[@}, ... ,"equilibrium frequencies"])
Protein substitution model, using the dcmutt implementation of Kosiol
and Goldman 2005 and free equilibrium frequencies. The @var{thetaX}
are frequencies parameters, where X is 1 to 19. Parameter @var{theta1}
is the proportion of A, @var{theta2} is the proportion of R over
(1-A), @var{theta3} the proportion of N over (1-A-R), etc. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1DSO78.html#details, Bio++ description, Bio++ description}.


@item JTT92+F([theta=@{real]0,1[@}, theta1=@{real]0,1[@}, theta2=@{real]0,1[@}, ..., "equilibrium frequencies"])
Protein substitution model, using the dcmutt implementation of Kosiol
and Goldman 2005 and free equilibrium frequencies. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1JTT92.html#details, Bio++ description, Bio++ description}.


@item WAG01+F([theta=@{real]0,1[@}, theta1=@{real]0,1[@}, theta2=@{real]0,1[@}, ..., "equilibrium frequencies"])
Protein substitution model, from Whelan & Goldman 2001, and free
equilibrium frequencies. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1WAG01.html#details, Bio++ description, Bio++ description}.


@item LG08+F([theta=@{real]0,1[@}, theta1=@{real]0,1[@}, theta2=@{real]0,1[@}, ..., "equilibrium frequencies"])
Protein substitution model, from Le & Gascuel 2008, and free
equilibrium frequencies. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1LG08.html#details, Bio++ description, Bio++ description}.


@item Empirical(name=@{chars@}, file=@{path@})
Build a protein substitution model from a file in PAML format, and use
'name' as a namespace for parameters.

@item Empirical+F(name=@{chars@}, file=@{path@}, [theta=@{real]0,1[@}, theta1=@{real]0,1[@}, theta2=@{real]0,1[@}, ..., "equilibrium frequencies"])
Build a protein substitution model from a file in PAML format, and use
free equilibrium frequencies. 'name' will be used as a parameter
namespace, including for frequencies.

@end table

@node Miscellaneous, Codon, Protein, Model
@subsubsection Miscellaneous models

@table @command
@item Binary([kappa=@{real>0@} ,"equilibrium frequencies"])
Build the model on binary alphabet, where @var{kappa} is the relative
proportion of 1 over 0 in the equilibrium distribution. Default:
@var{kappa}=1. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1BinarySubstitutionModel.html#details, Bio++ description, Bio++ description}.


@end table

@node Codon, Multiple, Miscellaneous, Model
@subsubsection Codon models

Some codon models also take as argument a @var{frequencies} option
specifying the equilibrium frequencies of the model. Any frequencies
description can be used here, but the syntax also supports options
similar to the ones used in the PAML software:

@itemize
@item F0: all frequencies are assumed to be fixed and equal to 1/61, 0 for stop codons.
@item F1X4: 4 distinct frequencies are used, with parameters theta, theta1, theta2 (@xref{Frequencies sets}, ``Full'' method).
@item F3X4: 4 distinct frequencies are used for each position, resulting in 9 parameters in total (3 independent ``Full'' frequencies set).
@item F61: free equilibrium frequencies, stop codons set to 0.
@end itemize

An optional option @var{mgmtStopCodon} can be set to define how the
frequencies computed to stop codons in the case of F1X4 et F3X4 are
distributed to other codons.

@itemize
@item uniform : each stop frequency is distributed evenly
@item linear : each stop frequency is distributed to the neighbour
codons (ie 1 substitution away), in proportion to each target codon
frequency.
@item quadratic (default): each stop frequency is distributed to the
neighbour codons (ie 1 substitution away), in proportion to the square
of each target codon frequency.
@end itemize

The same words can be used to specify root frequencies for codon
models, in the case of non stationarity.

@table @command

@item GY94([kappa=@{real>0@}, V=@{real>0@}, "equilibrium frequencies"])
Goldman and Yang (1994) substitution model for codons (default values:
@var{kappa}=1 and @var{V}=10000). See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1GY94.html#details, Bio++ description, Bio++ description}.


@item MG94([rho=@{real>0@}, "equilibrium frequencies"])
Muse and Gaut (1994) substitution model for codons (default values:
@var{rho}=1). See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1MG94.html#details, Bio++ description, Bio++ description}.


@item YN98([kappa=@{real>0@}, omega=@{real>0@}, "equilibrium frequencies"])
Yang and Nielsen (1998) substitution model for codons (default values:
@var{kappa}=1 and @var{omega}=1). See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1YN98.html#details, Bio++ description, Bio++ description}.


@item YNGP_M0([kappa=@{real>0@}, omega=@{real>0@}, "equilibrium frequencies"])
The M0 model of PAML, ie the same as YN98. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1YN98.html#details, Bio++ description, Bio++ description}.


@item YNGP_M1([kappa=@{real>0@}, omega=@{real>0@}, p0=@{real>0 and <1 @}, "equilibrium frequencies"])
The M1a model of PAML, see Yang, Z., R. Nielsen, N. Goldman, and A.-M.
K. Pedersen (2000) (default values: @var{kappa}=1, @var{p0}=0.5,
@var{omega}=0.5). See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1YNGP__M1.html#details, Bio++ description, Bio++ description}.


@item YNGP_M2([kappa=@{real>0@}, omega0=@{real>0 and <1@}, theta1=@{real>0 and <1 @}],  omega1=@{real>1@},  theta2=@{real>0 and <1 @}, "equilibrium frequencies"])

The M2a model of PAML, see Yang, Z., R. Nielsen, N. Goldman, and A.-M.
K. Pedersen (2000), with  p0=theta1  and
p1=(1-theta1)*theta2 (default values: @var{kappa}=1, @var{theta1}=0.33333,
@var{theta2}=0.5, @var{omega0}=0.5, @var{omega2}=0.5). See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1YNGP__M2.html#details, Bio++ description, Bio++ description}.
  

@item YNGP_M3([n=@{integer>0@}, kappa=@{real>0@}, omega0=@{real>0 and <1@}, delta1=@{real>0@}, ..., delta@var{n-1}=@{real>0@}, theta1=@{real>0 and <1 @}, ..., theta@var{n-1}1=@{real>0 and <1 @}, "equilibrium frequencies"])

The M3 model of PAML, see Yang, Z., R. Nielsen, N. Goldman, and A.-M.
K. Pedersen (2000), with @var{n} discrete values, with p0=theta1
and pk=(1-theta1)*...*(1-thetak)*theta(k+1), and
omegak=omega0+delta1+....+deltak (default values: @var{n}=3,
@var{kappa}=1, @var{thetak}=1/(n-k+1), @var{omega0}=0.5,
@var{deltak}=0.5). See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1YNGP__M3.html#details, Bio++ description, Bio++ description}.


@item YNGP_M7(n=@{integer>0@}, kappa=@{real>0@}, p=@{real>1@}, q=@{real>1 @}, "equilibrium frequencies"])

The M7 model of PAML, see Yang, Z., R. Nielsen, N. Goldman, and A.-M.
K. Pedersen (2000), with the Beta distribution discretized in @var{n}
classes (default values: @var{kappa}=1, @var{p}=2, @var{q}=2). See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1YNGP__M7.html#details, Bio++ description, Bio++ description}.


@item YNGP_M8(n=@{integer>0@}, [kappa=@{real>0@}, omegas=@{real>1@}, p0=@{real>0@},p=@{real>1@}, q=@{real>1 @}, "equilibrium frequencies"])

The M8 model of PAML, see Yang, Z., R. Nielsen, N. Goldman, and A.-M.
K. Pedersen (2000), with the Beta distribution discretized in @var{n}
classes (default values: @var{kappa}=1, @var{p}=2, @var{q}=2,
@var{p0}=0.5, @var{omegas}=2). See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1YNGP__M8.html#details, Bio++ description, Bio++ description}.


@end table

It is also possible to setup more specific models, by specifying a
nucleotide model for each position. Model parameters names then take
the form of <codon model name>.<position set>_<position model
name>.<position specific parameter name>.

In the following models, the arguments @var{model} and
@var{model@{i@}} are for descriptions of models on bases.

@itemize
@item If the argument is @var{model}, the @emph{same} single site model is
used on all positions (ie the parameters are shared between all
positions).
@item If the arguments are @var{model1}, @var{model2}, @var{model3}, each
single site model stands for a single-site substitution model. In that
case, all single site models parameters are position dependent.
@end itemize

Each single site model is normalized and the substitution rates
between codons that differ on more than one letter are null.

The generator is first computed with these models and parameters on
the whole triplet alphabet, and then the substitution rates to and
from stop codons are set to zero and the generator is normalized with
this modification.

The model names est defined through several words that can be mixed
together to build models at hand. Some words are exclusive. The
model description must begin with @var{Codon}.


@var{Rate} and @var{Prot} and @var{Dist} words define how the models
are mixed, either with specific rates, or using proteic models, or
with non-synonymous vs synonymous substitution rates. They are
exclusive, and one of the three must be used. The default model is
@var{Rate}.

@table @command
@item Rate(model... [, relrate1=@{real>0@}, relrate2=@{real>0@}]) 


Substitution model on codons with position specific evolution rates.

Arguments @var{relrate@{i@}} stands for the relative substitution rates
of the sites. Default: @var{relrate@{i@}=1/@{4-i@}}, such that the rate
of each site is 1/3.

@cartouche
@example
alphabet=Codon(letter=DNA)
genetic_code=Standard
model=CodonRate(model=T92)
@end example
@end cartouche

builds a model on codons, such all sites follow the same T92 model.
The parameters names are @var{CodonRate.123_T92.kappa},
@var{CodonRate.relrate1}, @var{CodonRate.relrate2}.

@cartouche
@example
alphabet=Codon(letter=DNA)
genetic_code=Standard
model=CodonRate(model1=T92, model2=T92, model3=JC69)
@end example
@end cartouche

builds a model on codons, such that first and second sites follow
independent T92 models, and third site follows a JC69 model. Then the
parameters names are @var{CodonRate.1_T92.kappa},
@var{CodonRate.2_T92.kappa}, @var{CodonRate.relrate1},
@var{CodonRate.relrate2}, and can be initialized as is:

@cartouche
@example
model=CodonRate(model1=T92(theta=0.5, kappa=2), \
                model2=T92(theta=0.4, kappa=2), model3=JC69)
@end example
@end cartouche

See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1CodonRateSubstitutionModel.html#details, Bio++ description, Bio++ description}.


@item Dist(model...[, beta=@{real>0@}])

Substitution model on codons that takes into account the difference
between synonymous and non-synonymous substitutions.

Optional argument @var{beta} is the ratio between non-synonymous
substitution rate and synonymous substitution rate. Default value: 1.

@cartouche
@example
alphabet=Codon(letter=DNA)
model=CodonDist(model=T92)
@end example
@end cartouche

builds a model on codons, such all sites follow the same T92 model.
The parameters names are @var{CodonDist.123_T92.kappa} and 
@var{CodonDist.beta}.

@cartouche 
@example
alphabet=Codon(letter=DNA, type=Standard)
model=CodonDist(model1=T92, model2=T92, model3=JC69)
@end example
@end cartouche

builds a model on codons, such that first and second sites follow
independent T92 models, and third site follows a JC69 model. Then the
parameters names are @var{CodonDist.1_T92.kappa},
@var{CodonDist.2_T92.kappa}, @var{CodonDist.beta}.

See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1CodonDistanceSubstitutionModel.html#details, Bio++ description, Bio++ description}.


@item Prot(model..., protmodel=@{proteic model name@}[, beta=@{real>0@}])

Substitution model on codons that takes into account the substitution
rates in a protein model. Those rates are multiplied by a
non-synonymous susbtitution factor, aka @var{beta}.

@var{Prot} and @var{Dist} words are exclusive.


Optional argument @var{beta} is the ratio between average substitution
rate between amino-acids and synonymous substitution rate. Default
value: 1.

@cartouche
@example
alphabet=Codon(letter=DNA)
genetic_code=Standard
model=CodonProt(model=T92, protmodel=LG08)
@end example
@end cartouche

builds a model on codons, such all sites follow the same T92 model,
and amino-acid rates are proportional to LG08 substition matrice.
The parameters names are @var{CodonProt.123_T92.kappa} and 
@var{CodonProt.beta}.

@end table

Optional words to describe the use of equilibrium frequencies
sets. This word should be used with nucleotidic models which
equilibrium distribution is fixed, ans does not depend on parameters.
Otherwise there may be problems of identifiability of the parameters.

@table @command
@item Freq(frequencies=@{frequencies set description@})

Sustitution rates are multiplied by the frequency of the target codon
in the given frequencies set. This factor is described by the
@var{frequencies} argument. See the description of the Frequencies Set
below.


@cartouche
@example
alphabet=Codon(letter=DNA)
genetic_code=Standard
model=CodonDistFreq(frequencies=Full())
@end example
@end cartouche

has parameters @var{CodonDistFreq.012_T92.kappa},
@var{CodonDistFreq.Full.theta_1}, ...,
@var{CodonDistFreq.Full.theta_60},
@var{CodonDistFreq.beta}.

See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1CodonDistanceFrequenciesSubstitutionModel.html#details, Bio++ description, Bio++ description}.

@item PhasFreq(frequencies=@{frequencies set description@})

The sustitution rates are multiplied by the product of the frequencies
of the changed nucleotides -- conditioned on the phase -- in the given
frequencies set. This factor is described by the @var{frequencies}
argument. See the description of the Frequencies Set below.


For example, see the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1CodonDistancePhaseFrequenciesSubstitutionModel.html#details, Bio++ description, Bio++ description}.

@end table



In addition some models are defined that allow multiple substitions,
with similar logic of included words. These models are prefixed by @var{Kron}.


@table @command

@item KronDistFreq(model=@{model name@} [,positions=pos1*pos2*...*posn + posx*...*posm + ...)])

@item KronDistFreq(model1=@{model name@}, model1=@{model name@}, ..., modeln=@{model name@}[,positions=pos1*pos2*...*posn + posx*...*posm + ...])

substitution model on codons as @var{CodonDistFreq} above, allowing
simultaneous substitutions.

Optional argument @var{positions} can be used to describe which
substitutions are allowed. See model @xref{Kron}.

@item KronDist(model=@{model name@} [,positions=pos1*pos2*...*posn + posx*...*posm + ...)])

@item KronDist(model1=@{model name@}, model1=@{model name@}, ..., modeln=@{model name@}[,positions=pos1*pos2*...*posn + posx*...*posm + ...])

substitution model on codons as @var{CodonDist} above, allowing
simultaneous substitutions.

Optional argument @var{positions} can be used to describe which
substitutions are allowed. See model @xref{Kron}.

@item KCM7() and  KCM19() 

Kronecker Codon Model based on a unique (KCM7) or one per position
(KCM19) GTR model. From Zaheri \& al, MBE, 2014.

See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1KCM.html#details, Bio++ description, Bio++ description}.



@end table


@node Multiple, Meta, Codon, Model
@subsubsection General multiple site models

@table @command

@item Word(model=@{model name@} [,relrate1=@{1>real>0@}, ..., relrate@{n-1@}=@{1>real>0@}]) 
or 
@item Word(model1=@{model name@}, model1=@{model name@}, ..., modeln=@{model name@}[, relrate1=@{1> real>0@}, ..., relrate@{n-1@}=@{1> real>0@}])

substitution model on words. The arguments @var{model} and
@var{model@{i@}} are for descriptions of models on single sites such
as nucleotides or proteins. The alphabet must be a Word alphabet.

If the argument is @var{model}, the length of the words in the
substitution model is determined by the length of the words in the
alphabet, and the @emph{same} single site model is used (ie the
parameters are shared between all positions).

If the arguments are @var{model1}, ..., @var{model@{n@}}, the length
of the words in the alphabet must be @var{n}, and each single site
model stands for a single-site substitution model. In that case, all
single site models parameters are position dependent.

Each single site model is normalized and the substitution rates
between words that differ on more than one letter are null.

Arguments @var{relrate@{i@}} stands for the relative substitution rates
of the sites. Default: @var{relrate@{i@}=1/@{n-i+1@}}, such that the rate
of each site is 1/n.

@cartouche
@example
alphabet=Word(letter=DNA,length=4)
model=Word(model=T92())
@end example
@end cartouche

builds a model on 4 bases words, such all sites follow the same T92
model. The parameters names are @var{Word.1234_T92.kappa},
@var{Word.relrate1}, @var{Word.relrate2}, @var{Word.relrate3}.

@cartouche
@example
alphabet=Word(letter=DNA,length=4)
model=Word(model1=T92(), model2=T92(), model3=JC69(), \
           model4=HKY85())
@end example
@end cartouche

builds a model on 4 bases words, such first and second sites follow
independent T92 models, third site follows a JC69 model, and fourth
site follows a HKY85 model. Then the parameters names are
@var{Word.1_T92.kappa}, @var{Word.2_T92.kappa},
@var{Word.4_HKY85.kappa}, @var{Word.4_HKY85.theta},
@var{Word.4_HKY85.theta1}, @var{Word.4_HKY85.theta2},
@var{Word.relrate1}, @var{Word.relrate2}, @var{Word.relrate3}.

See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1WordSubstitutionModel.html#details, Bio++ description, Bio++ description}.

@item Kron(model=@{model name@} [,positions=pos1*pos2*...*posn + posx*...*posm + ...)])
@anchor{Kron}

@item Kron(model1=@{model name@}, model1=@{model name@}, ..., modeln=@{model name@}[,positions=pos1*pos2*...*posn + posx*...*posm + ...])

substitution model on words, allowing simultaneous substitutions. The
arguments @var{model} and @var{model@{i@}} are for descriptions of
models on single sites such as nucleotides or proteins. The alphabet
must be a Word alphabet.

If the argument is @var{model}, the length of the words in the
substitution model is determined by the length of the words in the
alphabet, and the @emph{same} single site model is used (ie the
parameters are shared between all positions).

If the arguments are @var{model1}, ..., @var{model@{n@}}, the length
of the words in the alphabet must be @var{n}, and each single site
model stands for a single-site substitution model. In that case, all
single site models parameters are position dependent.

The rate of a multiple substitution is the product of the rates of the
single substitutions it is made of.

Without optional argument @var{positions}, all single and multiple
substitutions are allowed.

Optional argument @var{positions} describes the allowed substitutions.
It is written as a formula with positions between 1 and the length of
the word, and symbols '*' (to link positions that must change
together) and '+' (to link sets of multiple susbtitutions that are
allowed).

As examples, on a DNA word with 3 positions:

@cartouche
@example
model=Kron(model=K80(), positions=1*2*3)
@end example
@end cartouche
allows only substitutions that change the 3 positions.

@cartouche
@example
model=Kron(model=K80(), positions=1*2+3)
@end example
@end cartouche
allows only substitutions that change the positions 1 and 2, and the
ones that change position 3 alone.

@cartouche
@example
model=Kron(model=K80(), positions=1*2+2*3)
@end example
@end cartouche
allows only substitutions that change two neighbor positions.

@cartouche
@example
model=Kron(model=K80(), positions=1+2+3)
@end example
@end cartouche
allows only substitutions that change one position, i.e. @var{Word}
model.


See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1KronSubstitutionModel.html#details, Bio++ description, Bio++ description}.


@item Triplet(model=@{model description@} [, relrate1=@{real>0@}, relrate2=@{real>0@}]) 
or 
@item Triplet(model1=@{model description@}, model2=@{model description@}, model3=@{model description@}[, relrate1=@{real>0@}, relrate2=@{real>0@}]) 

substitution model on 3 letters words. The arguments @var{model} and
@var{model@{i@}} are for descriptions of models on single sites such as
nucleotides or proteins. The alphabet must be a 3-letters word
alphabet or a codon alphabet.

If the argument is @var{model}, the @emph{same} single site model is
used on all positions (ie the parameters are shared between all
positions).

If the arguments are @var{model1}, @var{model2}, @var{model3}, each
single site model stands for a single-site substitution model. In that
case, all single site models parameters are position dependent.

Each single site model is normalized and the substitution rates
between triplets that differ on more than one letter are null.

Arguments @var{relrate@{i@}} stands for the relative substitution rates
of the sites. Default: @var{relrate@{i@}=1/@{4-i@}}, such that the rate
of each site is 1/3.

@cartouche
@example
alphabet=Codon(letter=DNA)
genetic_code=Standard
model=Triplet(model=T92)
@end example
@end cartouche
builds a model on codons, such all sites follow the same T92 model.
The parameters names are @var{Triplet.123_T92.kappa},
@var{Triplet.relrate1}, @var{Triplet.relrate2}.

@cartouche
@example
alphabet=Word(letter=DNA, length=3)
model=Triplet(model1=T92, model2=T92, model3=JC69)
@end example
@end cartouche
builds a model on 3 bases words, such first and second sites follow
independent T92 models, and third site follows a JC69 model. Then the
parameters names are @var{Triplet.1_T92.kappa},
@var{Triplet.2_T92.kappa}, @var{Triplet.relrate1},
@var{Triplet.relrate2}.

See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1TripletSubstitutionModel.html#details, Bio++ description, Bio++ description}.

@item YpR_Sym(model=@{model description@}, [rCgT=@{real>=0@}, rTgC=@{real>=0@}, rCaT=@{real>=0@}, rTaC=@{real>=0@}])

substitution model on quotiented triplets to handle strand symetric
neighbour-dependency inside dinucleotides YpR (see Bérard and Guéguen
2012). See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1YpR_SymSubstitutionModel.html#details, Bio++ description, Bio++ description}.


@item YpR_Gen(model=@{model description@}, [rCgT=@{real>=0@}, rcGA=@{real>=0@}, rTgC=@{real>=0@}, rtGA=@{real>=0@}, rCaT=@{real>=0@}, rcAG=@{real>=0@}, rTaC=@{real>=0@}, rtAG=@{real>=0@}])

substitution model on quotiented triplets to handle general symetric
neighbour-dependency inside dinucleotides YpR (see Bérard and Guéguen
2012). See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1YpR_GenSubstitutionModel.html#details, Bio++ description, Bio++ description}.


@end table

@node Meta, Mixture, Multiple, Model
@subsubsection Meta models

These substitution models take as argument another substitution model, and add several parameters.
 
@table @command

@item TS98(model=@{model description@}, s1=@{real>0@}, s2=@{real>0@} [, "equilibrium frequencies"])
Tuffley and Steel 1998's 'covarion' model, taking a nested
substitution model as argument for @var{model}. The nested model can
be any substitution model for any alphabet. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1TS98.html#details, Bio++ description, Bio++ description}.


@item G01(model=@{model description@}, rdist=@{rate distribution description@}, mu=@{real>0@} [, "equilibrium frequencies"])
Galtier 2001's 'covarion' model, taking a nested substitution model as
argument for @var{model} and a rate distribution for parameter
@var{rdist} (see below). The nested model can be any substitution
model for any alphabet. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1G01.html#details, Bio++ description, Bio++ description}.


@item RE08(model=@{model description@}, lambda=@{real>0@}, mu=@{real>0@} [, "equilibrium frequencies"])
Rivas and Eddy 2008's substitution model with gaps, taking a nested
substitution model as argument for @var{model}. Parameter @var{lambda}
is the insertion rate, while @var{mu} is the deletion rate. See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1RE08.html#details, Bio++ description, Bio++ description}.


@end table

@node Mixture, Conditioned , Meta, Model
@subsubsection Mixture of models

@table @command

Mixed models are sometimes called "site models".

Mixed models combine substitution models with respective
probabilities. We call submodels all the models that are mixed in the
mixture. A Mixed model is either the mixture of several predefined
models, or based on a "simple" model in which some parameters follow
given distributions.

During the likelihood computation process, all the submodels of the
mixture are successively applied on the branches, and the mean (see
below) of all the likelihoods is computed.

A site can follow given paths all along the tree, with given
probabilities. 

In homogeneous reconstruction, a path corresponds to a same submodel
on all the branches, in a stationary condition. The probability of a
path is the probability of its submodel. Given a site follows a path,
a likelihood can be computed; and the overall likelihood on this site
is the mean of these likelihoods (given the probabilities of the
paths). This means that the root distribution is a mixture of the
equilibrium distributions of the submodels.

With nonhomogeneous reconstruction, several models are applied on the
tree, some models are mixed, some are not. A path is a vector which
size is the number of mixed models (see below for more details and the
declaration of paths). 

Since the attribution of a submodel from a mixed model to a given site
is a unique random variable, affecting the same mixed model to a set
of branches S means that the attribution to this site is the same on
all the branches of S. If model M=(Ma,Mb,Mc) is defined on a set of
branches S, a site in constrained to follow either Ma on all S, or Mb
on all S, or Ms on all S. If we want that two branches of S are
independant, two similar mixed models must be defined. Moreover, it is
possible to define paths that define dependencies between submodels of
different mixtures (see below).


@item MixedModel(model=@{model description@})
Mixture model from a given @var{model} in which some parameters follow
a probabilistic distribution. Any discrete distribution available can
be used @xref{Discrete distributions}. The description of the
parameters distributions is described below. In case the range of a
parameter is limited, the domain of the corresponding distribution is
truncated accordingly.

@cartouche
@example
model=MixedModel(model=TN93(kappa1=Gamma(n=4,alpha=3,beta=1),\
                            kappa2=Exponential(lambda=2),\
                            theta=0.5,theta1=0.2,theta2=0.1))
@end example
@end cartouche
has parameters @var{TN93.kappa1_Gamma.alpha},
@var{TN93.kappa1_Gamma.beta},
@var{TN93.kappa2_Exponential.lamba},
@var{TN93.theta}, @var{MixedModel.TN93.theta1},
@var{TN93.theta2}.

See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1MixtureOfASubstitutionModel.html#details, Bio++ description, Bio++ description}.

@item Mixture(model1=@{model description@},..., modeln=@{model description@} [, relrate1=@{1>real>0@},..., relrate@{n-1@}=@{1>real>0@}, relproba1=@{1>real>0@}, ..., relproba@{n-1@}=@{1>real>0@}, "equilibrium frequencies"])
Mixture model built from several @var{models}: each model has its own
probability and rate. 

Arguments @var{relproba@{i@}} stands for the relative probability and
@var{relrate@{i@}} stands for the relative rate of each model (in the
order the models are given). Default: @var{relproba@{i@}=1/@{n-i+1@}},
such that the probabilty of each site is 1/n, and
@var{relrate@{i@}=1/@{n-i+1@}} such that the rate of each site is 1.

@cartouche
@example
model=Mixture(model1=GY94(), model2=YN98(), relrate1=0.1)
@end example
@end cartouche
has parameters@var{Mixture.relrate1}, @var{Mixture.relproba1},
@var{Mixture.1_GY94.kappa}, @var{Mixture.1_GY94.V},
@var{Mixture.2_YN98.kappa}, @var{Mixture.2_YN98.omega}.

See the
@uref{http://bioweb.me/bpp-phyl-doc/classbpp_1_1MixtureOfSubstitutionModels.html#details, Bio++ description, Bio++ description}.

@end table

@node Conditioned, , Mixture, Model
@subsubsection Conditioned models

The transition probabilities on the branches are conditioned by the
occurence of given events. The model is then no-markovian, but
semi-markovian. The sets of considered events follow the one (ie
register) defined for substitution mapping (see the testnh manual).

@table @command

@item OneChange(model=@{model description@})
The transition probabilities along each branch are conditioned by the
fact that there has been at least one substitution on this branch with
thid model.

@item OneChange(model=@{model description@}, register=@{register
name@}, numReg=num1+num2+...)

The transition probabilities along each branch are conditioned by the
fact that there has been on this branch at least one substitution
of the specific types in the register. The "+" permits the declaration
of several types.

@end table

@node Non-homogeneity, FrequenciesSet, Model, Process
@subsection Setting up non-stationary / non-homogeneous models

You can specify a wide range of non-homogeneous models, by combining different options.

@subsubsection One-per-branch non-homogeneous models

This option share the same parameters as the homogeneous case, since the same kind of model is used for each branch. The additional options are the following:
@table @command

@item nonhomogeneous_one_per_branch.shared_parameters = @{list<chars>@}
List the names of the parameters that are shared by all branches.
In Galtier & Gouy model, that would be @var{T92.kappa}, since only the theta parameter is branch-specific.

The '*' wildcard can be used, as in @command{*theta*} for all the
parameters whose name has @command{theta} in it.

@end table

@subsubsection General non-homogeneous models

Bio++ provides a general syntax to specify almost any non-homogeneous model.

@table @command

@item nonhomogeneous.number_of_models = @{int>0@}
Set the number of distinct models to use.

@end table

You now have to configure each model individually, using the syntax introduced for the homogeneous case, excepted that model will be numbered, for instance:

@cartouche
@example
model1 = T92(theta=0.39, kappa=2.79)
@end example
@end cartouche

The additional option is available to attach the model to branches in the tree, specified by the id of the upper node in the tree:

@table @command

@item model1.nodes_id = 1,5,10:15,19
Specify the ids of the nodes to which the node is attached.
Id ranges can be specified using the @option{begin:end} syntax.

@end table

Finally, you may find useful the following options:

@table @command

@item output.parameter_names.file = @{@{path@}|none@}
A text file listing all parameter names. This might come handy in
order to specify the parameter that should not be optimized (see
optimization.ignore_parameter) or aliased (see above). The use of that
option will cause the program to exit just after producing the list
file.

@end table

@subsubsection Paths among non-homogeneous mixture models

To define constraints for sites between submodels, we can set "paths"
that any site must follow. For example, in the following description:

@cartouche
@example
nonhomogeneous = general
nonhomogeneous.number_of_models = 3

model1=T92()
model2=MixedModel(model=T92(kappa=Simple(values=(4,10,20),\
                                probas=(0.1,0.5,0.4))))
model3=MixedModel(model=TN93(theta1=Simple(values=(0.1,0.5,0.9),\
                                probas=(0.3,0.2,0.5))))

model1.nodes_id=0:1
model2.nodes_id=2:3
model3.nodes_id=4:5
@end example
@end cartouche

In this case, on branches 2 & 3 a site follows any submodel of model 2
(but the same submodel on both branches), and on branches 4 & 5, a
site follows any submodel of model  3 (the same on both branches as
well).  But there is no constraint between models 2 & 3, which means
that a site can follow any submodel of model 2 and any submodel of
model 3.

If the user wants that a site with @var{T92.kappa=4} in model 2 has
@var{TN93.theta1=0.1} in model 3, that a site with @var{T92.kappa=10}
in model 2 has @var{TN93.theta1=0.9} in model 3, and that other cases
are free (in this case it means that @var{T92.kappa=20} in model 2 is
linked with @var{TN93.theta1=0.5} in model 3), then we can use the
declarations:

@cartouche
@example
site.number_of_paths=2
site.path1=model2[T92.kappa_1] & model3[TN93.theta1_2]
site.path2=model2[T92.kappa_2] & model3[TN93.theta1_3]
@end example
@end cartouche

The third path (for the remaining submodels) is automatically
computed.

It is possible to link mixtures of submodels. For example,

@cartouche
@example 
site.path1=model2[T92.kappa_1] & model3[TN93.theta1_2]\
                               & model3[TN93.theta1_3]
@end example
@end cartouche

means that a site that has @var{T92.kappa=4} in model2 has either
@var{TN93.theta1=0.5} or @var{TN93.theta1=0.9} in model3.


Because of these constraints, the probabilities of the submodels are
linked. In the first example, probability of @var{T92.kappa=4} in
model 2 equals the probability of @var{TN93.theta1=0.5} in model 3.
Since it is contradictory with the probabilities defined in models 2
or 3, the reference probabilities are the ones of the first numbered
mixed model, here model 2. In this case, the probabilities in model 3
may have no use, but with the second example the probability of
submodel T92.kappa=4 equals the sum of the probabilities of submodels
TN93.theta1=0.5 or TN93.theta1=0.9. The relative proportion of those
models used in the declaration of model 3 is then used. Here their
respective probabilities are then: 0.1*0.2/ (0.2+0.5)=0.0286 and
0.1*0.5/(0.2+0.5)=0.0714.

Concerning the optimization procedure, this choice may entail the non-
identifiability of several parameters (here the probabilities in model
3), so the user should be careful about this. 


When the submodel is aliased behind a model name, the paths should be
defined as combinations of the model that is mixed. For example,
YNGP_M2 is made of 3 YN98 models, depending of three @var{omega}
values: <1, =1, >1. If we want a site to switch between <1 and >1
omega values between two sets of branches:

@cartouche
@example
nonhomogeneous = general
nonhomogeneous.number_of_models = 2

model1=YNGP_M2(frequencies=F1X4)
model2=YNGP_M2(frequencies=F1X4)

model1.nodes_id=0:1
model2.nodes_id=2:3

site.number_of_paths=3
site.path1=model1[YN98.omega_1] & model2[YN98.omega_3]
site.path2=model1[YN98.omega_2] & model2[YN98.omega_2]
site.path3=model1[YN98.omega_3] & model2[YN98.omega_1]

@end example
@end cartouche

Another example in the case of mixtures of mixed models, where the
submodels are defined by their names:

@cartouche
@example
nonhomogeneous = general
nonhomogeneous.number_of_models = 2

model1=LLG08_UL2()
model2=LLG08_UL3()

site.number_of_paths=2
site.path1=model1[LLG08_UL2.M2] & model2[LLG08_UL3.Q1]
site.path2=model1[LLG08_UL2.M1] & model2[LLG08_UL3.Q2] \
                                & model2[LLG08_UL3.Q3]
@end example
@end cartouche

When nonhomogeneity option is @option{one_per_branch}, each site is
constrained to follow the same submodel from leaves to root.

@subsubsection Root frequencies

In case of nonstationary models, the ancestral frequencies are
distinct parameters. If a model is assumed to be stationary, the
``None'' parameter value can be used, which is strictly equivalent to
setting
@command{nonhomogeneous.stationary=yes}.

When the model is a mixture model, since there is not a set of
equilibrium frequencies, with this option the root frequencies are set
to be the average (with the respective probabilities of the submodels)
of the equilibrium frequencies of the submodels.

As since version 0.4.0, BppSuite uses the keyval syntax to set up root
frequencies,
@table @command
@item nonhomogeneous.root_freq=@{frequency set description@}
@end table

The Frequencies set used can be any of the ones described below
@xref{Frequencies sets}, depending on the alphabet used.


@node FrequenciesSet, Rates, Non-homogeneity, Process
@subsection Frequencies sets
@anchor{Frequencies sets}

The following frequencies distributions are available:

@table @command

@item Fixed()
All frequencies are fixed to their initial value and are not
estimated. 

@item GC(theta=@{real]0,1[@})
For nucleotides only, set the G content equal to the C content.

@item Full(theta1=@{real]0,1[@}, theta2=@{real]0,1[@}, ..., thetaN=@{real]0,1[@})
Full parametrization. Contains N free parameters, where N is equal to the size of the alphabet - 1. For codon models, N is the size of the alphabet - 1 - the number of stop codons, whose frequencies are set to 0.
For nucleotide sequences, theta is the GC content, theta1 is the proportion of A over A+T, and theta2 is the proportion of G over G+C.

@item Empirical(file=@{path@} [,col=@{int@}])
Read frequencies from a file. Each frequencies is set as plain column
in the file. If several columns are in the file, the number of the
column can be given with @{col@} argument (default: 1).

@item Empirical+F(name=@{chars@}, file=@{path@}, [theta=@{real]0,1[@}, theta1=@{real]0,1[@}, theta2=@{real]0,1[@}, ..., "equilibrium frequencies"])
Build a protein substitution model from a file in PAML format, and use
free equilibrium frequencies. 'name' will be used as a parameter
namespace, including for frequencies.


@item Word(frequency=@{frequency set description@})

or 

@item Word(frequency1=@{frequency set description@}, frequency2=@{frequency set description@}, ..., frequencyn=@{frequency set description@})

frequencies on words computed as the product of frequencies on the
letters. The arguments @var{frequency} and @var{frequency@{i@}} are for
descriptions of frequency sets on single sites such as nucleotides or
proteins. The alphabet must be a Word alphabet.

If the argument is @var{frequency}, the number of multiplied single
site frequencies is the length of the words in the alphabet, and the
@emph{same} single site frequency set is used (ie the parameters are
shared between all positions).

If the arguments are @var{frequency1}, ..., @var{frequency@{n@}}, the
length of the words in the alphabet must be @var{n}, and all single
site frequency sets are independent. In that case, all single site
frequency set parameters are position dependent.

@cartouche
@example
alphabet=Word(letter=DNA,length=4)
nonhomogeneous.root_freq=Word(frequency=GC())
@end example
@end cartouche
builds a root frequency set on 4 bases words, such that all sites
frequencies follow the same GC frequency set model. The parameter
name is @var{1234_GC.theta}.

@cartouche
@example
alphabet=Word(letter=DNA,length=4)
nonhomogeneous.root_freq=Word(frequency1=GC(),frequency2=GC(),\
                      frequency3=Fixed(),frequency4=Full())
@end example
@end cartouche
builds a root frequency set on 4 bases words, such first and second sites
follow independent GC frequency sets, third site follows a Fixed
frequency set, and fourth site follows a Full frequency set. Then the
parameters names are @var{1_GC.theta},
@var{2_GC.theta}, @var{4_Full.theta_1},
@var{4_Full.theta_2}, @var{4_Full.theta_3}.

@item Codon(frequency=@{frequency set description@})

or 

@item Codon(frequency1=@{frequency set description@}, frequency2=@{frequency set description@}, frequency3=@{frequency set description@})

frequencies on codons computed as the product of frequencies on the
letters, with stop codon frequencies set to zero. The arguments
@var{frequency} and @var{frequency@{i@}} are for descriptions of
frequency sets on nucleotides. The alphabet must be a Codon alphabet.

If the argument is @var{frequency}, the @emph{same} single site
frequency set is used (ie the parameters are shared between all
positions).

If the arguments are @var{frequency1}, @var{frequency2},
@var{frequency3}, all single site frequency sets are independent. In
that case, all single site frequency set parameters are position
dependent.

@cartouche
@example
alphabet=Codon(letter=DNA)
genetic_code=Standard
nonhomogeneous.root_freq=Codon(frequency=GC())
@end example
@end cartouche
builds a frequency set on codons, such that all sites frequencies
follow the same GC frequency set model. The parameter name is
@var{123_GC.theta}.

@cartouche
@example
alphabet=Codon(letter=DNA)
genetic_code=Standard
nonhomogeneous.root_freq=Codon(frequency1=GC(),frequency2=GC(),\
                               frequency3=Fixed())
@end example
@end cartouche

builds a frequency set on codons, such that first and second sites
follow independent GC frequency sets, third site follows a Fixed
frequency set. Then the parameters names are @var{1_GC.theta},
@var{2_GC.theta}.


Predefined codon frequencies are available, with a syntax similar to
the one used in the PAML software. See above Codon Models section.

@end table

All functions accept the following arguments, that take priority over
the parameter specification:

@table @command

@item init=@{balanced,observed@}
Set all frequencies to the same value, or to their observed counts.

@item observedPseudoCount=@{integer@}
If the frequencies are set from observed counts, a pseudoCount is
added to all the counts.

@item values=(@{vector<double>@})
Explicitly set all frequencies manually. The size of the input vector
should equal the number of resolved states in the alphabet, be in
alphabetical order of states, and sum to one.

@end table

@node Rates, Linking, FrequenciesSet, Process
@subsection Rate across site distribution

@table @command

@item rate_distribution = @{rate distribution description@}
Specify the rate across sites distribution.

@end table

The rate distribution is set to have a mean of 1.
The following distributions are currently available:

@table @command

@item Constant
Uses a constant rate across sites.

@item Gamma(n=@{int>=2@}, alpha=@{float>0@})
A discretized gamma distribution of rates, with @var{n} classes, and a
given shape, with mean 1 (scale=shape).

@item Invariant(dist=@{rate distribution description@}, p=@{real[0,1]@})
A composite distribution allowing a special class of invariant site,
with a probability @var{p}.

@end table

@node Linking,  , Rates, Process
@subsection Linking parameters

It is possible to reduce the parameter space by putting extra
constraints on parameters, using for instance

@cartouche
@example
model=TN93(kappa1=1.0, kappa2=kappa1, theta=0.5)
@end example
@end cartouche

In that particular case the resulting model is strictly equivalent to
the HKY85 model. This syntax however allows to define a larger set of
models.

As long as their range match, parameters of several objects (models,
root frequencies, rates, etc) can be linked.

For instance:
@cartouche
@example
model1 = T92(theta=GC.theta, kappa=3)
model2 = T92(theta=0.39, kappa=T92.kappa_1)

nonhomogeneous.root_freq=GC
@end example
@end cartouche

In the case of nonhomogeneous modelling, a specific syntax is available:

@cartouche
@example
nonhomogeneous.alias = @{list of aliases@}
@end example
@end cartouche

where each alias is described as `param1->param2'. The full name of the parameters have to be used, see for example:

@cartouche
@example
model1 = T92(theta=0.4, kappa=4)
model2 = GTR(theta=0.4, a = 1.1, b=0.4, c=0.4, d=0.25, e=0.1)
nonhomogeneous.alias=GTR.theta1->T92.theta1
@end example
@end cartouche

This option can be used to link parameters of the root frequencies if the model is non-stationary:
@cartouche
@example
model1=GTR(theta1=0.7)
nonhomogeneous.root_freq=Full(init=balanced)
nonhomogeneous.alias=Full.theta1->GTR.theta1_1
@end example
@end cartouche

Note that this option is only available with the 'general' nonhomogeneous substitution models and will be ignored if used with "one_per_branch".


@node Distribution, Estimation, Process, Common
@section Discrete distributions
@anchor{Discrete distributions}

Bio++ contains several probability distributions (currently only
dicrete or discretized ones). These are:

@subsection Standard Distributions

@table @command

@item Constant(value=@{float@})
a Dirac distribution on @var{value}, with parameter @var{value}.

@item Beta(n=@{int>=2@}, alpha=@{float>0@}, beta=@{float>0@}) 
a discretized beta distribution, with @var{n} classes, with standard
parameters @var{alpha} and @var{beta}.

@item Gamma(n=@{int>=2@}, alpha=@{float>0@}, beta=@{float>0@}) 
a discretized gamma distribution, with @var{n} classes, a shape
@var{alpha} and a rate @var{beta}, with parameters @var{alpha} and
@var{beta}.

@item Gaussian(n=@{int>=1@}, mu=@{float@}, sigma=@{float>0@}) 
a discretized gaussian distribution, with @var{n} classes, a mean
@var{mu} and a standard deviation @var{sigma}, with parameters
@var{mu} and @var{sigma}.

@item Exponential(n=@{int>=2@}, lambda=@{float>0@})
a discretized exponential distribution, with @var{n} classes and
parameter @var{lambda}.

@item Simple(values=@{vector<double>@}, probas=@{vector<double>@} [, ranges=@{vector<parametername[min;max]>@}])
a discrete distribution with specific values (in @var{values}) and
their respective non-negative probabibilities (in @var{probas}). The
parameters are @var{V1}, @var{V2}, ..., @var{Vn} for all the values
and the relative probabibility parameters are @var{theta1},
@var{theta2}, ..., @var{thetan-1}. Optional argument @{ranges@} sets
the allowed ranges of values taken by the parameters; usage is like
@samp{ranges=(V1[0.2;0.9],V2[1.1;999])}.

@item TruncExponential(n=@{int>=2@}, lambda=@{float>0@}, tp=@{float>0@})
a discretized truncated exponential distribution, with @var{n}
classes, parameter @var{lambda} and a truncation point @var{tp}. The
parameters are @var{lambda} and @var{tp}.

@item Uniform(n=@{int>=1@}, begin=@{float>0@}, end=@{float>0@})
a uniform distribution, with @var{n} classes in interval
[@var{begin},@var{end}]. There are no parameters.

@end table

@subsection Mixture Distributions

@table @command

@item Invariant(dist=@{distribution description@}, p=@{float>0@})

a Mixture of a given discrete distributution and a 0 Dirac. @var{p} is
the probability of this 0 Dirac.

For example :
@cartouche
@example
Invariant(dist=Gaussian(n=4,2,0.5),p=0.1)
@end example
@end cartouche
builds a mixture of a gaussian distribution with 4 categories (and
probability 0.9) and a 0 Dirac with probability 0.1. Overall, there
are 5 categories. The parameters names are
@var{Invariant.Gaussian.mu}, @var{Invariant.Gaussian.sigma},
@var{Invariant.p}.

@item Mixture(probas=@{vector<double>@}, dist1=@{distribution description@}, ..., distn=@{distribution description@}) 

a Mixture of discrete distributions with specific probabilities (in
@var{probas}) and their respective desccriptions (in @var{probas}).
The parameters are the relative probabibility parameters @var{theta1},
@var{theta2}, ..., @var{thetan-1}, and the parameters of the included
distributions prefixed by @var{Mixture.i_} where @var{i} is the order
of the distribution.

For example:
@cartouche
@example
Mixture(probas=(0.3,0.7),dist1=Beta(n=5,alpha=2,beta=3),\
                       dist2=Gamma(n=10,alpha=9,beta=2)) 
@end example
@end cartouche
builds a mixture of a discrete beta distribution and of a discrete
gamma distribution, with a total of 15 classes. The parameters names
are @var{Mixture.theta1}, @var{Mixture.1_Beta.alpha},
@var{Mixture.1_Beta.beta}, @var{Mixture.2_Gamma.alpha} and
@var{Mixture.2_Gamma.beta}.

@end table


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

@node Estimation, WritingSequences, Distribution, Common
@section Numerical parameters estimation

Some programs allow you to (re-)estimate numerical parameters, including
@itemize @bullet
@item
Branch lengths

@item
Entries of the substitution matrices, included base frequencies values)

@item
Parameters of the rate distribution (currently shape parameter of the gamma law, proportion of invariant sites).

@end itemize

@table @command

@item optimization = @{method@}
where ``method'' can be one of

@table @command
@item None
No optimization is performed, initial values are kept ``as is''.

@item FullD(derivatives=@{Newton|Gradient@})
Full-derivatives method. Branch length derivatives are computed
analytically, others numerically. The @var{derivatives} arguments
specifies if first or second order derivatives should be used. In the
first case, the optimization method used is the so-called conjugate
gradient method, otherwise the Newton-Raphson method will be used.

@item D-Brent(derivatives=@{Newton|Gradient@}, nstep=@{int>0@})
Branch lengths parameters are optimized using either the conjugate
gradient or the Newton-Raphson method, other parameters are estimated
using the Brent method in one dimension. The algorithm then loops over
all parameters until convergence. The @var{nstep} arguments allow to
specify a number of progressive steps to perform during optimization.
If @option{nstep=3} and @option{precision=E-6}, a first optimization
with @option{precision=E-2}, will be performed, then a round with
@option{precision} set to E-4 and finally @option{precision} will be
set to E-6. This approach generally increases convergence time.

@item D-BFGS(derivatives=@{Newton|Gradient@}, nstep=@{int>0@})
Branch lengths parameters are optimized using either the conjugate
gradient or the Newton-Raphson method, other parameters are estimated
using the BFGS method. The algorithm then loops over all parameters
until convergence. The @var{nstep} arguments allow to specify a number
of progressive steps to perform during optimization. If
@option{nstep=3} and @option{precision=E-6}, a first optimization with
@option{precision=E-2}, will be performed, then a round with
@option{precision} set to E-4 and finally @option{precision} will be
set to E-6. This approach generally increases convergence time.
@end table

@item optimization.reparametrization = @{boolean@}
Tells if parameters should be transformed in order to remove constraints
(for instance positivie-only parameters will be log transformed in order to obtain
 parameters defined from -inf to +inf).
This may improve the optimization, particularly for parameter-rich models,
but the likelihood calculations will take a bit more time.

@item optimization.final = @{powell|simplex@}
Optional final optimization step, useful if numerical derivatives are to be used.
Leave the field empty in order to skip this step.

@item optimization.profiler = @{@{path@}|std|none@}
A file where to dump optimization steps (a file path or std for
standard output or none for no output).

@item optimization.message_handler = @{@{path@}|std|none@}
A file where to dump warning messages.

@item optimization.max_number_f_eval = @{int<0@}
The maximum number of likelihood evaluations to perform.

@item optimization.ignore_parameter = @{list<chars>@}
A list of parameters to ignore during the estimation process. The
parameter name should include there "namespace", that is their model
name, for instance K80.kappa, TN93.theta, GTR.a, Gamma.alpha, etc. For
nested models, the syntax is the following:
@command{G01.rdist_Gamma.alpha}, @command{TS98.model_T92.kappa},
@command{RE08.lamba}, @command{RE08.model_G01.model_GTR.a}, etc.
'Ancient' will ignore all parameters in the ancestral frequency set
(non-homogeneous models), 'BrLen' will ignore all branch lengths and
'Model' will ignore all model parameters.

The '*' wildcard can be used, as in @command{*theta*} for all the
parameters whose name has @command{theta} in it.

@item optimization.constrain_parameter = @{list<chars=interval>@}
A list of parameters on which the authorized values are limited to a
given interval. 

@cartouche
@example
optimization.constrain_parameter = YN98.omega = [-inf;1.9[,\
                       *theta* = [0.1;0.7[, BrLen*=[0.01;inf]
@end example
@end cartouche 

@item optimization.tolerance = @{float>0@}
The precision on the log-likelihood to reach.

@item output.infos = @{@{path@}|none@}
A text file containing several statistics for each site in the
alignment.
These statistics include the posterior rate, rate class with maximum posterior probability and whether the site is conserved or not.

@end table

The resulting tree will be written to a file specified by the general tree writing options (@ref{WritingTrees}).

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

@node WritingSequences, WritingTrees, Estimation, Common
@section Writing sequences/alignments to files

@table @command

@item output.sequence.file = @{path@}
The output file where to write the sequences.

@item output.sequence.format = @{sequence format description@}
The output file format, using the same syntax as for reading (@pxref{Sequences}).
Only formats Fasta, Mase and Phylip are supported for writing.
In addition, most of the formats support the @command{length} argument, that specifies the maximum number of sequence characters to output on each line (default set to 100).

@end table

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

@node WritingTrees,  , WritingSequences, Common
@section Writing trees to files

@table @command
@item output.tree.file = @{path@}
The phylogenetic tree file to write to.

@item output.tree.format = @{Newick|Nexus|NHX@}
The format of the output tree file.

@end table

Some programs may require that you write multiple trees to a file.
The corresponding options are then:

@table @command
@item output.trees.file = @{path@}
The file that will contain multiple trees.

@item output.trees.format = @{Newick|Nexus|NHX@}
The format of the output tree file.

@end table

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

@node Reference,  , Common, Top
@chapter Bio++ Program Suite Reference

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

This section now details the specific options for each program in the Bio++ Program suite.

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

@menu
* bppml::                       Bio++ Maximum Likelihood.
* bppseqgen::                   Bio++ Sequence Generator.
* bppancestor::                 Bio++ Ancestral Sequences and Rates reconstruction.
* bppmixedlikelihoods::         Bio++ Site-Likelihoods Inside Mixed Models.
* bppdist::                     Bio++ Distance Methods.
* bpppars::                     Bio++ Maximum Parsimony.
* bppconsense::                 Bio++ Consensus Trees.
* bppreroot::                   Bio++ Serial Tree Re-rooting.
* bppseqman::                   Bio++ Sequences Manipulation.
* bppalnscore::                 Bio++ Alignment Scoring.
* bpppopstats::                 Bio++ Population Genetics Statistics.
* bpptreedraw::                 Bio++ Tree Drawing.
@end menu

@node bppml, bppseqgen, Reference, Reference
@section BppML: Bio++ Maximum Likelihood

The BppML program uses the common syntax introduced in the previous section for setting the alphabet, loading the sequences (@pxref{Sequences}), specifying the model (@pxref{Model}), and estimating parameters (@pxref{Estimation}).

The BppML program allows you to optimize tree topologies and model parameters and perform a bootstrap analysis.

@subsection Branch lengths initial values

@table @command

@item init.tree = @{user|random@}
Set the method for the initial tree to use.
The @option{user} option allows you to use an existing file using the method described in the Common options section.
This file may have been built using another method like neighbor joining or parsimony for instance.
The @option{random} option picks a random tree, which is handy to test convergence.
This may however slows down significantly the optimization process.

@item init.brlen.method = @{method description@}
Set how to initialize the branch lengths.
Available methods include:

@table @command

@item Input(midpoint_root_branch=@{boolean@})
Keep initial branch lengths as is. Additional argument specifies if the root position should be moved to the midpoint position of the branch containing it. 

@item Equal(value=@{float>0@})
Set all branch lengths to the same value, provided as argumemt.

@item Clock
Coerce to a clock tree.

@item Grafen(height=@{@{real>0@}|input@}, rho = @{real>0@})
Uses Grafen's method to compute branch lengths.
In Grafen's method, each node is given a weight equal to the number of underlying leaves.
The length of each branch is then computed as the difference of the weights of the connected nodes, and further divided by the number of leaves in the tree.
The height of all nodes are then raised to the power of 'rho', a user specified value.
The tree is finally scaled to match a given total height, which can be the original one (@option{height=input}), or fixed to a certain value (usually @option{height=1}).
A value of rho=0 provides a star tree, and the greater the value of rho, the more recent the inner nodes. 

@end table

@item input.tree.check_root = @{boolean@}
Tell if the input tree should be checked regarding to the presence of a root. If set to yes (the default), rooted trees will be unrooted if a homogenous model is used.
If not, a rooted tree will be fitted, which can lead to optimization issues in most cases. Use the non default option with care!
@end table

@subsection Topology optimization

@table @command

@item optimization.topology = @{boolean@}
Enable the tree topology estimation.

@item optimization.topology.algorithm = @{NNI@}
Algorithm to use for topology estimation: only NNI available for now.

@item optimization.topology.algorithm_nni.method = @{fast|better|phyml@}
Set the NNI method to use.
@option{fast}: test sequentially all NNI, if a NNI improving the likelihood is found, it is performed.
@option{better}: test all possible NNIs, do the one with the biggest likelihood increase.
@option{phyml}: test all possible NNIs, try doing all the improving ones.
If the final likelihoods is better, perform all NNIs.
Otherwise, try to do half of them, and so on. 
In most cases the @option{phyml} option shows the best performance.

@item optimization.topology.nstep = @{int>0@}
Number of phyml topology movement steps before re-optimizing parameters.

@item optimization.topology.numfirst = @{boolean@}
Shall we estimate parameters before looking for topology movements?

@item optimization.topology.tolerance.before = @{real>0@}
Tolerance for the prior-topology estimation.
The tolerance numbers should not be too low, in order to save computation time and also for a better topology estimation.
The @option{optimization.tolerance} parameter will be used for the final optimization of numerical parameters (see Common options).

@item optimization.topology.tolerance.during = 100
Tolerance for the during-topology estimation

@item optimization.scale_first = no
Shall we first scale the tree before optimizing parameters?

@item optimization.scale_first.tolerance = @{double@}
The convergence criterion to achieve in the optimization.

@end table


@subsection Molecular clock

BppML can also optimize branch lengths with a molecular clock:

@table @command

@item optimization.clock=@{no|global@}
Tell if a molecular clock should be assumed.
Topology estimation is not possible with a clock constraint.

@end table


@subsection Output results

@table @command

@item output.infos = @{@{path@}|none@}
Alignment information log file (site specific rates, etc):

@item output.estimates = @{@{path@}|none@}
Write parameter estimated values.

@item output.estimates.alias = @{boolean@}
Write the alias names of the aliased parameters instead of their
values (default: true).

@end table

@subsection Bootstrap analysis

@table @command

@item bootstrap.number = @{int>0@}
Number of replicates. A reasonable value would be >= 100.

@item bootstrap.approximate = @{boolean@}
Tell if numerical parameters should be kept to their initial value when bootstrapping. 

@item bootstrap.verbose = @{boolean@}
Set this to yes for detailed output when bootstrapping. 

@item bootstrap.output.file = @{@{path@}|none@}
Where to write the resulting trees (multi-trees newick format).

@end table

@subsection Rather technical options

Theses options are mainly for debugging or testing purpose, in most case you will be happy with the default setting.

@table @command

@item likelihood.recursion = @{simple|double@}
Set the type of likelihood recursion to use.
@option{simple}: derivatives take more time to compute, but likelihood computation is faster.
For big data sets, it can save a lot of memory usage too, particularly when the data are compressed.
@option{double}: uses more memory and need more time to compute likelihood, due to the double recursion.
Analytical derivatives are however faster to compute.

This command has no effect in the following cases: (i) topology estimation: this requires a double recursive algorithm, (ii) optimization with a molecular clock: a simple recursion with data compression is used in this case, due to the impossibility of computing analytical derivatives.

@item likelihood.recursion_simple.compression = @{simple|recursive@}

Site compression for the simple recursion:
@option{simple}: identical sites are not computed twice, @option{recursive}: look for site patterns to save computation time during optimization, but requires extra time for building the patterns.
This is usually the best option, particularly for nucleotide data sets.

@end table

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

@node bppseqgen, bppancestor, bppml, Reference
@section BppSeqGen: Bio++ Sequence Simulator

The BppSeqGen program uses the common syntax introduced in the previous section for setting the alphabet, loading the sequences (@pxref{Sequences}) and tree (@pxref{Tree}), specifying the model (@pxref{Model}) and writing sequence data (@pxref{WritingSequences}).

The root sequence can be sampled from the model specification, with
additional argument:

@table @command
@item number_of_sites = @{int>0@}
The number of site positions to simulate.

@end table


Or the root sequence can be built from a file of a sequence:

@table @command

@item input.sequence.file=@{path@}
A sequence is be loaded, from which the simulation will be performed,
or from which a root sequence can be sampled.
(@pxref{Sequences}).

@item input.infos = @{path@}
A info file like the one output by bppML.
The estimated site-specific rates will then be used to simulate the same number of sites as found in the info file, with the corresponding rates.

In this case, additional options are possible:

@table @command

@item input.infos.rates = @{string@}
Name of the column on which the rates are described (default: pr).

@item input.infos.states = @{string@}
Name of the column on which the states are read (default: none, which
means a random sequence).

@item input.site.selection = @{string@} 
used to sample from the given sequence (@pxref{Sequences}).

@end table

Addition optional arguments include:

@table @command

@item input.tree.scale = @{float@}
An optional scaling factor for the branch length (default to 1.0)

@item input.tree.method = @{single|MS|CoaSim@}
Format of input tree(s). By default, a single tree is expected ('single'). Ancestral recombination graphs (ARGs), in the form of multiple trees, can also be provided in the MS or CoaSim format.
Note that in the case of MS, ARG are given for a certain number of sites, wich should be provided as additional argument (e.g. @command{MS(number_of_sites=100)}).
The ARG will be unscaled according to the given size, and rescaled according to the given number of sites to simulate. ARG in CoaSim format are already in relative scale.

@end table

In addition, command line argument @option{--seed=@{int>0@}} can be
used to set the seed of the random generator.

@end table

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

@node bppancestor, bppmixedlikelihoods, bppseqgen, Reference
@section BppAncestor: Bio++ Ancestral Sequence and Rate Reconstruction

The BppAncestor program uses the common syntax introduced in the previous section for setting the alphabet, loading the sequences (@pxref{Sequences}) and tree (@pxref{Tree}), specifying the model (@pxref{Model}) and writing sequence data (@pxref{WritingSequences}).

Specific options are:
@table @command

@item input.tree.check_root = @{boolean@}
Tell if the input tree should be checked regarding to the presence of a root. If set to yes (the default), rooted trees will be unrooted if a homogenous model is used.
If not, a rooted tree will be fitted, which can lead to optimization issues in most cases. Use the non default option with care!

@item asr.method = @{none|marginal@}
Marginal is the only option for now. If set to "none", only nodes frequencies can be output.

@item asr.probabilities = @{boolean@}
Tells if we should output the site specific probabilities in each case.

@item asr.sample = @{boolean@}
Tell if we should sample from the posterior distribution instead of using the maximum probability.

@item asr.sample.number = 10 [[asr.sample=yes]]
Number of sample sequences to output.

@item asr.add_extant = @{boolean@}
Should extant (observed) sequences be added to the output sequence file?
The sequences added are the ones which are used for the actual calculation.
It they contained gaps for instance, and that these have been replaced by the unknown character (N or X for example),
then the sequence with unknown characters will be used.

@item output.sites.file = @{@{path@}|none@}
Alignment information log file (site specific rates, probabilities, etc).

@item output.nodes.file = @{@{path@}|none@}
Ancestral nodes information: expected frequencies (prefix exp) (see Galtier & Gouy
1998) and a posteriori probabilities of ancestral states (prefix eb).

@item output.nodes.add_extant = @{boolean@}
Tell if leaf nodes should be added to the output file.

@end table

@c ------------------------------------------------------------------------------------------------------------------
@node bppmixedlikelihoods, bppdist, bppancestor, Reference
@section BppMixedLikelihoods: Bio++ Site-Likelihoods Inside Mixed Models.

The BppMixedLikelihoods program uses the common syntax introduced in the previous section for setting the alphabet, loading the sequences (@pxref{Sequences}) and tree (@pxref{Tree}) and specifying the model (@pxref{Model}).

Given a mixed parameter name of mixed model, or a mixed model made of
several models, the BppMixedLikelihoods program computes site per site
log-likelihoods of the several values of the parameter, or of the
several sub-models of the mixture. If the mixed model is built on a
parameter which value follows a distribution, and in an additional
column -- named "mean" -- the a posteriori mean value of the paramater
is computed.

Specific options are:
@table @command

@item output.likelihoods.file = @{@{path@}@}
Ouput file of the program (site specific log-likelihood, and mean of
the mixed parameters, if any).

@item likelihoods.model_number = @{integer@}
In case of a non-homogeneous modeling, the number of the mixed model
which parameter or sub-models are considered.

@item likelihoods.parameter_name = @{string@}
If the considered mixed model is built from a distribution on a
parameter, the name of the parameter to be considered. In this case,
an additional column is written, in which the average a posteriori
value of the parameter is.

@end table

@c ------------------------------------------------------------------------------------------------------------------
@node bppdist, bpppars, bppmixedlikelihoods, Reference
@section BppDist: Bio++ Distance Methods
 
The BppDist program uses the common syntax introduced in the previous section for setting the alphabet, loading the sequences (@pxref{Sequences}) and tree (@pxref{Tree}) and specifying the model (@pxref{Model}, only the section corresponding to the homogeneous case).

Specific options are:
@table @command

@item output.matrix.file = @{@{path@}|none@}
Where to write the matrix file (only philip format supported for now).

@item method = @{wpgma|upgma|nj|bionj@}
The algorithm to use to build the tree.

@item optimization.method = @{init|pairwise|iterations@}
There are several ways to optimize substitution parameters.
The @option{init} option corresponds to the standard behavior, that is, keeping them to their initial, user-provided value.
The @option{pairwise} option estimate those parameters in a pairwise manner.
This should be avoided, particularly with parameter-rich models.
Finally the @option{iterations} option corresponds to Ninio et al, Bioinformatics (2007) recursive algorithm:
After each distance tree, a global ML estimation of the substitution parameters is performed.
The estimated values are then used to rebuild a distance matrix and a tree.
The algorithm stops when the topology does not change anymore.
The ML optimization uses the parameters described in (@pxref{Estimation}).

@item output.tree.file = @{@{path@}|none@}
The final tree, possibly with bootstrap values:
BppDist uses the same options for bootstrap analysis than the BppML program (@pxref{bppml}).
@end table

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

@node bpppars, bppconsense, bppdist, Reference
@section BppPars: Bio++ Maximum Parsimony
 
The BppPars program is currently quite limited and should not be used for serious phylogenetic analysis.
It can compute parsimony scores and perform topology estimation using the same algorithm of BppML.
It uses the common syntax introduced in the previous section for setting the alphabet, loading the sequences (@pxref{Sequences}) and tree (@pxref{Tree})).

Specific options are:
@table @command

@item optimization.topology = @{boolean@}
Tell if topology has to be estimated.

@item output.tree.file = @{@{path@}|none@}
Where to print the output file.

@item bootstrap.number = @{int>0@}
Number of bootstrap replicates to perform.

@item bootstrap.output.file = @{@{path@}|none@}
Where to write bootstrap trees.

@end table

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

@node bppconsense, bppreroot, bpppars, Reference
@section BppConsense: Bio++ Consensus Trees

Probably one of the simplest program to use in the suite, just takes a list of trees (for instance produced by BppML, BppDist or BppPars with the bootstrap option enabled) and compute bootstrap values for a reference tree, provided as input, or constructed using a consensus method.
The program uses the multiple-trees reading options for input (@pxref{Tree}) and single-tree writing options for output.

There are only specific options here:
@table @command

@item tree = @{tree methods@}
The method to use for getting the reference tree.
Available function are:

@table @command

@item Input
The tree is loaded using the single-tree reading options (@pxref{Tree}). 

@item Consensus(threshold = @{int[0,1]@})
Build a consensus tree according to a given threshold.
0 will output a fully resolved tree, 0.5 corresponds to the majority rule and 1 to the strict consensus, but any intermediate value can be specified.

@end table

@end table

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

@node bppreroot, bppseqman, bppconsense, Reference
@section BppReroot: Bio++ Serial Tree Re-rooting
 
@table @command

@item input.trees.file=@{path@}
A path toward multi-trees file (newick).

@item outgroups.file=@{path@}
A path toward a file containing the different levels of outgroups.

@item print.option=@{boolean@}
If set to true, the unrootable trees are printed as unrooted in the output file, otherwise the unrootable trees are not printed.
  
@item tryAgain.option=@{boolean@}
If set to true and ReRoot finds a non-monophyletic outgroup, it tries the next outgroup.
Otherwise, if ReRoot finds a non-monophyletic outgroup, the analysis for this tree is interrupted.
No more outgroup are analysed.

@item output.trees.file=@{path@}
File where to write the rerooted trees.

@end table

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

@node bppseqman, bppalnscore, bppreroot, Reference
@section BppSeqMan: Bio++ Sequence Manipulation

The Bio++ Sequence Manipulator convert between various file formats, and can also perform various operations on sequences.
It uses the common options for setting the alphabet, loading the sequences (@pxref{Sequences}) and writing the resulting data set (@pxref{WritingSequences}).
It can use the ``Generic'' option for alphabets if only file format conversion is to be performed, but the correct alphabet must be specified for more advanced manipulations, like in silico molecular biology.

BppSeqMan can perform any number of elementary operation, in any order, providing the output of operation n is compatible with input of operation n+1, and that the input of operation 1 is compatible with the input data.

Specific options:
@table @command

@item input.alignment = @{boolean@}
Are the input sequence aligned? If so site selection and filtering is enabled and can be used to preprocess the input data.

@item sequence.manip = @{list<string>@}
The list, in appropriate order, of elementary operations to perform.
See below for a list of these operations.
@end table

@table @option
@item Complement [[alphabet = DNA or RNA]]
Convert to the complementary sequence, keeping the original alphabet.

@item Transcript [[alphabet = DNA or RNA]]
Convert to the complementary sequence, switching the type of alphabet (DNA<->RNA).

@item Switch [[alphabet = DNA or RNA]]
Change the alphabet type (DNA<->RNA).

@item Translate [[alphabet = DNA or RNA]]
Convert to proteins.
The genetic code used for translation is set via the genetic_code option.
Genetic code is set once for all sequences.

@item Invert
Invert the sequence 5' <-> 3' or N <-> C

@item RemoveGaps
Remove all gaps in sequences (ie, 'unalign').

@item GapToUnknown
Change gaps to fully unresolved characters, N for nucleotides and X for proteins.

@item UnknownToGap
Change (partially) unresolved characters to gaps.

@item RemoveStops
Remove all stop codons in sequences. If sequences are aligned, stop codons will be replaced by gaps.
The genetic code used for translation is set via the genetic_code option.
Genetic code is set once for all sequences.

@item RemoveEmptySequences
Remove all empty sequences (ie sequences with only gaps).

@item RemoveColumnsWithStop
Remove all sites with at least one stop codon.
The genetic code used for translation is set via the genetic_code option.
Genetic code is set once for all sequences.

@item GetCDS
Remove the first stop codon and everything after in codon sequences.

@item CoerceToAlignment
Try to convert a set of sequence to an alignment. This will fail if sequences do not have the same length.
This step is required before trying commands 'ResolveDotted' or 'KeepComplete'.

@item ResolveDotted(alphabet=@{RNA|DNA|Proteins@}) [[Aligned sequences]]
Convert a human-readable alignment to a machine-readable alignment.
This manipulation must be first if it is used, and the data must be load with the @option{Generic} alphabet.
@option{alphabet}: The alphabet to use in order to resolve a dotted alignment.

@item KeepComplete(maxGapAllowed=@{int>0@} or @{float[0,100]@}+%) [[Aligned sequences]]
Keep only complete sites, ie sites without any gap. Sites with unresolved characters are not removed.
It is also possible to fix a maximum proportion of gaps, see specific options.
@option{maxGapAllowed}: The maximum proportion of gaps allowed.

@item GetCodonPosition(position=@{1|2|3@})
Retrieve the given positions from codon sequences (aligned or not).

@item FilterFromTree(tree.file=@{path@}, tree.format=@{chars@})
Get a subset of sequences based on a tree file. The order of sequences in the file will reflect the tree structure. All sequences which do not have a corresponding leaf in the tree, based on the sequence name, will be removed.
This method can therefore be used for subsetting a list of sequences, and/or rearrange them in a more convenient manner.

@end table

Examples of use:

@itemize @bullet

@item Just change file format:
@cartouche
@example
sequence.manip=
@end example
@end cartouche

@item Change DNA to RNA:
@cartouche
@example
sequence.manip=Switch
@end example
@end cartouche

@item Unalign sequences, perform transcription and translate to proteins:
@cartouche
@example
sequence.manip=RemoveGaps,Transcript,Translate
@end example
@end cartouche

@item Change all unresolved characters to gaps and keep only positions with less than 5 gaps:
@cartouche
@example
sequence.manip=UnknownToGap,KeepComplete(maxGapAllowed=5)
@end example
@end cartouche

@item Keep only positions with less than 30% of gaps, and change them to unresolved characters:
@cartouche
@example
sequence.manip=KeepComplete(maxGapAllowed=30%),GapToUnknown
@end example
@end cartouche

@end itemize

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

@node bppalnscore, bpppopstats, bppseqman, Reference
@section BppAlnScore: Bio++ Alignment Scoring

This program compares two alignments and computes column scores.
Scores are output to a text file, and/or can be used to generate
a site selection, to be output in a mase file.

The two input alignments are specified using the input.sequences
procedures (@pxref{Sequences}), with suffixes ``.test'' for the
first one, and ``.ref'' for the second. Scores will be computed 
for each column of the ``.test'' alignment.

Two scores are computed, following work by Thompson (1999):
@table @emph
@item column score (CS)
is 1 if the column is found in the reference alignment, 0 otherwise.
@item sum-of-pairs score (SPS)
is the proportion of pairs of residues which are also aligned in
the reference alignment.
@end table

Specific options:
@table @command

@item output.scores = @{path@}
A text file where scores can be written, one row per column.
If set to 'none', no file will be produced.

@item output.mase = @{path@}
If not 'none', a Mase alignment will be generated, as a copy
of the ``.test'' input alignment, with two sites selections
names CS and SPS.

@item output.sps_thresholds = @{float@}
The threshold to use for generating the site selection based 
on SPS score. All positions with at least the threshold value
will be included in the selection.

@item score.word_size = @{int>0@}
If alignment is for a word alphabet (typically codons), the word
size can be specified in order to produce a compatible site selection.
Please note that in this case, the alignment must not be loaded with
the world alphabet, but the corresponding letter alphabet.

@item score.phase = @{int>0|chars@}
Eather a number (1-based) stating the starting position for words,
or the starting word. In this latter case, the first occurrence of the
word in all sequences will be used to determine the phase.

@end table


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

@node bpppopstats, bpptreedraw, bppalnscore, Reference
@section BppPopStats: Bio++ Population Genetics Statistics

The @command{BppPopStats} program computes population genetics statistics from a sequence input alignement.
It can compute glabal alignment statistics, as well as site-specific statistics. In the first case, results
are output on screen or in a log file. In the second case, results are written in a table file, with one site per line.
Statistics available also depend on the type on input data (coding or non-coding).

@command{BppPopStats} recognizes the standard options for alphabet and genetic code, in case a codon alphabet was specified.
Sequences will be considered as coding if encoded with a codon alphabet, and non-coding otherwise.

@subsection Specific options

@table @command

@item input.sequence.file.ingroup = @{path@}
Path toward the file containing the ingroup sequences.

@item input.sequence.format.ingroup = @{string@}
Alignment input format, following standard options.

@item input.sequence.file.outgroup = @{path@}
Path toward the file containing the outgroup sequences.

@item input.sequence.format.outgroup = @{string@}
Alignment input format, following standard options.

@item input.sequence.file = @{path@}
Path toward the file containing all sequences.
This option is only recognized if @command{input.sequence.file.ingroup} was not specified.

@item input.sequence.format = @{string@}
Alignment input format, following standard options.

@item input.sequence.outgroup.index = @{[int>0]@}
Vector of positions indicating the positions of the outgroup sequences in the alignment.
This option is only recognized if @command{input.sequence.file.ingroup} was not specified.

@item input.sequence.outgroup.name = @{[string]@}
Vector of sequence names indicating the positions of the outgroup sequences in the alignment.
This option is only recognized if @command{input.sequence.file.ingroup} was not specified.

@item input.sequence.stop_codons_policy = Keep|RemoveIfLast|RemoveAll
Tells what to do with positions containing at least one stop codon: keep them, remove them only if they are at the end of the alignment, or remove them all.

@item estimate.kappa = @{[boolean]@}
Tells if the ratio of transitions / transversion should be estimated from the data and used for further analyses. If yes, kappa will be estimated by maximum likelihood using a model of (codon) sequence evolution.

@item estimate.ancestor = @{[boolean]@}
If an outgroup sequence is present, it will be used to estimate the ancestral allele for each polymorphic position.
A model of (codon) sequence evolution will be used with a marginal ancestral state reconstruction method.

@item estimate.sample_ingroup = @{[bollean]@}
Tell if a random subset of ingroup sequences should be used to fit model (speeds up calculations in case of large data sets).

@item estimate.sample_ingroup.size = @{[integer]@}
Number of ingroup sequences to sample.

@item pop.stats = @{[string]@}
The list of statistics to compute. The next section describes all available statistics.

@item logfile = @{path@}
Optional file where to output results.

@end table

@subsection Available statistics

@table @command

@item SiteFrequencies
Output the number of segregating sites as well as the number of singletons.
 
@item Watterson75
Compute Watterson's nucleotide diversity estimator (theta, averaged per site).

@item Tajima83
Compute Tajima's nucleotide diversity estimator (pi, averaged per site).

@item TajimaD
Compute Tajima's D. If a codon alignment is specified (and alphabet is set to codon type),
the @command{positions} argument further allow to compute Tajima's D on synonymous sites only
(@command{positions=synonymous}), non-synonymous sites (@command{positions=non-synonymous}).
Default is to use all sites (@command{positions=all}).

@item FuAndLiDStar | FuAndLiFStar
Compute Fu and Li's (1993) D and F statistics. If argument @command{tot_mut} is set to yes,
then the total number of mutations is used in the calculation, instead of the number of segregating sites (default).

@item PiN_PiS
For codon sequences only, obviously. Compute nucleotide diversity at synonymous and non-synonymous site,
the number of synonymous and non-synonymous sites, as well as the weighted ratio (PiN / NbN) / (PiS / NbS). 

@item dN_dS
For codon sequences only. Build the consensus sequence of both ingroup and outgroup alignments and fit a Yang and Nielsen model of codon sequence evolution with a maximum likelihood approach.
Reports the estimated parameters omega (dN / dS ratio) and kappa (transitions / transversions ratio), as well as the divergence between the two sequences. 

@item MKT
Compute the MacDonald-Kreitman table, for codon sequences with outgroup.

@item CodonSitesStatistics
Generate a table with codon-site specifics statistics, including:

@itemize @bullet

@item Whether the site is complete or not

@item Number of distinct states

@item Minor allele frequency

@item Major allele frequency

@item Minor allele

@item Major allele

@item State in the first outgroup sequence, if any

@item Ancestral state, if computed

@item Mean number of synonymous positions for polymorphism

@item Whether the site is synonymous polymorphic

@item Whether the site is four-fold degenerated

@item Non-synonymous diversity (piN)

@item Synonymous diversity (piS)

@item Mean number of synonymous positions for divergence

@item dN, if an outgroup is available

@item dS, if an outgroup is available

@end itemize

The @command{output.file} argument allows to specify the output file (mandatory).

@end table

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

@node bpptreedraw,  , bpppopstats, Reference
@section BppTreeDraw: Bio++ Tree Drawing

This is a simple program that outputs a tree in various vector formats.
It takes as input a tree following the standard syntax.

Specific options:
@table @command

@item output.drawing.file = @{path@}
The file where to output the figure.

@item output.drawing.format = @{Svg|Xfig|Inkscape|Pgf@}
The file format.
@item output.drawing.plot = @{plotting algorithm@}
The plotting algorithm can be either Phylogram or Cladogram.
They follow the keyval syntax, with the following arguments:
@end table

@table @option
@item xu, yu @{float@}
The scale units for x and y axis.

@item direction.h @{left2right|right2left@}
Horizontal orientation of the tree plot.

@item direction.v @{top2bottom|bottom2top@}
Vertical orientation of the tree plot.

@item draw.leaves, draw.ids, draw.brlen, draw.bs @{boolean@}
Tell if leaf names, node ids, branch lengths and/or bootstrap should be drawn.

@end table

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

@c ------------------------------------------------------------------------------------------------------------------
@c end of document

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

@bye
