amici.petab.petab_importer

PEtab v2 handling.

Functionality for importing and simulating PEtab v2 problems.

The relevant classes are:

PetabImporter: Import a PEtab problem as an AMICI model.
PetabSimulator: Simulate PEtab problems with AMICI.
ExperimentManager: Create amici.ExpData objects for PEtab experiments.

Functions

`flatten_timepoint_specific_output_overrides`(...)	Flatten timepoint-specific output parameter overrides.
`has_timepoint_specific_overrides`(petab_problem)	Check if the measurements have timepoint-specific observable or noise parameter overrides.
`rdatas_to_measurement_df`(rdatas, model, ...)	Create a measurement dataframe in the PEtab format from the passed `rdatas` and own information.
`rdatas_to_simulation_df`(rdatas, model, ...)	Create a simulation dataframe in the PEtab format from the passed `rdatas` and own information.
`unflatten_simulation_df`(simulation_df, ...)	Unflatten simulations from a flattened PEtab problem.

Classes

`ExperimentManager`(model, petab_problem)	Handles the creation of `ExpData` objects for a given model and PEtab problem.
`ExperimentsToPySBConverter`(petab_problem)	Convert PEtab experiments to amici events and PySB initials.
`PetabImporter`(petab_problem, *[, compile_, ...])	Importer for PEtab2 problems.
`PetabSimulator`(em[, solver, num_threads])	Simulator for PEtab2 problems.

class amici.petab.petab_importer.ExperimentManager(model, petab_problem)[source]

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

The assumption is that we have a set of amici.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).

__init__(model, petab_problem)[source]

Initialize the ExperimentManager.

Parameters:

model (amici.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.ExperimentsToSbmlConverter or an equivalent problem. This object must not be modified after the creation of this ExperimentManager instance.

apply_parameters(edata, problem_parameters)[source]

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.

Parameters:

edata (amici.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.

Return type:

None

create_edata(experiment, problem_parameters=None)[source]

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. If None, the nominal parameters of the PEtab problem are used.

Return type:

amici.amici.ExpData

Returns:

The created ExpData object for the given experiment.

create_edatas()[source]

Create ExpData objects for all experiments.

Return type:: list[amici.amici.ExpData]

property model: Model: The AMICI model used by this ExperimentManager.

property petab_problem: Problem

The PEtab problem used by this ExperimentManager.

This must not be modified.

class amici.petab.petab_importer.PetabImporter(petab_problem, *, compile_=None, validate=True, module_name=None, outdir=None, jax=False, output_parameter_defaults=None, verbose=20, non_estimated_parameters_as_constants=True)[source]

Importer for PEtab2 problems.

This class is used to create an AMICI model from a PEtab problem.

The underlying SBML or PySB model will be modified to encode the experiments defined in the PEtab problem as events or initial conditions.

Be careful when using the imported model for anything other than the PEtab-encoded experiments.

All PEtab experiments will be encoded in the model, independent of whether they have measurements. This is to make it easier to simulate the respective experiments with the resulting AMICI model. This may make the resulting model more bloated. If this is not desired, the problem should be simplified before import.

Parameters:: petab_problem (petab.v2.core.Problem | petab.v1.problem.Problem) – The PEtab problem to import. The problem must not be changed after construction of the importer.

__init__(petab_problem, *, compile_=None, validate=True, module_name=None, outdir=None, jax=False, output_parameter_defaults=None, verbose=20, non_estimated_parameters_as_constants=True)[source]

Create a new PetabImporter instance.

Parameters:

petab_problem (petab.v2.core.Problem | petab.v1.problem.Problem) – The PEtab problem to import.
compile – Whether to compile the model extension after import.
validate (bool) – Whether to validate the PEtab problem before import.
module_name (str) – The name of model module to generate.
outdir (str | pathlib._local.Path) – The output directory where the model files are written to.
jax (bool) – Whether to generate a JAX model instead of a SUNDIALS model. Currently, only False is supported.
output_parameter_defaults (dict[str, float] | None) – Optional default parameter values for output parameters introduced in the PEtab observables table, in particular for placeholder parameters. A dictionary mapping parameter IDs to default values.
verbose (int | bool) – The verbosity level. If True, set to logging.INFO. If False, set to logging.WARNING. Otherwise, use the given logging level.
non_estimated_parameters_as_constants (bool) – Whether parameters marked as non-estimated in PEtab should be considered constant in AMICI. Setting this to True will reduce model size and simulation times. If sensitivities with respect to those parameters are required, this should be set to False.

create_model()[source]

Create a amici.Model instance from the imported model.

Return type:: amici.amici.Model

create_simulator(force_import=False)[source]

Create a PEtab simulator for the imported model.

Parameters:: force_import (bool) – Whether to force re-import even if the model module already exists.
Return type:: amici.petab.petab_importer.PetabSimulator
Returns:: The created PEtab simulator.

import_module(force_import=False)[source]

Import the generated model module.

Parameters:: force_import (bool) – Whether to force re-import even if the model module already exists.
Return type:: amici.ModelModule
Returns:: The imported model module.

property model_id: str: The model ID.

property outdir: Path: The output directory where the model files are written to.

class amici.petab.petab_importer.PetabSimulator(em, solver=None, num_threads=1)[source]

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)[source]

Initialize the simulator.

Parameters:

em (amici.petab.petab_importer.ExperimentManager) – The ExperimentManager to generate the amici.ExpData objects.
solver (amici.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)[source]

Simulate all experiments of the given PEtab problem.

Return type:

dict[str, typing.Any]

Returns:

Dictionary of

the summed cost function value (LLH),

list of amici.amici.ReturnData (RDATAS) for each experiment,

list of amici.amici.ExpData (EDATAS) for each experiment

Note that the returned amici.amici.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.

amici.petab.petab_importer.flatten_timepoint_specific_output_overrides(petab_problem)[source]

Flatten timepoint-specific output parameter overrides.

If the PEtab problem definition has timepoint-specific observableParameters or noiseParameters for the same observable, replace those by replicating the respective observable.

This is a helper function for some tools which may not support such timepoint-specific mappings. The observable table and measurement table are modified in place.

Parameters:: petab_problem (petab.v2.core.Problem) – PEtab problem to work on. Modified in place.
Return type:: None

amici.petab.petab_importer.has_timepoint_specific_overrides(petab_problem, ignore_scalar_numeric_noise_parameters=False, ignore_scalar_numeric_observable_parameters=False)[source]

Check if the measurements have timepoint-specific observable or noise parameter overrides.

Parameters:

petab_problem (petab.v2.core.Problem) – PEtab problem to check.
ignore_scalar_numeric_noise_parameters (bool) – ignore scalar numeric assignments to noiseParameter placeholders
ignore_scalar_numeric_observable_parameters (bool) – ignore scalar numeric assignments to observableParameter placeholders

Return type:

bool

Returns:

True if the problem has timepoint-specific overrides, False otherwise.

amici.petab.petab_importer.rdatas_to_measurement_df(rdatas, model, petab_problem)[source]

Create a measurement dataframe in the PEtab format from the passed rdatas and own information.

Parameters:

rdatas (collections.abc.Sequence[amici.amici.ReturnData]) – A sequence of amici.ReturnData.
model (amici.amici.Model | amici.amici.ModelPtr) – AMICI model used to generate rdatas.
petab_problem (petab.v2.core.Problem) – The PEtab problem used to generate rdatas.

Return type:

pandas.core.frame.DataFrame

Returns:

A dataframe built from simulation results in rdatas in the format of the PEtab measurement table.

amici.petab.petab_importer.rdatas_to_simulation_df(rdatas, model, petab_problem)[source]

Create a simulation dataframe in the PEtab format from the passed rdatas and own information.

Parameters:

rdatas (collections.abc.Sequence[amici.amici.ReturnData]) – A sequence of amici.ReturnData.
model (amici.amici.Model | amici.amici.ModelPtr) – AMICI model used to generate rdatas.
petab_problem (petab.v2.core.Problem) – The PEtab problem used to generate rdatas.

Return type:

pandas.core.frame.DataFrame

Returns:

A dataframe built from simulation results in rdatas in the format of the PEtab simulation table.

amici.petab.petab_importer.unflatten_simulation_df(simulation_df, petab_problem)[source]

Unflatten simulations from a flattened PEtab problem.

A flattened PEtab problem is the output of applying flatten_timepoint_specific_output_overrides() to a PEtab problem.

Parameters:

simulation_df (pandas.core.frame.DataFrame) – The simulation dataframe. A dataframe in the same format as a PEtab measurements table, but with the measurement column switched with a simulation column.
petab_problem (petab.v2.core.Problem) – The unflattened PEtab problem.

Return type:

pandas.core.frame.DataFrame

Returns:

The simulation dataframe for the unflattened PEtab problem.