API Reference
PEtab global
- petab.ENV_NUM_THREADS
Name of environment variable to set number of threads or processes PEtab should use for operations that can be performed in parallel. By default, all operations are performed sequentially.
- class petab.CompositeProblem(parameter_df: Optional[DataFrame] = None, problems: Optional[List[Problem]] = None)[source]
Bases:
object
Representation of a PEtab problem consisting of multiple models
- problems
List of
petab.Problem
s
- parameter_df
PEtab parameter DataFrame
- class petab.Problem(sbml_model: libsbml.Model = None, sbml_reader: libsbml.SBMLReader = None, sbml_document: libsbml.SBMLDocument = None, model: Model = None, condition_df: pd.DataFrame = None, measurement_df: pd.DataFrame = None, parameter_df: pd.DataFrame = None, visualization_df: pd.DataFrame = None, observable_df: pd.DataFrame = None, extensions_config: Dict = None)[source]
Bases:
object
PEtab parameter estimation problem as defined by
model
condition table
measurement table
parameter table
observables table
Optionally it may contain visualization tables.
- condition_df
PEtab condition table
- measurement_df
PEtab measurement table
- parameter_df
PEtab parameter table
- observable_df
PEtab observable table
- visualization_df
PEtab visualization table
- model
The underlying model
- sbml_reader
Stored to keep object alive (deprecated).
- sbml_document
Stored to keep object alive (deprecated).
- sbml_model
PEtab SBML model (deprecated)
- extensions_config
Information on the extensions used
- _apply_mask(v: List, free: bool = True, fixed: bool = True)[source]
Apply mask of only free or only fixed values.
- Parameters
v – The full vector the mask is to be applied to.
free – Whether to return free parameters, i.e. parameters to estimate.
fixed – Whether to return fixed parameters, i.e. parameters not to estimate.
- Return type
The reduced vector with applied mask.
- static from_combine(filename: Union[Path, str]) Problem [source]
Read PEtab COMBINE archive (http://co.mbine.org/documents/archive).
See also
petab.create_combine_archive()
.- Parameters
filename – Path to the PEtab-COMBINE archive
- Returns
A
petab.Problem
instance.
- static from_files(sbml_file: Optional[Union[Path, str]] = None, condition_file: Optional[Union[str, Path, Iterable[Union[str, Path]]]] = None, measurement_file: Optional[Union[str, Path, Iterable[Union[str, Path]]]] = None, parameter_file: Optional[Union[str, Path, Iterable[Union[str, Path]]]] = None, visualization_files: Optional[Union[str, Path, Iterable[Union[str, Path]]]] = None, observable_files: Optional[Union[str, Path, Iterable[Union[str, Path]]]] = None, extensions_config: Optional[Dict] = None) Problem [source]
Factory method to load model and tables from files.
- Parameters
sbml_file – PEtab SBML model
condition_file – PEtab condition table
measurement_file – PEtab measurement table
parameter_file – PEtab parameter table
visualization_files – PEtab visualization tables
observable_files – PEtab observables tables
extensions_config – Information on the extensions used
- static from_yaml(yaml_config: Union[Dict, Path, str]) Problem [source]
Factory method to load model and tables as specified by YAML file.
- Parameters
yaml_config – PEtab configuration as dictionary or YAML file name
- get_lb(free: bool = True, fixed: bool = True, scaled: bool = False)[source]
Generic function to get lower parameter bounds.
- Parameters
free – Whether to return free parameters, i.e. parameters to estimate.
fixed – Whether to return fixed parameters, i.e. parameters not to estimate.
scaled – Whether to scale the values according to the parameter scale, or return them on linear scale.
- Return type
The lower parameter bounds.
- get_optimization_to_simulation_parameter_mapping(**kwargs)[source]
See
petab.parameter_mapping.get_optimization_to_simulation_parameter_mapping()
, to which all keyword arguments are forwarded.
- get_ub(free: bool = True, fixed: bool = True, scaled: bool = False)[source]
Generic function to get upper parameter bounds.
- Parameters
free – Whether to return free parameters, i.e. parameters to estimate.
fixed – Whether to return fixed parameters, i.e. parameters not to estimate.
scaled – Whether to scale the values according to the parameter scale, or return them on linear scale.
- Return type
The upper parameter bounds.
- get_x_ids(free: bool = True, fixed: bool = True)[source]
Generic function to get parameter ids.
- Parameters
free – Whether to return free parameters, i.e. parameters to estimate.
fixed – Whether to return fixed parameters, i.e. parameters not to estimate.
- Return type
The parameter IDs.
- get_x_nominal(free: bool = True, fixed: bool = True, scaled: bool = False)[source]
Generic function to get parameter nominal values.
- Parameters
free – Whether to return free parameters, i.e. parameters to estimate.
fixed – Whether to return fixed parameters, i.e. parameters not to estimate.
scaled – Whether to scale the values according to the parameter scale, or return them on linear scale.
- Return type
The parameter nominal values.
- scale_parameters(x_dict: Dict[str, float]) Dict[str, float] [source]
Scale parameter values.
- Parameters
x_dict – Keys are parameter IDs in the PEtab problem, values are unscaled parameter values.
- Return type
The scaled parameter values.
- to_files(sbml_file: Union[None, str, Path] = None, condition_file: Union[None, str, Path] = None, measurement_file: Union[None, str, Path] = None, parameter_file: Union[None, str, Path] = None, visualization_file: Union[None, str, Path] = None, observable_file: Union[None, str, Path] = None, yaml_file: Union[None, str, Path] = None, prefix_path: Union[None, str, Path] = None, relative_paths: bool = True, model_file: Union[None, str, Path] = None) None [source]
Write PEtab tables to files for this problem
Writes PEtab files for those entities for which a destination was passed.
NOTE: If this instance was created from multiple measurement or visualization tables, they will be merged and written to a single file.
- Parameters
sbml_file – SBML model destination
model_file – Model destination
condition_file – Condition table destination
measurement_file – Measurement table destination
parameter_file – Parameter table destination
visualization_file – Visualization table destination
observable_file – Observables table destination
yaml_file – YAML file destination
prefix_path – Specify a prefix to all paths, to avoid specifying the prefix for all paths individually. NB: the prefix is added to paths before relative_paths is handled.
relative_paths – whether all paths in the YAML file should be relative to the location of the YAML file. If False, then paths are left unchanged.
- Raises
ValueError – If a destination was provided for a non-existing entity.
- to_files_generic(prefix_path: Union[str, Path]) str [source]
Save a PEtab problem to generic file names.
The PEtab problem YAML file is always created. PEtab data files are only created if the PEtab problem contains corresponding data (e.g. a PEtab visualization TSV file is only created if the PEtab problem has one).
- Parameters
prefix_path – Specify a prefix to all paths, to avoid specifying the prefix for all paths individually. NB: the prefix is added to paths before relative_paths is handled downstream in petab.yaml.create_problem_yaml.
- Returns
The path to the PEtab problem YAML file.
- unscale_parameters(x_dict: Dict[str, float]) Dict[str, float] [source]
Unscale parameter values.
- Parameters
x_dict – Keys are parameter IDs in the PEtab problem, values are scaled parameter values.
- Return type
The unscaled parameter values.
- property x_nominal_fixed_scaled: List
Parameter table nominal values with applied parameter scaling, for fixed parameters.
- class petab.Simulator(petab_problem: Problem, working_dir: Union[None, str, Path] = None)[source]
Bases:
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: 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 __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) 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.
**kwargs – Additional keyword arguments are passed to 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 the __init__ method), with simulated values.
- petab.assert_all_parameters_present_in_parameter_df(parameter_df: DataFrame, model: Model, observable_df: DataFrame, measurement_df: DataFrame, condition_df: DataFrame) None [source]
Ensure all required parameters are contained in the parameter table with no additional ones
- Parameters
parameter_df – PEtab parameter DataFrame
model – model
observable_df – PEtab observable table
measurement_df – PEtab measurement table
condition_df – PEtab condition table
- Raises
AssertionError – in case of problems
- petab.assert_measured_observables_defined(measurement_df: DataFrame, observable_df: DataFrame) None [source]
Check if all observables in the measurement table have been defined in the observable table
- Parameters
measurement_df – PEtab measurement table
observable_df – PEtab observable table
- Raises
AssertionError – in case of problems
- petab.assert_measurement_conditions_present_in_condition_table(measurement_df: DataFrame, condition_df: DataFrame) None [source]
Ensure that all entries from measurement_df.simulationConditionId and measurement_df.preequilibrationConditionId are present in condition_df.index.
- Parameters
measurement_df – PEtab measurement table
condition_df – PEtab condition table
- Raises
AssertionError – in case of problems
- petab.assert_measurements_not_null(measurement_df: DataFrame) None [source]
Check whether all measurements are not null.
- Parameters
measurement_df – PEtab measurement table.
- Raises
AssertionError – Some measurement value(s) are null (missing).
- petab.assert_measurements_numeric(measurement_df: DataFrame) None [source]
Check whether all measurements are numeric.
Note that null (missing) measurements are ignored.
- Parameters
measurement_df – PEtab measurement table.
- Raises
AssertionError – Some measurement value(s) are not numeric.
- petab.assert_model_parameters_in_condition_or_parameter_table(model: Model, condition_df: DataFrame, parameter_df: DataFrame) None [source]
Model parameters that are rule targets must not be present in the parameter table. Other parameters must only be present in either in parameter table or condition table columns. Check that.
- Parameters
parameter_df – PEtab parameter DataFrame
model – PEtab model
condition_df – PEtab condition table
- Raises
AssertionError – in case of problems
- petab.assert_no_leading_trailing_whitespace(names_list: Iterable[str], name: str) None [source]
Check that there is no trailing whitespace in elements of Iterable
- Parameters
names_list – strings to check for whitespace
name – name of names_list for error messages
- Raises
AssertionError – if there is trailing whitespace
- petab.assert_noise_distributions_valid(observable_df: DataFrame) None [source]
Ensure that noise distributions and transformations for observables are valid.
- Parameters
observable_df – PEtab observable table
- Raises
AssertionError – in case of problems
- petab.assert_overrides_match_parameter_count(measurement_df: DataFrame, observable_df: DataFrame) None [source]
Ensure that number of parameters in the observable definition matches the number of overrides in
measurement_df
- Parameters
measurement_df – PEtab measurement table
observable_df – PEtab observable table
- petab.assert_parameter_bounds_are_numeric(parameter_df: DataFrame) None [source]
Check if all entries in the lowerBound and upperBound columns of the parameter table are numeric.
- Parameters
parameter_df – PEtab parameter DataFrame
- Raises
AssertionError – in case of problems
- petab.assert_parameter_estimate_is_boolean(parameter_df: DataFrame) None [source]
Check if all entries in the estimate column of the parameter table are 0 or 1.
- Parameters
parameter_df – PEtab parameter DataFrame
- Raises
AssertionError – in case of problems
- petab.assert_parameter_id_is_string(parameter_df: DataFrame) None [source]
Check if all entries in the parameterId column of the parameter table are string and not empty.
- Parameters
parameter_df – PEtab parameter DataFrame
- Raises
AssertionError – in case of problems
- petab.assert_parameter_prior_parameters_are_valid(parameter_df: DataFrame) None [source]
Check that the prior parameters are valid.
- Parameters
parameter_df – PEtab parameter table
- Raises
AssertionError – in case of invalid prior parameters
- petab.assert_parameter_prior_type_is_valid(parameter_df: DataFrame) None [source]
Check that valid prior types have been selected
- Parameters
parameter_df – PEtab parameter table
- Raises
AssertionError – in case of invalid prior
- petab.assert_parameter_scale_is_valid(parameter_df: DataFrame) None [source]
Check if all entries in the parameterScale column of the parameter table are ‘lin’ for linear, ‘log’ for natural logarithm or ‘log10’ for base 10 logarithm.
- Parameters
parameter_df – PEtab parameter DataFrame
- Raises
AssertionError – in case of problems
- petab.assert_single_condition_and_sbml_file(problem_config: Dict) None [source]
Check that there is only a single condition file and a single SBML file specified.
- Parameters
problem_config – Dictionary as defined in the YAML schema inside the problems list.
- Raises
NotImplementedError – If multiple condition or SBML files specified.
- petab.assert_unique_observable_ids(observable_df: DataFrame) None [source]
Check if the observableId column of the observable table is unique.
- Parameters
observable_df – PEtab observable DataFrame
- Raises
AssertionError – in case of problems
- petab.assert_unique_parameter_ids(parameter_df: DataFrame) None [source]
Check if the parameterId column of the parameter table is unique.
- Parameters
parameter_df – PEtab parameter DataFrame
- Raises
AssertionError – in case of problems
- petab.calculate_chi2(measurement_dfs: Union[List[DataFrame], DataFrame], simulation_dfs: Union[List[DataFrame], DataFrame], observable_dfs: Union[List[DataFrame], DataFrame], parameter_dfs: Union[List[DataFrame], DataFrame], normalize: bool = True, scale: bool = True) float [source]
Calculate the chi2 value.
- Parameters
measurement_dfs – The problem measurement tables.
simulation_dfs – Simulation tables corresponding to the measurement tables.
observable_dfs – The problem observable tables.
parameter_dfs – The problem parameter tables.
normalize – Whether to normalize residuals by the noise standard deviation terms.
scale – Whether to calculate residuals of scaled values.
- Returns
The aggregated chi2 value.
- petab.calculate_chi2_for_table_from_residuals(residual_df: DataFrame) float [source]
Compute chi2 value for a single residual table.
- petab.calculate_llh(measurement_dfs: Union[List[DataFrame], DataFrame], simulation_dfs: Union[List[DataFrame], DataFrame], observable_dfs: Union[List[DataFrame], DataFrame], parameter_dfs: Union[List[DataFrame], DataFrame]) float [source]
Calculate total log likelihood.
- Parameters
measurement_dfs – The problem measurement tables.
simulation_dfs – Simulation tables corresponding to the measurement tables.
observable_dfs – The problem observable tables.
parameter_dfs – The problem parameter tables.
- Returns
The log-likelihood.
- petab.calculate_llh_for_table(measurement_df: DataFrame, simulation_df: DataFrame, observable_df: DataFrame, parameter_df: DataFrame) float [source]
Calculate log-likelihood for one set of tables. For the arguments, see calculate_llh.
- petab.calculate_residuals(measurement_dfs: Union[List[DataFrame], DataFrame], simulation_dfs: Union[List[DataFrame], DataFrame], observable_dfs: Union[List[DataFrame], DataFrame], parameter_dfs: Union[List[DataFrame], DataFrame], normalize: bool = True, scale: bool = True) List[DataFrame] [source]
Calculate residuals.
- Parameters
measurement_dfs – The problem measurement tables.
simulation_dfs – Simulation tables corresponding to the measurement tables.
observable_dfs – The problem observable tables.
parameter_dfs – The problem parameter tables.
normalize – Whether to normalize residuals by the noise standard deviation terms.
scale – Whether to calculate residuals of scaled values.
- Returns
List of DataFrames in the same structure as measurement_dfs with a field residual instead of measurement.
- petab.calculate_residuals_for_table(measurement_df: DataFrame, simulation_df: DataFrame, observable_df: DataFrame, parameter_df: DataFrame, normalize: bool = True, scale: bool = True) DataFrame [source]
Calculate residuals for a single measurement table. For the arguments, see calculate_residuals.
- petab.calculate_single_llh(measurement: float, simulation: float, scale: str, noise_distribution: str, noise_value: float) float [source]
Calculate a single log likelihood.
- Parameters
measurement – The measurement value.
simulation – The simulated value.
scale – The scale on which the noise model is to be applied.
noise_distribution – The noise distribution.
noise_value – The considered noise models possess a single noise parameter, e.g. the normal standard deviation.
- Returns
The computed likelihood for the given values.
- petab.check_condition_df(df: DataFrame, model: Optional[Model] = None) None [source]
Run sanity checks on PEtab condition table
- Parameters
df – PEtab condition DataFrame
model – Model for additional checking of parameter IDs
- Raises
AssertionError – in case of problems
- petab.check_ids(ids: Iterable[str], kind: str = '') None [source]
Check IDs are valid
- Parameters
ids – Iterable of IDs to check
kind – Kind of IDs, for more informative error message
- Raises
ValueError – in case of invalid IDs
- petab.check_measurement_df(df: DataFrame, observable_df: Optional[DataFrame] = None) None [source]
Run sanity checks on PEtab measurement table
- Parameters
df – PEtab measurement DataFrame
observable_df – PEtab observable DataFrame for checking if measurements are compatible with observable transformations.
- Raises
AssertionError, ValueError – in case of problems
- petab.check_observable_df(observable_df: DataFrame) None [source]
Check validity of observable table
- Parameters
observable_df – PEtab observable DataFrame
- Raises
AssertionError – in case of problems
- petab.check_parameter_bounds(parameter_df: DataFrame) None [source]
Check if all entries in the lowerBound are smaller than upperBound column in the parameter table and that bounds are positive for parameterScale log|log10.
- Parameters
parameter_df – PEtab parameter DataFrame
- Raises
AssertionError – in case of problems
- petab.check_parameter_df(df: DataFrame, model: Optional[Model] = None, observable_df: Optional[DataFrame] = None, measurement_df: Optional[DataFrame] = None, condition_df: Optional[DataFrame] = None) None [source]
Run sanity checks on PEtab parameter table
- Parameters
df – PEtab condition DataFrame
model – Model for additional checking of parameter IDs
observable_df – PEtab observable table for additional checks
measurement_df – PEtab measurement table for additional checks
condition_df – PEtab condition table for additional checks
- Raises
AssertionError – in case of problems
- petab.concat_tables(tables: Union[str, Path, DataFrame, Iterable[Union[DataFrame, str, Path]]], file_parser: Optional[Callable] = None) DataFrame [source]
Concatenate DataFrames provided as DataFrames or filenames, and a parser
- Parameters
tables – Iterable of tables to join, as DataFrame or filename.
file_parser – Function used to read the table in case filenames are provided, accepting a filename as only argument.
- Returns
The concatenated DataFrames
- petab.condition_table_is_parameter_free(condition_df: DataFrame) bool [source]
Check if all entries in the condition table are numeric (no parameter IDs)
- Parameters
condition_df – PEtab condition table
- Returns
True
if there are no parameter overrides in the condition table,False
otherwise.
- petab.create_combine_archive(yaml_file: Union[str, Path], filename: Union[str, Path], family_name: Optional[str] = None, given_name: Optional[str] = None, email: Optional[str] = None, organization: Optional[str] = None) None [source]
Create COMBINE archive (https://co.mbine.org/documents/archive) based on PEtab YAML file.
- Parameters
yaml_file – Path to PEtab YAML file
filename – Destination file name
family_name – Family name of archive creator
given_name – Given name of archive creator
email – E-mail address of archive creator
organization – Organization of archive creator
- petab.create_condition_df(parameter_ids: Iterable[str], condition_ids: Optional[Iterable[str]] = None) DataFrame [source]
Create empty condition DataFrame
- Parameters
parameter_ids – the columns
condition_ids – the rows
- Returns
A
pandas.DataFrame
with empty given rows and columns and all nan values
- petab.create_measurement_df() DataFrame [source]
Create empty measurement dataframe
- Returns
Created DataFrame
- petab.create_observable_df() DataFrame [source]
Create empty observable dataframe
- Returns
Created DataFrame
- petab.create_parameter_df(sbml_model: Optional[Model] = None, condition_df: Optional[DataFrame] = None, observable_df: Optional[DataFrame] = None, measurement_df: Optional[DataFrame] = None, model: Optional[Model] = None, include_optional: bool = False, parameter_scale: str = 'log10', lower_bound: Optional[Iterable] = None, upper_bound: Optional[Iterable] = None) DataFrame [source]
Create a new PEtab parameter table
All table entries can be provided as string or list-like with length matching the number of parameters
- Parameters
sbml_model – SBML Model
model – PEtab model
condition_df – PEtab condition DataFrame
observable_df – PEtab observable DataFrame
measurement_df – PEtab measurement DataFrame
include_optional – By default this only returns parameters that are required to be present in the parameter table. If set to True, this returns all parameters that are allowed to be present in the parameter table (i.e. also including parameters specified in the model).
parameter_scale – parameter scaling
lower_bound – lower bound for parameter value
upper_bound – upper bound for parameter value
- Returns
The created parameter DataFrame
- petab.create_problem_yaml(sbml_files: Union[str, Path, List[Union[str, Path]]], condition_files: Union[str, Path, List[Union[str, Path]]], measurement_files: Union[str, Path, List[Union[str, Path]]], parameter_file: Union[str, Path], observable_files: Union[str, Path, List[Union[str, Path]]], yaml_file: Union[str, Path], visualization_files: Optional[Union[str, Path, List[Union[str, Path]]]] = None, relative_paths: bool = True) None [source]
Create and write default YAML file for a single PEtab problem
- Parameters
sbml_files – Path of SBML model file or list of such
condition_files – Path of condition file or list of such
measurement_files – Path of measurement file or list of such
parameter_file – Path of parameter file
observable_files – Path of observable file or list of such
yaml_file – Path to which YAML file should be written
visualization_files – Optional Path to visualization file or list of such
relative_paths – whether all paths in the YAML file should be relative to the location of the YAML file. If
False
, then paths are left unchanged.
- petab.evaluate_noise_formula(measurement: Series, noise_formulas: Dict[str, Expr], parameter_df: DataFrame, simulation: Number) float [source]
Fill in parameters for measurement and evaluate noise_formula.
- Parameters
measurement – A measurement table row.
noise_formulas – The noise formulas as computed by get_symbolic_noise_formulas.
parameter_df – The parameter table.
simulation – The simulation corresponding to the measurement, scaled.
- Returns
The noise value.
- petab.flatten_timepoint_specific_output_overrides(petab_problem: petab.problem.Problem) None [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 problem to work on
- petab.get_condition_df(condition_file: Optional[Union[str, DataFrame, Path]]) DataFrame [source]
Read the provided condition file into a
pandas.Dataframe
Conditions are rows, parameters are columns, conditionId is index.
- Parameters
condition_file – File name of PEtab condition file or pandas.Dataframe
- petab.get_formula_placeholders(formula_string: str, observable_id: str, override_type: str) List[str] [source]
Get placeholder variables in noise or observable definition for the given observable ID.
- Parameters
formula_string – observable formula
observable_id – ID of current observable
override_type – ‘observable’ or ‘noise’, depending on whether formula is for observable or for noise model
- Returns
List of placeholder parameter IDs in the order expected in the observableParameter column of the measurement table.
- petab.get_measurement_df(measurement_file: Union[None, str, Path, DataFrame]) DataFrame [source]
Read the provided measurement file into a
pandas.Dataframe
.- Parameters
measurement_file – Name of file to read from or pandas.Dataframe
- Returns
Measurement DataFrame
- petab.get_measurement_parameter_ids(measurement_df: DataFrame) List[str] [source]
Return list of ID of parameters which occur in measurement table as observable or noise parameter overrides.
- Parameters
measurement_df – PEtab measurement DataFrame
- Returns
List of parameter IDs
- petab.get_model_for_condition(petab_problem: Problem, sim_condition_id: Optional[str] = None, preeq_condition_id: Optional[str] = None) Tuple[SBMLDocument, Model] [source]
Create an SBML model for the given condition.
Creates a copy of the model and updates parameters according to the PEtab files. Estimated parameters are set to their
nominalValue
. Observables defined in the observables table are not added to the model.- Parameters
petab_problem – PEtab problem
sim_condition_id – Simulation
conditionId
for which to generate a modelpreeq_condition_id – Preequilibration
conditionId
of the settings for which to generate a model. This is only used to determine the relevant output parameter overrides. Preequilibration is not encoded in the resulting model.
- Returns
The generated SBML document, and SBML model
- petab.get_model_parameters(sbml_model: Model, with_values=False) Union[List[str], Dict[str, float]] [source]
Return SBML model parameters which are not Rule targets
- Parameters
sbml_model – SBML model
with_values – If False, returns list of SBML model parameter IDs which are not Rule targets. If True, returns a dictionary with those parameter IDs as keys and parameter values from the SBML model as values.
- petab.get_notnull_columns(df: DataFrame, candidates: Iterable)[source]
Return list of
df
-columns incandidates
which are not all null/nan.The output can e.g. be used as input for
pandas.DataFrame.groupby
.- Parameters
df – Dataframe
candidates – Columns of
df
to consider
- petab.get_observable_df(observable_file: Optional[Union[str, DataFrame, Path]]) Optional[DataFrame] [source]
Read the provided observable file into a
pandas.Dataframe
.- Parameters
observable_file – Name of the file to read from or pandas.Dataframe.
- Returns
Observable DataFrame
- petab.get_optimization_parameter_scaling(parameter_df: DataFrame) Dict[str, str] [source]
Get Dictionary with optimization parameter IDs mapped to parameter scaling strings.
- Parameters
parameter_df – PEtab parameter DataFrame
- Returns
Dictionary with optimization parameter IDs mapped to parameter scaling strings.
- petab.get_optimization_parameters(parameter_df: DataFrame) List[str] [source]
Get list of optimization parameter IDs from parameter table.
- Parameters
parameter_df – PEtab parameter DataFrame
- Returns
List of IDs of parameters selected for optimization.
- petab.get_optimization_to_simulation_parameter_mapping(condition_df: DataFrame, measurement_df: DataFrame, parameter_df: Optional[DataFrame] = None, observable_df: Optional[DataFrame] = None, sbml_model: Optional[Model] = None, simulation_conditions: Optional[DataFrame] = None, warn_unmapped: Optional[bool] = True, scaled_parameters: bool = False, fill_fixed_parameters: bool = True, allow_timepoint_specific_numeric_noise_parameters: bool = False, model: Optional[Model] = None) List[Tuple[Dict[str, Union[str, Number]], Dict[str, Union[str, Number]], Dict[str, str], Dict[str, str]]] [source]
Create list of mapping dicts from PEtab-problem to model parameters.
Mapping can be performed in parallel. The number of threads is controlled by the environment variable with the name of
petab.ENV_NUM_THREADS
.- Parameters
condition_df – The dataframes in the PEtab format.
measurement_df – The dataframes in the PEtab format.
parameter_df – The dataframes in the PEtab format.
observable_df – The dataframes in the PEtab format.
sbml_model – The SBML model (deprecated)
model – The model.
simulation_conditions – Table of simulation conditions as created by
petab.get_simulation_conditions
.warn_unmapped – If
True
, log warning regarding unmapped parametersscaled_parameters – Whether parameter values should be scaled.
fill_fixed_parameters – Whether to fill in nominal values for fixed parameters (estimate=0 in parameters table).
allow_timepoint_specific_numeric_noise_parameters – Mapping of timepoint-specific parameters overrides is generally not supported. If this option is set to True, this function will not fail in case of timepoint-specific fixed noise parameters, if the noise formula consists only of one single parameter. It is expected that the respective mapping is performed elsewhere. The value mapped to the respective parameter here is undefined.
- Returns
Parameter value and parameter scale mapping for all conditions.
The length of the returned array is the number of unique combinations of
simulationConditionId
s andpreequilibrationConditionId
s from the measurement table. Each entry is a tuple of four dicts of length equal to the number of model parameters. The first two dicts map simulation parameter IDs to optimization parameter IDs or values (where values are fixed) for preequilibration and simulation condition, respectively. The last two dicts map simulation parameter IDs to the parameter scale of the respective parameter, again for preequilibration and simulation condition. If no preequilibration condition is defined, the respective dicts will be empty.NaN
is used where no mapping exists.
- petab.get_output_parameters(observable_df: DataFrame, model: Model, observables: bool = True, noise: bool = True) List[str] [source]
Get output parameters
Returns IDs of parameters used in observable and noise formulas that are not defined in the model.
- Parameters
observable_df – PEtab observable table
model – The underlying model
observables – Include parameters from observableFormulas
noise – Include parameters from noiseFormulas
- Returns
List of output parameter IDs
- petab.get_parameter_df(parameter_file: Optional[Union[str, Path, DataFrame, Iterable[Union[DataFrame, str, Path]]]]) Optional[DataFrame] [source]
Read the provided parameter file into a
pandas.Dataframe
.- Parameters
parameter_file – Name of the file to read from or pandas.Dataframe,
Iterable. (or an) –
- Returns
Parameter
DataFrame
, orNone
ifNone
was passed.
- petab.get_parameter_mapping_for_condition(condition_id: str, is_preeq: bool, cur_measurement_df: Optional[DataFrame], sbml_model: Optional[Model] = None, condition_df: Optional[DataFrame] = None, parameter_df: Optional[DataFrame] = None, simulation_parameters: Optional[Dict[str, str]] = None, warn_unmapped: bool = True, scaled_parameters: bool = False, fill_fixed_parameters: bool = True, allow_timepoint_specific_numeric_noise_parameters: bool = False, model: Optional[Model] = None) Tuple[Dict[str, Union[str, Number]], Dict[str, str]] [source]
Create dictionary of parameter value and parameter scale mappings from PEtab-problem to SBML parameters for the given condition.
- Parameters
condition_id – Condition ID for which to perform mapping
is_preeq – If
True
, output parameters will not be mappedcur_measurement_df – Measurement sub-table for current condition, can be
None
if not relevant for parameter mappingcondition_df – PEtab condition DataFrame
parameter_df – PEtab parameter DataFrame
sbml_model – The SBML model (deprecated)
model – The model.
simulation_parameters – Model simulation parameter IDs mapped to parameter values (output of
petab.sbml.get_model_parameters(.., with_values=True)
). Optional, saves time if precomputed.warn_unmapped – If
True
, log warning regarding unmapped parametersscaled_parameters – Whether parameter values should be scaled.
fill_fixed_parameters – Whether to fill in nominal values for fixed parameters (estimate=0 in parameters table).
allow_timepoint_specific_numeric_noise_parameters – Mapping of timepoint-specific parameters overrides is generally not supported. If this option is set to True, this function will not fail in case of timepoint-specific fixed noise parameters, if the noise formula consists only of one single parameter. It is expected that the respective mapping is performed elsewhere. The value mapped to the respective parameter here is undefined.
- Returns
Tuple of two dictionaries. First dictionary mapping model parameter IDs to mapped parameters IDs to be estimated or to filled-in values in case of non-estimated parameters. Second dictionary mapping model parameter IDs to their scale.
NaN
is used where no mapping exists.
- petab.get_parametric_overrides(condition_df: DataFrame) List[str] [source]
Get parametric overrides from condition table
- Parameters
condition_df – PEtab condition table
- Returns
List of parameter IDs that are mapped in a condition-specific way
- petab.get_placeholders(observable_df: DataFrame, observables: bool = True, noise: bool = True) List[str] [source]
Get all placeholder parameters from observable table observableFormulas and noiseFormulas
- Parameters
observable_df – PEtab observable table
observables – Include parameters from observableFormulas
noise – Include parameters from noiseFormulas
- Returns
List of placeholder parameters from observable table observableFormulas and noiseFormulas.
- petab.get_priors_from_df(parameter_df: DataFrame, mode: str) List[Tuple] [source]
Create list with information about the parameter priors
- Parameters
parameter_df – PEtab parameter table
mode – ‘initialization’ or ‘objective’
- Returns
List with prior information.
- petab.get_rows_for_condition(measurement_df: DataFrame, condition: Union[Series, DataFrame, Dict]) DataFrame [source]
Extract rows in measurement_df for condition according to ‘preequilibrationConditionId’ and ‘simulationConditionId’ in condition.
- Parameters
measurement_df – PEtab measurement DataFrame
condition – DataFrame with single row (or Series) and columns ‘preequilibrationConditionId’ and ‘simulationConditionId’. Or dictionary with those keys.
- Returns
The subselection of rows in
measurement_df
for the conditioncondition
.
- petab.get_sbml_model(filepath_or_buffer) Tuple[SBMLReader, SBMLDocument, Model] [source]
Get an SBML model from file or URL or file handle
- Parameters
filepath_or_buffer – File or URL or file handle to read the model from
- Returns
The SBML document, model and reader
- petab.get_simulation_conditions(measurement_df: DataFrame) DataFrame [source]
Create a table of separate simulation conditions. A simulation condition is a specific combination of simulationConditionId and preequilibrationConditionId.
- Parameters
measurement_df – PEtab measurement table
- Returns
Dataframe with columns ‘simulationConditionId’ and ‘preequilibrationConditionId’. All-null columns will be omitted. Missing ‘preequilibrationConditionId’s will be set to ‘’ (empty string).
- petab.get_simulation_df(simulation_file: str) DataFrame [source]
Read PEtab simulation table
- Parameters
simulation_file – URL or filename of PEtab simulation table
- Returns
Simulation DataFrame
- petab.get_symbolic_noise_formulas(observable_df) Dict[str, Expr] [source]
Sympify noise formulas.
- Parameters
observable_df – The observable table.
- Returns
{noise_formula}.
- Return type
Dictionary of {observable_id}
- petab.get_visualization_df(visualization_file: Union[str, Path]) DataFrame [source]
Read PEtab visualization table
- Parameters
visualization_file – URL or filename of PEtab visualization table
- Returns
Visualization DataFrame
- petab.globalize_parameters(sbml_model: Model, prepend_reaction_id: bool = False) None [source]
Turn all local parameters into global parameters with the same properties
Local parameters are currently ignored by other PEtab functions. Use this function to convert them to global parameters. There may exist local parameters with identical IDs within different kinetic laws. This is not checked here. If in doubt that local parameter IDs are unique, enable prepend_reaction_id to create global parameters named ${reaction_id}_${local_parameter_id}.
- Parameters
sbml_model – The SBML model to operate on
prepend_reaction_id – Prepend reaction id of local parameter when creating global parameters
- petab.handle_missing_overrides(mapping_par_opt_to_par_sim: Dict[str, Union[str, Number]], warn: bool = True, condition_id: Optional[str] = None) None [source]
Find all observable parameters and noise parameters that were not mapped and set their mapping to np.nan.
Assumes that parameters matching “(noise|observable)Parameter[0-9]+_” were all supposed to be overwritten.
- Parameters
mapping_par_opt_to_par_sim – Output of
get_parameter_mapping_for_condition()
warn – If True, log warning regarding unmapped parameters
condition_id – Optional condition ID for more informative output
- petab.is_composite_problem(yaml_config: Union[Dict, str, Path]) bool [source]
Does this YAML file comprise multiple models?
- Parameters
yaml_config – PEtab configuration as dictionary or YAML file name
- petab.is_empty(val) bool [source]
Check if the value val, e.g. a table entry, is empty.
- Parameters
val – The value to check.
- Returns
Whether the field is to be considered empty.
- petab.is_sbml_consistent(sbml_document: SBMLDocument, check_units: bool = False) bool [source]
Check for SBML validity / consistency
- Parameters
sbml_document – SBML document to check
check_units – Also check for unit-related issues
- Returns
False
if problems were detected, otherwiseTrue
- petab.is_scalar_float(x: Any)[source]
Checks whether input is a number or can be transformed into a number via float
- Parameters
x – input
- Returns
True
if is or can be converted to number,False
otherwise.
- petab.is_valid_identifier(x: str) bool [source]
Check whether x is a valid identifier
Check whether x is a valid identifier for conditions, parameters, observables… . Identifiers may contain upper and lower case letters, digits and underscores, but must not start with a digit.
- Parameters
x – string to check
- Returns
True
if valid,False
otherwise
- petab.lint_problem(problem: Problem) bool [source]
Run PEtab validation on problem
- Parameters
problem – PEtab problem to check
- Returns
True
if errors occurred,False
otherwise
- petab.load_sbml_from_file(sbml_file: str) Tuple[SBMLReader, SBMLDocument, Model] [source]
Load SBML model from file
- Parameters
sbml_file – Filename of the SBML file
- Returns
The SBML document, model and reader
- petab.load_sbml_from_string(sbml_string: str) Tuple[SBMLReader, SBMLDocument, Model] [source]
Load SBML model from string
- Parameters
sbml_string – Model as XML string
- Returns
The SBML document, model and reader
- petab.load_yaml(yaml_config: Union[Dict, Path, str]) Dict [source]
Load YAML
Convenience function to allow for providing YAML inputs as filename, URL or as dictionary.
- Parameters
yaml_config – PEtab YAML config as filename or dict or URL.
- Returns
The unmodified dictionary if
yaml_config
was dictionary. Otherwise the parsed the YAML file.
- petab.log_sbml_errors(sbml_document: SBMLDocument, minimum_severity=1) None [source]
Log libsbml errors
- Parameters
sbml_document – SBML document to check
minimum_severity – Minimum severity level to report (see libsbml)
- petab.map_scale(parameters: Iterable[Number], scale_strs: Union[Iterable[str], str]) Iterable[Number] [source]
Scale the parameters, i.e. as scale(), but for Iterables.
- Parameters
parameters – Parameters to be scaled.
scale_strs – Scales to apply. Broadcast if a single string.
- Returns
The scaled parameters.
- petab.map_unscale(parameters: Iterable[Number], scale_strs: Union[Iterable[str], str]) Iterable[Number] [source]
Unscale the parameters, i.e. as unscale(), but for Iterables.
- Parameters
parameters – Parameters to be unscaled.
scale_strs – Scales that the parameters are currently on. Broadcast if a single string.
- Returns
The unscaled parameters.
- petab.measurement_is_at_steady_state(time: float) bool [source]
Check whether a measurement is at steady state.
- Parameters
time – The time.
- Returns
Whether the measurement is at steady state.
- petab.measurement_table_has_observable_parameter_numeric_overrides(measurement_df: DataFrame) bool [source]
Are there any numbers to override observable parameters?
- Parameters
measurement_df – PEtab measurement table
- Returns
True
if there are any numbers to override observable/noise parameters,False
otherwise.
- petab.measurement_table_has_timepoint_specific_mappings(measurement_df: Optional[DataFrame], allow_scalar_numeric_noise_parameters: bool = False, allow_scalar_numeric_observable_parameters: bool = False) bool [source]
Are there time-point or replicate specific parameter assignments in the measurement table.
- Parameters
measurement_df – PEtab measurement table
allow_scalar_numeric_noise_parameters – ignore scalar numeric assignments to noiseParameter placeholders
allow_scalar_numeric_observable_parameters – ignore scalar numeric assignments to observableParameter placeholders
- Returns
True if there are time-point or replicate specific (non-numeric) parameter assignments in the measurement table, False otherwise.
- petab.measurements_have_replicates(measurement_df: DataFrame) bool [source]
Tests whether the measurements come with replicates
- Parameters
measurement_df – Measurement table
- Returns
True
if there are replicates,False
otherwise
- petab.merge_preeq_and_sim_pars(parameter_mappings: Iterable[Tuple[Dict[str, Union[str, Number]], Dict[str, Union[str, Number]]]], scale_mappings: Iterable[Tuple[Dict[str, str], Dict[str, str]]]) Tuple[List[Tuple[Dict[str, Union[str, Number]], Dict[str, Union[str, Number]]]], List[Tuple[Dict[str, str], Dict[str, str]]]] [source]
Merge preequilibration and simulation parameters and scales for a list of conditions while checking for compatibility.
- Parameters
parameter_mappings – As returned by
petab.get_optimization_to_simulation_parameter_mapping()
.scale_mappings – As returned by
petab.get_optimization_to_simulation_parameter_mapping()
.
- Returns
The parameter and scale simulation mappings, modified and checked.
- petab.merge_preeq_and_sim_pars_condition(condition_map_preeq: Dict[str, Union[str, Number]], condition_map_sim: Dict[str, Union[str, Number]], condition_scale_map_preeq: Dict[str, str], condition_scale_map_sim: Dict[str, str], condition: Any) None [source]
Merge preequilibration and simulation parameters and scales for a single condition while checking for compatibility.
This function is meant for the case where we cannot have different parameters (and scales) for preequilibration and simulation. Therefore, merge both and ensure matching scales and parameters.
condition_map_sim
andcondition_scale_map_sim
will ne modified in place.- Parameters
condition_map_preeq – Parameter mapping as obtained from
get_parameter_mapping_for_condition()
condition_map_sim – Parameter mapping as obtained from
get_parameter_mapping_for_condition()
condition_scale_map_preeq – Parameter scale mapping as obtained from
get_parameter_mapping_for_condition()
condition_scale_map_sim – Parameter scale mapping as obtained from
get_parameter_mapping_for_condition()
condition – Condition identifier for more informative error messages
- petab.normalize_parameter_df(parameter_df: DataFrame) DataFrame [source]
Add missing columns and fill in default values.
- petab.observable_table_has_nontrivial_noise_formula(observable_df: Optional[DataFrame]) bool [source]
Does any observable have a noise formula that is not just a single parameter?
- Parameters
observable_df – PEtab observable table
- Returns
True
if any noise formula does not consist of a single identifier,False
otherwise.
- petab.sample_from_prior(prior: Tuple[str, list, str, list], n_starts: int) array [source]
Creates samples for one parameter based on prior
- Parameters
prior – A tuple as obtained from
petab.parameter.get_priors_from_df
n_starts – Number of samples
- Returns
Array with sampled values
- petab.sample_noise(petab_problem: Problem, measurement_row: Series, simulated_value: float, noise_formulas: Optional[Dict[str, Expr]] = None, rng: Optional[Generator] = 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 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.
- petab.sample_parameter_startpoints(parameter_df: DataFrame, n_starts: int = 100, seed: Optional[int] = None) array [source]
Create numpy.array with starting points for an optimization
- Parameters
parameter_df – PEtab parameter DataFrame
n_starts – Number of points to be sampled
seed – Random number generator seed (see numpy.random.seed)
- Returns
Array of sampled starting points with dimensions n_startpoints x n_optimization_parameters
- petab.scale(parameter: Number, scale_str: str) Number [source]
Scale parameter according to scale_str.
- Parameters
parameter – Parameter to be scaled.
scale_str – One of ‘lin’ (synonymous with ‘’), ‘log’, ‘log10’.
- Returns
The scaled parameter.
- petab.split_parameter_replacement_list(list_string: Union[str, Number], delim: str = ';') List[Union[str, Number]] [source]
Split values in observableParameters and noiseParameters in measurement table.
- Parameters
list_string – delim-separated stringified list
delim – delimiter
- Returns
List of split values. Numeric values may be converted to float, and parameter IDs are kept as strings.
- petab.to_float_if_float(x: Any) Any [source]
Return input as float if possible, otherwise return as is
- Parameters
x – Anything
- Returns
x
as float if possible, otherwisex
- petab.unique_preserve_order(seq: Sequence) List [source]
Return a list of unique elements in Sequence, keeping only the first occurrence of each element
- Parameters
seq – Sequence to prune
- Returns
List of unique elements in
seq
- petab.unscale(parameter: Number, scale_str: str) Number [source]
Unscale parameter according to scale_str.
- Parameters
parameter – Parameter to be unscaled.
scale_str – One of ‘lin’ (synonymous with ‘’), ‘log’, ‘log10’.
- Returns
The unscaled parameter.
- petab.validate(yaml_config: Union[Dict, str, Path], path_prefix: Union[None, str, Path] = None)[source]
Validate syntax and semantics of PEtab config YAML
- Parameters
yaml_config – PEtab YAML config as filename or dict.
path_prefix – Base location for relative paths. Defaults to location of YAML file if a filename was provided for
yaml_config
or the current working directory.
- petab.validate_yaml_semantics(yaml_config: Union[Dict, str, Path], path_prefix: Union[None, str, Path] = None)[source]
Validate PEtab YAML file semantics
Check for existence of files. Assumes valid syntax.
Version number and contents of referenced files are not yet checked.
- Parameters
yaml_config – PEtab YAML config as filename or dict.
path_prefix – Base location for relative paths. Defaults to location of YAML file if a filename was provided for
yaml_config
or the current working directory.
- Raises
AssertionError – in case of problems
- petab.validate_yaml_syntax(yaml_config: Union[Dict, str, Path], schema: Union[None, Dict, str] = None)[source]
Validate PEtab YAML file syntax
- Parameters
yaml_config – PEtab YAML file to validate, as file name or dictionary
schema – Custom schema for validation
- Raises
see jsonschema.validate –
- petab.write_condition_df(df: DataFrame, filename: Union[str, Path]) None [source]
Write PEtab condition table
- Parameters
df – PEtab condition table
filename – Destination file name
- petab.write_measurement_df(df: DataFrame, filename: Union[str, Path]) None [source]
Write PEtab measurement table
- Parameters
df – PEtab measurement table
filename – Destination file name
- petab.write_observable_df(df: DataFrame, filename: Union[str, Path]) None [source]
Write PEtab observable table
- Parameters
df – PEtab observable table
filename – Destination file name
- petab.write_parameter_df(df: DataFrame, filename: Union[str, Path]) None [source]
Write PEtab parameter table
- Parameters
df – PEtab parameter table
filename – Destination file name
- petab.write_sbml(sbml_doc: SBMLDocument, filename: Union[Path, str]) None [source]
Write PEtab visualization table
- Parameters
sbml_doc – SBML document containing the SBML model
filename – Destination file name
- petab.write_simulation_df(df: DataFrame, filename: str) None [source]
Write PEtab simulation table
- Parameters
df – PEtab simulation table
filename – Destination file name
Modules
This file contains constant definitions. |
|
Functions performing various calculations. |
|
PEtab problems consisting of multiple models |
|
Functions operating on the PEtab condition table |
|
PEtab core functions (or functions that don't fit anywhere else) |
|
Integrity checks and tests for specific features used |
|
Functions operating on the PEtab measurement table |
|
Functions for working with the PEtab observables table |
|
Functions related to mapping parameter from model to parameter estimation problem |
|
Functions operating on the PEtab parameter table |
|
PEtab Problem class |
|
Functions related to parameter sampling |
|
Functions for interacting with SBML models |
|
PEtab simulator base class and related functions. |
|
Visualize |
|
Code regarding the PEtab YAML config files |