petab_select.model

The Model class.

Functions

`default_compare`(model0, model1, criterion[, ...])	Compare two calibrated models by their criterion values.
`models_from_yaml_list`(model_list_yaml[, ...])	Generate a model from a PEtab Select list of model YAML file.
`models_to_yaml_list`(models, output_yaml[, ...])

Classes

Model(petab_yaml[, model_subspace_id, ...])

A (possibly uncalibrated) model.

class petab_select.model.Model(petab_yaml, model_subspace_id=None, model_id=None, model_subspace_indices=None, predecessor_model_hash=None, parameters=None, estimated_parameters=None, criteria=None, petab_problem=None, model_hash=None)[source]

A (possibly uncalibrated) model.

NB: some of these attribute names correspond to constants defined in the constants.py file, to facilitate loading models from/saving models to disk (see the saved_attributes attribute).

converters_load: Functions to convert attributes from YAML to Model.

converters_save: Functions to convert attributes from Model to YAML.

criteria: The criteria values of the calibrated model (e.g. AIC).

hash_attributes: This attribute is currently not used. Attributes that will be used to calculate the hash of the Model instance. NB: this hash is used during pairwise comparison to determine whether any two Model instances are unique. The model instances are compared by their parameter estimation problems, as opposed to parameter estimation results, which may differ due to e.g. floating-point arithmetic.

model_id: The model ID.

petab_yaml: The path to the PEtab problem YAML file.

parameters: Parameter values that will overwrite the PEtab problem definition, or change parameters to be estimated.

estimated_parameters: Parameter estimates from a model calibration tool, for parameters that are specified as estimated in the PEtab problem or PEtab Select model YAML. These are untransformed values (i.e., not on log scale).

saved_attributes: Attributes that will be saved to disk by the Model.to_yaml() method.

__init__(petab_yaml, model_subspace_id=None, model_id=None, model_subspace_indices=None, predecessor_model_hash=None, parameters=None, estimated_parameters=None, criteria=None, petab_problem=None, model_hash=None)[source]

compute_criterion(criterion, raise_on_failure=True)[source]

Compute a criterion value for the model.

The value will also be stored, which will overwrite any previously stored value for the criterion.

Parameters:

criterion (Criterion) – The ID of the criterion (e.g. petab_select.constants.Criterion.AIC).
raise_on_failure (bool) – Whether to raise a ValueError if the criterion could not be computed. If False, None is returned.

Return type:

float

Returns:

The criterion value.

static from_dict(model_dict, base_path=None, petab_problem=None)[source]

Generate a model from a dictionary of attributes.

Parameters:

model_dict (Dict[str, Any]) – A dictionary of attributes. The keys are attribute names, the values are the corresponding attribute values for the model. Required attributes are the required arguments of the Model.__init__() method.
base_path (Union[str, Path]) – The path that any relative paths in the model are relative to (e.g. the path to the PEtab problem YAML file Model.petab_yaml() may be relative).
petab_problem (Problem) – Optionally provide the PEtab problem, to avoid loading it multiple times. NB: This may cause issues if multiple models write to the same PEtab problem in memory.

Return type:

Model

Returns:

A model instance, initialized with the provided attributes.

static from_yaml(model_yaml)[source]

Generate a model from a PEtab Select model YAML file.

Parameters:: model_yaml (Union[str, Path]) – The path to the PEtab Select model YAML file.
Return type:: Model
Returns:: A model instance, initialized with the provided attributes.

get_criterion(criterion, compute=True, raise_on_failure=True)[source]

Get a criterion value for the model.

Parameters:

criterion (Criterion) – The ID of the criterion (e.g. petab_select.constants.Criterion.AIC).
compute (bool) – Whether to try to compute the criterion value based on other model attributes. For example, if the 'AIC' criterion is requested, this can be computed from a predetermined model likelihood and its number of estimated parameters.
raise_on_failure (bool) – Whether to raise a ValueError if the criterion could not be computed. If False, None is returned.

Return type:

Optional[float]

Returns:

The criterion value, or None if it is not available. TODO check for previous use of this method before .get was used

get_hash()[source]

Get the model hash.

Currently designed to only use pre-calibration information, such that if a model is calibrated twice and the two calibrated models differ in their parameter estimates, then they will still have the same hash.

This is not implemented as __hash__ because Python automatically truncates values in a system-dependent manner, which reduces interoperability ( https://docs.python.org/3/reference/datamodel.html#object.__hash__ ).

Return type:: int
Returns:: The hash.

get_mle()[source]

Get the maximum likelihood estimate of the model.

Return type:: Dict[str, float]

get_parameter_values(parameter_ids=None)[source]

Get parameter values.

Includes ESTIMATE for parameters that should be estimated.

The ordering is by parameter_ids if supplied, else self.petab_parameters.

Parameters:: parameter_ids (Optional[List[str]]) – The IDs of parameters that values will be returned for. Order is maintained.
Return type:: List[Union[float, int, Literal['estimate']]]
Returns:: The values of parameters.

has_criterion(criterion)[source]

Check whether the model provides a value for a criterion.

Parameters:: criterion (Criterion) – The criterion (e.g. petab_select.constants.Criterion.AIC).
Return type:: bool

property petab_parameter_ids_estimated: List[str]

Get the IDs of all estimated parameters.

Returns:: The parameter IDs.

property petab_parameter_ids_fixed: List[str]

Get the IDs of all fixed parameters.

Returns:: The parameter IDs.

property petab_parameters_singular: Dict[str, float | int | Literal['estimate']]: TODO deprecate and remove?

set_criterion(criterion, value)[source]

Set a criterion value for the model.

Parameters:

criterion (Criterion) – The criterion (e.g. petab_select.constants.Criterion.AIC).
value (float) – The criterion value for the (presumably calibrated) model.

Return type:

None

set_estimated_parameters(estimated_parameters, scaled=False)[source]

Set the estimated parameters.

Parameters:

estimated_parameters (Dict[str, float]) – The estimated parameters.
scaled (bool) – Whether the estimated_parameters values are on the scale defined in the PEtab problem (True), or untransformed (False).

Return type:

None

to_dict(resolve_paths=True, paths_relative_to=None)[source]

Generate a dictionary from the attributes of a Model instance.

Parameters:

resolve_paths (bool) – Whether to resolve relative paths into absolute paths.
paths_relative_to (Union[str, Path]) – If not None, paths will be converted to be relative to this path. Takes priority over resolve_paths.

Return type:

Dict[str, Any]

Returns:

A dictionary of attributes. The keys are attribute names, the values are the corresponding attribute values for the model. Required attributes are the required arguments of the Model.__init__() method.

to_petab(output_path=None, set_estimated_parameters=None)[source]

Generate a PEtab problem.

Parameters:

output_path (Union[str, Path]) – The directory where PEtab files will be written to disk. If not specified, the PEtab files will not be written to disk.
set_estimated_parameters (Optional[bool]) – Whether to set the nominal value of estimated parameters to their estimates. If parameter estimates are available, this will default to True.

Return type:

Dict[str, Union[Problem, str, Path]]

Returns:

A 2-tuple. The first value is a PEtab problem that can be used with a PEtab-compatible tool for calibration of this model. If output_path is not None, the second value is the path to a PEtab YAML file that can be used to load the PEtab problem (the first value) into any PEtab-compatible tool.

to_yaml(petab_yaml, *args, **kwargs)[source]

Generate a PEtab Select model YAML file from a Model instance.

Parameters:

petab_yaml (Union[str, Path]) – The location where the PEtab Select model YAML file will be saved.
args – Additional arguments are passed to self.to_dict.
kwargs – Additional arguments are passed to self.to_dict.

Return type:

None

petab_select.model.default_compare(model0, model1, criterion, criterion_threshold=0)[source]

Compare two calibrated models by their criterion values.

It is assumed that the model model0 provides a value for the criterion criterion, or is the VIRTUAL_INITIAL_MODEL.

Parameters:

model0 (Model) – The original model.
model1 (Model) – The new model.
criterion (Criterion) – The criterion by which models will be compared.
criterion_threshold (float) – The value by which the new model must improve on the original model. Should be non-negative.

Return type:

bool

Returns:

True` if ``model1 has a better criterion value than model0, else False.

petab_select.model.models_from_yaml_list(model_list_yaml, petab_problem=None, allow_single_model=True)[source]

Generate a model from a PEtab Select list of model YAML file.

Parameters:

model_list_yaml (Union[str, Path]) – The path to the PEtab Select list of model YAML file.
petab_problem (Problem) – See Model.from_dict().
allow_single_model (bool) – Given a YAML file that contains a single model directly (not in a 1-element list), if True then the single model will be read in, else a ValueError will be raised.

Return type:

List[Model]

Returns:

A list of model instances, initialized with the provided attributes.