BAMBE

Bayesian Analysis in Molecular Biology and Evolution

Version 2.03 beta, January 2001

Run control file format

The run control file contains all of the run characteristics and tree and parameter initialization information. Here is the default run control file.

#################### BAMBE Default Run Control File #################### 
# Last updated September 16, 1999   Change parameters as necessary.
# Any text on a line after the symbol `#' is a comment. 
########################################################################

#
# general run settings
#
seed = 194024933              # 1 < odd integer < 2147483647 (2^31 - 1)
burn = 1000                   # number of cycles to run burn algorithm 
cycles = 6000                 # number of cycles to run main algorithm 
burn-algorithm = global       # global or local
main-algorithm = local        # global or local
use-beta = false              # use scaled beta distribution modification of local
window-interval = 200         # interval to print information to the screen 

#
# output run settings
#
sample-interval = 10          # interval to save information to file
file-root = run1              # root name for output files
newick-format = true          # format of output tree, false implies bambe format

#
# model specification
#
molecular-clock = true        # true or false 
likelihood-model = HKY85      # F84, HKY85, TN93 are current choices 
category-list = 1*            # one site category
single-kappa = false          # use separate kappa values for all site categories 
initial-kappa = 2.0
initial-theta = 1.0
estimate-pi = true            # use empirical relative frequencies
#initial-pia = 0.25
#initial-pig = 0.25
#initial-pic = 0.25
#initial-pit = 0.25
#initial-ttp = 1.0
#initial-gamma = 1.0

#
# parameter updating
#
parameter-update-interval = 1 # number of tree updates after each parameter update 
                              # use 0 for no parameter updating 
update-kappa = true           # transition/tranversion bias parameters, not used with TN93
update-theta = true           # substitution rate parameters 
update-pi = true              # base relative frequency parameters
update-ttp = true             # transition/transversion parameters for TN93
update-gamma = true           # transition/transversion parameters for TN93

# 
# tuning parameters
# 
tune-interval = 200         # interval to adapt global-tune during burn-in 
global-tune = 0.01          # half window width for global
local-tune = 0.19           # stretch parameter for local
theta-tune = 2000.0         # Dirichlet parameter for theta update
pi-tune = 2000.0            # Dirichlet parameter for pi update
kappa-tune = 0.1            # half window width for kappa update
#ttp-tune = 0.1              # half window width for ttp update
#gamma-tune = 0.1            # half window width for gamma update
beta-tune = 10.0            # Beta parameter for local update (with beta)

#
# data file
#
data-file = infile          # file name
outgroup = 1

#
# initial tree information
#
initial-tree-type = random    # random, upgma, neighbor-joining, newick, or bambe  
max-initial-tree-height = 0.1 # height of initial random tree
#tree-file = treefile          # name of file with initial tree (newick or bambe)

In addition to this example, the distribution contains several other sample run control files.

All options may be entered into the run control file in any order. The symbol `=' appears after the name of the option followed by the value. White space may separate the run parameter name, the equal sign, and the value. Any text after the symbol `#' on a line is a comment and ignored. All options have default values, which are boldface in the following table.

Run control file options.
Option Choices Description
seed 1 < odd integer < 2147483647.
Default is 194024933 Seed for random number generator.
burn Any nonnegative integer.
Default is 1000 Number of cycles to run the burn algorithm.
Parameter values are not updated during burn.
User should discard these cycles and the initial cycles of the main algorithm before summarizing the remaining results.
cycles Any nonnegative integer.
Default is 6000 Number of cycles to run the main algorithm.
burn-algorithm global or local Algorithm to run during burn.
main-algorithm global or local Algorithm to run during production cycles.
use-beta true or false Indicates whether or not to use the Beta distribution modification of the local algorithm.
window-interval Any nonnegative integer.
Default is 200 Interval at which tree topology and parameter values are printed to screen.
sample-interval Any positive integer.
Default is 10 During burn and main algorithms, the tree topology, log likelihoods, and parameters are written to files at each cycle divisible by this value.
file-root Any valid file name.
Default is run1 Output files use file-root in their file names.
newick-format true or false. Indicates the format of the output tree. False implies BAMBE format which mimics the internal data structure of the tree and is useful for debugging.
molecular-clock true or false Indicates if molecular clock is used during run of the main algorithm.
likelihood-model HKY85, F84, or TN93 Hasegawa, Kishino, Yano (1985),
Felsenstein's PHYLIP (1984),
Tamura-Nei (1993).
See section on likelihood models for more detail.
category-list A valid category list.
Default is 1*
A comma-separated list of categories with optional repeat counts and optionally one repetitive asterisk. See the section on category lists for more details.
single-kappa true or false If true, the same kappa parameter is used for all site categories. If false, there are different values for different site categories. It has no effect if there is only one rate category.
initial-kappa Comma separated list of positive kappa values.
Default is 2.0 If single-kappa is true, a warning is given if more than one value is specified. The first value will be used. If single-kappa is false, a value must be specified for each category in use.
initial-theta Comma separated list of positive theta values.
Default is 1.0 The weighted average of these values should be 1, with weights given by the proportion of sites in each site category. (Renormalization is automatic and a warning given if the condition fails.) If there are an equal number of sites in each category, for example, the numbers should average to 1.
estimate-pi true or false
If true, the initial stationary probabilities for each base in each category are estimated by the relative frequencies with which they appear in the data.
initial-pia Comma separated list of positive numbers between 0 and 1.
Default is 0.25 if estimate-pi is false. The initial stationary probability of the base A. There must be a value specified for each site-category used if estimate-pi is false.
initial-pig Comma separated list of positive numbers between 0 and 1.
Default is 0.25 if estimate-pi is false. The initial stationary probability of the base G. There must be a value specified for each site-category used if estimate-pi is false.
initial-pic Comma separated list of positive numbers between 0 and 1.
Default is 0.25 if estimate-pi is false. The initial stationary probability of the base C. There must be a value specified for each site-category used if estimate-pi is false.
initial-pit Comma separated list of positive numbers between 0 and 1.
Default is 0.25 if estimate-pi is false. The initial stationary probability of the base T. There must be a value specified for each site-category used if estimate-pi is false.
initial-ttp Comma separated list of positive transition/transversion parameter values.
Default is 1.0 This is used only with TN93. There must be a value specified for each site-category used if TN93 is the chosen model.
initial-gamma Comma separated list of positive gamma values.
Default is 1.0 This is used only with TN93. There must be a value specified for each site-category used if TN93 is the chosen model.
parameter-update-interval Any nonnegative integer.
Default is 1 During the main algorithm, any ``on'' parameters are updated at each cycle divisible by this value.
update-kappa true or false Indicates if kappa parameter value(s) are updated. Not used in model TN93.
update-theta true or false Indicates if theta parameter value(s) are updated.
update-pi true or false Indicates if pi parameter values are updated.
update-ttp true or false Indicates if the ttp parameter values are updated. Only used if the model is TN93.
update-gamma true or false Indicates if the gamma parameter values are updated. Only used if the model is TN93.
tune-interval Any positive integer.
Default is 200 While running global during the burn, if the acceptance rate for tree proposal falls below 15% during this interval, global-tune is halved.
global-tune Positive number.
Default is 0.01 This tuning parameter is only used with the global algorithm during burn. The smaller its value, the greater the tree acceptance rate will be.
local-tune Positive number.
Default is 0.19 This tuning parameter is only used with the local algorithm. It modulates the size of a maximal stretch. The smaller its value, the greater the tree acceptance rate will be.
theta-tune Any positive real number
Default is 2000.0 Tuning parameter used during update of theta value(s). The larger its value, the more likely proposals are to be accepted.
pi-tune Any positive real number
Default is 2000.0 Tuning parameter used during update of pi values. The larger its value, the more likely proposals are to be accepted.
kappa-tune Positive number.
Default is 0.1 This tuning parameter is only used when parameter-update-interval is positive and update-kappa is true. The smaller its value, the greater the parameter acceptance rate will be.
ttp-tune Positive number.
Default is 0.1 This tuning parameter is only used when parameter-update-interval is positive and update-ttp is true. The smaller its value, the greater the parameter acceptance rate will be.
gamma-tune Positive number.
Default is 0.1 This tuning parameter is only used when parameter-update-interval is positive and update-gamma is true. The smaller its value, the greater the parameter acceptance rate will be.
beta-tune Positive number.
Default is 10.0 This tuning parameter is only used if use-beta is true The larger its value, the greater the parameter acceptance rate will be.
data-file Filename in directory program is run that contains data
Default is infile Data may be in either BAMBE or CLUSTAL formats. The format is automatically recognized.
outgroup Positive integer with outgroup in order of data file.
Default is 1 This is ignored if a molecular clock is assumed. In the absence of a clock, trees and tree topologies are printed with the outgroup emerging directly from the root.
initial-tree-type random, upgma, neighbor-joining, newick, or bambe
random selects a tree from the prior;
upgma sets the initial (clock) tree to the UPGMA tree using maximum likelihood distances with the specified model and initial parameter values;
neighbor-joining sets the initial (nonclock) tree to the neighbor joining tree using maximum likelihood distances with the specified model and initial parameter values;
newick reads in an initial tree in Newick format from a file;
bambe reads in an initial tree in BAMBE format from a file.
max-initial-tree-height Positive number.
Default is 0.1 This parameter is only used to generate an initial random tree.
tree-file Filename in directory in which the program is run that contains the initial tree.
Default is treefile. This is only used if initial-tree-type is newick or bambe, and the format should match.

Run control file options.
Option	Choices	Description
`seed`	1 < odd integer < 2147483647. Default is 194024933	Seed for random number generator.
`burn`	Any nonnegative integer. Default is 1000	Number of cycles to run the burn algorithm. Parameter values are not updated during burn. User should discard these cycles and the initial cycles of the main algorithm before summarizing the remaining results.
`cycles`	Any nonnegative integer. Default is 6000	Number of cycles to run the main algorithm.
`burn-algorithm`	global or local	Algorithm to run during burn.
`main-algorithm`	global or local	Algorithm to run during production cycles.
`use-beta`	true or false	Indicates whether or not to use the Beta distribution modification of the local algorithm.
`window-interval`	Any nonnegative integer. Default is 200	Interval at which tree topology and parameter values are printed to screen.
`sample-interval`	Any positive integer. Default is 10	During burn and main algorithms, the tree topology, log likelihoods, and parameters are written to files at each cycle divisible by this value.
`file-root`	Any valid file name. Default is run1	Output files use file-root in their file names.
`newick-format`	true or false.	Indicates the format of the output tree. False implies BAMBE format which mimics the internal data structure of the tree and is useful for debugging.
`molecular-clock`	true or false	Indicates if molecular clock is used during run of the main algorithm.
`likelihood-model`	HKY85, F84, or TN93	Hasegawa, Kishino, Yano (1985), Felsenstein's PHYLIP (1984), Tamura-Nei (1993). See section on likelihood models for more detail.
`category-list`	A valid category list. Default is 1* A comma-separated list of categories with optional repeat counts and optionally one repetitive asterisk.	See the section on category lists for more details.
`single-kappa`	true or false	If true, the same kappa parameter is used for all site categories. If false, there are different values for different site categories. It has no effect if there is only one rate category.
`initial-kappa`	Comma separated list of positive kappa values. Default is 2.0	If single-kappa is true, a warning is given if more than one value is specified. The first value will be used. If single-kappa is false, a value must be specified for each category in use.
`initial-theta`	Comma separated list of positive theta values. Default is 1.0	The weighted average of these values should be 1, with weights given by the proportion of sites in each site category. (Renormalization is automatic and a warning given if the condition fails.) If there are an equal number of sites in each category, for example, the numbers should average to 1.
`estimate-pi`	true or false	If true, the initial stationary probabilities for each base in each category are estimated by the relative frequencies with which they appear in the data.
`initial-pia`	Comma separated list of positive numbers between 0 and 1. Default is 0.25 if `estimate-pi` is false.	The initial stationary probability of the base A. There must be a value specified for each site-category used if `estimate-pi` is false.
`initial-pig`	Comma separated list of positive numbers between 0 and 1. Default is 0.25 if `estimate-pi` is false.	The initial stationary probability of the base G. There must be a value specified for each site-category used if `estimate-pi` is false.
`initial-pic`	Comma separated list of positive numbers between 0 and 1. Default is 0.25 if `estimate-pi` is false.	The initial stationary probability of the base C. There must be a value specified for each site-category used if `estimate-pi` is false.
`initial-pit`	Comma separated list of positive numbers between 0 and 1. Default is 0.25 if `estimate-pi` is false.	The initial stationary probability of the base T. There must be a value specified for each site-category used if `estimate-pi` is false.
`initial-ttp`	Comma separated list of positive transition/transversion parameter values. Default is 1.0	This is used only with TN93. There must be a value specified for each site-category used if TN93 is the chosen model.
`initial-gamma`	Comma separated list of positive gamma values. Default is 1.0	This is used only with TN93. There must be a value specified for each site-category used if TN93 is the chosen model.
`parameter-update-interval`	Any nonnegative integer. Default is 1	During the main algorithm, any ``on'' parameters are updated at each cycle divisible by this value.
`update-kappa`	true or false	Indicates if kappa parameter value(s) are updated. Not used in model TN93.
`update-theta`	true or false	Indicates if theta parameter value(s) are updated.
`update-pi`	true or false	Indicates if pi parameter values are updated.
`update-ttp`	true or false	Indicates if the ttp parameter values are updated. Only used if the model is TN93.
`update-gamma`	true or false	Indicates if the gamma parameter values are updated. Only used if the model is TN93.
`tune-interval`	Any positive integer. Default is 200	While running global during the burn, if the acceptance rate for tree proposal falls below 15% during this interval, global-tune is halved.
`global-tune`	Positive number. Default is 0.01	This tuning parameter is only used with the global algorithm during burn. The smaller its value, the greater the tree acceptance rate will be.
`local-tune`	Positive number. Default is 0.19	This tuning parameter is only used with the local algorithm. It modulates the size of a maximal stretch. The smaller its value, the greater the tree acceptance rate will be.
`theta-tune`	Any positive real number Default is 2000.0	Tuning parameter used during update of theta value(s). The larger its value, the more likely proposals are to be accepted.
`pi-tune`	Any positive real number Default is 2000.0	Tuning parameter used during update of pi values. The larger its value, the more likely proposals are to be accepted.
`kappa-tune`	Positive number. Default is 0.1	This tuning parameter is only used when `parameter-update-interval` is positive and `update-kappa` is true. The smaller its value, the greater the parameter acceptance rate will be.
`ttp-tune`	Positive number. Default is 0.1	This tuning parameter is only used when `parameter-update-interval` is positive and `update-ttp` is true. The smaller its value, the greater the parameter acceptance rate will be.
`gamma-tune`	Positive number. Default is 0.1	This tuning parameter is only used when `parameter-update-interval` is positive and `update-gamma` is true. The smaller its value, the greater the parameter acceptance rate will be.
`beta-tune`	Positive number. Default is 10.0	This tuning parameter is only used if `use-beta` is true The larger its value, the greater the parameter acceptance rate will be.
`data-file`	Filename in directory program is run that contains data Default is infile	Data may be in either BAMBE or CLUSTAL formats. The format is automatically recognized.
`outgroup`	Positive integer with outgroup in order of data file. Default is 1	This is ignored if a molecular clock is assumed. In the absence of a clock, trees and tree topologies are printed with the outgroup emerging directly from the root.
`initial-tree-type`	random, upgma, neighbor-joining, newick, or bambe	random selects a tree from the prior; upgma sets the initial (clock) tree to the UPGMA tree using maximum likelihood distances with the specified model and initial parameter values; neighbor-joining sets the initial (nonclock) tree to the neighbor joining tree using maximum likelihood distances with the specified model and initial parameter values; newick reads in an initial tree in Newick format from a file; bambe reads in an initial tree in BAMBE format from a file.
`max-initial-tree-height`	Positive number. Default is 0.1	This parameter is only used to generate an initial random tree.
`tree-file`	Filename in directory in which the program is run that contains the initial tree. Default is treefile.	This is only used if `initial-tree-type` is newick or bambe, and the format should match.

Back to the table of contents.

This page was most recently updated on January 19, 2001.

bambe@mathcs.duq.edu