petab.simulate

PEtab simulator base class and related functions.

Functions

sample_noise(petab_problem, measurement_row, ...)

Generate a sample from a PEtab noise distribution.

Classes

Simulator(petab_problem[, working_dir])

Base class that specific simulators should inherit.
class petab.simulate.Simulator(petab_problem: Problem, working_dir: None | str | Path = None)[source]

Bases: ABC

Base class that specific simulators should inherit.

Specific simulators should minimally implement the petab.simulate.Simulator.simulate_without_noise() method. Example (AMICI): https://bit.ly/33SUSG4

noise_formulas

The formulae that will be used to calculate the scale of noise distributions.

petab_problem

A PEtab problem, which will be simulated.

rng

A NumPy random generator, used to sample from noise distributions.

temporary_working_dir

Whether working_dir is a temporary directory, which can be deleted without significant consequence.

working_dir

All simulator-specific output files will be saved here. This directory and its contents may be modified and deleted, and should be considered ephemeral.

add_noise(simulation_df: DataFrame, noise_scaling_factor: float = 1, **kwargs) → DataFrame[source]

Add noise to simulated data.

Parameters:

  • simulation_df – A PEtab measurements table that contains simulated data.

  • noise_scaling_factor – A multiplier of the scale of the noise distribution.

  • **kwargs – Additional keyword arguments are passed to sample_noise().

Returns:

Simulated data with noise, as a PEtab measurements table.

remove_working_dir(force: bool = False, **kwargs) → None[source]

Remove the simulator working directory, and all files within.

See the petab.simulate.Simulator.__init__() method arguments.

Parameters:

  • force – If True, the working directory is removed regardless of whether it is a temporary directory.

  • **kwargs – Additional keyword arguments are passed to shutil.rmtree().

simulate(noise: bool = False, noise_scaling_factor: float = 1, as_measurement: bool = False, **kwargs) → DataFrame[source]

Simulate a PEtab problem, optionally with noise.

Parameters:
Returns:

Simulated data, as a PEtab measurements table.

abstract simulate_without_noise() → DataFrame[source]

Simulate the PEtab problem.

This is an abstract method that should be implemented with a simulation package. Examples of this are referenced in the class docstring.

Returns:

Simulated data, as a PEtab measurements table, which should be equivalent to replacing all values in the petab.C.MEASUREMENT column of the measurements table (of the PEtab problem supplied to the petab.simulate.Simulator.__init__() method), with simulated values.

petab.simulate.sample_noise(petab_problem: Problem, measurement_row: Series, simulated_value: float, noise_formulas: Dict[str, Expr] | None = None, rng: Generator | None = None, noise_scaling_factor: float = 1, zero_bounded: bool = False) → float[source]

Generate a sample from a PEtab noise distribution.

Parameters:

  • petab_problem – The PEtab problem used to generate the simulated value. Instance of petab.Problem.

  • measurement_row – The row in the PEtab problem measurement table that corresponds to the simulated value.

  • simulated_value – A simulated value without noise.

  • noise_formulas – Processed noise formulas from the PEtab observables table, in the form output by petab.calculate.get_symbolic_noise_formulas().

  • rng – A NumPy random generator.

  • noise_scaling_factor – A multiplier of the scale of the noise distribution.

  • zero_bounded – Return zero if the sign of the return value and simulated_value differ. Can be used to ensure non-negative and non-positive values, if the sign of simulated_value should not change.

Returns:

The sample from the PEtab noise distribution.