Difference between revisions of "GARLI Configuration Settings"

From MolEvol
(Created page with "criptions of GARLI configuration settings== The format for these configuration settings descriptions is generally: '''entryname''' (possible values, '''default value in bold'...")
 
(datatype (sequence type and inference model))
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
criptions of GARLI configuration settings==
+
==Descriptions of GARLI configuration settings==
 
The format for these configuration settings descriptions is generally:
 
The format for these configuration settings descriptions is generally:
'''entryname''' (possible values, '''default value in bold''') – description
+
'''entryname''' (possible values, '''default value in bold''') – description
  
==General settings==
+
==General settings==
===datafname (file containing sequence dataset)===  
+
===datafname (file containing sequence dataset)===  
'''datafname''' = (filename) –
+
'''datafname''' = (filename) –
Name of the file containing the aligned sequence data.  Formats accepted are  
+
Name of the file containing the aligned sequence data.  Formats accepted are  
PHYLIP, NEXUS and FASTA.  Robust reading of Nexus formatted  
+
PHYLIP, NEXUS and FASTA.  Robust reading of Nexus formatted  
datasets is done using the Nexus Class Library.  This accommodates things such as interleaved  
+
datasets is done using the Nexus Class Library.  This accommodates things such as interleaved  
alignments and exclusion sets (exset’s) in NEXUS assumptions blocks (see the FAQ for an  
+
alignments and exclusion sets (exset’s) in NEXUS assumptions blocks (see the FAQ for an  
example of [[FAQ#Can_I_specify_alignment_columns_of_my_data_matrix_to_be_excluded.3F | exset usage]]).  Use of NEXUS files is recommended, and is required for partitioned models.
+
example of [[Garli_FAQ#Can_I_specify_alignment_columns_of_my_data_matrix_to_be_excluded.3F | exset usage]]).  Use of NEXUS files is recommended, and is required for partitioned models.
  
===constraintfile (file containing constraint definition)===
+
===constraintfile (file containing constraint definition)===
'''constraintfile''' = (filename, '''none''') –
+
'''constraintfile''' = (filename, '''none''') –
Name of the file containing any topology constraint specifications, or “none” if  
+
Name of the file containing any topology constraint specifications, or “none” if  
there are no constraints.  The easiest way to explain the format of the constraint file is by  
+
there are no constraints.  The easiest way to explain the format of the constraint file is by  
example.  Consider a dataset of 8 taxa, in which your constraint consists of grouping taxa 1, 3  
+
example.  Consider a dataset of 8 taxa, in which your constraint consists of grouping taxa 1, 3  
and 5.  You may specify either positive constraints (inferred tree MUST contain constrained  
+
and 5.  You may specify either positive constraints (inferred tree MUST contain constrained  
group) or negative constraints (also called converse constraints, inferred tree CANNOT  
+
group) or negative constraints (also called converse constraints, inferred tree CANNOT  
contain constrained group).  These are specified with either a ‘+’ or a ‘-‘ at the beginning of  
+
contain constrained group).  These are specified with either a ‘+’ or a ‘-‘ at the beginning of  
the constraint specification, for positive and negative constraints, respectively.  
+
the constraint specification, for positive and negative constraints, respectively.  
*For a positive constraint on a grouping of taxa 1, 3 and 5:  
+
*For a positive constraint on a grouping of taxa 1, 3 and 5:  
  +((1,3,5),2,4,6,7,8);  
+
+((1,3,5),2,4,6,7,8);  
  *For a negative constraint on a grouping of taxa 1, 3 and 5:  
+
*For a negative constraint on a grouping of taxa 1, 3 and 5:  
  -((1,3,5),2,4,6,7,8);  
+
-((1,3,5),2,4,6,7,8);  
  *Note that there are many other equivalent parenthetical representations of these constraints.  
+
*Note that there are many other equivalent parenthetical representations of these constraints.  
  *Multiple groups may be positively constrained, but currently only a single negatively constrained group is allowed.  
+
*Multiple groups may be positively constrained, but currently only a single negatively constrained group is allowed.  
  *Multiple constrained groupings may be specified in a single string:  
+
*Multiple constrained groupings may be specified in a single string:  
    +((1,3,5),2,4,(6,7),8);  
+
+((1,3,5),2,4,(6,7),8);  
    or in two separate strings on successive lines:  
+
or in two separate strings on successive lines:  
    +((1,3,5),2,4,6,7,8);  
+
+((1,3,5),2,4,6,7,8);  
      +(1,3,5,2,4,(6,7),8);  
+
+(1,3,5,2,4,(6,7),8);  
      *Constraint strings may also be specified in terms of taxon names (matching those used in the alignment) instead of numbers.  
+
*Constraint strings may also be specified in terms of taxon names (matching those used in the alignment) instead of numbers.  
      *Positive and negative constraints cannot be mixed.  
+
*Positive and negative constraints cannot be mixed.  
      *GARLI also accepts another constraint format that may be easier to use in some cases. This involves specifying a single branch to be constrained with a string of ‘*’ (asterisk) and ‘.’ (period) characters, with one character per taxon.  Each taxon specified with a ‘*’ falls on one side of the constrained branch, and all those specified with a ‘.’ fall on the other.  This should be familiar to anyone who has looked at PAUP* bootstrap output. With this format, a positive constraint on a grouping of taxa 1, 3 and 5 would look like this:  
+
*GARLI also accepts another constraint format that may be easier to use in some cases. This involves specifying a single branch to be constrained with a string of ‘*’ (asterisk) and ‘.’ (period) characters, with one character per taxon.  Each taxon specified with a ‘*’ falls on one side of the constrained branch, and all those specified with a ‘.’ fall on the other.  This should be familiar to anyone who has looked at PAUP* bootstrap output. With this format, a positive constraint on a grouping of taxa 1, 3 and 5 would look like this:  
      +*.*.*…  
+
+*.*.*…  
      or equivalently like this:  
+
or equivalently like this:  
        +.*.*.***  
+
+.*.*.***  
        With this format each line only designates a single branch, so multiple constrained branches must be specified as multiple lines in the file.  
+
With this format each line only designates a single branch, so multiple constrained branches must be specified as multiple lines in the file.  
        *The program also allows “backbone” constraints, which are simply constraints that do not include all of the taxa.  For example if one wanted to constrain (1,3,5) but didn’t care where taxon 6 appeared in the tree, this string could be used:  
+
*The program also allows “backbone” constraints, which are simply constraints that do not include all of the taxa.  For example if one wanted to constrain (1,3,5) but didn’t care where taxon 6 appeared in the tree, this string could be used:  
        +((1,3,5),2,4,7,8);  
+
+((1,3,5),2,4,7,8);  
        :Nothing special needs to be done to identify this as a backbone constraint, simply leave out some taxa.
+
:Nothing special needs to be done to identify this as a backbone constraint, simply leave out some taxa.
  
        ===streefname (source of starting tree and/or model)===
+
===streefname (source of starting tree and/or model)===
        '''streefname''' = (random, <u>'''stepwise'''</u>, <filename>) – Specifies where the starting tree topology and/or  
+
'''streefname''' = (random, <u>'''stepwise'''</u>, <filename>) – Specifies where the starting tree topology and/or  
        model parameters will come from.  The tree topology may be a completely random topology  
+
model parameters will come from.  The tree topology may be a completely random topology  
        (constraints will be enforced), a tree provided by the user in a file, <u>or a tree generated by the  
+
(constraints will be enforced), a tree provided by the user in a file, <u>or a tree generated by the  
        program using a fast ML stepwise-addition algorithm (see [[GARLI_Configuration_Settings#attachmentspertaxon_.28control_creation_of_stepwise_addition_starting_tree.29|attachmentspertaxon]] below)</u>.  
+
program using a fast ML stepwise-addition algorithm (see [[GARLI_Configuration_Settings#attachmentspertaxon_.28control_creation_of_stepwise_addition_starting_tree.29|attachmentspertaxon]] below)</u>.  
        Starting or fixed model parameter values may also be provided in the specified file, with or  
+
Starting or fixed model parameter values may also be provided in the specified file, with or  
        without a tree topology.  Some notes on starting trees/models:  
+
without a tree topology.  Some notes on starting trees/models:  
        *Specified starting trees may have polytomies, which will be arbitrarily resolved before the run begins.
+
*Specified starting trees may have polytomies, which will be arbitrarily resolved before the run begins.
        *Starting tree formats:  
+
*Starting tree formats:  
        **Plain newick tree string (with taxon numbers or names, with or without branch lengths)  
+
**Plain newick tree string (with taxon numbers or names, with or without branch lengths)  
        **NEXUS trees block.  The trees block can appear in the same file as a NEXUS data or characters block that contains the alignment, although the same filename should then be specified on both the datafname and streefname lines.
+
**NEXUS trees block.  The trees block can appear in the same file as a NEXUS data or characters block that contains the alignment, although the same filename should then be specified on both the datafname and streefname lines.
        *If multiple trees appear in the specified file and multiple search replicates are specified (see '''[[GARLI_Configuration_Settings#searchreps_.28number_of_independent_search_replicates.29|searchreps]]''' setting), then the first tree is used in the first replicate, the second in the second replicate, etc.  
+
*If multiple trees appear in the specified file and multiple search replicates are specified (see '''[[GARLI_Configuration_Settings#searchreps_.28number_of_independent_search_replicates.29|searchreps]]''' setting), then the first tree is used in the first replicate, the second in the second replicate, etc.  
        *Providing model parameter values: see this page '''[[Specifying_model_parameter_values | Specifying model parameter values]]'''
+
*Providing model parameter values: see this page '''[[Specifying_model_parameter_values | Specifying model parameter values]]'''
        *See also the FAQ items on model parameters '''[[FAQ#Model_parameters | here]]'''.
+
*See also the FAQ items on model parameters '''[[Garli_FAQ#Model_parameters | here]]'''.
  
        ===attachmentspertaxon (control creation of stepwise addition starting tree)===
+
===attachmentspertaxon (control creation of stepwise addition starting tree)===
        '''attachmentspertaxon''' = (1 to infinity, '''50''') – The number of attachment branches evaluated for each taxon to be added to the tree during the creation of an ML stepwise-addition starting tree.  Briefly, stepwise addition is an algorithm used to make a tree, and involves adding taxa in a random order to a growing tree.  For each taxon to be added, a number of randomly chosen attachment branches are tried and scored, and then the best scoring one is chosen as the location of that taxon.  The attachmentspertaxon setting controls how many attachment points are evaluated for each taxon to be added.  A value of one is equivalent to a completely random tree (only one randomly chosen location is evaluated).  A value of greater than 2 times the number of taxa in the dataset means that all attachment points will be evaluated for each taxon, and will result in very good starting trees (but may take a while on large datasets).  Even fairly small values (< 10) can result in starting trees that are much, much better than random, but still fairly different from one another.  
+
'''attachmentspertaxon''' = (1 to infinity, '''50''') – The number of attachment branches evaluated for each taxon to be added to the tree during the creation of an ML stepwise-addition starting tree.  Briefly, stepwise addition is an algorithm used to make a tree, and involves adding taxa in a random order to a growing tree.  For each taxon to be added, a number of randomly chosen attachment branches are tried and scored, and then the best scoring one is chosen as the location of that taxon.  The attachmentspertaxon setting controls how many attachment points are evaluated for each taxon to be added.  A value of one is equivalent to a completely random tree (only one randomly chosen location is evaluated).  A value of greater than 2 times the number of taxa in the dataset means that all attachment points will be evaluated for each taxon, and will result in very good starting trees (but may take a while on large datasets).  Even fairly small values (< 10) can result in starting trees that are much, much better than random, but still fairly different from one another.  
        ===ofprefix (output filename prefix)===
+
===ofprefix (output filename prefix)===
        '''ofprefix''' = (text) – Prefix of all output filenames, such as log, treelog, etc.  Change this for each run that you do or the program will overwrite previous results.  
+
'''ofprefix''' = (text) – Prefix of all output filenames, such as log, treelog, etc.  Change this for each run that you do or the program will overwrite previous results.  
        ===randseed (random number seed)===
+
===randseed (random number seed)===
        '''randseed''' = (-1 or positive integers, '''-1''') – The random number seed used by the random number generator.  Specify “–1” to have a seed chosen for you.  Specifying the same seed number in multiple runs will give exactly identical results, if all other parameters and settings are also identical.  
+
'''randseed''' = (-1 or positive integers, '''-1''') – The random number seed used by the random number generator.  Specify “–1” to have a seed chosen for you.  Specifying the same seed number in multiple runs will give exactly identical results, if all other parameters and settings are also identical.  
        ===availablemememory (control maximum program memory usage)===
+
===availablemememory (control maximum program memory usage)===
        '''availablemememory''' – Typically this is the amount of available physical memory on the system, in megabytes.  This lets GARLI determine how much system memory it may be able to use to store computations for reuse.  The program will be conservative and use at most about 90% of this value, although for typical datasets it will use much, much less.  If other programs must be open or used when GARLI is running, you may need to reduce this value. This setting can also have a significant effect on performance (speed), but more is not always better.  When a run is started, GARLI will output the '''availablememory''' value necessary for that dataset to achieve each of the “memory levels” (from best to worst, termed “great”, “good”, “low”, and “very low”).  More memory is generally better because more calculations are stored and can be reused, but when the amount of memory needed for “great” becomes more than 512 megabytes or so, performance can be slowed because the operating system has difficulty managing that much memory.  In general, chose an amount of memory that allows “great” when this is less than 512 MB, and if it is greater reduce the amount of memory into “good” or “low” as necessary.  Avoid “very low” whenever possible.  You can find the value is approximately optimal for your dataset by setting the '''randseed''' to some  
+
'''availablemememory''' – Typically this is the amount of available physical memory on the system, in megabytes.  This lets GARLI determine how much system memory it may be able to use to store computations for reuse.  The program will be conservative and use at most about 90% of this value, although for typical datasets it will use much, much less.  If other programs must be open or used when GARLI is running, you may need to reduce this value. This setting can also have a significant effect on performance (speed), but more is not always better.  When a run is started, GARLI will output the '''availablememory''' value necessary for that dataset to achieve each of the “memory levels” (from best to worst, termed “great”, “good”, “low”, and “very low”).  More memory is generally better because more calculations are stored and can be reused, but when the amount of memory needed for “great” becomes more than 512 megabytes or so, performance can be slowed because the operating system has difficulty managing that much memory.  In general, chose an amount of memory that allows “great” when this is less than 512 MB, and if it is greater reduce the amount of memory into “good” or “low” as necessary.  Avoid “very low” whenever possible.  You can find the value is approximately optimal for your dataset by setting the '''randseed''' to some  
        positive value (so that the searches are identical) and doing runs with various '''availablememory''' values.  Typically it will only make at most a 30% difference, so it isn't worth worrying about too much.  
+
positive value (so that the searches are identical) and doing runs with various '''availablememory''' values.  Typically it will only make at most a 30% difference, so it isn't worth worrying about too much.  
        ===logevery (frequency to log best score to file)===
+
===logevery (frequency to log best score to file)===
        '''logevery''' = (1 to infinity, '''10''') – The frequency at which the best score is written to the log file.  
+
'''logevery''' = (1 to infinity, '''10''') – The frequency at which the best score is written to the log file.  
        ===saveevery (frequency to save best tree to file or write checkpoints)===
+
===saveevery (frequency to save best tree to file or write checkpoints)===
        '''saveevery''' = (1 to infinity, '''100''') – If '''writecheckpoints''' or '''outputcurrentbesttopology''' are specified, this is the frequency (in generations) at which checkpoints or the current best tree are written to file.  
+
'''saveevery''' = (1 to infinity, '''100''') – If '''writecheckpoints''' or '''outputcurrentbesttopology''' are specified, this is the frequency (in generations) at which checkpoints or the current best tree are written to file.  
        ===refinestart (whether to optimize a bit before starting a search)===
+
===refinestart (whether to optimize a bit before starting a search)===
        '''refinestart''' = (0 or 1, '''1''') – Specifies whether some initial rough optimization is performed on the starting branch lengths and rate heterogeneity parameters.  This is always recommended.  
+
'''refinestart''' = (0 or 1, '''1''') – Specifies whether some initial rough optimization is performed on the starting branch lengths and rate heterogeneity parameters.  This is always recommended.  
        ===outputcurrentbesttopology (continuously write the best tree to file during a run)===
+
===outputcurrentbesttopology (continuously write the best tree to file during a run)===
        '''outputcurrentbesttopology''' = (0 or 1, '''0''') – If true, the current best tree of the current search replicate is written to <ofprefix>.best.current.tre every '''saveevery''' generations.  In versions before 0.96 the current best topology was always written to file, but that is no longer the case. Seeing the current best tree has no real use apart from satisfying your curiosity about how a  
+
'''outputcurrentbesttopology''' = (0 or 1, '''0''') – If true, the current best tree of the current search replicate is written to <ofprefix>.best.current.tre every '''saveevery''' generations.  In versions before 0.96 the current best topology was always written to file, but that is no longer the case. Seeing the current best tree has no real use apart from satisfying your curiosity about how a  
        run is going.
+
run is going.
        ===outputeachbettertopology (write each improved topology to file)===
+
===outputeachbettertopology (write each improved topology to file)===
        '''outputeachbettertopology''' (0 or 1, '''0''') – If true, each new topology encountered with a better score than the previous best is written to file.  In some cases this can result in really big files (hundreds of MB) though, especially for random starting topologies on large datasets.  Note that this file is interesting to get an idea of how the topology changed as the searches progressed, but the collection of trees should NOT be interpreted in any meaningful way.  This option is not available while bootstrapping.  
+
'''outputeachbettertopology''' (0 or 1, '''0''') – If true, each new topology encountered with a better score than the previous best is written to file.  In some cases this can result in really big files (hundreds of MB) though, especially for random starting topologies on large datasets.  Note that this file is interesting to get an idea of how the topology changed as the searches progressed, but the collection of trees should NOT be interpreted in any meaningful way.  This option is not available while bootstrapping.  
        ===enforcetermconditions (use automatic termination)===
+
===enforcetermconditions (use automatic termination)===
        '''enforcetermconditions''' = (0 or 1, '''1''') – Specifies whether the automatic termination conditions will be used.  The conditions specified by both of the following two parameters must be met.  See the following two parameters for their definitions.  If this is false, the run will continue until it reaches the time ('''stoptime''') or generation ('''stopgen'') limit.  It is highly recommended that this option be used!  
+
'''enforcetermconditions''' = (0 or 1, '''1''') – Specifies whether the automatic termination conditions will be used.  The conditions specified by both of the following two parameters must be met.  See the following two parameters for their definitions.  If this is false, the run will continue until it reaches the time ('''stoptime''') or generation ('''stopgen'') limit.  It is highly recommended that this option be used!  
        ===genthreshfortopoterm (number of generations without topology improvement required for termination) ===
+
===genthreshfortopoterm (number of generations without topology improvement required for termination) ===
        '''genthreshfortopoterm''' = (1 to infinity, '''20,000''') – This specifies the first part of the termination condition.  When no new significantly better scoring topology (see significanttopochange below) has been encountered in greater thanthis number of generations, this condition is met. Increasing this parameter may improve the lnL scores obtained (especially on large datasets), but will also increase runtimes.  
+
'''genthreshfortopoterm''' = (1 to infinity, '''20,000''') – This specifies the first part of the termination condition.  When no new significantly better scoring topology (see significanttopochange below) has been encountered in greater thanthis number of generations, this condition is met. Increasing this parameter may improve the lnL scores obtained (especially on large datasets), but will also increase runtimes.  
        ===scorethreshforterm (max score improvement over recent generations required for termination)===
+
===scorethreshforterm (max score improvement over recent generations required for termination)===
        '''scorethreshforterm''' = (0 to infinity, '''0.05''') – The second part of the termination condition.  When the total improvement in score over the last '''intervallength''' x '''intervalstostore''' generations (default is 500 generations, see below) is less than this value, this condition is met.  This does not usually need to be changed.  
+
'''scorethreshforterm''' = (0 to infinity, '''0.05''') – The second part of the termination condition.  When the total improvement in score over the last '''intervallength''' x '''intervalstostore''' generations (default is 500 generations, see below) is less than this value, this condition is met.  This does not usually need to be changed.  
        ===significanttopochange (required score improvement for topology to be considered better)===
+
===significanttopochange (required score improvement for topology to be considered better)===
        '''significanttopochange''' = (0 to infinity, '''0.01''') – The lnL increase required for a new topology to be  
+
'''significanttopochange''' = (0 to infinity, '''0.01''') – The lnL increase required for a new topology to be  
        considered significant as far as the termination condition is concerned. It probably doesn’t  
+
considered significant as far as the termination condition is concerned. It probably doesn’t  
        need to be played with, but you might try increasing it slightly if your runs reach a stable  
+
need to be played with, but you might try increasing it slightly if your runs reach a stable  
        score and then take a very long time to terminate due to very minor changes in topology.  
+
score and then take a very long time to terminate due to very minor changes in topology.  
        ===outputphyliptree (write trees to file in Phylip as well as Nexus format)===
+
===outputphyliptree (write trees to file in Phylip as well as Nexus format)===
        '''outputphyliptree''' = (0 or 1, '''0''') – Whether a phylip formatted tree files will be output in addition to  
+
'''outputphyliptree''' = (0 or 1, '''0''') – Whether a phylip formatted tree files will be output in addition to  
        the default nexus files for the best tree across all replicates (<ofprefix>.best.phy), the best  
+
the default nexus files for the best tree across all replicates (<ofprefix>.best.phy), the best  
        tree for each replicate (<ofprefix>.best.all.phy) or in the case of bootstrapping, the best tree  
+
tree for each replicate (<ofprefix>.best.all.phy) or in the case of bootstrapping, the best tree  
        for each bootstrap replicate (<ofprefix.boot.phy>.  
+
for each bootstrap replicate (<ofprefix.boot.phy>.  
        ===outputmostlyuselessfiles (output uninteresting files)===
+
===outputmostlyuselessfiles (output uninteresting files)===
        '''outputmostlyuselessfiles''' = (0 or 1, '''0''') – Whether to output three files of little general interest: the  
+
'''outputmostlyuselessfiles''' = (0 or 1, '''0''') – Whether to output three files of little general interest: the  
        “fate”, “problog” and “swaplog” files.  The fate file shows the parentage, mutation types and  
+
“fate”, “problog” and “swaplog” files.  The fate file shows the parentage, mutation types and  
        scores of every individual in the population during the entire search.  The problog shows how  
+
scores of every individual in the population during the entire search.  The problog shows how  
        the proportions of the different mutation types changed over the course of the run.  The  
+
the proportions of the different mutation types changed over the course of the run.  The  
        swaplog shows the number of unique swaps and the number of total swaps on the current  
+
swaplog shows the number of unique swaps and the number of total swaps on the current  
        best tree over the course of the run.  
+
best tree over the course of the run.  
        ===writecheckpoints (write checkpoint files during run)===
+
===writecheckpoints (write checkpoint files during run)===
        '''writecheckpoints''' (0 or 1, '''0''') – Whether to write three files to disk containing all information  
+
'''writecheckpoints''' (0 or 1, '''0''') – Whether to write three files to disk containing all information  
        about the current state of the population every saveevery generations, with each successive  
+
about the current state of the population every saveevery generations, with each successive  
        checkpoint overwriting the previous one.  These files can be used to restart a run at the last  
+
checkpoint overwriting the previous one.  These files can be used to restart a run at the last  
        written checkpoint by setting the '''restart''' configuration entry.
+
written checkpoint by setting the '''restart''' configuration entry.
        ===restart (restart run from checkpoint)===
+
===restart (restart run from checkpoint)===
        '''restart''' = (0 or 1, '''0''') – Whether to restart at a previously saved checkpoint.  To use this option the '''writecheckpoints''' option must have been used during a previous run.  The program will look for checkpoint files that are named based on the ofprefix of the previous run.  If you intend to restart a run, NOTHING should be changed in the config file except setting '''restart''' to 1.  
+
'''restart''' = (0 or 1, '''0''') – Whether to restart at a previously saved checkpoint.  To use this option the '''writecheckpoints''' option must have been used during a previous run.  The program will look for checkpoint files that are named based on the ofprefix of the previous run.  If you intend to restart a run, NOTHING should be changed in the config file except setting '''restart''' to 1.  
        A run that is restarted from checkpoint will give ''exactly'' the same results it would have if the run had gone to completion.  
+
A run that is restarted from checkpoint will give ''exactly'' the same results it would have if the run had gone to completion.  
        ===outgroup (orient inferred trees consistently)===
+
===outgroup (orient inferred trees consistently)===
        '''outgroup''' = (ougroup taxa numbers, separated by spaces) – This option allow for orienting the tree topologies in a consistent way when they are written to file.  Note that this has NO effect whatsoever on the actual inference and the specified outgroup is NOT constrained to be present in the inferred trees.  If multiple outgroup taxa are specified and they do not form a monophyletic group in the inferred tree, this setting will be ignored.  If you specify a single outgroup taxon it will always be present, and the tree will always be consistently oriented.  Ranges can be indicated with a hyphen.  e.g., to specify an outgroup consisting of taxa 1, 2, 3 and 5 the format is this:  
+
'''outgroup''' = (ougroup taxa numbers, separated by spaces) – This option allow for orienting the tree topologies in a consistent way when they are written to file.  Note that this has NO effect whatsoever on the actual inference and the specified outgroup is NOT constrained to be present in the inferred trees.  If multiple outgroup taxa are specified and they do not form a monophyletic group in the inferred tree, this setting will be ignored.  If you specify a single outgroup taxon it will always be present, and the tree will always be consistently oriented.  Ranges can be indicated with a hyphen.  e.g., to specify an outgroup consisting of taxa 1, 2, 3 and 5 the format is this:  
          outgroup = 1-3 5
+
outgroup = 1-3 5
  
          ===searchreps (number of independent search replicates)===
+
===searchreps (number of independent search replicates)===
          '''searchreps''' = (1 to infinity, '''2''') – The number of independent search replicates to perform during a program execution.  You should always either do multiple search replicates or multiple program executions with any dataset to get a feel for whether you are getting consistent results, which suggests that the program is doing a decent job of searching.  Note that if this is > 1 and you are performing a bootstrap analysis, this is the number of search replicates to be done per bootstrap replicate.  That can increase the chance of finding the best tree per bootstrap replicate, but will also increase bootstrap runtimes enormously.
+
'''searchreps''' = (1 to infinity, '''2''') – The number of independent search replicates to perform during a program execution.  You should always either do multiple search replicates or multiple program executions with any dataset to get a feel for whether you are getting consistent results, which suggests that the program is doing a decent job of searching.  Note that if this is > 1 and you are performing a bootstrap analysis, this is the number of search replicates to be done per bootstrap replicate.  That can increase the chance of finding the best tree per bootstrap replicate, but will also increase bootstrap runtimes enormously.
          ===bootstrapreps (number of bootstrap replicates)===
+
===bootstrapreps (number of bootstrap replicates)===
          bootstrapreps (0 to infinity, '''0''') - The number of bootstrap reps to perform.  If this is greater than  
+
bootstrapreps (0 to infinity, '''0''') - The number of bootstrap reps to perform.  If this is greater than  
          0, normal searching will not be performed.  The resulting bootstrap trees (one per rep) will be  
+
0, normal searching will not be performed.  The resulting bootstrap trees (one per rep) will be  
          output to a file named <ofprefix>.boot.tre.  To obtain the bootstrap proportions they will then  
+
output to a file named <ofprefix>.boot.tre.  To obtain the bootstrap proportions they will then  
          need to be read into PAUP* or a similar program to obtain a majority rule consensus.  Note  
+
need to be read into PAUP* or a similar program to obtain a majority rule consensus.  Note  
          that it is probably safe to reduce the strictness of the termination conditions during  
+
that it is probably safe to reduce the strictness of the termination conditions during  
          bootstrapping (perhaps halve genthreshfortopoterm), which will greatly speed up the  
+
bootstrapping (perhaps halve genthreshfortopoterm), which will greatly speed up the  
          bootstrapping process with negligible effects on the results.
+
bootstrapping process with negligible effects on the results.
  
          Note that GARLI does NOT do the bootstrap consensus or calculate the bootstrap proportions itself.  It simply infers the trees and are the input to that consensus.  The trees in the .boot.tre file will need to be read into a program such as SumTrees (or PAUP* or CONSENSE) to do a majority-rule consensus and obtain your bootstrap support values. See the following part of the "Advanced topics" page for suggestions on making the consensus: '''[[Advanced_topics#Detailed_Example:_A_bootstrap_analysis|Detailed Example: A bootstrap analysis]]'''.
+
Note that GARLI does NOT do the bootstrap consensus or calculate the bootstrap proportions itself.  It simply infers the trees and are the input to that consensus.  The trees in the .boot.tre file will need to be read into a program such as SumTrees (or PAUP* or CONSENSE) to do a majority-rule consensus and obtain your bootstrap support values. See the following part of the "Advanced topics" page for suggestions on making the consensus: '''[[Garli_Advanced_topics#Detailed_Example:_A_bootstrap_analysis|Detailed Example: A bootstrap analysis]]'''.
  
          ===resampleproportion (relative size of re-sampled data matrix)===
+
===resampleproportion (relative size of re-sampled data matrix)===
          resampleproportion (0.1 to 10, '''1.0''' ) – When bootstrapreps > 0, this setting allows for     
+
resampleproportion (0.1 to 10, '''1.0''' ) – When bootstrapreps > 0, this setting allows for     
          bootstrap-like resampling, but with the psuedoreplicate datasets having the number of  
+
bootstrap-like resampling, but with the psuedoreplicate datasets having the number of  
          alignment columns different from the real data.  Setting values < 1.0 is somewhat similar to jackknifing, but not identical.  
+
alignment columns different from the real data.  Setting values < 1.0 is somewhat similar to jackknifing, but not identical.  
          ===inferinternalstateprobs (infer ancestral states)===
+
===inferinternalstateprobs (infer ancestral states)===
          inferinternalstateprobs = (0 or 1, '''0''') – Specify 1 to have GARLI infer the marginal posterior  
+
inferinternalstateprobs = (0 or 1, '''0''') – Specify 1 to have GARLI infer the marginal posterior  
          probability of each character at each internal node.  This is done at the very end of the run,  
+
probability of each character at each internal node.  This is done at the very end of the run,  
          just before termination.  The results are output to a file named <ofprefix>.internalstates.log.
+
just before termination.  The results are output to a file named <ofprefix>.internalstates.log.
  
          ===outputsitelikelihoods (write a file with the log-likelihood of each site)===
+
===outputsitelikelihoods (write a file with the log-likelihood of each site)===
  
          '''outputsitelikelihoods''' = (0 or 1, '''0''') - Causes a file named <ofprefix>.sitelikes.log to be created containing the sitewise log-likelihood values for each individual site for the final tree of each search replicate.  Note that the format of the file is exactly the same as that output by PAUP, so it can be directly used in CONSEL using the PAUP file-format option.  For partitioned models the sites are listed in sets by partition subset, but the site numbers will match those in the original datamatrix.  Thus, when using a partitioned model that divides site by codon position, the ordering would be 1, 4, 7, ... 2, 5, 8, ... 3, 6, 9 ....  Note that this makes no difference to CONSEL, which just assumes the the sitelikelihoods are ordered the same for each tree and ignores the site numbers.   
+
'''outputsitelikelihoods''' = (0 or 1, '''0''') - Causes a file named <ofprefix>.sitelikes.log to be created containing the sitewise log-likelihood values for each individual site for the final tree of each search replicate.  Note that the format of the file is exactly the same as that output by PAUP, so it can be directly used in CONSEL using the PAUP file-format option.  For partitioned models the sites are listed in sets by partition subset, but the site numbers will match those in the original datamatrix.  Thus, when using a partitioned model that divides site by codon position, the ordering would be 1, 4, 7, ... 2, 5, 8, ... 3, 6, 9 ....  Note that this makes no difference to CONSEL, which just assumes the the sitelikelihoods are ordered the same for each tree and ignores the site numbers.   
  
          Also note that using the site likelihoods from a partitioned model is a violation of CONSEL's assumptions, since it will not know about the partitions and its internal bootstrap resampling will not obey them.  It isn't clear what the effects of this will be on the various tests.   
+
Also note that using the site likelihoods from a partitioned model is a violation of CONSEL's assumptions, since it will not know about the partitions and its internal bootstrap resampling will not obey them.  It isn't clear what the effects of this will be on the various tests.   
  
          Finally, if you want to calculate the site likelihoods for a set of trees that you provide, use the '''[[GARLI_Configuration_Settings#optimizeinputonly_.28do_not_search.2C_only_optimize_model_and_branch_lengths_on_user_trees.29 | optimizeinputonly]]''' setting.
+
Finally, if you want to calculate the site likelihoods for a set of trees that you provide, use the '''[[GARLI_Configuration_Settings#optimizeinputonly_.28do_not_search.2C_only_optimize_model_and_branch_lengths_on_user_trees.29 | optimizeinputonly]]''' setting.
  
          ===optimizeinputonly (do not search, only optimize model and branch lengths on user trees)===
+
===optimizeinputonly (do not search, only optimize model and branch lengths on user trees)===
          (new in version 2.0)
+
(new in version 2.0)
  
          '''optimizeinputonly''' = (0 or 1, '''0''') - Requires a NEXUS formatted input tree file (only NEXUS format will work!), specified through the '''[[GARLI_Configuration_Settings#streefname_.28source_of_starting_tree_and.2For_model.29 | streefname]]''' setting.  All trees in that file will have model parameters and branch lengths optimized, giving their maximum likelihood scores.  A file with the site-likelihoods of each tree will also be output.  See the '''[[GARLI_Configuration_Settings#outputsitelikelihoods_.28write_a_file_with_the_log-likelihood_of_each_site.29 | outputsitelikelihoods]]''' setting for details.
+
'''optimizeinputonly''' = (0 or 1, '''0''') - Requires a NEXUS formatted input tree file (only NEXUS format will work!), specified through the '''[[GARLI_Configuration_Settings#streefname_.28source_of_starting_tree_and.2For_model.29 | streefname]]''' setting.  All trees in that file will have model parameters and branch lengths optimized, giving their maximum likelihood scores.  A file with the site-likelihoods of each tree will also be output.  See the '''[[GARLI_Configuration_Settings#outputsitelikelihoods_.28write_a_file_with_the_log-likelihood_of_each_site.29 | outputsitelikelihoods]]''' setting for details.
  
          ===collapsebranches (collapse zero length branches before writing final trees to file)===
+
===collapsebranches (collapse zero length branches before writing final trees to file)===
  
          '''collapsebranches''' = (0 or 1, '''1''') - Before version 1.0, all trees that are returned were fully resolved. This is true even if the maximum-likelihood estimate of some internal branch lengths are effectively zero (or GARLI's minimum, which is 1e-8).  In such cases, collapsing the branch into a polytomy would be a better representation. Note that GARLI will never return a tree with an actual branch length of zero, but rather with its minimum value of 1.0e-8. The drawback of always returning fully resolved trees is that what is effectively a polytomy can be resolved in three ways, and different independent searches may randomly return one of those resolutions. Thus, if you compare the trees by topology only, they will look different. If you pay attention to the branch lengths and likelihood scores of the trees it will be apparent that they are effectively the same.
+
'''collapsebranches''' = (0 or 1, '''1''') - Before version 1.0, all trees that are returned were fully resolved. This is true even if the maximum-likelihood estimate of some internal branch lengths are effectively zero (or GARLI's minimum, which is 1e-8).  In such cases, collapsing the branch into a polytomy would be a better representation. Note that GARLI will never return a tree with an actual branch length of zero, but rather with its minimum value of 1.0e-8. The drawback of always returning fully resolved trees is that what is effectively a polytomy can be resolved in three ways, and different independent searches may randomly return one of those resolutions. Thus, if you compare the trees by topology only, they will look different. If you pay attention to the branch lengths and likelihood scores of the trees it will be apparent that they are effectively the same.
  
          I think that collapsing of branches is particularly important when bootstrapping, since no support should be given to a branch that doesn't really exist, i.e., that is a random resolution of a polytomy.  Collapsing is also good when calculating tree to tree distances such as the symmetric tree distance, for example when calculating phylogenetic error to a known target tree.  Zero-length branches would add to the distances (~error) although they really should not.
+
I think that collapsing of branches is particularly important when bootstrapping, since no support should be given to a branch that doesn't really exist, i.e., that is a random resolution of a polytomy.  Collapsing is also good when calculating tree to tree distances such as the symmetric tree distance, for example when calculating phylogenetic error to a known target tree.  Zero-length branches would add to the distances (~error) although they really should not.
  
          ==Model specification settings==
+
==Model specification settings==
  
          With version 1.0 and later there are now many more options dealing with model specification because of  
+
With version 1.0 and later there are now many more options dealing with model specification because of  
          the inclusion of amino acid and codon-based models.  The description of the settings will be  
+
the inclusion of amino acid and codon-based models.  The description of the settings will be  
          broken up by data type.  Note that in terms of the model settings in GARLI, “empirical” means  
+
broken up by data type.  Note that in terms of the model settings in GARLI, “empirical” means  
          to fix parameter values at those observed in the dataset being analyzed, and “fixed” means to fix  
+
to fix parameter values at those observed in the dataset being analyzed, and “fixed” means to fix  
          them at user specified values.  See the '''[[GARLI_Configuration_Settings#streefname_.28source_of_starting_tree_and.2For_model.29|streefname]]''' setting for details on how to provide  
+
them at user specified values.  See the '''[[GARLI_Configuration_Settings#streefname_.28source_of_starting_tree_and.2For_model.29|streefname]]''' setting for details on how to provide  
          parameter values to be fixed during inference.
+
parameter values to be fixed during inference.
  
          '''PARTITIONED MODELS: To use partitioned models you'll still need to use the same basic model settings detailed below for each individual partition subset, and then some other details to set up the partition model itself.  Be sure that you are familiar with the rest of this section, then see [[Using_partitioned_models | Using partitioned models]].'''
+
'''PARTITIONED MODELS: To use partitioned models you'll still need to use the same basic model settings detailed below for each individual partition subset, and then some other details to set up the partition model itself.  Be sure that you are familiar with the rest of this section, then see [[Using_partitioned_models | Using partitioned models]].'''
  
          ===datatype (sequence type and inference model)===  
+
===datatype (sequence type and inference model)===  
          '''datatype''' = ('''nucleotide''', aminoacid, codon-aminoacid, codon, standard, standardordered, standardvariable, standardvariableordered) – The type of data and model that is  
+
'''datatype''' = ('''nucleotide''', aminoacid, codon-aminoacid, codon, standard, standardordered, standardvariable, standardvariableordered) – The type of data and model that is  
          to be used during tree inference.  Nucleotide and amino acid data are self explanatory.
+
to be used during tree inference.  Nucleotide and amino acid data are self explanatory.
  
          The codon-aminoacid datatype means that the data will be  
+
The codon-aminoacid datatype means that the data will be  
          supplied as a nucleotide alignment, but will be internally translated and analyzed using an  
+
supplied as a nucleotide alignment, but will be internally translated and analyzed using an  
          amino acid model.  The codon and codon-aminoacid datatypes require nucleotide sequence  
+
amino acid model.  The codon and codon-aminoacid datatypes require nucleotide sequence  
          that is aligned in the correct reading frame. In other words, all gaps in the alignment should  
+
that is aligned in the correct reading frame. In other words, all gaps in the alignment should  
          be a multiple of 3 in length, and the alignment should start at the first position of a codon.  If  
+
be a multiple of 3 in length, and the alignment should start at the first position of a codon.  If  
          the alignment has extra columns at the start, middle or end, they should be removed or  
+
the alignment has extra columns at the start, middle or end, they should be removed or  
          excluded with a Nexus exset (see '''[[FAQ#Can_I_specify_alignment_columns_of_my_data_matrix_to_be_excluded.3F | this FAQ item]]''' for an example of exset usage).  The correct  
+
excluded with a Nexus exset (see '''[[Garli_FAQ#Can_I_specify_alignment_columns_of_my_data_matrix_to_be_excluded.3F | this FAQ item]]''' for an example of exset usage).  The correct  
          '''[[GARLI_Configuration_Settings#geneticcode_.28code_to_use_in_codon_translation.29 | geneticcode]]''' must also be set.
+
'''[[GARLI_Configuration_Settings#geneticcode_.28code_to_use_in_codon_translation.29 | geneticcode]]''' must also be set.
  
          (New in Version 2.0)
+
(New in Version 2.0)
  
          The various "standard" datatypes are new in GARLI 2.0.  These represent morphology-like discrete characters, with any number of states.  These are also termed the "Mk" and "Mkv" models by Lewis (2001). See this page for more details on using standard data: '''[[Mkv morphology model]]'''.
+
The various "standard" datatypes are new in GARLI 2.0.  These represent morphology-like discrete characters, with any number of states.  These are also termed the "Mk" and "Mkv" models by Lewis (2001). See this page for more details on using standard data: '''[[Garli_Mkv morphology model]]'''.
  
          ===Settings for datatype = nucleotide===  
+
===Settings for datatype = nucleotide===  
          ====ratematrix (relative rate parameters assumed by substitution model)====
+
====ratematrix (relative rate parameters assumed by substitution model)====
          '''ratematrix''' = (1rate, 2rate, '''6rate''', fixed, custom string) – The number of relative substitution rate  
+
'''ratematrix''' = (1rate, 2rate, '''6rate''', fixed, custom string) – The number of relative substitution rate  
          parameters (note that the number of free parameters is this value minus one).  Equivalent to  
+
parameters (note that the number of free parameters is this value minus one).  Equivalent to  
          the “nst” setting in PAUP* and MrBayes.  1rate assumes that substitutions between all pairs  
+
the “nst” setting in PAUP* and MrBayes.  1rate assumes that substitutions between all pairs  
          of nucleotides occur at the same rate (JC model), 2rate allows different rates for transitions and  
+
of nucleotides occur at the same rate (JC model), 2rate allows different rates for transitions and  
          transversions (K2P or HKY models), and 6rate allows a different rate between each nucleotide pair (GTR).  These rates are  
+
transversions (K2P or HKY models), and 6rate allows a different rate between each nucleotide pair (GTR).  These rates are  
          estimated unless the fixed option is chosen.  Since version 0.96, parameters for any  
+
estimated unless the fixed option is chosen.  Since version 0.96, parameters for any  
          submodel of the GTR model may be estimated.  The format for specifying this is very  
+
submodel of the GTR model may be estimated.  The format for specifying this is very  
          similar to that used in the “rclass’ setting of PAUP*.  Within parentheses, six letters are  
+
similar to that used in the “rclass’ setting of PAUP*.  Within parentheses, six letters are  
          specified, with spaces between them.  The six letters represent the rates of substitution  
+
specified, with spaces between them.  The six letters represent the rates of substitution  
          between the six pairs of nucleotides, with the order being A-C, A-G, A-T, C-G, C-T and G-T.  
+
between the six pairs of nucleotides, with the order being A-C, A-G, A-T, C-G, C-T and G-T.  
          Letters within the parentheses that are the same mean that a single parameter is shared by  
+
Letters within the parentheses that are the same mean that a single parameter is shared by  
          multiple nucleotide pairs.  For example,  
+
multiple nucleotide pairs.  For example,  
          ratematrix = (a b a a b a)  
+
ratematrix = (a b a a b a)  
          would specify the HKY 2-rate model (equivalent to ratematrix = 2rate).  This entry,  
+
would specify the HKY 2-rate model (equivalent to ratematrix = 2rate).  This entry,  
            ratematrix = (a b c c b a)  
+
ratematrix = (a b c c b a)
            would specify 3 estimated rates of subtitution, with one rate shared by A-C and G-T  
+
would specify 3 estimated rates of subtitution, with one rate shared by A-C and G-T  
            substitutions, another rate shared by A-G and C-T substitutions, and the final rate shared by  
+
substitutions, another rate shared by A-G and C-T substitutions, and the final rate shared by  
            A-T and C-G substitutions.
+
A-T and C-G substitutions.
  
            ====statefrequencies (equilibrium base frequencies assumed by substitution model)====
+
====statefrequencies (equilibrium base frequencies assumed by substitution model)====
            '''statefrequencies''' = (equal, empirical, '''estimate''', fixed) – Specifies how the equilibrium state  
+
'''statefrequencies''' = (equal, empirical, '''estimate''', fixed) – Specifies how the equilibrium state  
            frequencies (A, C, G and T) are treated.  The empirical setting fixes the frequencies at their  
+
frequencies (A, C, G and T) are treated.  The empirical setting fixes the frequencies at their  
            observed proportions, and the other options should be self-explanatory.  
+
observed proportions, and the other options should be self-explanatory.  
            ===For datatype = nucleotide or aminoacid===
+
===For datatype = nucleotide or aminoacid===
            ====invariantsites (treatment of proportion of invariable sites parameter)====
+
====invariantsites (treatment of proportion of invariable sites parameter)====
            '''invariantsites''' = (none, '''estimate''', fixed) – Specifies whether a parameter representing the  
+
'''invariantsites''' = (none, '''estimate''', fixed) – Specifies whether a parameter representing the  
            proportion of sites that are unable to change (i.e. have a substitution rate of zero) will be  
+
proportion of sites that are unable to change (i.e. have a substitution rate of zero) will be  
            included.  This is typically referred to as “invariant sites”, but would better be termed  
+
included.  This is typically referred to as “invariant sites”, but would better be termed  
            “invariable sites”.  
+
“invariable sites”.  
            ====ratehetmodel (type of rate heterogeneity to assume for variable sites)====
+
====ratehetmodel (type of rate heterogeneity to assume for variable sites)====
            '''ratehetmodel''' = (none, '''gamma''', gammafixed) – The model of rate heterogeneity assumed.  
+
'''ratehetmodel''' = (none, '''gamma''', gammafixed) – The model of rate heterogeneity assumed.  
            “gammafixed” requires that the alpha shape parameter is provided, and a setting of “gamma”  
+
“gammafixed” requires that the alpha shape parameter is provided, and a setting of “gamma”  
            estimates it.  
+
estimates it.  
            ====numratecats (number of overall substitution rate categories)====  
+
====numratecats (number of overall substitution rate categories)====  
            '''numratecats''' = (1 to 20, '''4''') – The number of categories of variable rates (not including the  
+
'''numratecats''' = (1 to 20, '''4''') – The number of categories of variable rates (not including the  
            invariant site class if it is being used).  Must be set to 1 if '''ratehetmodel''' is set to none.  Note  
+
invariant site class if it is being used).  Must be set to 1 if '''ratehetmodel''' is set to none.  Note  
            that runtimes and memory usage scale linearly with this setting.  
+
that runtimes and memory usage scale linearly with this setting.  
            ===For datatype = aminoacid or codon-aminoacid===
+
===For datatype = aminoacid or codon-aminoacid===
            Amino acid analyses are typically done using fixed rate matrices that have been estimated on  
+
Amino acid analyses are typically done using fixed rate matrices that have been estimated on  
            large datasets and published.  Typically the only model parameters that are estimated during tree  
+
large datasets and published.  Typically the only model parameters that are estimated during tree  
            inference relate to the rate heterogeneity distribution.  Each of the named matrices also has  
+
inference relate to the rate heterogeneity distribution.  Each of the named matrices also has  
            corresponding fixed amino acid frequencies, and a given rate matrix can either be used with those  
+
corresponding fixed amino acid frequencies, and a given rate matrix can either be used with those  
            frequencies or with the amino acid frequencies observed in your dataset.  This second option is  
+
frequencies or with the amino acid frequencies observed in your dataset.  This second option is  
            often denoted as “+F” in a model description, although in terms of the GARLI configuration  
+
often denoted as “+F” in a model description, although in terms of the GARLI configuration  
            settings this is referred to as “empirical” frequencies.  In GARLI the Dayhoff model would be  
+
settings this is referred to as “empirical” frequencies.  In GARLI the Dayhoff model would be  
            specified by setting both the ratematrix and statefrequencies options to “dayhoff”.  The  
+
specified by setting both the ratematrix and statefrequencies options to “dayhoff”.  The  
            Dayhoff+F model would be specified by setting the ratematrix to “dayhoff”, and  
+
Dayhoff+F model would be specified by setting the ratematrix to “dayhoff”, and  
            statefrequencies to “empirical”.
+
statefrequencies to “empirical”.
  
            The following named amino acid models are implemented:  
+
The following named amino acid models are implemented:  
            {| border="1"
+
{| border="1"
            |-
+
|-
            !'''ratematrix'''/'''statefrequencies''' setting  !! reference  
+
!'''ratematrix'''/'''statefrequencies''' setting  !! reference  
            |-
+
|-
            |align="center" | dayhoff || Dayhoff, Schwartz and Orcutt. 1978.
+
|align="center" | dayhoff || Dayhoff, Schwartz and Orcutt. 1978.
            |-
+
|-
            |align="center" | jones || Jones, Taylor and Thornton (JTT), 1992.  
+
|align="center" | jones || Jones, Taylor and Thornton (JTT), 1992.  
            |-
+
|-
            |align="center" | WAG || Whelan and Goldman, 2001.
+
|align="center" | WAG || Whelan and Goldman, 2001.
            |-
+
|-
            |align="center" | mtREV || Adachi and Hasegawa, 1996.
+
|align="center" | mtREV || Adachi and Hasegawa, 1996.
            |-
+
|-
            |align="center" | mtmam || Yang, Nielsen and Hasegawa, 1998.
+
|align="center" | mtmam || Yang, Nielsen and Hasegawa, 1998.
            |}
+
|}
            Note that most programs allow either the use of a named rate matrix and its corresponding state  
+
Note that most programs allow either the use of a named rate matrix and its corresponding state  
            frequencies, or a named rate matrix and empirical frequencies.  GARLI technically allows the  
+
frequencies, or a named rate matrix and empirical frequencies.  GARLI technically allows the  
            mixing of different named matrices and equilibrium frequencies (for example, wag matrix with  
+
mixing of different named matrices and equilibrium frequencies (for example, wag matrix with  
            jones equilibrium frequencies), but this is not recommended.  
+
jones equilibrium frequencies), but this is not recommended.  
            ====ratematrix (amino acid substitution rates)====
+
====ratematrix (amino acid substitution rates)====
            '''ratematrix''' = (poisson, jones, dayhoff, wag, mtmam, mtrev) – The fixed amino acid rate matrix to  
+
'''ratematrix''' = (poisson, jones, dayhoff, wag, mtmam, mtrev) – The fixed amino acid rate matrix to  
            use.  You should use the matrix that gives the best likelihood, and could use a program like  
+
use.  You should use the matrix that gives the best likelihood, and could use a program like  
            PROTTEST (very much like MODELTEST, but for amino acid models) to determine which  
+
PROTTEST (very much like MODELTEST, but for amino acid models) to determine which  
            fits best for your data.  Poisson assumes a single rate of substitution between all amino acid  
+
fits best for your data.  Poisson assumes a single rate of substitution between all amino acid  
            pairs, and is a very poor model.
+
pairs, and is a very poor model.
            ====statefrequencies (equilibrium base frequencies assumed by substitution model)====
+
====statefrequencies (equilibrium base frequencies assumed by substitution model)====
            '''statefrequencies''' = (equal, empirical, estimate, fixed, jones, dayhoff, wag, mtmam, mtrev) –  
+
'''statefrequencies''' = (equal, empirical, estimate, fixed, jones, dayhoff, wag, mtmam, mtrev) –  
            Specifies how the equilibrium state frequencies of the 20 amino acids are treated.  The  
+
Specifies how the equilibrium state frequencies of the 20 amino acids are treated.  The  
            “empirical” option fixes the frequencies at their observed proportions (when describing a  
+
“empirical” option fixes the frequencies at their observed proportions (when describing a  
            model this is often termed “+F”).   
+
model this is often termed “+F”).   
            ===For datatype = codon===
+
===For datatype = codon===
            The codon models are built with three components: (1) parameters describing the process of  
+
The codon models are built with three components: (1) parameters describing the process of  
            individual nucleotide substitutions, (2) equilibrium codon frequencies, and (3) parameters  
+
individual nucleotide substitutions, (2) equilibrium codon frequencies, and (3) parameters  
            describing the relative rate of nonsynonymous to synonymous substitutions.  The nucleotide  
+
describing the relative rate of nonsynonymous to synonymous substitutions.  The nucleotide  
            substitution parameters within the codon models are exactly the same as those possible with  
+
substitution parameters within the codon models are exactly the same as those possible with  
            standard nucleotide models in GARLI, and are specified with the ratematrix configuration  
+
standard nucleotide models in GARLI, and are specified with the ratematrix configuration  
            entry.  Thus, they can be of the 2rate variety (inferring different rates for transitions and  
+
entry.  Thus, they can be of the 2rate variety (inferring different rates for transitions and  
            transversions, K2P or HKY-like), the 6rate variety (inferring different rates for all nucleotide  
+
transversions, K2P or HKY-like), the 6rate variety (inferring different rates for all nucleotide  
            pairs, GTR-like) or any other sub-model of GTR.  The options for codon frequencies are  
+
pairs, GTR-like) or any other sub-model of GTR.  The options for codon frequencies are  
            specified with the statefrequencies configuration entry.  The options are to use equal  
+
specified with the statefrequencies configuration entry.  The options are to use equal  
            frequencies (not a good option), the frequencies observed in your dataset (termed “empirical” in  
+
frequencies (not a good option), the frequencies observed in your dataset (termed “empirical” in  
            GARLI), or the codon frequencies implied by the “F1x4” or “F3x4” methods (using PAML's  
+
GARLI), or the codon frequencies implied by the “F1x4” or “F3x4” methods (using PAML's  
            terminology).  These last two options calculate the codon frequencies as the product of the  
+
terminology).  These last two options calculate the codon frequencies as the product of the  
            frequencies of the three nucleotides that make up each codon.  In the “F1x4” case the nucleotide  
+
frequencies of the three nucleotides that make up each codon.  In the “F1x4” case the nucleotide  
            frequencies are those observed in the dataset across all codon positions, while the “F3x4” option  
+
frequencies are those observed in the dataset across all codon positions, while the “F3x4” option  
            uses the nucleotide frequencies observed in the data at each codon position separately.  The final  
+
uses the nucleotide frequencies observed in the data at each codon position separately.  The final  
            component of the codon models is the nonsynonymous to synonymous relative rate parameters  
+
component of the codon models is the nonsynonymous to synonymous relative rate parameters  
            (aka dN/dS or omega parameters).  The default is to infer a single dN/dS value.  Alternatively, a  
+
(aka dN/dS or omega parameters).  The default is to infer a single dN/dS value.  Alternatively, a  
            model can be specified that infers a given number of dN/dS categories, with the dN/dS values  
+
model can be specified that infers a given number of dN/dS categories, with the dN/dS values  
            and proportions falling in each category estimated (ratehetmodel = nonsynonymous).  This is  
+
and proportions falling in each category estimated (ratehetmodel = nonsynonymous).  This is  
            the “discrete” or “M3” model in PAML's terminology.  
+
the “discrete” or “M3” model in PAML's terminology.  
            ====ratematrix (relative ''nucleotide'' rate parameters assumed by codon model)====
+
====ratematrix (relative ''nucleotide'' rate parameters assumed by codon model)====
            '''ratematrix''' = (1rate, '''2rate''', 6rate, fixed, custom string) – This determines the relative rates of  
+
'''ratematrix''' = (1rate, '''2rate''', 6rate, fixed, custom string) – This determines the relative rates of  
            nucleotide substitution assumed by the codon model.  The options are exactly the same as  
+
nucleotide substitution assumed by the codon model.  The options are exactly the same as  
            those allowed under a normal nucleotide model.  A codon model with '''ratematrix''' = 2rate  
+
those allowed under a normal nucleotide model.  A codon model with '''ratematrix''' = 2rate  
            specifies the standard Goldman and Yang (1994) model, with different substitution rates for  
+
specifies the standard Goldman and Yang (1994) model, with different substitution rates for  
            transitions and transversions.  
+
transitions and transversions.  
            ====statefrequencies (equilibrium codon frequencies)====
+
====statefrequencies (equilibrium codon frequencies)====
            '''statefrequencies''' = (equal, empirical, f1x4, '''f3x4'') - The options are to use equal codon frequencies  
+
'''statefrequencies''' = (equal, empirical, f1x4, '''f3x4'') - The options are to use equal codon frequencies  
            (not a good option), the frequencies observed in your dataset (termed “empirical” in GARLI),  
+
(not a good option), the frequencies observed in your dataset (termed “empirical” in GARLI),  
            or the codon frequencies implied by the “F1x4” or “F3x4” methods (using PAML's  
+
or the codon frequencies implied by the “F1x4” or “F3x4” methods (using PAML's  
            terminology).  These last two options calculate the codon frequencies as the product of the  
+
terminology).  These last two options calculate the codon frequencies as the product of the  
            frequencies of the three nucleotides that make up each codon.  In the “F1x4” case the  
+
frequencies of the three nucleotides that make up each codon.  In the “F1x4” case the  
            nucleotide frequencies are those observed in the dataset across all codon positions, while the  
+
nucleotide frequencies are those observed in the dataset across all codon positions, while the  
            “F3x4” option uses the nucleotide frequencies observed in the data at each codon position  
+
“F3x4” option uses the nucleotide frequencies observed in the data at each codon position  
            separately.  
+
separately.  
            ====ratehetmodel (variation in dN/dS across sites====  
+
====ratehetmodel (variation in dN/dS across sites====  
            '''ratehetmodel''' = ('''none''', nonsynonymous) – For codon models, the default is to infer a single dN/dS  
+
'''ratehetmodel''' = ('''none''', nonsynonymous) – For codon models, the default is to infer a single dN/dS  
            parameter.  Alternatively, a model can be specified that infers a given number of dN/dS  
+
parameter.  Alternatively, a model can be specified that infers a given number of dN/dS  
            categories, with the dN/dS values and proportions falling in each category estimated  
+
categories, with the dN/dS values and proportions falling in each category estimated  
            ('''ratehetmodel''' = nonsynonymous).  This is the “discrete” or “M3” model of Yang et al.  
+
('''ratehetmodel''' = nonsynonymous).  This is the “discrete” or “M3” model of Yang et al.  
            (2000).  
+
(2000).  
            ====numratecats (number of discrete dN/dS categories)====
+
====numratecats (number of discrete dN/dS categories)====
            '''numratecats''' = (1 to 20, '''1''') – When ratehetmodel = nonsynonymous, this is the number of dN/dS parameter  
+
'''numratecats''' = (1 to 20, '''1''') – When ratehetmodel = nonsynonymous, this is the number of dN/dS parameter  
            categories.
+
categories.
            ====invariantsites====
+
====invariantsites====
            '''invariantsites''' = (none) - '''NOTE:''' Due to an error on my part, the '''invariantsites''' entry must appear with codon models for them to run (despite the fact that it doesn't apply).  i.e., be sure that this appears:
+
'''invariantsites''' = (none) - '''NOTE:''' Due to an error on my part, the '''invariantsites''' entry must appear with codon models for them to run (despite the fact that it doesn't apply).  i.e., be sure that this appears:
            invariantsites = none.
+
invariantsites = none.
  
            ===For datatype = codon or codon-aminoacid===  
+
===For datatype = codon or codon-aminoacid===  
            ====geneticcode (code to use in codon translation)====
+
====geneticcode (code to use in codon translation)====
            '''geneticcode''' = ('''standard''', vertmito, invertmito) – The genetic code to be used in translating codons  
+
'''geneticcode''' = ('''standard''', vertmito, invertmito) – The genetic code to be used in translating codons  
            into amino acids.
+
into amino acids.
  
            ==Population settings==
+
==Population settings==
            ===nindivs (number of individuals in population)===
+
===nindivs (number of individuals in population)===
            '''nindivs''' = (2 to 100, '''4''')- The number of individuals in the population.  This may be increased, but  
+
'''nindivs''' = (2 to 100, '''4''')- The number of individuals in the population.  This may be increased, but  
            doing so is generally not beneficial.  Note that typical genetic algorithms tend to have much,  
+
doing so is generally not beneficial.  Note that typical genetic algorithms tend to have much,  
            much larger population sizes than GARLI's defaults.  
+
much larger population sizes than GARLI's defaults.  
            ===holdover (unmutated copies of best individual)===
+
===holdover (unmutated copies of best individual)===
            '''holdover''' = (1 to nindivs-1, '''1''')- The number of times the best individual is copied to the next  
+
'''holdover''' = (1 to nindivs-1, '''1''')- The number of times the best individual is copied to the next  
            generation with no chance of mutation.  It is best not to mess with this.  
+
generation with no chance of mutation.  It is best not to mess with this.  
            ===selectionintensity (strength of selection)===
+
===selectionintensity (strength of selection)===
            '''selectionintensity''' = (0.01 to 5.0, '''0.5''')- Controls the strength of selection, with larger numbers  
+
'''selectionintensity''' = (0.01 to 5.0, '''0.5''')- Controls the strength of selection, with larger numbers  
            denoting stronger selection.  The relative probability of reproduction of two individuals  
+
denoting stronger selection.  The relative probability of reproduction of two individuals  
            depends on the difference in their log likelihoods (&Delta;lnL) and is formulated very similarly to  
+
depends on the difference in their log likelihoods (&Delta;lnL) and is formulated very similarly to  
            the procedure of calculating Akaike weights.  The relative probability of reproduction of the  
+
the procedure of calculating Akaike weights.  The relative probability of reproduction of the  
            less fit individual is equal to:
+
less fit individual is equal to:
  
            <big><big>
+
<big><big>
            ''e''<sup> (-selectionIntensity &times; &Delta; lnL)</sup>
+
''e''<sup> (-selectionIntensity &times; &Delta; lnL)</sup>
            </big></big>
+
</big></big>
  
            In general, this setting does not seem to have much of an effect on the progress of a run.  In  
+
In general, this setting does not seem to have much of an effect on the progress of a run.  In  
            theory higher values should cause scores to increase more quickly, but make the search more  
+
theory higher values should cause scores to increase more quickly, but make the search more  
            likely to be entrapped in a local optimum.  Low values will increase runtimes, but may be  
+
likely to be entrapped in a local optimum.  Low values will increase runtimes, but may be  
            more likely to reach the true optimum. The following table gives the relative probabilities of  
+
more likely to reach the true optimum. The following table gives the relative probabilities of  
            reproduction for different values of the selection intensity when the difference in log  
+
reproduction for different values of the selection intensity when the difference in log  
            likelihood is 1.0
+
likelihood is 1.0
            {| border="1"
+
{| border="1"
            |-
+
|-
            !'''selectionintensity''' value  !! Ratio of probabilities of reproduction  
+
!'''selectionintensity''' value  !! Ratio of probabilities of reproduction  
            |-
+
|-
            |align="center" |0.05 || align="center" |0.95:1.0  
+
|align="center" |0.05 || align="center" |0.95:1.0  
            |-
+
|-
            |align="center" |0.1 || align="center" |0.90:1.0  
+
|align="center" |0.1 || align="center" |0.90:1.0  
            |-
+
|-
            |align="center" |0.25 || align="center" |0.78:1.0  
+
|align="center" |0.25 || align="center" |0.78:1.0  
            |-
+
|-
            |align="center" |0.5 || align="center" |0.61:1.0  
+
|align="center" |0.5 || align="center" |0.61:1.0  
            |-
+
|-
            |align="center" |0.75 || align="center" |0.47:1.0  
+
|align="center" |0.75 || align="center" |0.47:1.0  
            |-
+
|-
            |align="center" |1.0 || align="center" |0.37:1.0  
+
|align="center" |1.0 || align="center" |0.37:1.0  
            |-
+
|-
            |align="center" |2.0 || align="center" |0.14:1.0
+
|align="center" |2.0 || align="center" |0.14:1.0
            |}
+
|}
            ===holdoverpenalty (fitness handicap for best individual)===
+
===holdoverpenalty (fitness handicap for best individual)===
            '''holdoverpenalty''' = (0 to 100, '''0''') – This can be used to bias the probability of reproduction of the  
+
'''holdoverpenalty''' = (0 to 100, '''0''') – This can be used to bias the probability of reproduction of the  
            best individual downward.  Because the best individual is automatically copied into the next  
+
best individual downward.  Because the best individual is automatically copied into the next  
            generation, it has a bit of an unfair advantage and can cause all population variation to be lost  
+
generation, it has a bit of an unfair advantage and can cause all population variation to be lost  
            due to genetic drift, especially with small populations sizes.  The value specified here is  
+
due to genetic drift, especially with small populations sizes.  The value specified here is  
            subtracted from the best individual’s lnL score before calculating the probabilities of
+
subtracted from the best individual’s lnL score before calculating the probabilities of
            reproduction.  It seems plausible that this might help maintain variation, but I have not seen it  
+
reproduction.  It seems plausible that this might help maintain variation, but I have not seen it  
            cause a measurable effect.
+
cause a measurable effect.
  
            ===stopgen (maximum number of generations to run)===
+
===stopgen (maximum number of generations to run)===
            '''stopgen''' – The maximum number of generations to run.  Note that this supersedes the automated  
+
'''stopgen''' – The maximum number of generations to run.  Note that this supersedes the automated  
            stopping criterion (see enforcetermconditions  above), and should therefore be set to a very  
+
stopping criterion (see enforcetermconditions  above), and should therefore be set to a very  
            large value if automatic termination is desired.  
+
large value if automatic termination is desired.  
            ===stoptime (maximum time to run)===
+
===stoptime (maximum time to run)===
            '''stoptime''' – The maximum number of seconds for the run to continue. Note that this supersedes  
+
'''stoptime''' – The maximum number of seconds for the run to continue. Note that this supersedes  
            the automated stopping criterion (see enforcetermconditions  above), and should therefore  
+
the automated stopping criterion (see enforcetermconditions  above), and should therefore  
            be set to a very large value if automatic termination is desired.
+
be set to a very large value if automatic termination is desired.
  
            ==Branch-length optimization settings==  
+
==Branch-length optimization settings==  
            After a topological rearrangement, branch lengths in the vicinity of the rearrangement are  
+
After a topological rearrangement, branch lengths in the vicinity of the rearrangement are  
            optimized by the Newton-Raphson method.  Optimization passes are performed on a particular  
+
optimized by the Newton-Raphson method.  Optimization passes are performed on a particular  
            branch until the expected improvement in likelihood for the next pass is less than a threshold  
+
branch until the expected improvement in likelihood for the next pass is less than a threshold  
            value, termed the optimization precision.  Note that this name is somewhat misleading, as the  
+
value, termed the optimization precision.  Note that this name is somewhat misleading, as the  
            precision of the optimization algorithm is inversely related to this value (i.e., smaller values of  
+
precision of the optimization algorithm is inversely related to this value (i.e., smaller values of  
            the optimization precision lead to more precise optimization).  If the improvement in likelihood  
+
the optimization precision lead to more precise optimization).  If the improvement in likelihood  
            due to optimization for a particular branch is greater than the optimization precision,  
+
due to optimization for a particular branch is greater than the optimization precision,  
            optimization is also attempted on adjacent branches, spreading out across the tree.  When no new  
+
optimization is also attempted on adjacent branches, spreading out across the tree.  When no new  
            topology with a better likelihood score is discovered for a while, the value is automatically  
+
topology with a better likelihood score is discovered for a while, the value is automatically  
            reduced.  The value can have a large effect on speed, with smaller values significantly slowing  
+
reduced.  The value can have a large effect on speed, with smaller values significantly slowing  
            down the algorithm.  The value of the optimization precision and how it changes over the course  
+
down the algorithm.  The value of the optimization precision and how it changes over the course  
            of a run are determined by the following three parameters.  
+
of a run are determined by the following three parameters.  
            ===startoptprec===
+
===startoptprec===
            startoptprec (0.005 to 5.0, '''0.5''') – The beginning optimization precision.  
+
startoptprec (0.005 to 5.0, '''0.5''') – The beginning optimization precision.  
            ===minoptprec===
+
===minoptprec===
            minoptprec (0.001 to startoptprec, '''0.01''') – The minimum allowed value of the optimization precision.
+
minoptprec (0.001 to startoptprec, '''0.01''') – The minimum allowed value of the optimization precision.
  
            ===numberofprecreductions===
+
===numberofprecreductions===
            numberofprecreductions (0 to 100, '''10''') – Specify the number of steps that it will take for the  
+
numberofprecreductions (0 to 100, '''10''') – Specify the number of steps that it will take for the  
            optimization precision to decrease (linearly) from startoptprec to minoptprec.  
+
optimization precision to decrease (linearly) from startoptprec to minoptprec.  
            ===treerejectionthreshold===
+
===treerejectionthreshold===
            treerejectionthreshold (0 to 500, '''50''') – This setting controls which trees have more extensive  
+
treerejectionthreshold (0 to 500, '''50''') – This setting controls which trees have more extensive  
            branch-length optimization applied to them.  All trees created by a branch swap receive  
+
branch-length optimization applied to them.  All trees created by a branch swap receive  
            optimization on a few branches that directly took part in the rearrangement.  If the difference  
+
optimization on a few branches that directly took part in the rearrangement.  If the difference  
            in score between the partially optimized tree and the best known tree is greater than treerejectionthreshold, no further optimization is applied to the branches of that tree.  
+
in score between the partially optimized tree and the best known tree is greater than treerejectionthreshold, no further optimization is applied to the branches of that tree.  
            Reducing this value can significantly reduce runtimes, often with little or no effect on results.  
+
Reducing this value can significantly reduce runtimes, often with little or no effect on results.  
            However, it is possible that a better tree could be missed if this is set too low.  In cases in  
+
However, it is possible that a better tree could be missed if this is set too low.  In cases in  
            which obtaining the very best tree per search is not critical (e.g., bootstrapping), setting this  
+
which obtaining the very best tree per search is not critical (e.g., bootstrapping), setting this  
            lower (~20) is probably safe.
+
lower (~20) is probably safe.
  
            ==Settings controlling the proportions of the mutation types==  
+
==Settings controlling the proportions of the mutation types==  
            Each mutation type is assigned a prior ''weight''. These values determine the expected  
+
Each mutation type is assigned a prior ''weight''. These values determine the expected  
            proportions of the various mutation types that are performed.  The primary mutation categories  
+
proportions of the various mutation types that are performed.  The primary mutation categories  
            are ''topology'' (t), ''model'' (m) and ''branch length'' (b).  Each are assigned a prior weight ( P<sub>i</sub> ) in the  
+
are ''topology'' (t), ''model'' (m) and ''branch length'' (b).  Each are assigned a prior weight ( P<sub>i</sub> ) in the  
            config file.  Each time that a new best likelihood score is attained, the amount of the increase in  
+
config file.  Each time that a new best likelihood score is attained, the amount of the increase in  
            score is credited to the mutation type responsible, with the sum of the increases ( S<sub>i</sub> ) maintained  
+
score is credited to the mutation type responsible, with the sum of the increases ( S<sub>i</sub> ) maintained  
            over the last intervallength x intervalstostore generations.  The number of times that each  
+
over the last intervallength x intervalstostore generations.  The number of times that each  
            mutation is performed ( N<sub>i</sub> ) is also tallied.  The total weight of a mutation type is W<sub>i</sub> = P<sub>i</sub> + ( S<sub>i</sub> / N<sub>i</sub> ).  
+
mutation is performed ( N<sub>i</sub> ) is also tallied.  The total weight of a mutation type is W<sub>i</sub> = P<sub>i</sub> + ( S<sub>i</sub> / N<sub>i</sub> ).  
            The proportion of mutations of type i out of all mutations is then  
+
The proportion of mutations of type i out of all mutations is then  
  
            <big><big>
+
<big><big>
            Pr(i) = W<sub>i</sub> /  
+
Pr(i) = W<sub>i</sub> /  
            (W<sub>t</sub> + W<sub>m</sub> + W<sub>b</sub>)  
+
(W<sub>t</sub> + W<sub>m</sub> + W<sub>b</sub>)  
            </big></big>
+
</big></big>
  
            The proportion of each mutation is thus related to its prior weight and the average increase in  
+
The proportion of each mutation is thus related to its prior weight and the average increase in  
            score that it has caused over recent generations.  The prior weights can be used to control the  
+
score that it has caused over recent generations.  The prior weights can be used to control the  
            expected (and starting) proportions of the mutation types, as well as how sensitive the  
+
expected (and starting) proportions of the mutation types, as well as how sensitive the  
            proportions are to the course of events in a run.  It is generally a good idea to make the topology  
+
proportions are to the course of events in a run.  It is generally a good idea to make the topology  
            prior much larger than the others so that when no mutations are improving the score many  
+
prior much larger than the others so that when no mutations are improving the score many  
            topology mutations are still attempted.  If you set '''outputmostlyuselessfiles''' to 1, you can look at the “problog” file to determine what the  
+
topology mutations are still attempted.  If you set '''outputmostlyuselessfiles''' to 1, you can look at the “problog” file to determine what the  
            proportions of the mutations actually were over the course of a run.  
+
proportions of the mutations actually were over the course of a run.  
            ===topoweight (weight on topology mutations)===
+
===topoweight (weight on topology mutations)===
            topoweight (0 to infinity, '''1.0''') The prior weight assigned to the class of topology mutations  
+
topoweight (0 to infinity, '''1.0''') The prior weight assigned to the class of topology mutations  
            (NNI, SPR and limSPR). Note that setting this to 0.0 turns off topology mutations, meaning that the tree topology is fixed for the run.  This used to be a way to have the program estimate only model parameters and branch-lengths, but the '''[[GARLI_Configuration_Settings#optimizeinputonly_.28do_not_search.2C_only_optimize_model_and_branch_lengths_on_user_trees.29 | optimizeinputonly]]''' setting is now a better way to go.
+
(NNI, SPR and limSPR). Note that setting this to 0.0 turns off topology mutations, meaning that the tree topology is fixed for the run.  This used to be a way to have the program estimate only model parameters and branch-lengths, but the '''[[GARLI_Configuration_Settings#optimizeinputonly_.28do_not_search.2C_only_optimize_model_and_branch_lengths_on_user_trees.29 | optimizeinputonly]]''' setting is now a better way to go.
  
            ===modweight (weight on model parameter mutations)===
+
===modweight (weight on model parameter mutations)===
            modweight (0 to infinity, '''0.05''') The prior weight assigned to the class of model mutations.  Note  
+
modweight (0 to infinity, '''0.05''') The prior weight assigned to the class of model mutations.  Note  
            that setting this at 0.0 fixes the model during the run.  
+
that setting this at 0.0 fixes the model during the run.  
            ===brlenweight (weight on branch-length parameter mutations)===
+
===brlenweight (weight on branch-length parameter mutations)===
            brlenweight (0 to infinity, '''0.2''') The prior weight assigned to branch-length mutations.
+
brlenweight (0 to infinity, '''0.2''') The prior weight assigned to branch-length mutations.
  
            The same procedure used above to determine the proportion of Topology:Model:Branch-Length  
+
The same procedure used above to determine the proportion of Topology:Model:Branch-Length  
            mutations is also used to determine the relative proportions of the three types of topological  
+
mutations is also used to determine the relative proportions of the three types of topological  
            mutations (NNI:SPR:limSPR), controlled by the following three weights. Note that the  
+
mutations (NNI:SPR:limSPR), controlled by the following three weights. Note that the  
            proportion of mutations applied to each of the model parameters is not user controlled.  
+
proportion of mutations applied to each of the model parameters is not user controlled.  
            ===randnniweight (weight on NNI topology changes)===
+
===randnniweight (weight on NNI topology changes)===
            randnniweight (0 to infinity, '''0.1''') - The prior weight assigned to NNI mutations.  
+
randnniweight (0 to infinity, '''0.1''') - The prior weight assigned to NNI mutations.  
            ===randsprweight (weight on SPR topology changes)===
+
===randsprweight (weight on SPR topology changes)===
            randsprweight (0 to infinity, '''0.3''') - The prior weight assigned to random SPR mutations.  For  
+
randsprweight (0 to infinity, '''0.3''') - The prior weight assigned to random SPR mutations.  For  
            very large datasets it is often best to set this to 0.0, as random SPR mutations essentially  
+
very large datasets it is often best to set this to 0.0, as random SPR mutations essentially  
            never result in score increases.  
+
never result in score increases.  
            ===limsprweight (weight on localized SPR topology changes)===
+
===limsprweight (weight on localized SPR topology changes)===
            limsprweight (0 to infinity, '''0.6''') - The prior weight assigned to SPR mutations with the  
+
limsprweight (0 to infinity, '''0.6''') - The prior weight assigned to SPR mutations with the  
            reconnection branch limited to being a maximum of limsprrange branches away from where  
+
reconnection branch limited to being a maximum of limsprrange branches away from where  
            the branch was detached.  
+
the branch was detached.  
            ===intervallength===
+
===intervallength===
            intervallength (10 to 1000, '''100''') – The number of generations in each interval during which the  
+
intervallength (10 to 1000, '''100''') – The number of generations in each interval during which the  
            number and benefit of each mutation type are stored.  
+
number and benefit of each mutation type are stored.  
            ===intervalstostore===
+
===intervalstostore===
            intervalstostore = (1 to 10, '''5''') – The number of intervals to be stored.  Thus, records of  
+
intervalstostore = (1 to 10, '''5''') – The number of intervals to be stored.  Thus, records of  
            mutations are kept for the last (intervallength x intervalstostore) generations.  Every  
+
mutations are kept for the last (intervallength x intervalstostore) generations.  Every  
            intervallength generations the probabilities of the mutation types are updated by the scheme  
+
intervallength generations the probabilities of the mutation types are updated by the scheme  
            described above.
+
described above.
  
            ==Settings controlling mutation details==
+
==Settings controlling mutation details==
            ===limsprrange (max range for localized SPR topology changes)===
+
===limsprrange (max range for localized SPR topology changes)===
            limsprrange (0 to infinity, '''6''') – The maximum number of branches away from its original  
+
limsprrange (0 to infinity, '''6''') – The maximum number of branches away from its original  
            location that a branch may be reattached during a limited SPR move.  Setting this too high (>  
+
location that a branch may be reattached during a limited SPR move.  Setting this too high (>  
            10) can seriously degrade performance, but if you do so in conjunction with a large increase in genthreshfortopoterm you might end up with better trees.
+
10) can seriously degrade performance, but if you do so in conjunction with a large increase in genthreshfortopoterm you might end up with better trees.
            ===meanbrlenmuts (mean # of branch lengths to change per mutation)===
+
===meanbrlenmuts (mean # of branch lengths to change per mutation)===
            meanbrlenmuts (1 to # taxa, '''5''') - The mean of the binomial distribution from which the number  
+
meanbrlenmuts (1 to # taxa, '''5''') - The mean of the binomial distribution from which the number  
            of branch lengths mutated is drawn during a branch length mutation.  
+
of branch lengths mutated is drawn during a branch length mutation.  
            ===gammashapebrlen (magnitude of branch-length mutations)===
+
===gammashapebrlen (magnitude of branch-length mutations)===
            gammashapebrlen (50 to 2000, '''1000''') - The shape parameter of the gamma distribution (with a  
+
gammashapebrlen (50 to 2000, '''1000''') - The shape parameter of the gamma distribution (with a  
            mean of 1.0) from which the branch-length multipliers are drawn for branch-length  
+
mean of 1.0) from which the branch-length multipliers are drawn for branch-length  
            mutations.  Larger numbers cause smaller changes in branch lengths.  (Note that this has  
+
mutations.  Larger numbers cause smaller changes in branch lengths.  (Note that this has  
            nothing to do with gamma rate heterogeneity.)  
+
nothing to do with gamma rate heterogeneity.)  
            ===gammashapemodel (magnitude of model parameter mutations)===
+
===gammashapemodel (magnitude of model parameter mutations)===
            gammashapemodel (50 to 2000, '''1000''') - The shape parameter of the gamma distribution (with a  
+
gammashapemodel (50 to 2000, '''1000''') - The shape parameter of the gamma distribution (with a  
            mean of 1.0) from which the model mutation multipliers are drawn for model parameters  
+
mean of 1.0) from which the model mutation multipliers are drawn for model parameters  
            mutations. Larger numbers cause smaller changes in model parameters. (Note that this has  
+
mutations. Larger numbers cause smaller changes in model parameters. (Note that this has  
            nothing to do with gamma rate heterogeneity.)  
+
nothing to do with gamma rate heterogeneity.)  
            ===uniqueswapbias (relative weight assigned to already attempted branch swaps)===
+
===uniqueswapbias (relative weight assigned to already attempted branch swaps)===
            uniqueswapbias (0.01 to 1.0, '''0.1''') –  With version 0.95 and later, GARLI keeps track of which branch  
+
uniqueswapbias (0.01 to 1.0, '''0.1''') –  With version 0.95 and later, GARLI keeps track of which branch  
            swaps it has attempted on the current best tree.  Because swaps are applied randomly, it is  
+
swaps it has attempted on the current best tree.  Because swaps are applied randomly, it is  
            possible that some swaps are tried twice before others are tried at all.  This option allows the  
+
possible that some swaps are tried twice before others are tried at all.  This option allows the  
            program to bias the swaps applied toward those that have not yet been attempted.  Each swap  
+
program to bias the swaps applied toward those that have not yet been attempted.  Each swap  
            is assigned a relative weight depending on the number of times that it has been attempted on  
+
is assigned a relative weight depending on the number of times that it has been attempted on  
            the current best tree.  This weight is equal to (uniqueswapbias) raised to the (# times swap  
+
the current best tree.  This weight is equal to (uniqueswapbias) raised to the (# times swap  
            attempted) power.  In other words, a value of 0.5 means that swaps that have already been  
+
attempted) power.  In other words, a value of 0.5 means that swaps that have already been  
            tried once will be half as likely as those not yet attempted, swaps attempted twice will be ¼  
+
tried once will be half as likely as those not yet attempted, swaps attempted twice will be ¼  
            as likely, etc.  A value of 1.0 means no biasing.  If this value is not equal to 1.0 and the  
+
as likely, etc.  A value of 1.0 means no biasing.  If this value is not equal to 1.0 and the  
            outputmostlyuseless files option is on, a file called <ofprefix>.swap.log is output.  This file  
+
outputmostlyuseless files option is on, a file called <ofprefix>.swap.log is output.  This file  
            shows the total number rearrangements tried and the number of unique ones over the course  
+
shows the total number rearrangements tried and the number of unique ones over the course  
            of a run.  Note that this bias is only applied to NNI and limSPR rearrangements.  Use of this  
+
of a run.  Note that this bias is only applied to NNI and limSPR rearrangements.  Use of this  
            option may allow the use of somewhat larger values of limsprrange.  
+
option may allow the use of somewhat larger values of limsprrange.  
            ===distanceswapbias (relative weight assigned to branch swaps based on locality)===
+
===distanceswapbias (relative weight assigned to branch swaps based on locality)===
            distanceswapbias (0.1 to 10, '''1.0''') – This option is similar to uniqueswapbias, except that it  
+
distanceswapbias (0.1 to 10, '''1.0''') – This option is similar to uniqueswapbias, except that it  
            biases toward certain swaps based on the topological distance between the initial and  
+
biases toward certain swaps based on the topological distance between the initial and  
            rearranged trees.  The distance is measured as in the limsprrange, and is half the the  
+
rearranged trees.  The distance is measured as in the limsprrange, and is half the the  
            Robinson-Foulds distance between the trees.  As with uniqueswapbias, distanceswapbias  
+
Robinson-Foulds distance between the trees.  As with uniqueswapbias, distanceswapbias  
            assigns a relative weight to each potential swap.  In this case the weight is  
+
assigns a relative weight to each potential swap.  In this case the weight is  
            (distanceswapbias) raised to the (reconnection distance - 1) power.  Thus, given a value of  
+
(distanceswapbias) raised to the (reconnection distance - 1) power.  Thus, given a value of  
            0.5, the weight of an NNI is 1.0, the weight of an SPR with distance 2 is 0.5, with distance 3  
+
0.5, the weight of an NNI is 1.0, the weight of an SPR with distance 2 is 0.5, with distance 3  
            is 0.25, etc.  Note that values less than 1.0 bias toward more localized swaps, while values  
+
is 0.25, etc.  Note that values less than 1.0 bias toward more localized swaps, while values  
            greater than 1.0 bias toward more extreme swaps. Also note that this bias is only applied to  
+
greater than 1.0 bias toward more extreme swaps. Also note that this bias is only applied to  
            limSPR rearrangements.  Be careful in setting this, as extreme values can have a very large  
+
limSPR rearrangements.  Be careful in setting this, as extreme values can have a very large  
            effect.
+
effect.

Latest revision as of 12:32, 21 July 2015

Contents

Descriptions of GARLI configuration settings

The format for these configuration settings descriptions is generally: entryname (possible values, default value in bold) – description

General settings

datafname (file containing sequence dataset)

datafname = (filename) – Name of the file containing the aligned sequence data. Formats accepted are PHYLIP, NEXUS and FASTA. Robust reading of Nexus formatted datasets is done using the Nexus Class Library. This accommodates things such as interleaved alignments and exclusion sets (exset’s) in NEXUS assumptions blocks (see the FAQ for an example of exset usage). Use of NEXUS files is recommended, and is required for partitioned models.

constraintfile (file containing constraint definition)

constraintfile = (filename, none) – Name of the file containing any topology constraint specifications, or “none” if there are no constraints. The easiest way to explain the format of the constraint file is by example. Consider a dataset of 8 taxa, in which your constraint consists of grouping taxa 1, 3 and 5. You may specify either positive constraints (inferred tree MUST contain constrained group) or negative constraints (also called converse constraints, inferred tree CANNOT contain constrained group). These are specified with either a ‘+’ or a ‘-‘ at the beginning of the constraint specification, for positive and negative constraints, respectively.

  • For a positive constraint on a grouping of taxa 1, 3 and 5:
+((1,3,5),2,4,6,7,8); 
  • For a negative constraint on a grouping of taxa 1, 3 and 5:

-((1,3,5),2,4,6,7,8);

  • Note that there are many other equivalent parenthetical representations of these constraints.
  • Multiple groups may be positively constrained, but currently only a single negatively constrained group is allowed.
  • Multiple constrained groupings may be specified in a single string:

+((1,3,5),2,4,(6,7),8); or in two separate strings on successive lines:

+((1,3,5),2,4,6,7,8); 
+(1,3,5,2,4,(6,7),8); 
  • Constraint strings may also be specified in terms of taxon names (matching those used in the alignment) instead of numbers.
  • Positive and negative constraints cannot be mixed.
  • GARLI also accepts another constraint format that may be easier to use in some cases. This involves specifying a single branch to be constrained with a string of ‘*’ (asterisk) and ‘.’ (period) characters, with one character per taxon. Each taxon specified with a ‘*’ falls on one side of the constrained branch, and all those specified with a ‘.’ fall on the other. This should be familiar to anyone who has looked at PAUP* bootstrap output. With this format, a positive constraint on a grouping of taxa 1, 3 and 5 would look like this:

+*.*.*… or equivalently like this:

+.*.*.*** 

With this format each line only designates a single branch, so multiple constrained branches must be specified as multiple lines in the file.

  • The program also allows “backbone” constraints, which are simply constraints that do not include all of the taxa. For example if one wanted to constrain (1,3,5) but didn’t care where taxon 6 appeared in the tree, this string could be used:
+((1,3,5),2,4,7,8); 
Nothing special needs to be done to identify this as a backbone constraint, simply leave out some taxa.

streefname (source of starting tree and/or model)

streefname = (random, stepwise, <filename>) – Specifies where the starting tree topology and/or model parameters will come from. The tree topology may be a completely random topology (constraints will be enforced), a tree provided by the user in a file, or a tree generated by the program using a fast ML stepwise-addition algorithm (see attachmentspertaxon below). Starting or fixed model parameter values may also be provided in the specified file, with or without a tree topology. Some notes on starting trees/models:

  • Specified starting trees may have polytomies, which will be arbitrarily resolved before the run begins.
  • Starting tree formats:
    • Plain newick tree string (with taxon numbers or names, with or without branch lengths)
    • NEXUS trees block. The trees block can appear in the same file as a NEXUS data or characters block that contains the alignment, although the same filename should then be specified on both the datafname and streefname lines.
  • If multiple trees appear in the specified file and multiple search replicates are specified (see searchreps setting), then the first tree is used in the first replicate, the second in the second replicate, etc.
  • Providing model parameter values: see this page Specifying model parameter values
  • See also the FAQ items on model parameters here.

attachmentspertaxon (control creation of stepwise addition starting tree)

attachmentspertaxon = (1 to infinity, 50) – The number of attachment branches evaluated for each taxon to be added to the tree during the creation of an ML stepwise-addition starting tree. Briefly, stepwise addition is an algorithm used to make a tree, and involves adding taxa in a random order to a growing tree. For each taxon to be added, a number of randomly chosen attachment branches are tried and scored, and then the best scoring one is chosen as the location of that taxon. The attachmentspertaxon setting controls how many attachment points are evaluated for each taxon to be added. A value of one is equivalent to a completely random tree (only one randomly chosen location is evaluated). A value of greater than 2 times the number of taxa in the dataset means that all attachment points will be evaluated for each taxon, and will result in very good starting trees (but may take a while on large datasets). Even fairly small values (< 10) can result in starting trees that are much, much better than random, but still fairly different from one another.

ofprefix (output filename prefix)

ofprefix = (text) – Prefix of all output filenames, such as log, treelog, etc. Change this for each run that you do or the program will overwrite previous results.

randseed (random number seed)

randseed = (-1 or positive integers, -1) – The random number seed used by the random number generator. Specify “–1” to have a seed chosen for you. Specifying the same seed number in multiple runs will give exactly identical results, if all other parameters and settings are also identical.

availablemememory (control maximum program memory usage)

availablemememory – Typically this is the amount of available physical memory on the system, in megabytes. This lets GARLI determine how much system memory it may be able to use to store computations for reuse. The program will be conservative and use at most about 90% of this value, although for typical datasets it will use much, much less. If other programs must be open or used when GARLI is running, you may need to reduce this value. This setting can also have a significant effect on performance (speed), but more is not always better. When a run is started, GARLI will output the availablememory value necessary for that dataset to achieve each of the “memory levels” (from best to worst, termed “great”, “good”, “low”, and “very low”). More memory is generally better because more calculations are stored and can be reused, but when the amount of memory needed for “great” becomes more than 512 megabytes or so, performance can be slowed because the operating system has difficulty managing that much memory. In general, chose an amount of memory that allows “great” when this is less than 512 MB, and if it is greater reduce the amount of memory into “good” or “low” as necessary. Avoid “very low” whenever possible. You can find the value is approximately optimal for your dataset by setting the randseed to some positive value (so that the searches are identical) and doing runs with various availablememory values. Typically it will only make at most a 30% difference, so it isn't worth worrying about too much.

logevery (frequency to log best score to file)

logevery = (1 to infinity, 10) – The frequency at which the best score is written to the log file.

saveevery (frequency to save best tree to file or write checkpoints)

saveevery = (1 to infinity, 100) – If writecheckpoints or outputcurrentbesttopology are specified, this is the frequency (in generations) at which checkpoints or the current best tree are written to file.

refinestart (whether to optimize a bit before starting a search)

refinestart = (0 or 1, 1) – Specifies whether some initial rough optimization is performed on the starting branch lengths and rate heterogeneity parameters. This is always recommended.

outputcurrentbesttopology (continuously write the best tree to file during a run)

outputcurrentbesttopology = (0 or 1, 0) – If true, the current best tree of the current search replicate is written to <ofprefix>.best.current.tre every saveevery generations. In versions before 0.96 the current best topology was always written to file, but that is no longer the case. Seeing the current best tree has no real use apart from satisfying your curiosity about how a run is going.

outputeachbettertopology (write each improved topology to file)

outputeachbettertopology (0 or 1, 0) – If true, each new topology encountered with a better score than the previous best is written to file. In some cases this can result in really big files (hundreds of MB) though, especially for random starting topologies on large datasets. Note that this file is interesting to get an idea of how the topology changed as the searches progressed, but the collection of trees should NOT be interpreted in any meaningful way. This option is not available while bootstrapping.

enforcetermconditions (use automatic termination)

enforcetermconditions = (0 or 1, 1) – Specifies whether the automatic termination conditions will be used. The conditions specified by both of the following two parameters must be met. See the following two parameters for their definitions. If this is false, the run will continue until it reaches the time ('stoptime) or generation (stopgen) limit. It is highly recommended that this option be used!

genthreshfortopoterm (number of generations without topology improvement required for termination)

genthreshfortopoterm = (1 to infinity, 20,000) – This specifies the first part of the termination condition. When no new significantly better scoring topology (see significanttopochange below) has been encountered in greater thanthis number of generations, this condition is met. Increasing this parameter may improve the lnL scores obtained (especially on large datasets), but will also increase runtimes.

scorethreshforterm (max score improvement over recent generations required for termination)

scorethreshforterm = (0 to infinity, 0.05) – The second part of the termination condition. When the total improvement in score over the last intervallength x intervalstostore generations (default is 500 generations, see below) is less than this value, this condition is met. This does not usually need to be changed.

significanttopochange (required score improvement for topology to be considered better)

significanttopochange = (0 to infinity, 0.01) – The lnL increase required for a new topology to be considered significant as far as the termination condition is concerned. It probably doesn’t need to be played with, but you might try increasing it slightly if your runs reach a stable score and then take a very long time to terminate due to very minor changes in topology.

outputphyliptree (write trees to file in Phylip as well as Nexus format)

outputphyliptree = (0 or 1, 0) – Whether a phylip formatted tree files will be output in addition to the default nexus files for the best tree across all replicates (<ofprefix>.best.phy), the best tree for each replicate (<ofprefix>.best.all.phy) or in the case of bootstrapping, the best tree for each bootstrap replicate (<ofprefix.boot.phy>.

outputmostlyuselessfiles (output uninteresting files)

outputmostlyuselessfiles = (0 or 1, 0) – Whether to output three files of little general interest: the “fate”, “problog” and “swaplog” files. The fate file shows the parentage, mutation types and scores of every individual in the population during the entire search. The problog shows how the proportions of the different mutation types changed over the course of the run. The swaplog shows the number of unique swaps and the number of total swaps on the current best tree over the course of the run.

writecheckpoints (write checkpoint files during run)

writecheckpoints (0 or 1, 0) – Whether to write three files to disk containing all information about the current state of the population every saveevery generations, with each successive checkpoint overwriting the previous one. These files can be used to restart a run at the last written checkpoint by setting the restart configuration entry.

restart (restart run from checkpoint)

restart = (0 or 1, 0) – Whether to restart at a previously saved checkpoint. To use this option the writecheckpoints option must have been used during a previous run. The program will look for checkpoint files that are named based on the ofprefix of the previous run. If you intend to restart a run, NOTHING should be changed in the config file except setting restart to 1. A run that is restarted from checkpoint will give exactly the same results it would have if the run had gone to completion.

outgroup (orient inferred trees consistently)

outgroup = (ougroup taxa numbers, separated by spaces) – This option allow for orienting the tree topologies in a consistent way when they are written to file. Note that this has NO effect whatsoever on the actual inference and the specified outgroup is NOT constrained to be present in the inferred trees. If multiple outgroup taxa are specified and they do not form a monophyletic group in the inferred tree, this setting will be ignored. If you specify a single outgroup taxon it will always be present, and the tree will always be consistently oriented. Ranges can be indicated with a hyphen. e.g., to specify an outgroup consisting of taxa 1, 2, 3 and 5 the format is this: outgroup = 1-3 5

searchreps (number of independent search replicates)

searchreps = (1 to infinity, 2) – The number of independent search replicates to perform during a program execution. You should always either do multiple search replicates or multiple program executions with any dataset to get a feel for whether you are getting consistent results, which suggests that the program is doing a decent job of searching. Note that if this is > 1 and you are performing a bootstrap analysis, this is the number of search replicates to be done per bootstrap replicate. That can increase the chance of finding the best tree per bootstrap replicate, but will also increase bootstrap runtimes enormously.

bootstrapreps (number of bootstrap replicates)

bootstrapreps (0 to infinity, 0) - The number of bootstrap reps to perform. If this is greater than 0, normal searching will not be performed. The resulting bootstrap trees (one per rep) will be output to a file named <ofprefix>.boot.tre. To obtain the bootstrap proportions they will then need to be read into PAUP* or a similar program to obtain a majority rule consensus. Note that it is probably safe to reduce the strictness of the termination conditions during bootstrapping (perhaps halve genthreshfortopoterm), which will greatly speed up the bootstrapping process with negligible effects on the results.

Note that GARLI does NOT do the bootstrap consensus or calculate the bootstrap proportions itself. It simply infers the trees and are the input to that consensus. The trees in the .boot.tre file will need to be read into a program such as SumTrees (or PAUP* or CONSENSE) to do a majority-rule consensus and obtain your bootstrap support values. See the following part of the "Advanced topics" page for suggestions on making the consensus: Detailed Example: A bootstrap analysis.

resampleproportion (relative size of re-sampled data matrix)

resampleproportion (0.1 to 10, 1.0 ) – When bootstrapreps > 0, this setting allows for bootstrap-like resampling, but with the psuedoreplicate datasets having the number of alignment columns different from the real data. Setting values < 1.0 is somewhat similar to jackknifing, but not identical.

inferinternalstateprobs (infer ancestral states)

inferinternalstateprobs = (0 or 1, 0) – Specify 1 to have GARLI infer the marginal posterior probability of each character at each internal node. This is done at the very end of the run, just before termination. The results are output to a file named <ofprefix>.internalstates.log.

outputsitelikelihoods (write a file with the log-likelihood of each site)

outputsitelikelihoods = (0 or 1, 0) - Causes a file named <ofprefix>.sitelikes.log to be created containing the sitewise log-likelihood values for each individual site for the final tree of each search replicate. Note that the format of the file is exactly the same as that output by PAUP, so it can be directly used in CONSEL using the PAUP file-format option. For partitioned models the sites are listed in sets by partition subset, but the site numbers will match those in the original datamatrix. Thus, when using a partitioned model that divides site by codon position, the ordering would be 1, 4, 7, ... 2, 5, 8, ... 3, 6, 9 .... Note that this makes no difference to CONSEL, which just assumes the the sitelikelihoods are ordered the same for each tree and ignores the site numbers.

Also note that using the site likelihoods from a partitioned model is a violation of CONSEL's assumptions, since it will not know about the partitions and its internal bootstrap resampling will not obey them. It isn't clear what the effects of this will be on the various tests.

Finally, if you want to calculate the site likelihoods for a set of trees that you provide, use the optimizeinputonly setting.

optimizeinputonly (do not search, only optimize model and branch lengths on user trees)

(new in version 2.0)

optimizeinputonly = (0 or 1, 0) - Requires a NEXUS formatted input tree file (only NEXUS format will work!), specified through the streefname setting. All trees in that file will have model parameters and branch lengths optimized, giving their maximum likelihood scores. A file with the site-likelihoods of each tree will also be output. See the outputsitelikelihoods setting for details.

collapsebranches (collapse zero length branches before writing final trees to file)

collapsebranches = (0 or 1, 1) - Before version 1.0, all trees that are returned were fully resolved. This is true even if the maximum-likelihood estimate of some internal branch lengths are effectively zero (or GARLI's minimum, which is 1e-8). In such cases, collapsing the branch into a polytomy would be a better representation. Note that GARLI will never return a tree with an actual branch length of zero, but rather with its minimum value of 1.0e-8. The drawback of always returning fully resolved trees is that what is effectively a polytomy can be resolved in three ways, and different independent searches may randomly return one of those resolutions. Thus, if you compare the trees by topology only, they will look different. If you pay attention to the branch lengths and likelihood scores of the trees it will be apparent that they are effectively the same.

I think that collapsing of branches is particularly important when bootstrapping, since no support should be given to a branch that doesn't really exist, i.e., that is a random resolution of a polytomy. Collapsing is also good when calculating tree to tree distances such as the symmetric tree distance, for example when calculating phylogenetic error to a known target tree. Zero-length branches would add to the distances (~error) although they really should not.

Model specification settings

With version 1.0 and later there are now many more options dealing with model specification because of the inclusion of amino acid and codon-based models. The description of the settings will be broken up by data type. Note that in terms of the model settings in GARLI, “empirical” means to fix parameter values at those observed in the dataset being analyzed, and “fixed” means to fix them at user specified values. See the streefname setting for details on how to provide parameter values to be fixed during inference.

PARTITIONED MODELS: To use partitioned models you'll still need to use the same basic model settings detailed below for each individual partition subset, and then some other details to set up the partition model itself. Be sure that you are familiar with the rest of this section, then see Using partitioned models.

datatype (sequence type and inference model)

datatype = (nucleotide, aminoacid, codon-aminoacid, codon, standard, standardordered, standardvariable, standardvariableordered) – The type of data and model that is to be used during tree inference. Nucleotide and amino acid data are self explanatory.

The codon-aminoacid datatype means that the data will be supplied as a nucleotide alignment, but will be internally translated and analyzed using an amino acid model. The codon and codon-aminoacid datatypes require nucleotide sequence that is aligned in the correct reading frame. In other words, all gaps in the alignment should be a multiple of 3 in length, and the alignment should start at the first position of a codon. If the alignment has extra columns at the start, middle or end, they should be removed or excluded with a Nexus exset (see this FAQ item for an example of exset usage). The correct geneticcode must also be set.

(New in Version 2.0)

The various "standard" datatypes are new in GARLI 2.0. These represent morphology-like discrete characters, with any number of states. These are also termed the "Mk" and "Mkv" models by Lewis (2001). See this page for more details on using standard data: Garli_Mkv morphology model.

Settings for datatype = nucleotide

ratematrix (relative rate parameters assumed by substitution model)

ratematrix = (1rate, 2rate, 6rate, fixed, custom string) – The number of relative substitution rate parameters (note that the number of free parameters is this value minus one). Equivalent to the “nst” setting in PAUP* and MrBayes. 1rate assumes that substitutions between all pairs of nucleotides occur at the same rate (JC model), 2rate allows different rates for transitions and transversions (K2P or HKY models), and 6rate allows a different rate between each nucleotide pair (GTR). These rates are estimated unless the fixed option is chosen. Since version 0.96, parameters for any submodel of the GTR model may be estimated. The format for specifying this is very similar to that used in the “rclass’ setting of PAUP*. Within parentheses, six letters are specified, with spaces between them. The six letters represent the rates of substitution between the six pairs of nucleotides, with the order being A-C, A-G, A-T, C-G, C-T and G-T. Letters within the parentheses that are the same mean that a single parameter is shared by multiple nucleotide pairs. For example,

ratematrix = (a b a a b a) 

would specify the HKY 2-rate model (equivalent to ratematrix = 2rate). This entry,

ratematrix = (a b c c b a)

would specify 3 estimated rates of subtitution, with one rate shared by A-C and G-T substitutions, another rate shared by A-G and C-T substitutions, and the final rate shared by A-T and C-G substitutions.

statefrequencies (equilibrium base frequencies assumed by substitution model)

statefrequencies = (equal, empirical, estimate, fixed) – Specifies how the equilibrium state frequencies (A, C, G and T) are treated. The empirical setting fixes the frequencies at their observed proportions, and the other options should be self-explanatory.

For datatype = nucleotide or aminoacid

invariantsites (treatment of proportion of invariable sites parameter)

invariantsites = (none, estimate, fixed) – Specifies whether a parameter representing the proportion of sites that are unable to change (i.e. have a substitution rate of zero) will be included. This is typically referred to as “invariant sites”, but would better be termed “invariable sites”.

ratehetmodel (type of rate heterogeneity to assume for variable sites)

ratehetmodel = (none, gamma, gammafixed) – The model of rate heterogeneity assumed. “gammafixed” requires that the alpha shape parameter is provided, and a setting of “gamma” estimates it.

numratecats (number of overall substitution rate categories)

numratecats = (1 to 20, 4) – The number of categories of variable rates (not including the invariant site class if it is being used). Must be set to 1 if ratehetmodel is set to none. Note that runtimes and memory usage scale linearly with this setting.

For datatype = aminoacid or codon-aminoacid

Amino acid analyses are typically done using fixed rate matrices that have been estimated on large datasets and published. Typically the only model parameters that are estimated during tree inference relate to the rate heterogeneity distribution. Each of the named matrices also has corresponding fixed amino acid frequencies, and a given rate matrix can either be used with those frequencies or with the amino acid frequencies observed in your dataset. This second option is often denoted as “+F” in a model description, although in terms of the GARLI configuration settings this is referred to as “empirical” frequencies. In GARLI the Dayhoff model would be specified by setting both the ratematrix and statefrequencies options to “dayhoff”. The Dayhoff+F model would be specified by setting the ratematrix to “dayhoff”, and statefrequencies to “empirical”.

The following named amino acid models are implemented:

ratematrix/statefrequencies setting reference
dayhoff Dayhoff, Schwartz and Orcutt. 1978.
jones Jones, Taylor and Thornton (JTT), 1992.
WAG Whelan and Goldman, 2001.
mtREV Adachi and Hasegawa, 1996.
mtmam Yang, Nielsen and Hasegawa, 1998.

Note that most programs allow either the use of a named rate matrix and its corresponding state frequencies, or a named rate matrix and empirical frequencies. GARLI technically allows the mixing of different named matrices and equilibrium frequencies (for example, wag matrix with jones equilibrium frequencies), but this is not recommended.

ratematrix (amino acid substitution rates)

ratematrix = (poisson, jones, dayhoff, wag, mtmam, mtrev) – The fixed amino acid rate matrix to use. You should use the matrix that gives the best likelihood, and could use a program like PROTTEST (very much like MODELTEST, but for amino acid models) to determine which fits best for your data. Poisson assumes a single rate of substitution between all amino acid pairs, and is a very poor model.

statefrequencies (equilibrium base frequencies assumed by substitution model)

statefrequencies = (equal, empirical, estimate, fixed, jones, dayhoff, wag, mtmam, mtrev) – Specifies how the equilibrium state frequencies of the 20 amino acids are treated. The “empirical” option fixes the frequencies at their observed proportions (when describing a model this is often termed “+F”).

For datatype = codon

The codon models are built with three components: (1) parameters describing the process of individual nucleotide substitutions, (2) equilibrium codon frequencies, and (3) parameters describing the relative rate of nonsynonymous to synonymous substitutions. The nucleotide substitution parameters within the codon models are exactly the same as those possible with standard nucleotide models in GARLI, and are specified with the ratematrix configuration entry. Thus, they can be of the 2rate variety (inferring different rates for transitions and transversions, K2P or HKY-like), the 6rate variety (inferring different rates for all nucleotide pairs, GTR-like) or any other sub-model of GTR. The options for codon frequencies are specified with the statefrequencies configuration entry. The options are to use equal frequencies (not a good option), the frequencies observed in your dataset (termed “empirical” in GARLI), or the codon frequencies implied by the “F1x4” or “F3x4” methods (using PAML's terminology). These last two options calculate the codon frequencies as the product of the frequencies of the three nucleotides that make up each codon. In the “F1x4” case the nucleotide frequencies are those observed in the dataset across all codon positions, while the “F3x4” option uses the nucleotide frequencies observed in the data at each codon position separately. The final component of the codon models is the nonsynonymous to synonymous relative rate parameters (aka dN/dS or omega parameters). The default is to infer a single dN/dS value. Alternatively, a model can be specified that infers a given number of dN/dS categories, with the dN/dS values and proportions falling in each category estimated (ratehetmodel = nonsynonymous). This is the “discrete” or “M3” model in PAML's terminology.

ratematrix (relative nucleotide rate parameters assumed by codon model)

ratematrix = (1rate, 2rate, 6rate, fixed, custom string) – This determines the relative rates of nucleotide substitution assumed by the codon model. The options are exactly the same as those allowed under a normal nucleotide model. A codon model with ratematrix = 2rate specifies the standard Goldman and Yang (1994) model, with different substitution rates for transitions and transversions.

statefrequencies (equilibrium codon frequencies)

'statefrequencies = (equal, empirical, f1x4, f3x4) - The options are to use equal codon frequencies (not a good option), the frequencies observed in your dataset (termed “empirical” in GARLI), or the codon frequencies implied by the “F1x4” or “F3x4” methods (using PAML's terminology). These last two options calculate the codon frequencies as the product of the frequencies of the three nucleotides that make up each codon. In the “F1x4” case the nucleotide frequencies are those observed in the dataset across all codon positions, while the “F3x4” option uses the nucleotide frequencies observed in the data at each codon position separately.

ratehetmodel (variation in dN/dS across sites

ratehetmodel = (none, nonsynonymous) – For codon models, the default is to infer a single dN/dS parameter. Alternatively, a model can be specified that infers a given number of dN/dS categories, with the dN/dS values and proportions falling in each category estimated (ratehetmodel = nonsynonymous). This is the “discrete” or “M3” model of Yang et al. (2000).

numratecats (number of discrete dN/dS categories)

numratecats = (1 to 20, 1) – When ratehetmodel = nonsynonymous, this is the number of dN/dS parameter categories.

invariantsites

invariantsites = (none) - NOTE: Due to an error on my part, the invariantsites entry must appear with codon models for them to run (despite the fact that it doesn't apply). i.e., be sure that this appears: invariantsites = none.

For datatype = codon or codon-aminoacid

geneticcode (code to use in codon translation)

geneticcode = (standard, vertmito, invertmito) – The genetic code to be used in translating codons into amino acids.

Population settings

nindivs (number of individuals in population)

nindivs = (2 to 100, 4)- The number of individuals in the population. This may be increased, but doing so is generally not beneficial. Note that typical genetic algorithms tend to have much, much larger population sizes than GARLI's defaults.

holdover (unmutated copies of best individual)

holdover = (1 to nindivs-1, 1)- The number of times the best individual is copied to the next generation with no chance of mutation. It is best not to mess with this.

selectionintensity (strength of selection)

selectionintensity = (0.01 to 5.0, 0.5)- Controls the strength of selection, with larger numbers denoting stronger selection. The relative probability of reproduction of two individuals depends on the difference in their log likelihoods (ΔlnL) and is formulated very similarly to the procedure of calculating Akaike weights. The relative probability of reproduction of the less fit individual is equal to:

e (-selectionIntensity × Δ lnL)

In general, this setting does not seem to have much of an effect on the progress of a run. In theory higher values should cause scores to increase more quickly, but make the search more likely to be entrapped in a local optimum. Low values will increase runtimes, but may be more likely to reach the true optimum. The following table gives the relative probabilities of reproduction for different values of the selection intensity when the difference in log likelihood is 1.0

selectionintensity value Ratio of probabilities of reproduction
0.05 0.95:1.0
0.1 0.90:1.0
0.25 0.78:1.0
0.5 0.61:1.0
0.75 0.47:1.0
1.0 0.37:1.0
2.0 0.14:1.0

holdoverpenalty (fitness handicap for best individual)

holdoverpenalty = (0 to 100, 0) – This can be used to bias the probability of reproduction of the best individual downward. Because the best individual is automatically copied into the next generation, it has a bit of an unfair advantage and can cause all population variation to be lost due to genetic drift, especially with small populations sizes. The value specified here is subtracted from the best individual’s lnL score before calculating the probabilities of reproduction. It seems plausible that this might help maintain variation, but I have not seen it cause a measurable effect.

stopgen (maximum number of generations to run)

stopgen – The maximum number of generations to run. Note that this supersedes the automated stopping criterion (see enforcetermconditions above), and should therefore be set to a very large value if automatic termination is desired.

stoptime (maximum time to run)

stoptime – The maximum number of seconds for the run to continue. Note that this supersedes the automated stopping criterion (see enforcetermconditions above), and should therefore be set to a very large value if automatic termination is desired.

Branch-length optimization settings

After a topological rearrangement, branch lengths in the vicinity of the rearrangement are optimized by the Newton-Raphson method. Optimization passes are performed on a particular branch until the expected improvement in likelihood for the next pass is less than a threshold value, termed the optimization precision. Note that this name is somewhat misleading, as the precision of the optimization algorithm is inversely related to this value (i.e., smaller values of the optimization precision lead to more precise optimization). If the improvement in likelihood due to optimization for a particular branch is greater than the optimization precision, optimization is also attempted on adjacent branches, spreading out across the tree. When no new topology with a better likelihood score is discovered for a while, the value is automatically reduced. The value can have a large effect on speed, with smaller values significantly slowing down the algorithm. The value of the optimization precision and how it changes over the course of a run are determined by the following three parameters.

startoptprec

startoptprec (0.005 to 5.0, 0.5) – The beginning optimization precision.

minoptprec

minoptprec (0.001 to startoptprec, 0.01) – The minimum allowed value of the optimization precision.

numberofprecreductions

numberofprecreductions (0 to 100, 10) – Specify the number of steps that it will take for the optimization precision to decrease (linearly) from startoptprec to minoptprec.

treerejectionthreshold

treerejectionthreshold (0 to 500, 50) – This setting controls which trees have more extensive branch-length optimization applied to them. All trees created by a branch swap receive optimization on a few branches that directly took part in the rearrangement. If the difference in score between the partially optimized tree and the best known tree is greater than treerejectionthreshold, no further optimization is applied to the branches of that tree. Reducing this value can significantly reduce runtimes, often with little or no effect on results. However, it is possible that a better tree could be missed if this is set too low. In cases in which obtaining the very best tree per search is not critical (e.g., bootstrapping), setting this lower (~20) is probably safe.

Settings controlling the proportions of the mutation types

Each mutation type is assigned a prior weight. These values determine the expected proportions of the various mutation types that are performed. The primary mutation categories are topology (t), model (m) and branch length (b). Each are assigned a prior weight ( Pi ) in the config file. Each time that a new best likelihood score is attained, the amount of the increase in score is credited to the mutation type responsible, with the sum of the increases ( Si ) maintained over the last intervallength x intervalstostore generations. The number of times that each mutation is performed ( Ni ) is also tallied. The total weight of a mutation type is Wi = Pi + ( Si / Ni ). The proportion of mutations of type i out of all mutations is then

Pr(i) = Wi / (Wt + Wm + Wb)

The proportion of each mutation is thus related to its prior weight and the average increase in score that it has caused over recent generations. The prior weights can be used to control the expected (and starting) proportions of the mutation types, as well as how sensitive the proportions are to the course of events in a run. It is generally a good idea to make the topology prior much larger than the others so that when no mutations are improving the score many topology mutations are still attempted. If you set outputmostlyuselessfiles to 1, you can look at the “problog” file to determine what the proportions of the mutations actually were over the course of a run.

topoweight (weight on topology mutations)

topoweight (0 to infinity, 1.0) The prior weight assigned to the class of topology mutations (NNI, SPR and limSPR). Note that setting this to 0.0 turns off topology mutations, meaning that the tree topology is fixed for the run. This used to be a way to have the program estimate only model parameters and branch-lengths, but the optimizeinputonly setting is now a better way to go.

modweight (weight on model parameter mutations)

modweight (0 to infinity, 0.05) The prior weight assigned to the class of model mutations. Note that setting this at 0.0 fixes the model during the run.

brlenweight (weight on branch-length parameter mutations)

brlenweight (0 to infinity, 0.2) The prior weight assigned to branch-length mutations.

The same procedure used above to determine the proportion of Topology:Model:Branch-Length mutations is also used to determine the relative proportions of the three types of topological mutations (NNI:SPR:limSPR), controlled by the following three weights. Note that the proportion of mutations applied to each of the model parameters is not user controlled.

randnniweight (weight on NNI topology changes)

randnniweight (0 to infinity, 0.1) - The prior weight assigned to NNI mutations.

randsprweight (weight on SPR topology changes)

randsprweight (0 to infinity, 0.3) - The prior weight assigned to random SPR mutations. For very large datasets it is often best to set this to 0.0, as random SPR mutations essentially never result in score increases.

limsprweight (weight on localized SPR topology changes)

limsprweight (0 to infinity, 0.6) - The prior weight assigned to SPR mutations with the reconnection branch limited to being a maximum of limsprrange branches away from where the branch was detached.

intervallength

intervallength (10 to 1000, 100) – The number of generations in each interval during which the number and benefit of each mutation type are stored.

intervalstostore

intervalstostore = (1 to 10, 5) – The number of intervals to be stored. Thus, records of mutations are kept for the last (intervallength x intervalstostore) generations. Every intervallength generations the probabilities of the mutation types are updated by the scheme described above.

Settings controlling mutation details

limsprrange (max range for localized SPR topology changes)

limsprrange (0 to infinity, 6) – The maximum number of branches away from its original location that a branch may be reattached during a limited SPR move. Setting this too high (> 10) can seriously degrade performance, but if you do so in conjunction with a large increase in genthreshfortopoterm you might end up with better trees.

meanbrlenmuts (mean # of branch lengths to change per mutation)

meanbrlenmuts (1 to # taxa, 5) - The mean of the binomial distribution from which the number of branch lengths mutated is drawn during a branch length mutation.

gammashapebrlen (magnitude of branch-length mutations)

gammashapebrlen (50 to 2000, 1000) - The shape parameter of the gamma distribution (with a mean of 1.0) from which the branch-length multipliers are drawn for branch-length mutations. Larger numbers cause smaller changes in branch lengths. (Note that this has nothing to do with gamma rate heterogeneity.)

gammashapemodel (magnitude of model parameter mutations)

gammashapemodel (50 to 2000, 1000) - The shape parameter of the gamma distribution (with a mean of 1.0) from which the model mutation multipliers are drawn for model parameters mutations. Larger numbers cause smaller changes in model parameters. (Note that this has nothing to do with gamma rate heterogeneity.)

uniqueswapbias (relative weight assigned to already attempted branch swaps)

uniqueswapbias (0.01 to 1.0, 0.1) – With version 0.95 and later, GARLI keeps track of which branch swaps it has attempted on the current best tree. Because swaps are applied randomly, it is possible that some swaps are tried twice before others are tried at all. This option allows the program to bias the swaps applied toward those that have not yet been attempted. Each swap is assigned a relative weight depending on the number of times that it has been attempted on the current best tree. This weight is equal to (uniqueswapbias) raised to the (# times swap attempted) power. In other words, a value of 0.5 means that swaps that have already been tried once will be half as likely as those not yet attempted, swaps attempted twice will be ¼ as likely, etc. A value of 1.0 means no biasing. If this value is not equal to 1.0 and the outputmostlyuseless files option is on, a file called <ofprefix>.swap.log is output. This file shows the total number rearrangements tried and the number of unique ones over the course of a run. Note that this bias is only applied to NNI and limSPR rearrangements. Use of this option may allow the use of somewhat larger values of limsprrange.

distanceswapbias (relative weight assigned to branch swaps based on locality)

distanceswapbias (0.1 to 10, 1.0) – This option is similar to uniqueswapbias, except that it biases toward certain swaps based on the topological distance between the initial and rearranged trees. The distance is measured as in the limsprrange, and is half the the Robinson-Foulds distance between the trees. As with uniqueswapbias, distanceswapbias assigns a relative weight to each potential swap. In this case the weight is (distanceswapbias) raised to the (reconnection distance - 1) power. Thus, given a value of 0.5, the weight of an NNI is 1.0, the weight of an SPR with distance 2 is 0.5, with distance 3 is 0.25, etc. Note that values less than 1.0 bias toward more localized swaps, while values greater than 1.0 bias toward more extreme swaps. Also note that this bias is only applied to limSPR rearrangements. Be careful in setting this, as extreme values can have a very large effect.