Skip to content

PopulationFunctionFromMaster

Jump to bottom
Tim Vaughan edited this page Jun 18, 2014 · 5 revisions

A PopulationFunctionFromMaster element allows a [[Trajectory specification|Trajectory]] simulation to be used to initialise a BEAST PopulationFunction object. Such objects are used in BEAST to compute coalescent tree probability densities.

For a usage example, see PopulationFunctionFromMasterExample.xml in the examples/ directory.

    <populationFunction spec='PopulationFunctionFromMaster'
         simulationTime="DOUBLE"
         nSamples="INTEGER"
         seed="INTEGER"
         recordTrajLogP="BOOLEAN"
         verbosity="INTEGER"
         popSizeExpression="STRING"
         origin="DOUBLE"
         popSizeStart="DOUBLE"
         popSizeEnd="DOUBLE">

      <!-- Stepper-->

      <!-- Stochastic Model -->

      <!-- Initial State -->

      <!-- Population End Conditions-->

      <!-- Outputs-->

    </populationFunction>

Note that unlike standard simulation types, the element which has PopulationFunctionFromMaster as its spec attribute is not named <run>. Instead, the name of the element depends on its context within the BEAST 2 XML file. The PopulationFunctionFromMaster object can be used wherever a BEAST PopulationFunction is expected.

The simulationTime attribute specifies the length of time the simulation is run for. This becomes a maximum time when other explicit end conditions are included.

The nSamples attribute sets a fixed number of evenly spaced population size samples to record. If this is left unspecified, the number of samples will depend on the particular "stepper" algorithm used to stochastically increment the state. (The default is Gillespie's stochastic simulation algorithm, in which case the population sizes are recorded following every reaction event.)

If provided, the values of the seed attribute is used to initialize the random number generator. If this is absent, a different seed is selected every time the simulation is run.

The optional recordTrajLogP attribute is used to tell MASTER to compute the probability density of the simulated trajectory. (Note that these densities will be approximate if an approximate stochastic integration stepper is used. The resulting density is recorded in the file produced by any JSON output element. The default value of this attribute is "false".

The verbosity attribute determines the amount of descriptive output to send to the screen during the simulation, on a scale of 0-3 where 0 means no output causes a maximum amount of output to be displayed.

The required popSizeExpression attribute determines how the population size returned by the PopulationFunction relates to the MASTER population sizes. This can be any simple arithmetic expression involving constants and/or population names. For example, a simple MASTER model with population X might use popSizeExpression="X". Alternatively, a more complicated model involving populations S and I might use popSizeExpression="I/(2*0.00075*S)". Structured populations are also supported via the same square bracket notation used elsewhere.

The required origin attribute specifies how time in the trajectory simulation relates to times measured as an age before the most recently sampled tree leaf. The value can be regarded as either the time before the most recent leaf that the simulation began, or equivalently as the time after the start of the simulation that the most recent leaf was sampled.

The optional popSizeStart and popSizeEnd attributes specify the population size that will be assumed if the PopulationFunction is asked for a size at a time outside of the bounds of the trajectory simulation. The default values are zero.

The following elements are described in detail on their own pages:

Note that only the model and initial state are absolutely mandatory - all other elements and attributes are optional. However, certain combinations of elements and attributes do not make sense. In particular, an error will be raised if simulationTime is unspecified and no end conditions are included, as this will result in an unending calculation.

Clone this wiki locally