amici.import_utils

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

Functions

cast_to_sym(value, input_name)

Typecasts the value to sympy.Float if possible, and ensures the value is a symbolic expression.

contains_periodic_subexpression(expr, symbol)

Check if a sympy expression contains any periodic subexpression.

generate_flux_symbol(reaction_index[, name])

Generate identifier symbol for a reaction flux.

generate_measurement_symbol(observable_id)

Generates the appropriate measurement symbol for the provided observable

generate_regularization_symbol(observable_id)

Generates the appropriate regularization symbol for the provided observable

grouper(iterable, n[, fillvalue])

Collect data into fixed-length chunks or blocks

noise_distribution_to_cost_function(...)

Parse noise distribution string to a cost function definition amici can work with.

noise_distribution_to_observable_transformation(...)

Parse noise distribution string and extract observable transformation

smart_subs(element, old, new)

Optimized substitution that checks whether anything needs to be done first

smart_subs_dict(sym, subs[, field, reverse])

Substitutes expressions completely flattening them out.

symbol_with_assumptions(name)

Central function to create symbols with consistent, canonical assumptions

toposort_symbols(symbols[, field])

Topologically sort symbol definitions according to their interdependency

unique_preserve_order(seq)

Return a list of unique elements in Sequence, keeping only the first occurrence of each element

Classes

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

A measurement channel (observable) definition.

ObservableTransformation(value[, names, ...])

Different modes of observable transformation.

Exceptions

CircularDependencyError(data)

SBMLException

exception amici.import_utils.CircularDependencyError(data)[source]
__init__(data)[source]
class amici.import_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.

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

Initialize a measurement channel.

Note

When providing expressions for (event) observables and their sigmas as strings (see below), those will be passed to sympy.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 (e.g., ‘normal’, ‘log-normal’; see amici.import_utils.noise_distribution_to_cost_function()). If None, a normal distribution is assumed.

    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.sympify().

  • event_id (str | None) – Identifier of the associated event for event-resolved observables. None for time-resolved observables.

Example usage: >>> # Time-resolved observable >>> mc1 = MeasurementChannel( … id_=”obs1”, … name=”Observable 1”, … formula=”k1 * x1 + k2”, … noise_distribution=”log-normal”, … sigma=”sigma1” … ) >>> mc1 # doctest: +NORMALIZE_WHITESPACE 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 # doctest: +NORMALIZE_WHITESPACE 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

property is_event_resolved: bool

Whether this is an event-resolved observable.

property is_time_resolved

Whether this is a time-resolved observable.

class amici.import_utils.ObservableTransformation(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Different modes of observable transformation.

LIN = 'lin'
LOG = 'log'
LOG10 = 'log10'
__init__(*args, **kwds)
static maketrans()

Return a translation table usable for str.translate().

If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

exception amici.import_utils.SBMLException[source]
amici.import_utils.cast_to_sym(value, input_name)[source]

Typecasts the value to sympy.Float if possible, and ensures the value is a symbolic expression.

Parameters:
Return type:

sympy.core.expr.Expr

Returns:

typecast value

amici.import_utils.contains_periodic_subexpression(expr, symbol)[source]

Check if a sympy expression contains any periodic subexpression.

Parameters:
Return type:

bool

Returns:

True if the expression contains a periodic subexpression, False otherwise.

amici.import_utils.generate_flux_symbol(reaction_index, name=None)[source]

Generate identifier symbol for a reaction flux. This function will always return the same unique python object for a given entity.

Parameters:

  • reaction_index (int) – index of the reaction to which the flux corresponds

  • name (str | None) – an optional identifier of the reaction to which the flux corresponds

Return type:

sympy.core.symbol.Symbol

Returns:

identifier symbol

amici.import_utils.generate_measurement_symbol(observable_id)[source]

Generates the appropriate measurement symbol for the provided observable

Parameters:

observable_id (str | sympy.core.symbol.Symbol) – symbol (or string representation) of the observable

Returns:

symbol for the corresponding measurement

amici.import_utils.generate_regularization_symbol(observable_id)[source]

Generates the appropriate regularization symbol for the provided observable

Parameters:

observable_id (str | sympy.core.symbol.Symbol) – symbol (or string representation) of the observable

Returns:

symbol for the corresponding regularization

amici.import_utils.grouper(iterable, n, fillvalue=None)[source]

Collect data into fixed-length chunks or blocks

grouper(‘ABCDEFG’, 3, ‘x’) –> ABC DEF Gxx”

Parameters:
Return type:

collections.abc.Iterable[tuple[typing.Any]]

Returns:

itertools.zip_longest of requested chunks

amici.import_utils.noise_distribution_to_cost_function(noise_distribution)[source]

Parse noise distribution string to a cost function definition amici can work with.

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 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)\).

In addition to the above-mentioned distributions, it is also possible to pass a function taking a symbol string and returning a log-distribution string with variables ‘{str_symbol}’, ‘m{str_symbol}’, ‘sigma{str_symbol}’ for y, m, sigma, respectively.

Parameters:

noise_distribution (str | collections.abc.Callable) –

An identifier specifying a noise model. Possible values are

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

For the meaning of the values see above.

Return type:

collections.abc.Callable[[str], str]

Returns:

A function that takes a strSymbol and then creates a cost function string (negative log-likelihood) from it, which can be sympified.

amici.import_utils.noise_distribution_to_observable_transformation(noise_distribution)[source]

Parse noise distribution string and extract observable transformation

Parameters:

noise_distribution (str | collections.abc.Callable) – see noise_distribution_to_cost_function()

Return type:

amici.import_utils.ObservableTransformation

Returns:

observable transformation

amici.import_utils.smart_subs(element, old, new)[source]

Optimized substitution that checks whether anything needs to be done first

Parameters:
Return type:

sympy.core.expr.Expr

Returns:

substituted expression

amici.import_utils.smart_subs_dict(sym, subs, field=None, reverse=True)[source]

Substitutes expressions completely flattening them out. Requires sorting of expressions with toposort.

Parameters:
Return type:

sympy.core.expr.Expr

Returns:

Substituted symbolic expression

amici.import_utils.symbol_with_assumptions(name)[source]

Central function to create symbols with consistent, canonical assumptions

Parameters:

name (str) – name of the symbol

Returns:

symbol with canonical assumptions

amici.import_utils.toposort_symbols(symbols, field=None)[source]

Topologically sort symbol definitions according to their interdependency

Parameters:
Return type:

dict[sympy.core.symbol.Symbol, dict[str, sympy.core.expr.Expr] | sympy.core.expr.Expr]

Returns:

ordered symbol definitions

amici.import_utils.unique_preserve_order(seq)[source]

Return a list of unique elements in Sequence, keeping only the first occurrence of each element

Parameters:

seq (collections.abc.Sequence) – Sequence to prune

Return type:

list

Returns:

List of unique elements in seq