TreeSlicer

TreeSlicer is a tool that is used to access dates/times along a tree in the BEAST2 XML file. The output of a TreeSlicer object is always measured from the most-recent sample in a tree (the "present") to specific points on a tree (heights in the tree). The input can be n equidistant times between specific anchor times (the tMRCA or the oldest sample of a tree) and the present or a vector of dates. In addition, all TreeSlicer objects can be logged either as heights or as dates.

The tool was developed to be used with the BDSKY package, because of two idiosyncrasies of the package:

1. Change-point times can only be specified relative to the tree, either as time from the origin or present, or as a percentage of the time between the origin and the present (this is not the same as the tree-height or tMRCA), measured from the origin or the present.
2. When change-point times are equally spaced, they can only be spaced between the origin and the present. In this parameterisation the change-point times are also obscured from the user (it is impossible to log them, or use them as input to any other model components).

TreeSlicer makes it possible to specify change-point times as absolute times (dates), independent of the tree, adds two new ways to specify equidistant change-point times, and gives control to the user to pass change-point times to other components (loggers or other model components).

Thanks to the similarities between the BDSKY and BDMM interfaces TreeSlicer works equally well with both packages. However, TreeSlicer is completely model-independent and can therefore also be used in other contexts - a TreeSlicer object is a RealParameter, so it can be substituted for any real-valued vector in a BEAST2 XML file. Depending on its inputs and whether it is operated on, it can be either a constant vector, a CalculationNode or a StateNode.

Examples

1. Setting the sampling proportion (or sampling rate) to 0 before the first sample was collected, or during periods when no sampling effort was made.
2. Setting change-point times for a rate (e.g. reproductive rate or birth-rate) at equally spaced times between the tMRCA and the present. This avoids a situation where multiple change-point times are placed on the origin branch, which is unidentifiable and leads to bad mixing.
3. Specifying change-point times for rates as dates, instead of time from the present/origin. This makes it easier to estimate weekly/monthly/yearly rates or to fix change-point times to the dates of known events.
4. Estimating change-point times of rates as dates (times of major transitions).
5. Estimating the same change-point dates across multiple trees, with different most recent sampling dates (joint analysis).
6. Setting the same change-point dates across multiple trees with different most recent sampling dates (joint analysis).

Many (but not all) of these examples are possible using only the base BDSKY/BDMM package as well (as detailed in the examples), but with TreeSlicer the XML specification is more straightforward and readable. It also reduces the chance of errors by directly calculating times on a tree, instead of relying on the user to do it (thus separating the model from the data).