amici.sim.sundials.petab

Functionality for simulating PEtab problems.

This submodule contains all functionality related to simulating PEtab problems.

See also amici.importers.petab for importing PEtab problems.

For simulating PEtab v2 problems, the relevant classes are:

• PetabSimulator: Simulate PEtab problems with AMICI.

• ExperimentManager: Create amici.ExpData objects for PEtab experiments.

See PEtab 2.0 import for example usage. Note that the PEtab v2 API is still under development and may change in future releases.

The PEtab v1 legacy functionality is still available under amici.simulations.sim.sundials.petab.v1. Note that this functionality will be deprecated once the PEtab v2 import is stable.

Classes

PetabSimulator(em, *[, solver, num_threads])	Simulator for PEtab2 problems.
ExperimentManager(model, petab_problem, *[, ...])	Handles the creation of ExpData objects for a given model and PEtab problem.
PetabSimulationResult([edatas, rdatas, ...])	Container for results of a PEtab simulation.

class amici.sim.sundials.petab.ExperimentManager(model, petab_problem, *, parameter_scales=None)

Handles the creation of ExpData objects for a given model and PEtab problem.

The assumption is that we have a set of ExpData objects, one for each PEtab experiment. Those are updated based on a set of global parameters (PEtab problem parameters, as opposed to model parameters for a single experiment period).

PEtab v2 does not specify on which scale parameters are estimated. By default, all problem parameters are on linear scale. Other scales can be chosen via the parameter_scales argument. All problem parameter values passed to or returned by this class are then on the respective scale, and so are the sensitivities computed for the resulting ExpData objects.

__init__(model, petab_problem, *, parameter_scales=None)

Initialize the ExperimentManager.

Parameters:

• model (amici._installation.amici.Model) – The AMICI model to use.

• petab_problem (petab.v2.core.Problem) – The PEtab problem to use. This is expected to be the output of petab.v2.converters.ExperimentsToSbmlConverter or an equivalent problem. This object must not be modified after the creation of this ExperimentManager instance.

• parameter_scales (collections.abc.Mapping[str, typing.Literal['lin', 'log', 'log10']] | None) – The scales of the PEtab problem parameters, as a mapping from problem parameter IDs to "lin", "log" (natural logarithm), or "log10". Parameters not included are on linear scale.

apply_parameters(edata, problem_parameters)

Apply problem parameters.

Update the parameter-dependent values of the given ExpData instance according to the provided problem parameters (i.e., values of the parameters in the PEtab parameter table).

This assumes that:

• the ExpData instance was created by create_edata(),

• no other changes except for calls to apply_parameters() were made,

• and the PEtab problem was not modified since the creation of this ExperimentManager instance.

Each model parameter takes the scale of the problem parameter it is mapped to in the given experiment, and model parameters that are not mapped to any problem parameter are on linear scale. Fixed model parameters are always on linear scale, so the values of the problem parameters they are mapped to are unscaled.

Parameters:

• edata (amici._installation.amici.ExpData) – The ExpData instance to be updated. In case of errors, the state of edata is undefined.

• problem_parameters (dict[str, float]) – Problem parameters to be applied, on the scales given by parameter_scales.

Return type:

None

create_edata(experiment, problem_parameters=None)

Create an ExpData object for a single experiment.

Sets timepoints, measurements, initial conditions, … based on the given experiment and the nominal parameters of the PEtab problem.

Parameters:

• experiment (petab.v2.core.Experiment | str | None) – The experiment or experiment ID to create the ExpData for.

• problem_parameters (dict[str, float] | None) – Optional dictionary of problem parameters to apply to the ExpData, on the scales given by parameter_scales. If None, the nominal parameters of the PEtab problem are used.

Return type:

amici._installation.amici.ExpData

Returns:

The created ExpData object for the given experiment.

create_edatas()

Create ExpData objects for all experiments.

Return type:

list[amici._installation.amici.ExpData]

property model: Model

The AMICI model used by this ExperimentManager.

property parameter_scales: dict[str, Literal['lin', 'log', 'log10']]

The scales of all PEtab problem parameters.

A mapping from problem parameter IDs to "lin", "log", or "log10". The keys are ordered like Problem.x_ids.

property petab_problem: Problem

The PEtab problem used by this ExperimentManager.

This must not be modified.

scale_parameters(problem_parameters)

Bring problem parameters from linear scale to their scales.

Parameters:

problem_parameters (collections.abc.Mapping[str, float]) – Values of (a subset of) the problem parameters on linear scale.

Return type:

dict[str, float]

Returns:

The values on the scales given by parameter_scales.

unscale_parameters(problem_parameters)

Bring problem parameters from their scales to linear scale.

Parameters:

problem_parameters (collections.abc.Mapping[str, float]) – Values of (a subset of) the problem parameters on the scales given by parameter_scales.

Return type:

dict[str, float]

Returns:

The values on linear scale.

class amici.sim.sundials.petab.PetabSimulationResult(edatas=<factory>, rdatas=<factory>, sllh=None, s2llh=None, sres=None)

Container for results of a PEtab simulation.

Holds the per-experiment AMICI data objects and aggregated metrics produced by PetabSimulator.simulate.

All sensitivities are with respect to the PEtab problem parameters on the scales given by ExperimentManager.parameter_scales.

__init__(edatas=<factory>, rdatas=<factory>, sllh=None, s2llh=None, sres=None)

edatas: list[ExpData]

List of amici.sim.sundials.ExpData instances, one per simulated experiment. These objects may be modified by subsequent operations.

property llh: float

The total log-likelihood across all experiments.

rdatas: list[ReturnDataView]

List of amici.sim.sundials.ReturnDataView instances, one per simulated experiment containing simulation outputs.

property res: ndarray | None

Concatenated residuals.

The residuals of the individual experiments are concatenated in the order of rdatas. This matches the row order of sres.

Returns:

Concatenated residuals from all experiments as a 1D numpy.ndarray, or None if they are not available, i.e., if any experiment failed to simulate or if residuals were not computed at all. If no experiment has any measurement, an empty array is returned.

s2llh: ndarray | None = None

Aggregated second-order sensitivities (Hessian or FIM-based) as a 2D numpy.ndarray in the order of Problem.x_free_ids. None if second-order sensitivities were not computed.

sllh: dict[str, float] | None = None

Aggregated first-order sensitivities of the log-likelihood with respect to PEtab problem parameters. Mapping from parameter ID to sensitivity value, or None if sensitivities were not computed.

sres: ndarray | None = None

Aggregated sensitivities of the residuals w.r.t. the estimated PEtab problem parameters as a 2D numpy.ndarray of shape (n_residuals, n_estimated). The rows correspond to the residuals returned by res, the columns are in the order of Problem.x_free_ids. None if residual sensitivities were not computed.

class amici.sim.sundials.petab.PetabSimulator(em, *, solver=None, num_threads=1)

Simulator for PEtab2 problems.

This class is used to simulate all experiments of a given PEtab problem using a given AMICI model and solver, and to aggregate the results.

__init__(em, *, solver=None, num_threads=1)

Initialize the simulator.

Parameters:

• em (amici.sim.sundials.petab._v2.ExperimentManager) – The ExperimentManager to generate the amici.ExpData objects.

• solver (amici._installation.amici.Solver | None) – The AMICI solver to use for the simulations. If not provided, a new solver with default settings will be used.

• num_threads (int) – The number of threads to use for parallel simulation of experiments. Only relevant if multiple experiments are present in the PEtab problem, and if AMICI was compiled with OpenMP support.

property exp_man: ExperimentManager

The ExperimentManager used by this simulator.

property model: Model

The AMICI model used by this simulator.

simulate(problem_parameters=None)

Simulate all experiments of the given PEtab problem.

Parameters:

problem_parameters (dict[str, float]) – Values of the PEtab problem parameters, on the scales given by ExperimentManager.parameter_scales. Nominal values are used for all parameters that are not specified.

Return type:

amici.sim.sundials.petab._v2.PetabSimulationResult

Returns:

A PetabSimulationResult instance containing the per-experiment data objects and aggregated results.

Note that the returned amici.sim.sundials.ExpData instances may be changed by subsequent calls to this function. Create a copy if needed.

property solver: Solver

The AMICI solver used by this simulator.