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: petab.problem.Problem, working_dir: Optional[Union[str, pathlib.Path]] = None)

Bases: abc.ABC

Base class that specific simulators should inherit.

Specific simulators should minimally implement the 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: pandas.core.frame.DataFrame, noise_scaling_factor: float = 1, **kwargs) → pandas.core.frame.DataFrame

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

Remove the simulator working directory, and all files within.

See the __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, **kwargs) → pandas.core.frame.DataFrame

Simulate a PEtab problem, optionally with noise.

Parameters

• noise – If True, noise is added to simulated data.

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

• **kwargs – Additional keyword arguments are passed to simulate_without_noise.

Returns

Simulated data, as a PEtab measurements table.

abstract simulate_without_noise() → pandas.core.frame.DataFrame

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 __init__ method), with simulated values.

petab.simulate.sample_noise(petab_problem: petab.problem.Problem, measurement_row: pandas.core.series.Series, simulated_value: float, noise_formulas: Optional[Dict[str, sympy.core.expr.Expr]] = None, rng: Optional[numpy.random._generator.Generator] = None, noise_scaling_factor: float = 1, zero_bounded: bool = False) → float

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 the petab.calculate.get_symbolic_noise_formulas method.

• 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.