27 June 2018 by Remco Bouckaert
In this post, we will look at a few BEAST XML editing tricks, including use of plates, XML entities, and parameterising XML.
Plates
Plates are small macros that are expanded before the XML is interpreted and are useful for things that are repeated with only a single value changed. For example, a set of taxa can be defined as:
Using a plate, this can be defined as follows:
The plate format is <plate var="$var" range="$range">
where $var
is the variable to be replaced in the XML fragment inside the plate element and $range
is a comma separated string of values that are used to replace the variable.
If var="n"
, any place in the XML inside the plate that contains $(n)
is replaced by a value from $range
. So, the XML above with the plate in it expands to the taxon set that we started with. Plates can also be useful for sets of operators, parameters, priors, etc. especially when there are many partitions in the analysis.
Plates can be nested, but be careful to use different var attributes.
Parameterising XML
Sometimes, it can be useful to get values from outside BEAST as values for the XML. There is now a -D option for BEAST that takes as argument a comma separated string with name-value pairs, e.g.
Every occurrence of $(name) will be replaced by value in the XML in a pre-processing step, so for instance $(chain_length) will be replaced by 10000000 and $(log_every) with 1000 in the example above.
XML Entities
When there are many partitions, and you want to be able to include and exclude partitions quickly, it may be useful to define XML entities in combination with plates. For example, let there be three partitions: COI, ND2, CYTB. We could have a HKY model for each of them, with associated operators requiring the following fragments:
If we want to exclude say COI, we just delete it from the range. But there may be quite a few places, if we also have a prior on kappa, a clock rate for the partition, a treelikelihood, loggers for each of these, etc. So, a more elegant solution is to be able to specify the range. If we replace the partitions "COI,ND2,CYTB" with "⦥", like so: At the top of the XML file, we define an XML entity, just after the XML declaration but before the beast-element, like so: By changing the value of the entity, the whole model changes with one simple edit. For example, removing COI from the analysis can be done by just removing COI from the entity definition.