Tuning model optimization and tree search

Choosing which parameters to optimize

By default, RAxML-NG will optimize all free model parameters (e.g., substitution rates and/or alpha parameter of discrete GAMMA distribution) as well as tree branch lengths. In most situations, this is the most reasonable choice. Nevertheless, RAxML-NG also offers ways to disable parameter optimization:

1. In tree evaluation mode (--evaluate option), you can use --opt-branches off and --opt-model off switches to disable branch length and model parameters optimization, respectively. You can re-use the optimized model parameters obtained in a previous RAxML-NG run:

raxml-ng --evaluate --opt-branches off --opt-model off --msa test.fa --tree oldRun.raxml.bestTree --model oldRun.raxml.bestModel

You can also use a shortcut command, --loglh:

raxml-ng --loglh --msa test.fa --tree oldRun.raxml.bestTree --model oldRun.raxml.bestModel

Please note, that --opt-branches off and --opt-model off options have no effect in the tree search mode.

2. Alternatively, individual parameters can be fixed to the user-specified values by making adjustments to the model definition. For instance:

raxml-ng --msa test.fa --model HKY{2.3/1}+G{1.5}

Per-rate-category likelihood scalers

When computing likelihoods on very large trees (thousands of taxa), condition likelihood vectors (CLVs) close to the virtual roots contain very small values. To avoid numerical underflow, RAxML(-NG) uses a simple technique called 'scaling': if all CLV entries are below a certain threshold, they are all multiplied with a (large) constant C. This is then compensated for by adding log(1/C) to the site log-likelihood. However, this approach can lead to problems with the Γ model of rate heterogeneity (see Izquierdo-Carrasco et al. 2012). To deal with this issue, RAxML-NG supports an alternative scaling mode in which CLVs for each Γ category are scaled independently (see technical discussion here). This per-category scaling mode incurs significant performance overhead, and therefore it is off by default. However, if you are are analysing a very large dataset (>~5000 taxa) with +G model, please consider using --rate-scalers on to avoid numerical problems.

Tuning tree search heuristic

RAxML-NG inherits its tree search algorithm from RAxML, which was described in (Stamatakis et al. 2005) and (Stamatakis et al. 2007). Please refer to these papers to gain better understanding of tuning parameters listed below.

Command	Meaning
--spr-radius N	SPR re-insertion radius for fast iterations (default: auto-detect). This option corresponds to -i in RAxML 8.x.
--spr-cutoff N	Relative LH cutoff for descending into subtrees (default: 1.0). This heuristic can be disabled with --spr-cutoff off, which corresponds to the slow hill-climbing algorithm in RAxML 8.x (-f o option)

Bootstrapping

By default, RAxML-NG bootstrapping analysis (--bootstrap and --all commands) will infer up to 1000 replicate trees (using autoMRE convergence test, see below), and then compute branch support using classical Felsentein's algorithm. This behavior can be modified in following ways:

1. Number of replicate trees can be set with the --bs-trees option, e.g.

raxml-ng --all --msa ali.fa --model GTR+G --bs-trees 500

2. Bootstopping: Alternatively, sufficient number of replicates can be determined automatically using the autoMRE bootstrap convergence test (so-called bootstopping, Pattengale et al. 2009):

raxml-ng --all --msa ali.fa --model GTR+G --bs-trees autoMRE

The maximum number of replicates can be additionally specified in curly brackets, e.g. --bs-trees autoMRE{500} (default: 1000). The 'strictness' of convergence test can be adjusted by changing the cutoff value (e.g. --bs-cutoff 0.01), although the default setting (0.03) should be appropriate in most cases.

3. Starting trees: In raxml-ng v1.2.0 and later, bootstrap searches will start from a parsimony tree by default. To use random starting trees instead, add --extra bs-start-rand option. Using random starting trees incurs substantial performance penalty (~30%), but eliminates potential bias towards parsimony tree topology. However, the difference in average support values seems to be negligible in practice (<=1-2 points).

4. Transfer Bootstrap Expectation (Lemoine et al., Nature 2018) is a recent alternative to the classical Felsenstein's bootstrap which can better reveal support for deep branches in very large phylogenies (thousands of taxa). It can be used as follows:

raxml-ng --all --msa ali.fa --model GTR+G --bs-metric TBE

Transfer bootstrap can be also computed from an existing set of replicate trees using the --support command:

raxml-ng --support --tree bestML.tree --bs-trees bootstraps.tree --bs-metric TBE

Expert options

Many internal default settings cam be changed via --extra flag. While not required for "regular" usage, it could be very helpful for debugging, benchmarking and exploration.

Command	Meaning
--extra bs-start-pars	Use parsimony starting trees in bootstrap searches
--extra bs-start-rand	Use random starting trees in bootstrap searches
--extra compat-v11	Run in raxml-ng v1.1.0 compatibility mode
--extra constraint-old	Use "old" algorithm for topological constraint check
--extra constraint-new	Use "new" algorithm for topological constraint check
--extra energy-off	Disable energy consumption monitoring and reporting
--extra fastclv-on	Enable fast CLV recomputation in SPR rounds
--extra fastclv-off	Disable fast CLV recomputation in SPR rounds
--extra lb-naive	Use "naive" round-robin load balancing algorithm
--extra lb-kassian	Use original partition-aware load balancing algorithm from (Kobert 2014)
--extra lb-benoit	Use improved load balancing algorithm accounting for site weights
--extra pars-par	Compute parsimony trees in parallel
--extra pars-seq	Compute parsimony trees sequentially
--extra rba-nopartload	Disable partial loading of RBA alignments
--extra tbe-naive	Use naive&slow TBE computation algorithm
--extra tbe-nature	Use fast re-implementation of the original TBE algorithm (Lutteropp 2020)
--extra thread-pin	Enable thread pinning
--extra thread-nopin	Disable thread pinning