Simulating traits

If the user needs to simulate data levolution offers the tools to do so. For instance, to simulate traits under an already existing tree then simply type in a command like this:

./levolution task=simulate rootState=0 brownVar=1 alpha=5 lambda=0.5

Here, the user needs to specify the parameters by which the trait values will be generated. For all cases, the arguments rootState, brownVar, alpha, and lambda are mandatory. Alternatively to the jump rate lambda one can also directly give the total number of jumps present on the tree with the argument numJumps. The value passed to rootState denotes the value at which the trait will start evolving. The value passed to brownVar denotes the Brownian variance during trait evolution. alpha will give the ratio of jump to brownian variance, and lambda or numJumps the jump rate or number of jumps, respectively. If the user wants to simulate traits evolving under pure Brownian motion without jumps then simply set alpha=1 and lambda=0 (or numJumps=0), like this:

./levolution task=simulate rootState=0 brownVar=1 alpha=1 lambda=0

Simulating trees and traits

To simulate both trees and trait values, specify task=simulate. Then specify the mandatory parameters: birthRate, deathRate, age, numLeaves, as well as the previous ones rootState, brownVar, alpha, and lambda (or numJumps). An example command line might look like this:

./levolution task=simulate birthRate=1 deathRate=1 age=1000 numLeaves=100 rootState=0 brownVar=1 alpha=5 lambda=0.5

This command line will simulate 1) a tree with 100 leaves, with a birth and death rate of 1, and with a total age of 1000 time units, and 2) 100 trait values that evolved from a starting root state value of 0, a brownian variance of 1, a jump variance that is 5 times larger than the brownian variance (alpha=5), and a jump rate (lambda) of 0.5.

Scaling of branch lengths

For some simulation purposes, or for studies involving comparisons between trees it is sometimes useful to scale the branch lengths or the total tree length to a unique single value. To accomplish this, simply add scaleTo=<someNumericValue> to the command line shown above. This will make all the branch lengths sum to the value entered by the user. For example scaleTo=1 will make all the branch lengths sum to 1.

Output files

Two output files will be generated: a tree file with the default name levolution.tree, and a traits file levolution.traits. Note that if you give a tree as input then only a traits file will be output. To change the default "levolution" just add outName=<myOutName> to the command line shown above. The output tree file and traits file will follow the same format described in input formats.