Models¶

The 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.

File structure¶

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):

sir_taoLeap_getIncidence.py: Wrapper function for accessing sirTaoLeap.
test_sir_taoLeap_getIncidence.py: Optional script for testing the sir_taoLeap_getIncidence wrapper.
./sir_taoLeap: sirTaoLeap class and auxiliary functions.

Note

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.

Naming conventions¶

Wrappers¶

Wrappers should be named as follows:

[type]_[descriptive name of model/library][_configuration name (optional)]

type

Indicates the type of model that is being implemented. Type can be any of the following:

sir for SIR models (or variations of sir for other compartmental models (e.g., SEIR)
distributions for 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

Tests¶

Wrapper test scripts should take the name of the wrapper with the test_ prefix.

Subfolders¶

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]

where type and 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 sir_taoLeap.

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.

Inputs¶

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.

Outputs¶

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.