petab.v1.problem

PEtab Problem class

Classes

Problem([sbml_model, sbml_reader, ...])	PEtab parameter estimation problem.
ProblemConfig(*[, filepath, base_path, ...])	The PEtab problem configuration.
SubProblem(*[, sbml_files, ...])	A problems object in the PEtab problem configuration.

class petab.v1.problem.Problem(sbml_model: libsbml.Model = None, sbml_reader: libsbml.SBMLReader = None, sbml_document: libsbml.SBMLDocument = None, model: Model = None, model_id: str = 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, mapping_df: pd.DataFrame = None, extensions_config: dict = None, config: ProblemConfig = None)

Bases: object

PEtab parameter estimation problem.

A PEtab problem as defined by:

• model

• condition table

• measurement table

• parameter table

• observables table

• mapping table

Optionally, it may contain visualization tables.

See also PEtab data format specification 1.0.

Parameters:

• 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

• mapping_df – PEtab mapping 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

add_condition(id_: str, name: str = None, **kwargs)

Add a simulation condition to the problem.

Parameters:

• id – The condition id

• name – The condition name

• kwargs – Parameter, value pairs to add to the condition table.

add_measurement(obs_id: str, sim_cond_id: str, time: float, measurement: float, observable_parameters: Sequence[str | float] = None, noise_parameters: Sequence[str | float] = None, preeq_cond_id: str = None)

Add a measurement to the problem.

Parameters:

• obs_id – The observable ID

• sim_cond_id – The simulation condition ID

• time – The measurement time

• measurement – The measurement value

• observable_parameters – The observable parameters

• noise_parameters – The noise parameters

• preeq_cond_id – The pre-equilibration condition ID

add_observable(id_: str, formula: str | float | int, noise_formula: str | float | int = None, noise_distribution: str = None, transform: str = None, name: str = None, **kwargs)

Add an observable to the problem.

Parameters:

• id – The observable id

• formula – The observable formula

• noise_formula – The noise formula

• noise_distribution – The noise distribution

• transform – The observable transformation

• name – The observable name

• kwargs – additional columns/values to add to the observable table

add_parameter(id_: str, estimate: bool | str | int = True, nominal_value: Number | None = None, scale: str = None, lb: Number = None, ub: Number = None, init_prior_type: str = None, init_prior_pars: str | Sequence = None, obj_prior_type: str = None, obj_prior_pars: str | Sequence = None, **kwargs)

Add a parameter to the problem.

Parameters:

• id – The parameter id

• estimate – Whether the parameter is estimated

• nominal_value – The nominal value of the parameter

• scale – The parameter scale

• lb – The lower bound of the parameter

• ub – The upper bound of the parameter

• init_prior_type – The type of the initialization prior distribution

• init_prior_pars – The parameters of the initialization prior distribution

• obj_prior_type – The type of the objective prior distribution

• obj_prior_pars – The parameters of the objective prior distribution

• kwargs – additional columns/values to add to the parameter table

create_parameter_df(**kwargs)

Create a new PEtab parameter table

See create_parameter_df().

static from_combine(filename: Path | str) → Problem

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: str | Path = None, condition_file: str | Path | Iterable[str | Path] = None, measurement_file: str | Path | Iterable[str | Path] = None, parameter_file: str | Path | Iterable[str | Path] = None, visualization_files: str | Path | Iterable[str | Path] = None, observable_files: str | Path | Iterable[str | Path] = None, model_id: str = None, extensions_config: dict = None) → Problem

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

• model_id – PEtab ID of the model

• extensions_config – Information on the extensions used

static from_yaml(yaml_config: dict | Path | str, base_path: str | Path = None) → Problem

Factory method to load model and tables as specified by YAML file.

Parameters:

• yaml_config – PEtab configuration as dictionary or YAML file name

• base_path – Base directory or URL to resolve relative paths

get_lb(free: bool = True, fixed: bool = True, scaled: bool = False)

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_model_parameters() → list[str] | dict[str, float]

See petab.sbml.get_model_parameters()

get_observable_ids() → list[str]

Returns dictionary of observable ids.

get_optimization_parameter_scales() → dict[str, str]

Return list of optimization parameter scaling strings.

See petab.parameters.get_optimization_parameters().

get_optimization_parameters() → list[str]

Return list of optimization parameter IDs.

See petab.parameters.get_optimization_parameters().

get_optimization_to_simulation_parameter_mapping(**kwargs)

See petab.parameter_mapping.get_optimization_to_simulation_parameter_mapping(), to which all keyword arguments are forwarded.

get_simulation_conditions_from_measurement_df()

See petab.get_simulation_conditions

get_ub(free: bool = True, fixed: bool = True, scaled: bool = False)

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)

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)

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.

property lb: list

Parameter table lower bounds.

property lb_scaled: list

Parameter table lower bounds with applied parameter scaling

property n_estimated: int

The number of estimated parameters.

property n_measurements: int

Number of measurements.

property n_priors: int

Number of priors.

sample_parameter_startpoints(n_starts: int = 100, **kwargs)

Create 2D array with starting points for optimization

See petab.sample_parameter_startpoints().

sample_parameter_startpoints_dict(n_starts: int = 100) → list[dict[str, float]]

Create dictionaries with starting points for optimization

See also petab.sample_parameter_startpoints().

Returns:

A list of dictionaries with parameter IDs mapping to samples parameter values.

scale_parameters(x_dict: dict[str, float]) → dict[str, float]

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: None | str | Path = None, condition_file: None | str | Path = None, measurement_file: None | str | Path = None, parameter_file: None | str | Path = None, visualization_file: None | str | Path = None, observable_file: None | str | Path = None, yaml_file: None | str | Path = None, prefix_path: None | str | Path = None, relative_paths: bool = True, model_file: None | str | Path = None, mapping_file: None | str | Path = None) → None

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 (deprecated)

• 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

• mapping_file – Mapping 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: str | Path) → str

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.

property ub: list

Parameter table upper bounds

property ub_scaled: list

Parameter table upper bounds with applied parameter scaling

unscale_parameters(x_dict: dict[str, float]) → dict[str, float]

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_fixed_ids: list[str]

Parameter table parameter IDs, for fixed parameters.

property x_fixed_indices: list[int]

Parameter table non-estimated parameter indices.

property x_free_ids: list[str]

Parameter table parameter IDs, for free parameters.

property x_free_indices: list[int]

Parameter table estimated parameter indices.

property x_ids: list[str]

Parameter table parameter IDs

property x_nominal: list

Parameter table nominal values

property x_nominal_fixed: list

Parameter table nominal values, for fixed parameters.

property x_nominal_fixed_scaled: list

Parameter table nominal values with applied parameter scaling, for fixed parameters.

property x_nominal_free: list

Parameter table nominal values, for free parameters.

property x_nominal_free_scaled: list

Parameter table nominal values with applied parameter scaling, for free parameters.

property x_nominal_scaled: list

Parameter table nominal values with applied parameter scaling