Feast

These classes allow trees to be loaded at runtime from Newick files rather than stored in the BEAST 2 XML:

<tree spec='feast.fileio.TreeFromNewickFile' fileName="example.tree"
    IsLabelledNewick="true" adjustTipHeights="false" .../>

or

<tree spec='feast.fileio.TreeFromNexusFile' fileName="example.nexus"
    IsLabelledNewick="true" adjustTipHeights="false" .../>

The optional attribute treeIndex can be used to specify the index (starting from zero) of the tree to read from the file.

For Nexus files, only the first trees block encountered is processed.

Both classes are thin wrappers around TreeParser, so all of the various inputs supported by that class are also supported. In particular, setting adjustTipHeights to "true" causes all tip ages to be set to zero, which is sometimes desirable when reading in trees with only extant tips in order to avoid rounding errors. (Such rounding errors can cause problems with tree priors such as BDSKY which use the age of tips to classify samples as resulting from ρ-sampling or ψ-sampling.)

This class allows TraitSet objects to be configured directly from TaxonSet objects. This is similar in spirit to the "auto configuration" option provided by BEAUti to set up tree tip dates from information encoded in the sequence names. While it's not directly i/o related, it solves a common problem that occurs when trees are loaded from an external file.

Use this as you would usually use a TraitSet, but instead of including the trait assignments directly in the body, specify inputs indicating how to extract the trait values from the taxon names.

For instance:

<trait spec="feast.fileio.TraitSetFromTaxonSet"
       delimiter="|"
       everythingAfterLast="true"
       traitname="date"
       dateFormat="yyyy-M-dd">
       <taxa id="taxonSet" spec="TaxonSet" alignment="@alignment"/>
</trait>

Instead of everythingAfterLast="true", one can also use everythingBeforeFirst="true" or takeGroup="N" where N is the index of the group (delimited by the chosen delimiter).

This class allows TraitSet objects to be initialised from external CSV/TSV files.

Use this as you would use TraitSet, but instead of including the trait assignments in the body, use the inputs to direct the class to load the trait assignments from a file.

For example:

<trait spec="feast.fileio.TraitSetFromXSV"
       fileName="example.csv" sep=",">
  <taxa spec="TaxonSet" alignment="@alignment"/>
</trait>

loads trait values for a taxon set from the CSV file example.csv, which would have the following format

first_taxon, 12.3
second_taxon, 7.8
third_taxon, 15.4
...

The order of the lines in the input file is not important, and any taxon names in the file which don't match the taxa provided by the taxa input are ignored.

By default, taxon names are read from the first column (index 0) of the input file and values are read from the second (index 1). This behaviour can be customized through the taxonNameCol and traitValueCol inputs, which accept the indicies of the columns to use. All other columns in the input file besides the two specified here are ignored, so you can read multiple trait sets from a single file simply by specifying different traitValueCol values.

Finally, you can set the optional input skipFirstRow to "true" to cause TraitSetFromXSV to ignore the first line of the input file. This can be useful for CSV/TSV files which include a header line.

These classs allow TaxonSet and TraitSet objects to be initialized from trees. Like TraitSetFromTaxonSet, these classes don't themselves perform any file i/o, but makes it easier to work with trees loaded from external files, or simulated inline.

An example use of TaxonSetFromTree is:

<taxonset spec="feast.fileio.TaxonSetFromTree" tree="@tree"/>

which could be included as an input to a TraitSetFromXSV as described in the previous section.

TipDatesFromTree is used similarly to create a TraitSet object representing the ages of tips on an input tree:

<traitset id="tipDates" spec="feast.fileio.TipDatesFromTree" tree="@tree">
  <taxa id="taxonSet" spec="feast.fileio.TaxonSetFromTree" tree="@tree"/>
</traitset>

This class allows alignments to be loaded at runtime from Nexus or Fasta files rather than stored in the BEAST 2 XML:

<!-- Nexus: -->
<alignment spec='feast.fileio.AlignmentFromNexus' fileName="example.nexus"/>

<!-- Fasta: -->
<alignment spec='feast.fileio.AlignmentFromFasta' fileName="example.fasta"/>

Sequence files can also be referenced using a URL:

<!-- Nexus: -->
<alignment spec="feast.fileio.AlignmentFromNexus"
           url="https://example.com/alignment.nexus"/>

<!-- Fasta: -->
<alignment spec="feast.fileio.AlignmentFromFasta"
           url="https://example.com/alignment.fasta"/>

The Fasta import uses the sequence labels from the file as taxon labels.

Obviously these classes runs contrary to BEAST's philosophy of keeping everything necessary to run an analysis in the XML file. However, it is sometimes convenient to be able to do this. As a bonus, the xmlFileName attribute can be used to write the appropriate XML fragment to disk.

When setting up complicated analyses, it can be useful to extract some (fixed) parameter values from an external CSV or TSV (or whatever-SV) file. The RealParameterFromXSV and RealParameterFromLabelledXSV classes can be used to do this.

RealParameterFromXSV simply initializes the parameter with values read (in row-major order) from a rectangular portion of the table in the specified file. For instance,

<migrationRates spec="feast.fileio.RealParameterFromXSV"
                fileName="migration_rates.csv"
                sep=","
                startRow="1" rowCount="3"
                startCol="1" colCount="3"/>

could be used to initialize a 3x3 matrix of migration rates in some analysis using elements in a CSV file. The inputs startRow and startCol both default to "0", while leaving either rowCount and colCount undefined will cause values to be taken up until the end of the corresponding row or column.

RealParameterFromLabelledXSV works simillarly, but assumes that the either or both of the first row or column contain labels, and allows these labels to be used to specify elements. For example,

<samplingProportions spec="feast.fileio.RealParameterFromLabelledXSV"
    fileName="sampling.tsv"
    colLabels="sampling"
    rowLabels="early_cretaceous, late_cretaceous, jurassic"/>

could be used to set sampling rates for geological epochs from some external data file. If rowLabels is omitted, the entire column will be read. Similarly, if colLabels is omitted, the entire row is read.

An instance of feast.function.Sequence is a Function which contains a sequence of numbers evenly separated between two bounds. For instance, the following XML fragment represents a sequence of 101 numbers evenly spaced between 0 and 10, i.e. 0,0.1,0.2,…,9.9,10:

<function spec="feast.function.Sequence" start="0" stop="10" length="101"/>

An instance of the feast.function.Slice class is a Function which represent or more elements of another Function. This allows element-specific priors to be set, and individual elements to be logged.

Here's a simple example of using Slice to place a prior on a subset of elements of a RealParameter:

<distrib spec="Prior">
    <x spec="feast.function.Slice" arg="@samplingProportion" index="2" count="1"/>
    <distr spec="LogNormalDistributionModel" M="0" S="1"/>
</distrib>

The optional by input can be used to increase the step size between elements. For example, here's how one could use Slice to apply a prior to elements 1,3,5 of the same RealParamter:

<distrib spec="Prior">
    <x spec="feast.function.Slice" arg="@samplingProportion" index="1" count="3" by="2"/>
</distrib>

Instances of the feast.function.Reverse class are Funtion and Loggable which represent the elements of another Function but in reverse order.

An instance of the feast.function.Concatenate class is a Function whose elements are composed of the elements of their input Function objects joined together. For example, here is a Function representing a piecewise constant reproductive number to be used as input to the BDSKY tree prior, but composed of distinct input parameters rather than a single real parameter with multiple dimensions:

<reproductiveNumber spec="feast.function.Concatenate">
    <arg spec="RealParameter" value="1.0"/>
    <arg spec="RealParameter" value="2.0"/>
</reproductiveNumber>

Instances of feast.function.Scale allow one Function to be scaled by another:

<scaledBirthRate spec="feast.function.Scale">
  <function spec="RealParameter" value="1.0 2.0 3.0"/>
  <scaleBy spec="RealParameter" value="1.5"/>
</scaledBirthRate>

Instances of feast.function.Interleave represent the result of interleaving the elements of several input Function objects. For example:

<twoDemeBirthRate spec="feast.function.interleave">
  <arg spec="RealParameter" value="1 3 5 7"/>
  <arg spec="RealParameter" value="2 4 6 8"/>
</twoDemeBirthRate>

is as a Function with elements 1,2,3,4,5,6,7,8.

Finally, instances of feast.function.UniqueElementCount are Function objects which contain a single integer representing the number of unique values contained in the elements of an input Function. For example,

<uniqueValues spec="feast.function.UniqueElementCount">
    <arg spec="RealParameter" value="1.5 10 1.5 1.4"/>
</uniqueValues>

is a Function with a value of 3.

Takes an arithmetic expression and returns the result by acting as a Loggable or a Function. Binary operators can be applied to Functions (including Parameters) of different lengths as in R, with the result having the maximum of the two lengths, and the index into the shortest parameter being the result index modulo the length of that parameter. True and false are represented by 1.0 and 0.0 respectively.

Example expressions follow. (I and J are IDs of RealParameters with elements 1.0,2.0,3.0 and 5.0,10.0, respectively.)

Note that since each ExpCalculator is a Function object itself, it can be used as the input for other ExpCalculators.

As an example, here is a use of ExpCalculator to transform a parameter representing the reproductive number to a parameter representing the birth rate of some birth-death model:

<reproductiveNumber spec="feast.expressions.ExpCalculator"
                    value="birthRate/(deathRate+sampRate)">
  <arg idref="birthRate"/>
  <arg idref="deathRate"/>
</reproductiveNumber>

Notice that the expression is supplied as the value input. The arg inputs provide one or more Function objects to be referenced within the expression by their IDs.

When used exclusively for logging, the value caching behaviour ExpCalculator uses by default to reduce unnecessary computation can result in the expression not being updated as necessary. To avoid this, set the boolean useCaching input to false.

This is basically identical to ExpCalculator, but extends the abstract Distribution class, allowing the definition of arbitrary distributions over Rⁿ at runtime. Distributions can be specified in terms of their log or directly as probabilities (/probability densities).

The file ECdistribTest.xml in the examples/ folder is a simple example where a multi-variate normal distribution is constructed. This example also illustrates the nested expression concept mentioned above. The file ECdistribArraytest.xml in the same folder samples the same posterior, but uses array notation to express the target density.

This provides a cut-down version of the ExpCalculatorDistribution functionality that is compatible with beast.math.distributions.Prior.

The RealParameterFromFunction class provides a RealParameter which is initialized from a Function. Thus you can do things like

<samplingRateChangeTimes spec="feast.parameter.RealParameterFromFunction">
    <function spec="feast.expressions.ExpCalculator" value="{0,max(taxonTimes)+0.1}">
        <arg id="taxonTimes" spec="feast.function.TraitSetAsFunction" traitSet="@dateTrait"/>
    </function>
</samplingRateChangeTimes>

which initializes a BDSKY sampling rate change time array so that the change automatically falls just before the oldest sample.

Beware that RealParameterFromFunction only retrieves the Function values during initialization. Changes in the Function values after initialization will not be reflected in the parameter!

Particularly in birth-death models, it is often desirable to specify several points in time as ages relative to the "present". This is done when setting up change times for birth-death parameters, and requires one to do a fairly large number of error-prone calculations involving converting date strings like "05/03/1980" and "27/02/1980" to fractional years before some later date such as "01/01/1990". Once converted, these values become extremely important yet difficult to interpret entries in the final BEAST XML file.

The TimeParameter class is intended to combat this. It can be used anywhere that a RealParameter is expected. For example, to create a RealParameter with the ages corresponding to the times above, use

<parameter spec="feast.parameter.TimeParameter"
           time="05/03/1980 27/02/1980"
           mostRecentSampleTime="01/01/1990"
           timeFormat="dd/MM/yyyy"/>

This is completely equivalent to

<parameter spec="RealParameter"
           value="9.825137 9.844262"/>

but much more readable.

In addition, the timeEarlier and timeLater inputs can be used to set the bounds of the parameter. These are equivalent to upper and lower inputs of RealParameter, but accept formatted times.

Note that the time format specification string is the same as used by the dateFormat input to TraitSet, and applies both to the values of time and the value of mostRecentSampleTime. If this format specifier is not provided, the time is assumed to have already been converted to fractional years, so the only action taken by TimeParameter is to subtract this value from mostRecentSampleTime.

It's occasionally necessary to tie multiple elements of a RealParameter together, for instance to represent a vector of rates where a subset of these rates are conditioned to be identical. The BlockScaleOperator operator makes this possible. It behaves essentially identically to the standard BEAST 2 ScaleOperator, with inputs "parameter" and "indicator" specifying respectively the RealParameter to scale and the BooleanParameter indicating which elements to scale. The differences are that BlockScaleOperator

1. always scales the selected elements together (i.e. using the same scale factor), and
2. it correctly takes into account the number of degrees of freedom (i.e. unique element values) among the selected elements.

An example usage of this operator is as follows:

<operator spec="feast.operators.BlockScaleOperator" parameter="@paramToScale"
          scaleFactor="0.8" weight="1.0">
    <indicator spec="BooleanParameter" value="true true false false" estimate="false"/>
</operator>

Here "@paramToScale" references a RealParameter with 4 elements, and the operator jointly scales the first two.

An alternative approach is available in the SmartScaleOperator, which does not use indicator variables but instead considers elements with identical values to represent the same random variable. Thus, the following achieves the same result as above, with the added requirement that values to be scaled together must be initialised to the same value:

<state>
    <stateNode spec="RealParameter" id="paramToScale" value="1 1 2 2"/>
</state>

<operator spec="feast.operators.SmartScaleOperator" parameter="@paramToScale"
          scaleFactor="0.8" weight="1.0"/>

The SmartRealRandomWalkOperator acts analogously, but implements a random walk equivalent to BEAST's RealRandomWalkOperator applied only to unique elements.

Parameters of type IntegerParameter require special operators. Beast has two main operators for this type: IntUniformOperator (now deprecated in favour of UniformOperator) and IntRandomWalkOperator. Feast exptends this collection with a pair of operators allowing for joint operation on a subset of elements of a single IntegerParameter. The new operators are:

1. BlockIntUniformOperator and
2. BlockIntRandomWalkOperator.

These operators take the same inputs as the vanilla (non-block) BEAST 2 versions, but with the addition of an input named indicator which takes the same BooleanParameter input as the similarly-named input of the BlockScaleOperator described above.

The ShiftedPopulationModel class allows you to create a new PopulationFunction which is a time-shifted view of an existing population function.

For example, here is a time-shifted exponential growth population mode:

<populationModel spec="feast.popmodels.ShiftedPopulationModel" offset="0.5">
    <populationModel spec="ExponentialGrowth" popSize="1.0" growthRate="1.0"/>
</populationModel>

At time 0, the population size of this shifted model is the same as the population size of the exponential growth model at time 0.5.

The offset input expects a Function value, so RealParameter objectss etc. can also be used here.

BEAST 2 includes several commonly-used coalescent population models such as a constant population function and an exponential growth function. To add other population functions required writing a new Java class. The CompoundPopulationModel class lifts this restriction.

This class allows you to combine existing population functions (i.e. objects which implement the PopulationFunction interface) in a piecewise manner to construct arbitrarily complicated compound models.

For example, here is a piecewise-constant population function created by joining together three ConstantPopulation models:

<populationModel spec="feast.popmodels.CompoundPopulationModel">
    <populationModel spec="ConstantPopulation"> <popSize spec="RealParameter" value="5.0"/></populationModel>
    <populationModel spec="ConstantPopulation"> <popSize spec="RealParameter" value="10.0"/></populationModel>
    <populationModel spec="ConstantPopulation"> <popSize spec="RealParameter" value="2.0"/></populationModel>
    <changeTimes spec="RealParameter" value="1.0 3.0"/>
</populationModel>

The changeTimes input specifies the times of the transitions between models, and thus must have one less element than the number of constituent models.

Setting the boolean makeContinuous input to "true" (by default it is "false") will cause all component populations besides the most recent (i.e. first) to be scaled so that the resulting compound population function is continuous. While this is useless for compound population functions composed solely of constant components (as it will result in a single constant population function), this is useful for creating piecewise-exponential functions or mixtures between exponential and constant components.

The file piecewiseCoalescent.xml illustrates how this class can be used in a simple coalescent analysis.

The ExpressionPopulationModel class allows you to specify a population function symbolically using a mathematical expression evaluated at runtime.

For example, here is a sinusoidally-varying population function with an exponentially-decaying amplitude:

<populationModel spec="feast.popmodels.ExpressionPopulationModel">
  exp(0.1t)*(cos(2*t) + 2)
</populationModel>

These models can also depend on one or more RealParameter or Function objects:

<populationModel spec="ExpressionPopulationModel">
  exp(gamma*t)*(cos(omega*t) + 2)
  <arg id="omega" spec="RealParameter" value="0.3"/>
  <arg idref="gamma"/>
</populationModel>

taking care that these objects have IDs defined, since these IDs are used to refer to the objects inside of the expression.

The optional isLog input (boolean) can be used to indicate that the value of the expression is the natural logarithm of the population size rather than the population size itself.

The optional maxTimeToConsider input (double) can be used to change the maximum time to be considered when numerically inverting the "intensity function" (integral of 1/N(t)), a procedure necessary for simulating coalescent trees using this model.

For a complete description of the arithmetic expression syntax which can be used to specify population dynamics, refer to 2.3.1.

Beware: ExpressionPopulationModel uses numerical integration and numerical root finding algorithms to compute the "intensity" (integral of 1/N(t)) and its inverse. The current implementation of this algorithm, particularly the inverse, is slow and susceptible to numerical errors. Take care when using this population model, particularly for quickly-changing population functions!

The DirichletProcessPrior and DirichletProcessOperator allow the application of Dirichlet Process Priors (DPPs) to the elements of ~Function~s.

For example, suppose you have a model with parameter X to which you wish to apply such a prior. To do this, include the following prior for X in the target density:

<distribution spec="feast.modelselect.DirichletProcessPrior" parameter="@X">
    <scaleParameter id="dppScale" spec="RealParameter" value="1.0"/>
    <baseDistrib id="dppBase" spec="LogNormalDistributionModel" M="0.8" S="0.5"/>
</distribution>

You also need to include the following operator:

<operator spec="DirichletProcessOperator" parameter="@X"
          scaleParameter="@dppScale" baseDistrib="@dppBase" weight="1.0"/>

Other operators on X can be included, but only if they do not alter the number of elements of X which are identical.

While model selection is extremely complicated in general, it can be almost trivial when the number of models you wish to consider is small and the models can be regarded as special cases of either each other (i.e. the are nested) or can easily expressed as special cases of a single general model.

The ModelSelectionParameter is created with this kind of BSSVS-style model selection in mind. It is a CalculationNode implementing Function which takes one or more parameters (also Function~s) as input, together with an ~IntegerParameter known as the selection index. The ModelSelectionParameter acts as though it is the parameter specified by the selection index.

The simplest application of this is to allow BEAST to select between models 1 and 2, where in model 1 a parameter (eg the extinction rate) is zero, while in model 2 the extinction rate has some unknown non-zero value.

We can implement this by defining the death rate to be a ModelSelectionParameter:

<deathRate id="deathRate" spec="feast.modelselect.ModelSelectionParameter">
    <parameter spec="RealParameter" value="0.0"/>
    <parameter id="nonZeroDeathRate" spec="RealParameter" value="1.0"/>
    <selectionIndices id="selectionIdx" spec="IntegerParameter" value="1" lower="0" upper="1"/>
</deathRate>

We then use this "deathRate" parameter as input to the tree prior, place some sensible prior on "nonZeroDeathRate", and add an operator to modify the "selectionIdx" IntegerParameter. The result is equivalent to placing a "spike and slab" prior on the death rate parameter, which is a mixture between a point mass at zero and whatever prior you place on "nonZeroDeathRate".

In addition to this simple case, if "selectionIndices" is an IntegerParameter with more than one element, the additional ModelSelectionParameter input, "thisIndex", can be used to specify which element to use to select the parameter. This allows you to sample across models where, for example, subsets of different parameters are allowed to be exactly equal. In this case, each model parameter is its own ModelSelectionParameter, shares exactly the same set of "parameter" and "selectionIndices" inputs, but has its own unique value of "thisIndex".

Beware that ModelSelectionParameter is that is only compatible with distributions which take Function objects rather than RealParameter objects as input.

Occasionally we wish to characterise the posterior for a parameter or tree which is constrained to a small set of discrete traits. This can be accomplished using the DiscreteUniformJumpOperator.

For instance, suppose we have a small set of trees we want the MCMC to sample from. We can accomplish this as follows:

<operator spec="feast.modelselect.DiscreteUniformJumpOperator" x="@tree" weight="1">
  <possibility spec="TreeParser" adjustTipHeight="false" taxa="@alignment" estimate="false"
               newick="((((1:0.232 ..."/>
  <possibility spec="TreeParser" adjustTipHeight="false" taxa="@alignment" estimate="false"
               newick="(((5:1.2321 ..."/>
  <possibility spec="TreeParser" adjustTipHeight="false" taxa="@alignment" estimate="false"
               newick="((((3:4.222 ..."/>
</operator>

where the "…" are the remainder of the newick strings.

Take care when using this operator that the state nodes specified by the <possibility/> elements are actually possible values of x. I.e. parameters must have the same dimension and satisfy the bounds of x, and trees must correspond to the same set of taxa as x.

One BEAST 2 idiom which is pervasive in my code at least is the existance of StateNodes that initialize their own state stochastically. RandomTree is an example of this in the core: this class is a Tree that initializes itself by drawing from a coalescent distribution with a given population function.

While such classes usually exist to choose a starting state for the MCMC chain, it is often necessary - particularly in the validation phase of model development - to simulate a large number of instances of this simulated state. This is usually because the simulation is often done from some known distribution, which can then be compared against the output of MCMC.

The class feast.simulation.GPSimulator (from "general purpose simulator") class simply makes it possible to configure this kind of simulation using a BEAST XML file. It is simply a beast.core.Runnable that takes a BEASTObject as input, a number of iterations and some loggers. For each iteration, it then simply calls the BEASTObject's initAndValidate method and tells the loggers to write their results.

See examples/SimulateCoalescentTrees.xml for an example of using GPSimulator to simulate 100 coalescent trees.

While BEAST contains its own alignment simulator in beast.app.seqgen.SimulatedAlignment, this can be awkward to use as it requires pre-specifying the taxa to associate with the simulated alignment.

The feast.simulation.SimulatedAlignment class is a simpler alignment simulator which lifts this requirement. For example, the following will initialize an alignment by simulating sequences down the input tree using a Jukes-Cantor substitution model:

<alignment spec="feast.simulation.SimulatedAlignment"
           outputFileName="simulated_alignment.nexus"
           tree="@tree" sequenceLength="1000">
    <siteModel spec="SiteModel">
        <substModel spec="JukesCantor"/>
    </siteModel>
</alignment>

The class supports the same inputs as Alignment and beast.app.seqgen.SimulatedAlignment, with the exception that the data input should be omitted - it will cause strange errors if you include it. Also, only strict clocks are currently supported, so there is no branchRateModel input.

feast.simulation.SimulatedAlignment also allows you to specify a known ancestral sequence for the simulation. To do this, supply a Sequence to the startingSequence input as follows:

<alignment spec="feast.simulation.SimulatedAlignment"
           outputFileName="simulated_alignment.nexus"
           tree="@tree" sequenceLength="10">
  <startingSequence spec="Sequence" taxon="ancestor"> GATCGATCGA </startingSequence>
  <siteModel spec="SiteModel">
    <substModel spec="JukesCantor"/>
  </siteModel>
</alignment>

When used with startingSequence, the optional input startingSequenceAge can be used to specify the age relative to the most recent leaf at which the lineage above the root (the stem lineage) held the specified sequence. This might be useful for birth-death models which consider the stem lineage to be part of the tree.

Sometimes several attempts are needed to find a acceptable starting state for MCMC. An initializer for trees, capable of generating a new starting tree at each attempt is implemented in BEAST. In the same way, RandomRealParameter allows you to sample new initial parameter values at each attempt. The distribution, from which to sample, can be the parameter prior or any other proper distribution.

For example, here we sample a birth rate value from a uniform distribution at each initialization attempt:

<init spec="feast.parameter.RandomRealParameter" initial="@birthRate">
    <distr spec="beast.base.inference.distribution.Uniform" lower="0" upper="1.5"/>
</init>

Alternatively, you can use RandomRealParameter wherever BEAST expects a RealParameter:

<birthRate spec="feast.parameter.RandomRealParameter">
  <distr spec="beast.base.inference.distribution.Uniform" lower="0" upper="1.5"/>
</birthRate>

Occasionally, for the purpose of date randomization tests, it is useful to be able to randomize the association between taxon names and the input sequences. The ShuffledAlignment class makes this easy. Simply replace the existing alignment definition in the XML, which is usually something like

<alignment id="data" spec="Alignment"> ... </alignment>

with the folllowing:

<alignment id="data" spec="feast.simulation.ShuffledAlignment">
  <alignment spec="Alignment"> ... </alignment>
</alignment>

When doing this, take care that you move any ID defined on the original alignment object to the new ShuffledAlignment object.

This class provides an easy way to produce plots of the variation in a particular Distribution (i.e. probability density) as a function of one or more parameters. The class extends the BEAST Runnable abstract class and thus takes the place of the MCMC class in a regular BEAST XML. To use DensityMapper you'll therefore need to create an XML with the following general form:

<beast version="2.0">
    <run spec="feast.mapping.DensityMapper">
        <distribution id="distrib" ... />

        <realParam spec="RealParameter" id="paramA"
            value="V_A" lower="LOWER_A" upper="UPPER_A"/>
        <steps spec="IntegerParameter"
            value="STEPS_A"/>

        <realParam spec="RealParameter" id="paramB"
            value="V_B1 V_B2" lower="LOWER_B" upper="UPPER_B"/>
        <steps spec="IntegerParameter"
            value="STEPS_B1 STEPS_B2"/>

        <logger spec="Logger" logEvery="1">
            <log idref="paramA"/>
            <log idref="paramB"/>
            <log idref="distrib"/>
        </logger>

        <!-- Additional (screen?) loggers -->
    </run>
</beast>

The <realParam> elements specify which parameters are varied, the upper and lower bounds of these parameters specify the range over which the parameter is varied, and the corresponding <steps> elements specify the number of steps to use for each parameter. When the number of steps is 1 the parameter is not varied and instead the contents of the value attribute is used.

When parameters are vectors, the associated <steps> parameter may have dimension 1 in which case all elements of the vector parameter are varied together (e.g. [0,0], [0.1,0.1], …, [1, 1]). Alternatively, the steps parameter may have dimension equal to that of the real parameter in which case each element of the parameter is varied independently with the corresponding number of steps (e.g. [0,0], [0, 0.1], …, [0, 1], [0.1, 0.0], …, [1, 1]). To keep one component of a vector parameter fixed, set the corresponding steps element to 1.

If, in addition to the <realParam> and <steps> elements a <logScale> BooleanParameter element is provided, DensityMapper will evaluate the densities at a logarithmic distribution of parameter values between the same bounds. I.e., the following snippet will cause paramA to be set to values logarithmically distributed between LOWER_A and UPPER_A:

<realParam spec="RealParameter" id="paramA"
    value="V_A" lower="LOWER_A" upper="UPPER_A"/>
<steps spec="IntegerParameter"
    value="STEPS_A"/>
<logScale spec="BooleanParameter"
    value="true"/>

Take care that if the log-scale element is provided for one parameter that it is also provided for all other parameters.

An example usage of DensityMapper which produces the variation in a coalescent tree density as a function of the population size is provided as DensityMapper.xml which can be found in the examples directory.