TiDeTree

TiDeTree is a BEAST 2 package that enables inference of time-scaled single-cell phylogenies and population dynamic parameters such as cell division, death, and differentiation rates from genetic lineage tracing data.

For further information please check out our publication or preprint and find the code to reproduce the analyses in this GitHub repo.

To apply TiDeTree to your data, adapt the example XML file in the examples directory. For general guidance on setting prior distributions on parameters, look at this BEAST2 tutorial.

Mini Tutorial

We migrated TiDeTree to BEAST 2.7. So you need to first install JAVA 17 as recommended here..

To run TiDeTree with the example.xml within the ./examples folder, use the following command:

java -jar bin/tidetree.jar examples/example.xml

Parameter choices

A key component of TiDeTree is the editing and silencing model. Let's talk about editing first. TiDeTree can model any editing process, where an initially unedited site is edited once. Experimentally, this could be achieved by CRISPR-Cas9 editing, where a random edit is introduced. Or by recombinase editing, where an unedited site is either inverted or deleted.

We model this editing process as a 2-step process. The rate at which any edit occurs per unit of time is the clock rate r.

Then, a particular edit $i$ is introduced with a relative editing rate $s_i$. You can also easily get the probability of introducing edit $i$ by taking $s_i / \sum_j s_j$ (This parameterisation is in TiDeTree's supplementary material page 5. An alternative parameterisation is in the main text page 3, matrix Q 2.2).

So how do we put this into our BEAST XML? We specify starting values for the clock and the editing rates. In this example, we have a clock rate of 1 per time unit and 3 editing rates for 3 different edited states.

<!-- the clock rate  -->
<parameter id="clockRate.c" spec="parameter.RealParameter" name="stateNode">
 1.0
</parameter>


<!--the editing rates -->
<parameter id="editRate" spec="parameter.RealParameter" lower="0.0" name="stateNode">
 0.8 0.1 0.1
</parameter>
        

These parameters are then used by the editing model (see the "@editRate" notation referencing the parameter with id="editRate").

<substModel id="substModel"
               spec="tidetree.substitutionmodel.EditAndSilencingModel"
               editRates="@editRate" silencingRate="@silencingRate"
               editHeight="54" editDuration="36">
    <frequencies spec="beast.base.evolution.substitutionmodel.Frequencies" frequencies="1 0 0 0" estimate="false"/>
  </substModel>

In the editing model we additinally have to specify the editHeight and the editDuration. The editHeight is the amount of time between the start of editing ($t_1$) and the end of the experiment ($t_{end}$). The editDuration is the amount of time from the start of editing ($t_1$) until the end of editing ($t_2$).

For example, let the entire experiment take 100 hours. Editing is induced after 10 hours and lasts for 10 hours. Then, the editHeight would be 90 hours and the editDuration 10 hours.

TODO:

• integrate with BEAUti to allow easy package installation
• Write a tutorial to be published on taming-the-beast.org