Efficiently simulating multi-type birth-death processes via forward-equivalent parameter mapping

The simulations and plots are produced by the jupyter notebooks in the notebooks directory. These should be run in the following order:

• Run all cells in efficiency.ipynb in order to run all simulations. It will read output to a data sub-directory provided the save_to_file global varialbe and the "save_tree" key in the respective sim_spec are set to True.
• After this, any of the three remaining notebooks can be run. These will create output images in a fig sub-directory.
  • distribution_tests.ipynb: This creates histograms comparing several tree statistics between the full and forward-equivalent simulations.
  • timing_plots.ipynb: This creates plots comparing the run-time of the ful and forward-equivalent simulations across three model specifications. By changing the sim_idx variable and then running all cells, one can create plots for each of the different model specificaitons.
  • draw_tree.ipynb: This draws a tree generated by the huge population simulation specification.

These modules are used by the jupyter notebooks.

• modulators.py: Defines the FEModulator class. An FEModulator object is initialized by a specification of the full model and sampling rates, and computes and stores internal data to allow simulation-time access to forward-equivalent model parameters.
• my_bdms.py: This module contains three classes:
  • DiscreteProcess: This sub-classes poisson.Process and can be used by bdms for simulation from a constant-rate (birth, death, or mutation) process taking on a finite phenotype space.
  • CustomProcess: This sub-classes poisson.Process and allows and user provided time- and state-dependent rates. In our code, we use this class to store birth, death, and mutation rates for the forward-equivalent model. the FEModulator class provides the CustomProcess initializer with the appropriate time- and state-dependent rate functions.
  • CustomMutator: This sub-classes mutators.Mutator. It is initialized with an FEModulator object, which is then used to carry out time- and state-dependent mutation transitions according the the forward-equivalent model.
• utils.py: This exports some utility functions, as well functions to compute all the tree statistics used for the distribution tests (in distribution_tests.ipynb).