amici.importers.petab

PEtab import related code.

This submodule contains all functionality related to importing PEtab problems.

For importing and simulating PEtab v2 problems, the relevant classes are:

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 legacy v1 import functionality is still available under amici.importers.petab.v1. Note that this functionality will be deprecated once the PEtab v2 import is stable. Most PEtab v1 problems can be also imported using the PEtab v2 import by passing a petab.v1.Problem instance to the PEtab v2 import functions.

class amici.importers.petab.PetabImporter(petab_problem, *, compile_=None, validate=True, module_name=None, output_dir=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, output_dir=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.

  • output_dir (str | pathlib.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.sim.sundials.Model instance from the imported model.

Return type:

amici._installation.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.sim.sundials.petab._v2.PetabSimulator | amici.sim.jax.petab.JAXProblem

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:

types.ModuleType

Returns:

The imported model module.

property model_id: str

The model ID.

property output_dir: Path

The output directory where the model files are written to.

amici.importers.petab.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.importers.petab.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.importers.petab.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:
Return type:

pandas.DataFrame

Returns:

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

amici.importers.petab.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:
Return type:

pandas.DataFrame

Returns:

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

amici.importers.petab.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.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.DataFrame

Returns:

The simulation dataframe for the unflattened PEtab problem.