means.core package

Submodules

Descriptors

Descriptors are small classes that describe the terms in ODE equations or the meaning of the trajectory generations. They are the key objects in parameter inference as they provide ways for the system to know which trajectory generated to compare to which of the trajectories observed.

Descriptor objects can be initialised directly, and the appropriate class documentations should be viewed for instructions on how to do so.

If one would like to create a new descriptor object, such object must inherit from the Descriptor object defined below.

class means.core.descriptors.Descriptor

Bases: means.io.serialise.SerialisableObject

mathtext()

Return the mathtext representation of this object. Used in the legend labels while plotting the trajectories. Should include the dollar signs ($) separating the mathtext from plaintext, e.g.

def mathtext(self):
    return "Some plain text string before the math representation of lambda $\lambda$"

Defaults to the same representation as provided by __str__.

yaml_tag = u'!descriptor'

class means.core.descriptors.Moment(n_vector, symbol)

Bases: means.core.descriptors.ODETermBase

An annotator for ODE expressions that describes that a particular expression in a set of ODEs corresponds to a Moment of the probability distribution. The particular moment is described by Moment.n_vector.

Creates an ODETerm that describes that a particular ODE term is a moment defined by the n_vector parameter. The said parameter should be a vector of ints describing the order of the particular species moment. For instance, for a two species system, the variance for the first species would have n_vector=[2, 0] as it is the expectation of the squared central moment for the first species.

Similarly, the covariance of the first and second species would have a n_vector=[1, 1] as it is the expectation of the product of the central moments for each of the species.

The sum of the terms of n_vector is referred as the order of the moment, and is accessible via the Moment.order attribute. The concept of n_vector is genearalisable to higher order moments as well.

It is worth noting that the concentrations of particular species are the first-order moments themselves, equivalent to vectors [1, 0] and [0, 1] for a two-species system. These moments are commonly referred to as the means of the systems.

When performing data inference, the Trajectory objects with appropriate descriptors have to be defined. In most cases, these descriptors will be the aforementioned first-order moments as most measurable data would be the mean concentrations of species, for instance:

>>> x_concentration_descriptor = Moment([1,0], symbol='x')

Note that both the moment’s n_vector and the symbol parameters must match the parameters generated by the trajectory. In the example above the first species in the model need to be named 'x'.

Parameters:

• n_vector – a vector specifying the multidimensional moment e.g. [1,0]
• symbol – the symbol for the particular descriptor, e.g. 'x'

descriptor

is_mixed

Returns whether the moment is a mixed moment, i.e. has a non-zero power to more than one species, or a raw moment (non-zero power to only one species).

n_vector

The n_vector this moment represents

order

The order of the moment

classmethod to_yaml(dumper, data)

yaml_tag = u'!moment'

class means.core.descriptors.ODETermBase(symbol)

Bases: means.core.descriptors.Descriptor

Base class for explaining terms in the ODE expressions. Instances of this class allow providing a description for each of the equations in the generated ODE system.

descriptor

Returns an uniquely identifying descriptor for this particular ODE term.

mathtext()

symbol

class means.core.descriptors.VarianceTerm(position, symbol)

Bases: means.core.descriptors.ODETermBase

Signifies that a particular equation generated from the model is part of a Variance Term

Creates a Descriptor for a particular ODE in the system that signifies that that particular equation computes the position-th term of a covariance matrix, where position is some tuple (row,column).

It is used in LNA approximation as there we need to deal with moment and variance terms differently

Parameters:

• position – position in the covariance matrix
• symbol – symbol assigned to the term

position

classmethod to_yaml(dumper, data)

yaml_tag = '!variance-term'

Model

Model objects describe a system in terms of stochastic reaction propensities/rates, species/variables, constants and a stoichiometry matrix. Generally, describing a model is a pre-requisite for any subsequent analysis.

An example showing the p53 model could be encoded:

>>> from means import Model
>>> my_model = Model(parameters=['c_0',   # P53 production rate
>>>                             'c_1',   # MDM2-independent p53 degradation rate
>>>                             'c_2',   # saturating p53 degradation rate
>>>                             'c_3',   # P53-dependent MDM2 production rate
>>>                             'c_4',   # MDM2 maturation rate
>>>                             'c_5',   # MDM2 degradation rate
>>>                             'c_6'],  # P53 threshold of degradation by MDM2
>>>                  species=['y_0',   # Concentration of p53
>>>                           'y_1',   # Concentration of MDM2 precursor
>>>                           'y_2'],  # Concentration of MDM2
>>>                  stoichiometry_matrix=[[1, -1, -1, 0, 0, 0],
>>>                                        [0, 0, 0, 1, -1, 0],
>>>                                        [0, 0, 0, 0, 1, -1]],
>>>                  propensities=['c_0',
>>>                                'c_1*y_0',
>>>                                'c_2*y_2*y_0/(y_0+c_6)',
>>>                                'c_3*y_0',
>>>                                'c_4*y_1',
>>>                                'c_5*y_2'])

Printing the model to ensure everything is all right:

>>> print my_model

Typically, a model would be used for approximation (e.g. moment_expansion_approximation, or lna) and stochastic simulations (e.g. ssa).

---

class means.core.model.Model(species, parameters, propensities, stoichiometry_matrix)

Bases: means.io.serialise.SerialisableObject, means.io.latex.LatexPrintableObject

Stores the model of reactions we want to analyse

Creates a Model object that stores the model of reactions we want to analyse :param species: variables of the model, as sympy.Symbol`s, i.e. species :param parameters: parameters of the model, as `sympy symbols :param propensities: a matrix of propensities for each of the reaction in the model. :param stoichiometry_matrix: stoichiometry matrix for the model

number_of_parameters

number_of_reactions

number_of_species

parameters

propensities

species

stoichiometry_matrix

classmethod to_yaml(dumper, data)

validate()

Validates whether the particular model is created properly

yaml_tag = u'!model'

Problems

This part of the package implement classes describing “problems”. Problems are required inputs for simulation and inference. Currently, there are two types of problems:

• A ODEProblem is a system of differential equations describing

  the temporal behaviour of the system. They are typically obtained through approximation (e.g. moment_expansion_approximation, or lna)

• A StochasticProblem can be used for stochastic simulationsand can be simply built from a Model:

>>> from means import StochasticProblem
>>> from means.examples.sample_models import MODEL_P53
>>> my_stoch_prob = StochasticProblem(MODEL_P53)

class means.core.problems.ODEProblem(method, left_hand_side_descriptors, right_hand_side, parameters)

Bases: means.io.serialise.SerialisableObject, means.io.latex.LatexPrintableObject, means.util.memoisation.MemoisableObject

Creates a ODEProblem object that stores a system of ODEs describing the kinetic of a system. Typically, ODEProblem`s will be further used in simulations (see :mod:`~means.simulation) and inference (see inference).

Parameters:method – a string describing the method used to generate the problem.

Currently, ‘MEA’ and ‘LNA’ are supported” :param left_hand_side_descriptors: the left hand side of equations as a list of

Descriptor objects (such as Moment)

Parameters:

• right_hand_side – the right hand side of equations
• parameters – the parameters of the model

descriptor_for_symbol(symbol)

Given the symbol associated with the problem. Returns the Descriptor associated with that symbol

Parameters:symbol (basestring|:class:sympy.Symbol) – Symbol Returns:

latex

left_hand_side

left_hand_side_descriptors

method

number_of_equations

number_of_parameters

number_of_species

parameters

right_hand_side

right_hand_side_as_function

Generates and returns the right hand side of the model as a callable function that takes two parameters: values for variables and values for constants, e.g. `f(values_for_variables=[1,2,3], values_for_constants=[3,4,5])

This function is directly used in means.simulation.Simulation :return: :rtype: function

classmethod to_yaml(dumper, data)

validate()

Validates whether the ODE equations provided make sense i.e. the number of right-hand side equations match the number of left-hand side equations.

variables

yaml_tag = '!problem'

class means.core.problems.StochasticProblem(model)

Bases: means.core.model.Model, means.util.memoisation.MemoisableObject

The formulation of a model for stochastic simulations such as GSSA (see means.simulation.ssa).

change

propensities_as_function

Module contents

This package defines the common classes that are used within all of the other means subpackages.

The module exposes the descriptor classes, such as Descriptor, VarianceTerm, Moment and ODETermBase that are used to describe the types of trajectories generated, as well as certain terms in the ODE equations.

Similarly, both the StochasticProblem and ODEProblem classes that are used in stochastic and deterministic simulations respectively are exposed by this module.

Finally, the Model class, which provides a standard interface to describe a biological model, and can be thought to be the center of the whole package, is also implemented here.