phylomodels.models module contains wrappers to models, as well as any code required
for execution of models. The goal of this module is to provide a standard
interface for sampling, feature extraction, and calibration functions.
This folder is organized as a collection of model wrappers. The wrappers themselves are (typically small) Python functions coded inside individual files. Additional functions (and files) that are necessary for the execution of a model must be in an individual subfolder. Optionally, there could be a test script for each individual wrapper.
For example, an SIR stochastic simulator based on Gillespie’s tao-leap method is
coded as a class called
sirTaoLeap. This class is coded in a file called
sirTaoLeap.py. The file structure for phyloModels-standard access to
sirTaoLeap is as follows (see naming conventions below):
Wrapper function for accessing sirTaoLeap.
Optional script for testing the
sirTaoLeap class and auxiliary functions.
A separate folder with model code may not be always necessary. For example, accessing models from a package that is already installed (and whose code is located in a separate folder/folder structure) may be called directly from the wrapper.
Wrappers should be named as follows:
[type]_[descriptive name of model/library][_configuration name (optional)]
Indicates the type of model that is being implemented. Type can be any of the following:
sirfor SIR models (or variations of
sirfor other compartmental models (e.g., SEIR)
distributionsfor random variables and probability distributions
- descriptive name of model/library
References the model or library that is being used by this wrapper.
- configuration name
Optional, describes a particular configuration mode used when calling the model.
The following are examples of wrapper names for different configurations of a model called sirTaoLeap:
sir_taoLeap sir_taoLeap_getIncidence sir_taoLeap_getPrevalence sir_taoLeap_getIncidenceSampled sir_taoLeap_getSampledIncidence
Wrapper test scripts should take the name of the wrapper with the
As mentioned above, any other file necessary for interfacing a model (or executing it) must be placed in a separate subfolder. The subfolder should be named as follows:
[type]_[descriptive name of model/library]
descriptive name of model/library follow the descriptions
mentioned for the wrappers above.
For example, a subfolder containing files for the sirTaoLeap model described for
wrappers above should be named
Note that the existence of a subfolder for a given model is optional. A subfolder should only be created if there is at least one file (other than the wrapper) necessary for calling a model.
Each wrapper receives only one input argument. This argument is a pandas dataframe. Each row of this dataframe is a set of arguments to be used as input for the model call. Columns are the arguments that will be passed to the model.
The input dataframe must not be modified by the wrapper or model.
The output is a tuple with the following items (in order):
A pandas dataframe, with the same number of rows of the input argument. Each row of this dataframe is the (possibly reformatted) model output corresponding to the input dataframe row. The output dataframe could be, for example, a time series.
A list of NetworkX structures. Each item of this list corresponds to the output of the model to the arguments in the corresponding row of the input dataframe.