amici.importers.utils

Miscellaneous functions related to model import, independent of any specific model format

Classes

MeasurementChannel(id_, *[, name, formula, ...])

A measurement channel (observable) definition.

class amici.importers.utils.MeasurementChannel(id_, *, name=None, formula=None, noise_distribution=None, sigma=None, event_id=None)[source]

A measurement channel (observable) definition.

Measurement channels define how model state and parameters are mapped to observables, including any associated noise models.

Measurement channels can be time-resolved (i.e., defined over the course of a simulation) or event-resolved (i.e., defined at specific events during a simulation). Event-resolved observables are associated with a specific event via the event_id attribute.

Example usage:

>>> # Time-resolved observable
>>> mc1 = MeasurementChannel(
...     id_="obs1",
...     name="Observable 1",
...     formula="k1 * x1 + k2",
...     noise_distribution="log-normal",
...     sigma="sigma1"
... )
>>> mc1
MeasurementChannel(id_='obs1', name='Observable 1', formula='k1 * x1 + k2', noise_distribution='log-normal', sigma='sigma1', event_id=None)
>>> mc1.is_time_resolved
True
>>> mc1.is_event_resolved
False
>>> # Event-resolved observable
>>> mc2 = MeasurementChannel(
...     id_="obs2",
...     name="Observable 2",
...     formula="x3",
...     noise_distribution="log-normal",
...     sigma="sigma1",
...     event_id="event1"
... )
>>> mc2
MeasurementChannel(id_='obs2', name='Observable 2', formula='x3', noise_distribution='log-normal', sigma='sigma1', event_id='event1')
>>> mc2.is_event_resolved
True
>>> mc2.is_time_resolved
False

__init__(id_, *, name=None, formula=None, noise_distribution=None, sigma=None, event_id=None)[source]

Initialize a measurement channel.

The noise distributions listed in the following are supported. \(m\) denotes the measurement, \(y\) the simulation, and \(\sigma\) a distribution scale parameter (currently, AMICI only supports a single distribution parameter).

‘normal’, ‘lin-normal’: A normal distribution:

\[\pi(m|y,\sigma) = \frac{1}{\sqrt{2\pi}\sigma}\ exp\left(-\frac{(m-y)^2}{2\sigma^2}\right)\]
‘log-normal’: A log-normal distribution (i.e. log(m) is normally distributed):

\[\pi(m|y,\sigma) = \frac{1}{\sqrt{2\pi}\sigma m}\ exp\left(-\frac{(\log m - \log y)^2}{2\sigma^2}\right)\]
‘log10-normal’: A log10-normal distribution (i.e. log10(m) is normally distributed):

\[\pi(m|y,\sigma) = \frac{1}{\sqrt{2\pi}\sigma m \log(10)}\ exp\left(-\frac{(\log_{10} m - \log_{10} y)^2}{2\sigma^2}\right)\]
‘laplace’, ‘lin-laplace’: A laplace distribution:

\[\pi(m|y,\sigma) = \frac{1}{2\sigma} \exp\left(-\frac{|m-y|}{\sigma}\right)\]
‘log-laplace’: A log-Laplace distribution (i.e. log(m) is Laplace distributed):

\[\pi(m|y,\sigma) = \frac{1}{2\sigma m} \exp\left(-\frac{|\log m - \log y|}{\sigma}\right)\]
‘log10-laplace’: A log10-Laplace distribution (i.e. log10(m) is Laplace distributed):

\[\pi(m|y,\sigma) = \frac{1}{2\sigma m \log(10)} \exp\left(-\frac{|\log_{10} m - \log_{10} y|}{\sigma}\right)\]
‘binomial’, ‘lin-binomial’: A (continuation of a discrete) binomial distribution, parameterized via the success probability \(p=\sigma\):

\[\pi(m|y,\sigma) = \operatorname{Heaviside}(y-m) \cdot \frac{\Gamma(y+1)}{\Gamma(m+1) \Gamma(y-m+1)} \sigma^m (1-\sigma)^{(y-m)}\]
‘negative-binomial’, ‘lin-negative-binomial’: A (continuation of a discrete) negative binomial distribution, with mean = y, parameterized via success probability p:

\[\pi(m|y,\sigma) = \frac{\Gamma(m+r)}{\Gamma(m+1) \Gamma(r)} (1-\sigma)^m \sigma^r\]

where

\[r = \frac{1-\sigma}{\sigma} y\]

The distributions above are for a single data point. For a collection \(D=\{m_i\}_i\) of data points and corresponding simulations \(Y=\{y_i\}_i\) and noise parameters \(\Sigma=\{\sigma_i\}_i\), AMICI assumes independence, i.e. the full distributions is

\[\pi(D|Y,\Sigma) = \prod_i\pi(m_i|y_i,\sigma_i)\]

AMICI uses the logarithm \(\log(\pi(m|y,\sigma)\).

Note

When providing expressions for (event) observables and their sigmas as strings (see below), those will be passed to sympy.core.sympify.sympify(). The supported grammar is not well-defined. Note there can be issues with, for example, == or n-ary (n>2) comparison operators. Also note that operator precedence and function names may differ from SBML L3 formulas or PEtab math expressions. Passing a sympy expression directly will be the safer option for more complex expressions.

Note

In any math expressions passed to this function, time will be interpreted as the time symbol.

Parameters:

id – Unique identifier for the measurement channel.
name (str | None) – Human-readable name for the measurement channel.
formula (str | sympy.core.expr.Expr | None) – Expression defining how the observable is computed from model state and parameters.
noise_distribution (str | collections.abc.Callable[[str], str] | None) –
Noise distribution associated with the observable. This is usually a string identifier:

{‘normal’, ‘lin-normal’, ‘log-normal’, ‘log10-normal’, ‘laplace’, ‘lin-laplace’, ‘log-laplace’, ‘log10-laplace’, ‘binomial’, ‘lin-binomial’, ‘negative-binomial’, ‘lin-negative-binomial’}

For the meaning of the values see above.

Alternatively, a callable can be passed to account for a custom noise model. The callable must take a single argument str_symbol, and return a string defining the negative log-likelihood contribution for a single data point, using variables {str_symbol}, m{str_symbol}, and sigma{str_symbol} for the simulation, measurement, and scale parameter, respectively.
sigma (str | sympy.core.expr.Expr | float | None) – Expression representing the scale parameter of the noise distribution. This can be a numeric value, a sympy expression, or an expression string that will be passed to sympy.core.sympify.sympify().
event_id (str | None) – Identifier of the associated event for event-resolved observables. None for time-resolved observables.

property is_event_resolved: bool: Whether this is an event-resolved observable.

property is_time_resolved: Whether this is a time-resolved observable.