amici.adapters.fiddy

Adapters for using AMICI with the fiddy package for finite difference checks.

Note

Like fiddy, this module is experimental and subject to change.

Functions

`run_simulation_to_cached_functions`(...[, ...])	Convert run_simulation to fiddy functions.
`simulate_petab_to_cached_functions`(...[, ...])	Convert `amici.sim.sundials.petab.v1.simulate_petab()` (PEtab v1 simulations) to fiddy functions.
`simulate_petab_v2_to_cached_functions`(...[, ...])	Create fiddy functions for PetabSimulator.

Classes

RobustConsistency(*args[, trend_n_sigma, ...])

Consistency, plus rejection of step sizes that are self-consistent but inconsistent with the majority of other step sizes.

class amici.adapters.fiddy.RobustConsistency(*args, trend_n_sigma=5.0, min_trend_samples=3, **kwargs)[source]

Consistency, plus rejection of step sizes that are self-consistent but inconsistent with the majority of other step sizes.

Consistency checks whether the requested methods (e.g. forward/backward/central) agree with each other at each step size (“self-consistent”), then blends every self-consistent size’s mean into the final value. Self-consistency alone is not a strong guarantee on its own: a step size can be small enough that all methods sample points within the target function’s floating-point noise floor and become correlated (affected by the same rounding/cancellation error) – self-consistent, yet biased away from the truth. Symmetrically, a step size can also be large enough that all methods are biased the same way by higher-order/truncation effects.

To guard against this, self-consistent step sizes are additionally required to agree with the majority of other self-consistent step sizes, via iterative outlier rejection (order-independent; step size magnitude is not used as a proxy for trustworthiness): repeatedly compute the median and a robust (MAD-based) spread of the current candidates, and drop the single worst-deviating one if it exceeds trend_n_sigma scaled MADs from the median, until nothing looks anomalous. This only activates once there are at least min_trend_samples self-consistent step sizes; below that, there isn’t enough data to estimate a spread, and all self-consistent step sizes are used, as in Consistency. A UserWarning is emitted whenever one or more step sizes are rejected this way.

This addresses a long-standing intermittent CI failure in AMICI’s PEtab benchmark gradient test (test_benchmark_gradient[Weber_BMC2015-*-unscaled], see https://github.com/AMICI-dev/AMICI/issues/3078): that test uses Consistency to finite-difference-check an analytically computed gradient for a model parameter (a32) several orders of magnitude smaller than the model’s other free parameters, and a small step size could become spuriously self-consistent while biased away from the true derivative.

Note that this is a majority-vote style method: like any check based purely on the agreement of the values themselves (no independent ground truth), it has a breakdown point of roughly 50% (a property of the underlying median/MAD statistics) – if close to half (or more) of the self-consistent step sizes are corrupted, this check cannot reliably tell which subset is trustworthy. This is a fundamental limitation of any purely data-driven consistency check, not something this implementation can detect or work around; sufficient step sizes with a real chance of being individually trustworthy should be provided.

This was originally proposed upstream, in fiddy, as https://github.com/ICB-DCM/fiddy/pull/77, but was not merged; it lives here instead.

__init__(*args, trend_n_sigma=5.0, min_trend_samples=3, **kwargs)[source]

Construct.

Parameters:

trend_n_sigma (float) – The number of scaled median-absolute-deviations a self-consistent step size’s estimate may deviate from the median of the other trusted step sizes’ estimates, before it is rejected as an outlier.
min_trend_samples (int) – The minimum number of self-consistent step sizes required before the cross-step-size outlier rejection is attempted. Below this, all self-consistent step sizes are trusted, same as in Consistency.
args – Positional arguments passed to Consistency.__init__.
kwargs – Keyword arguments passed to Consistency.__init__ (e.g. rtol, atol, equal_nan).

id: str = 'robust_consistency'

method(directional_derivative)[source]

Return type:: tuple[bool, float]

only_at_completion: bool = True

amici.adapters.fiddy.run_simulation_to_cached_functions(amici_model, *, cache=True, free_parameter_ids=None, amici_solver=None, amici_edata=None, derivative_variables=None)[source]

Convert run_simulation to fiddy functions.

Parameters:

amici_model (amici._installation.amici.Model | amici._installation.amici.ModelPtr) – The AMICI model to simulate.
amici_solver (typing.Union[amici._installation.amici.Solver, amici._installation.amici.SolverPtr]) – The AMICI solver to use. If None, a new solver will be created from the model.
amici_edata (typing.Union[amici._installation.amici.ExpData, amici._installation.amici.ExpDataPtr]) – The AMICI ExpData to use. If None, no data will be used.
derivative_variables (list[str]) – The variables that derivatives will be computed or approximated for. See the keys of all_rdata_derivatives for options.
free_parameter_ids (list[str]) – The IDs that correspond to the values in the free parameter vector that is simulated.
cache (bool) – Whether to cache the function calls.

Returns:

function, derivatives and structure

amici.adapters.fiddy.simulate_petab_to_cached_functions(petab_problem, *, amici_model, free_parameter_ids=None, cache=True, precreate_edatas=True, precreate_parameter_mapping=True, simulate_petab=None, **kwargs)[source]

Convert amici.sim.sundials.petab.v1.simulate_petab() (PEtab v1 simulations) to fiddy functions.

Note that all gradients are provided on linear scale. The correction from ‘log10’ scale is automatically done.

Parameters:

amici_model (amici._installation.amici.Model) – The AMICI model to simulate.
simulate_petab (collections.abc.Callable[[typing.Any], str]) – A method to simulate PEtab problems with AMICI, e.g. amici.petab_objective.simulate_petab.
free_parameter_ids (list[str]) – The IDs of the parameters, in the order that parameter values will be supplied. Defaults to petab_problem.parameter_df.index.
petab_problem (petab.v1.problem.Problem) – The PEtab problem.
cache (bool) – Whether to cache the function call.
precreate_edatas (bool) – Whether to create the AMICI measurements object in advance, to save time.
precreate_parameter_mapping (bool) – Whether to create the AMICI parameter mapping object in advance, to save time.
kwargs – Passed to simulate_petab.

Return type:

tuple[collections.abc.Callable[[numpy.typing.NDArray[numpy.double]], numpy.typing.NDArray[numpy.double]], collections.abc.Callable[[numpy.typing.NDArray[numpy.double]], numpy.typing.NDArray[numpy.double]]]

Returns:

A tuple of:

1: A method to compute the function at a point.
2: A method to compute the gradient at a point.

amici.adapters.fiddy.simulate_petab_v2_to_cached_functions(petab_simulator, *, free_parameter_ids=None, cache=True)[source]

Create fiddy functions for PetabSimulator.

Parameters:

petab_simulator (amici.sim.sundials.petab._v2.PetabSimulator) – The PEtab simulator to use.
free_parameter_ids (list[str]) – The IDs of the parameters, in the order that parameter values will be supplied. Defaults to the estimated parameters of the PEtab problem.
cache (bool) – Whether to cache the function call.

Return type:

tuple[collections.abc.Callable[[numpy.typing.NDArray[numpy.double]], numpy.typing.NDArray[numpy.double]], collections.abc.Callable[[numpy.typing.NDArray[numpy.double]], numpy.typing.NDArray[numpy.double]]]

Returns:

tuple of:

1: A method to compute the function at a point.
2: A method to compute the gradient at a point.