petab.v1.simulate
PEtab simulator base class and related functions.
Functions
|
Generate a sample from a PEtab noise distribution. |
Classes
|
Base class that specific simulators should inherit. |
- class petab.v1.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:
noise – If True, noise is added to simulated data.
noise_scaling_factor – A multiplier of the scale of the noise distribution.
as_measurement – Whether the data column is named
petab.C.MEASUREMENT
(True) orpetab.C.SIMULATION
(False).**kwargs – Additional keyword arguments are passed to
petab.simulate.Simulator.simulate_without_noise()
.
- 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 thepetab.simulate.Simulator.__init__()
method), with simulated values.
- petab.v1.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 ofsimulated_value
should not change.
- Returns:
The sample from the PEtab noise distribution.