Using an input file

The program levolution is launched via the command line, preferentially with the name of an input file as the only argument. All necessary arguments are then specified in the input file, which is the most convenient way to specify arguments since they are stored in a reusable fashion. Basically, an input file a simple collection of pairs of argument names and corresponding values (separated by one or several white space characters, i.e. blanks or tabs). While each name-value pair has to be at the beginning of a new line, the order is of no importance.

Comments may either be added after a name-value pair or given on a line on their own. Note that all comments must be proceeded with a double slash ``//''. Empty lines may be present anywhere within the file and are ignored. A minimal input file to conduct some simulations may look like this:

//My first input file for levolution!
task simulate
birthRate 1
deathRate 1
age 1000
numLeaves 100
rootState 0
brownVar 1
alpha 5
numJumps 4

Suppose the input file is named example.input, the program has to be launched as follows:

levolution example.input

Command Line Arguments

Additionally, arguments may be passed on the command line. In that case, arguments that are also given in the input file will be overwritten. The required syntax is as follows:

levolution example.input --name value

where name is the name of an argument and value is the corresponding value. For instance,

levolution example.input --outName test --alpha 2

launches .code:levolution as specified in example.input but adds the argument outName, which specifies a prefix for all output files, and also sets alpha=2 and thus overwrites the specification alpha=5 in the input file. Note that some arguments do not require a value.

There is no restriction on the number of arguments to be passed that way and arguments can also be specified on the command line only. Also, the order in which the arguments are given, both in the input file or on the command line, is of no importance. However, if an input file is to be used, the program levolution requires the name of it to be the first argument specified.

Note that previous versions of levolution required arguments to be passed using the name=value format. That format is still supported.

Choosing the right Task

Note that levolution is designed to perform multiple tasks. To specify the desired task, the mandatory argument task has to be specified either in the input file or on the command line. Available tasks are:

• simulate
• infer
• inferJumps
• testMCMC
• F-test

Progress Report & Log File

By default, levolution writes only minimal information to the screen. To get a more detailed progress report printed to the screen, simply add the argument verbose either in the input file or on the command line, for instance:

levolution example.input verbose

Alternatively, v can also write the progress report to a log file. To invoke this, simply use the argument logFile, followed by the name of the desired file. For instance,

levolution example.input --logFile example.log

will tell levolution to write the progress report to a file named example.log. Note that this will overwrite any existing file with that name. Note further that verbose and logFile can both be used at the same time.