fit.objects¶

Definition of Objects used in FitProblems and optimization.

MappingKind ¶

Bases: StrEnum

How the data of the fit mappings of a FitMappingCollection is used.

training (default) : the mappings are fitted, i.e., their residuals enter the cost of the optimization.

validation : the mappings are not fitted. They are simulated and evaluated with the training data when a fit is reported, which shows how the fitted parameters describe data they were not fitted on.

outlier : the mappings are not fitted, because the data is not usable, e.g. a curve which contradicts the rest of the data. They are simulated and evaluated like the validation data, so a report says how far the data a fit dropped is from the model and the decision to drop it can be checked.

excluded : the mappings are not used at all, and for another reason than an outlier: the model does not describe them, e.g. a study arm with a coadministration the model has no interaction for. The data is fine, the model is not the one for it, so it is not an outlier: an outlier is a decision about the data and an exclusion is a decision about the model. Excluded mappings are not resolved, so they have no metrics.

The kind is set on the FitMappingCollection, i.e., when the data of a fit is selected, not on the fit mappings of a simulation experiment: a mapping describes a curve, the kind describes what a fit does with it, and the same curve is training data of one fit and validation data of another.

FitMappingCollection ¶

FitMappingCollection(
    experiment,
    mappings=None,
    sid=None,
    weights=None,
    use_mapping_weights=False,
    fit_parameters=None,
    exclude=False,
    kind=TRAINING,
)

The fit mappings of a simulation experiment which a fit uses together.

A collection selects mappings of one SimulationExperiment, says what a fit does with them (MappingKind) and how they are weighted. It is the unit a fit is defined in and the unit a PEtab problem is built from: the mappings of a collection which share a simulation are one experiment of PEtab, see sbmlsim.fit.petab_v2.

Initialize simulation experiment used in a fitting.

The weights must be updated according to the mappings.

Parameters:

Name	Type	Description	Default
`experiment`	`type[SimulationExperiment]`	simulation experiment class the mappings belong to.	required
`mappings`	`list[str] \| None`	mappings to use from the experiment. `None` or an empty list uses all mappings of the experiment, they are resolved in `OptimizationProblem.initialize`, see `resolve_mappings`.	`None`
`sid`	`str \| None`	id of the collection, which names the experiments of a PEtab problem. The name of the simulation experiment class and the kind of its mappings by default, i.e. `Beermann1976_training`.	`None`
`weights`	`float \| list[float] \| None`	weight of the mappings, the larger the value the larger the weight. A single value is used for all mappings.	`None`
`use_mapping_weights`	`bool`	use the weights of the mappings instead of `weights`.	`False`
`fit_parameters`	`dict[str, list[FitParameter]] \| None`	LOCAL parameters only changed in this simulation experiment.	`None`
`exclude`	`bool`	flag to exclude the experiment from the fitting.	`False`
`kind`	`MappingKind`	what a fit does with these mappings, i.e., whether they are fitted, only evaluated or not used at all.	`TRAINING`

Raises:

Type	Description
`ValueError`	for duplicate mappings or unsupported local fit parameters.

weights `property` `writable` ¶

weights

Weights of fit mappings, None if the weight of the mapping is used.

resolve_mappings ¶

resolve_mappings(mapping_keys)

Use all mappings of the experiment if no mappings were selected.

A FitMappingCollection without mappings uses all fit mappings of its simulation experiment. The keys are only known once the experiment is instantiated, so the mappings and their weights are resolved in the initialization of the OptimizationProblem.

Parameters:

Name	Type	Description	Default
`mapping_keys`	`Iterable[str]`	keys of all fit mappings of the simulation experiment.	required

reduce `staticmethod` ¶

reduce(mapping_collections)

Combine the fit mappings of the FitMappingCollections of the same experiment.

Experiments are combined per simulation experiment and MappingKind, so that the training and the validation data stay apart. The mappings and their weights are concatenated, the inputs are not modified.

Raises:

Type	Description
`ValueError`	if experiments of the same class cannot be combined, i.e., they use different weighting or repeat a mapping.

MappingMetaData `dataclass` ¶

MappingMetaData()

Metadata for mapping.

Applications derive their metadata from this class to describe the curve, e.g., the tissue, the route, the dosing or the health of the group of a study. The metadata describes the data, not what a fit does with it: how a curve is used is the MappingKind of the FitMappingCollection which selects it.

The fields are keyword only, so that a subclass can add fields without a default.

to_dict ¶

to_dict()

Convert to dictionary for serialization.

FitMapping ¶

FitMapping(
    experiment,
    reference,
    observable,
    weight=None,
    metadata=None,
)

Mapping of reference data to observable data.

In the optimization the difference between the reference data (ground truth) and the observable (predicted data) is minimized. The weight allows to weight the FitMapping.

Initialize FitMapping.

To use the weight in the fit mapping the use_mapping_weights flag must be set on the FitMappingCollection.

Parameters:

Name	Type	Description	Default
`experiment`	`Any`	simulation experiment of the mapping.	required
`reference`	`FitData`	reference data (mostly experimental data).	required
`observable`	`FitData`	observable in the model.	required
`weight`	`float \| None`	weight of the fit mapping, the count of the reference data is used if no weight is given.	`None`
`metadata`	`MappingMetaData \| None`	metadata of the mapping.	`None`

weight `property` ¶

weight

Return the defined weight or the count of the reference data.

Raises:

Type	Description
`ValueError`	if neither a weight nor a count is available.

FitParameter ¶

FitParameter(
    pid,
    start_value=None,
    lower_bound=-inf,
    upper_bound=inf,
    unit=None,
    target=None,
    mappings=None,
)

Parameter adjusted in a parameter optimization.

The bounds define the box in which the parameter can be varied. The start value is the initial value in the parameter fitting for algorithms which use it.

Initialize FitParameter.

Parameters:

Name	Type	Description	Default
`pid`	`str`	id of the estimated parameter. It is the name in the parameter vector, in the parameter sets and in the profiles; it is the id of the entity of the model unless `target` says otherwise.	required
`start_value`	`float \| None`	initial value for the fitting.	`None`
`lower_bound`	`float`	lower bound for the fitting.	`-inf`
`upper_bound`	`float`	upper bound for the fitting.	`inf`
`unit`	`str \| None`	unit of the parameter, the model unit is assumed if not given.	`None`
`target`	`str \| None`	entity of the model the value is written to. `None` means the parameter is the entity, i.e. `target_id` is `pid`. Several parameters write one target when each of them selects a part of the data, see `mappings`.	`None`
`mappings`	`Any`	`MappingFilter` or an iterable of them which select the fit mappings the parameter applies to; a mapping passes when it passes every filter. `None` applies the parameter everywhere. A selector is a callable and is not serialized: it must be a module level function, because the workers of a parallel fit unpickle the parameters.	`None`

Raises:

Type	Description
`ValueError`	if the bounds or the start value are inconsistent.

target_id `property` ¶

target_id

Get the entity of the model the value is written to.

is_versioned `property` ¶

is_versioned

Check whether the parameter applies to a part of the data only.

to_json ¶

to_json(path=None)

Serialize to JSON.

Serializes to file if path is provided, otherwise returns JSON string.

to_dict ¶

to_dict()

Convert to dictionary for serialization.

from_json `staticmethod` ¶

from_json(json_info)

Load from JSON.

parameters_to_df `staticmethod` ¶

parameters_to_df(parameters)

DataFrame of parameters.

FitData ¶

FitData(
    experiment,
    xid,
    yid,
    xid_sd=None,
    xid_se=None,
    yid_sd=None,
    yid_se=None,
    count=None,
    dataset=None,
    task=None,
    function=None,
)

Data used in a fit.

This is either data from a dataset, a simulation results from a task or functional data, i.e. calculated from other data.

Initialize FitData.

Parameters:

Name	Type	Description	Default
`experiment`	`Any`	simulation experiment the data belongs to.	required
`xid`	`str`	index of the x data.	required
`yid`	`str`	index of the y data.	required
`xid_sd`	`str \| None`	index of the standard deviation of the x data.	`None`
`xid_se`	`str \| None`	index of the standard error of the x data.	`None`
`yid_sd`	`str \| None`	index of the standard deviation of the y data.	`None`
`yid_se`	`str \| None`	index of the standard error of the y data.	`None`
`count`	`int \| str \| None`	number of subjects, either an integer or a column of the dataset.	`None`
`dataset`	`str \| None`	id of the dataset the data comes from.	`None`
`task`	`str \| None`	id of the task the data comes from.	`None`
`function`	`str \| None`	id of the function the data is calculated with.	`None`

Raises:

Type	Description
`ValueError`	if `count` is set without a dataset or has a wrong type.

dtype `property` ¶

dtype

Get data type.

Raises:

Type	Description
`ValueError`	if the data is neither from a task, dataset nor function.

is_task ¶

is_task()

Check if FitData comes from a task (simulation).

is_dataset ¶

is_dataset()

Check if FitData comes from a dataset.

is_function ¶

is_function()

Check if FitData comes from a function.

get_data ¶

get_data()

Return actual data.

Numerical values are resolved using the executed simulation experiment.

FitDataInitialized `dataclass` ¶

FitDataInitialized(
    x=None,
    y=None,
    x_sd=None,
    x_se=None,
    y_sd=None,
    y_se=None,
)

Initialized FitData with actual data content.

The data is created from the simulation experiment, the values are quantities with the units of the data.

fit.objects¶

MappingKind ¶

FitMappingCollection ¶

weights property writable ¶

resolve_mappings ¶

reduce staticmethod ¶

MappingMetaData dataclass ¶

to_dict ¶

FitMapping ¶

weight property ¶

FitParameter ¶

target_id property ¶

is_versioned property ¶

to_json ¶

to_dict ¶

from_json staticmethod ¶

parameters_to_df staticmethod ¶

FitData ¶

dtype property ¶

is_task ¶

is_dataset ¶

is_function ¶

get_data ¶

FitDataInitialized dataclass ¶

weights `property` `writable` ¶

reduce `staticmethod` ¶

MappingMetaData `dataclass` ¶

weight `property` ¶

target_id `property` ¶

is_versioned `property` ¶

from_json `staticmethod` ¶

parameters_to_df `staticmethod` ¶

dtype `property` ¶

FitDataInitialized `dataclass` ¶