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.

NoiseDistribution ¶

Bases: StrEnum

Distribution of the noise of a measurement.

These are the distributions of PEtab v2. The simulation is the median of the distribution and the noise formula gives its scale: the standard deviation of normal, the standard deviation of the logarithm of log-normal and the scale b of laplace and, on the logarithm, of log-laplace.

is_log `property` ¶

is_log

Check whether the noise acts on the logarithm of the measurement.

PriorDistribution ¶

Bases: StrEnum

Distribution of the prior of a parameter.

These are the priors of PEtab v2, with the parameters of PEtab, e.g. the mean and the standard deviation of normal and the bounds of uniform.

Prior `dataclass` ¶

Prior(distribution, parameters)

The prior of a parameter.

The prior is a distribution of PEtab v2 over the value of the parameter in its unit, truncated at the bounds of the parameter, i.e. normalized over them. A parameter without a prior has the uniform prior over its bounds.

Attributes:

Name	Type	Description
`distribution`	`PriorDistribution`	the distribution.
`parameters`	`tuple[float, ...]`	the parameters of the distribution, see `PriorDistribution`.

log_density ¶

log_density(value, lower, upper)

Get the log density of the prior at a value.

The distributions are the ones of petab, which the PEtab test suite is calculated with.

Parameters:

Name	Type	Description	Default
`value`	`float`	the value of the parameter.	required
`lower`	`float`	the lower bound of the parameter.	required
`upper`	`float`	the upper bound of the parameter.	required

Returns:

Type	Description
`float`	The log density of the prior truncated at the bounds, `-inf`
`float`	outside of them.

Raises:

Type	Description
`ValueError`	if the parameters do not fit the distribution.

to_dict ¶

to_dict()

Convert to a dictionary for serialization.

NoiseParameter `dataclass` ¶

NoiseParameter(
    pid,
    value,
    estimate=False,
    lower_bound=None,
    upper_bound=None,
)

A parameter of a noise formula which is not an entity of a model.

Attributes:

Name	Type	Description
`pid`	`str`	id of the parameter.
`value`	`float`	nominal value, which the log-likelihood uses unless the parameter set it is evaluated at has a value for `pid`.
`estimate`	`bool`	whether the problem the noise model was read from estimates the parameter. `sbmlsim` does not estimate it, the flag and the bounds are kept so that the problem is written as it was read.
`lower_bound`	`float \| None`	lower bound of the estimation, `None` if there is none.
`upper_bound`	`float \| None`	upper bound of the estimation, `None` if there is none.

NoiseModel `dataclass` ¶

NoiseModel(
    formula,
    distribution=NORMAL,
    placeholders=(),
    placeholder_values=(),
    parameters=(),
    observable=None,
)

The noise of the measurements of a fit mapping.

The noise model does not enter the cost of a fit, which is a weighted least squares fit. It is what the log-likelihood of a problem is calculated with, see sbmlsim.fit.petab_v2.likelihood.

Attributes:

Name	Type	Description
`formula`	`str`	the noise formula in the math of PEtab over the selections of roadrunner, e.g. `0.05`, `sd` or `sigma_a + 0.1 * sd`, see `ObservableModel`. Its symbols are the `placeholders`, the `observable` and the `symbols`, i.e. selections of the simulation or `parameters`.
`distribution`	`NoiseDistribution`	distribution of the noise.
`placeholders`	`tuple[str, ...]`	symbols of the formula which have a value per measurement.
`placeholder_values`	`tuple[tuple[float \| str, ...], ...]`	for every measurement the values of the placeholders, in the order of the measurements of the mapping. A value is a number or a formula of the selections.
`parameters`	`tuple[NoiseParameter, ...]`	the parameters of the formula and of the placeholder values with their nominal value, for a symbol which the simulation does not select.
`observable`	`str \| None`	symbol of the formula which stands for the simulation, `None` if the formula has none.

formula_model `cached` `property` ¶

formula_model

Get the noise formula with its placeholders as a formula model.

Raises:

Type	Description
`ValueError`	if the formula or a placeholder value is not valid math.

symbols `property` ¶

symbols

Get the symbols the noise reads besides placeholders and observable.

These are selections of the simulation or parameters, sorted.

select ¶

select(mask)

Get the noise model of a selection of the measurements.

Parameters:

Name	Type	Description	Default
`mask`	`ndarray`	whether a measurement is selected, one entry per measurement.	required

Returns:

Type	Description
`NoiseModel`	The noise model with the placeholder values of the selected
`NoiseModel`	measurements.

ObservableModel `dataclass` ¶

ObservableModel(
    formula,
    placeholders=(),
    placeholder_values=(),
    unit="dimensionless",
)

An observable which is a formula of the selections of a simulation.

The formula is the math of PEtab over the selections of roadrunner, i.e. [S] is the concentration of a species and S its amount, e.g. scale * ([pSTAT] + [ppSTAT]), see sbmlsim.simulator.formula. A placeholder is a symbol which has a value per measurement, e.g. an offset which differs between the measurements of one observable; its value is a number or a formula of the selections, typically a parameter of the model. The fit evaluates the observable at the data, so the values of the placeholders belong to the data points of the reference of the mapping.

Attributes:

Name	Type	Description
`formula`	`str`	the formula of the observable.
`placeholders`	`tuple[str, ...]`	symbols of the formula which have a value per measurement.
`placeholder_values`	`tuple[tuple[float \| str, ...], ...]`	for every measurement the values of the placeholders, in the order of the reference data of the mapping. A value is a number or a formula of the selections.
`unit`	`str`	unit of the value of the formula, the reference data is converted into it.

symbols `property` ¶

symbols

Get the selections the observable reads, sorted.

These are the symbols of the formula which are not placeholders and the symbols of the placeholder values which are formulas.

select ¶

select(mask)

Get the observable of a selection of the measurements.

Parameters:

Name	Type	Description	Default
`mask`	`ndarray`	whether a measurement is selected, one entry per measurement.	required

Returns:

Type	Description
`ObservableModel`	The observable with the placeholder values of the selected
`ObservableModel`	measurements.

evaluate ¶

evaluate(values, size)

Evaluate the observable at the measurements.

Parameters:

Name	Type	Description	Default
`values`	`Mapping[str, ndarray]`	the values of the `symbols` at the measurements, one array of `size` values per symbol.	required
`size`	`int`	the number of measurements.	required

Returns:

Type	Description
`ndarray`	The value of the observable at every measurement.

Raises:

Type	Description
`ValueError`	if the observable has placeholders and not the values of `size` measurements.

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.

to_dict ¶

to_dict()

Serialize the collection definition without runtime attributes.

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,
    noise=None,
    observable_model=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`
`noise`	`NoiseModel \| None`	noise model of the measurements, which the log-likelihood of the problem uses. Without one the noise is normal with the standard deviation of the reference data, see `sbmlsim.fit.petab_v2.likelihood.default_noise_model`.	`None`
`observable_model`	`ObservableModel \| None`	the observable as a formula of the selections of the task of `observable`, evaluated at the reference data. The `y` of `observable` is then the name of the observable and not a selection, and the unit of the observable is the unit of the observable model.	`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,
    scale=None,
    prior=None,
    description=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. It is a unit of pint or has the unit ids of the model of its target, e.g. `per_min` or `mg_per_min/kg`, which the fit resolves with the units of that model, see `OptimizationProblem.parameter_units`. The tables of a fit show the unit as it is given here.	`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`
`scale`	`ParameterScaleType \| str \| None`	space the optimizer searches the parameter in, or its name. `None` is the `parameter_scale` of the `FitSettings`. A parameter which is negative or zero, e.g. a weight of a network, is searched on the linear scale.	`None`
`prior`	`Prior \| Mapping[str, Any] \| None`	the prior of the parameter or its dictionary, see `Prior`. `None` is the uniform prior over the bounds. The objective of a fit does not use it, `log_prior` evaluates it.	`None`
`description`	`str \| None`	description of the parameter for the reports of a fit. It is documentation and does not take part in the equality; `None` has the reports use the name of the entity in the model.	`None`

Raises:

Type	Description
`ValueError`	if the bounds or the start value are inconsistent, if a value is not a number, if the scale is not a scale, or if the target is the prefix of an external target alone.

target_id `property` ¶

target_id

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

is_external `property` ¶

is_external

Check whether the parameter is not an entity of the model.

The target of such a parameter has the prefix EXTERNAL_PREFIX. The fit writes no change for it, the derived changes of the problem read its value.

entity_id `property` ¶

entity_id

Get the target without the prefix of an external target.

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,
    sel=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 \| None`	index of the x data, `None` for data without x, i.e. a value per simulation.	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`
`sel`	`Mapping[str, Any] \| None`	labels of the dimensions of a task, or column values of the rows of a dataset, for every data of the fit data, see `Data`.	`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.

describe_array ¶

describe_array(label, elements, members, values)

Describe an array of elements, e.g. of a network, in one line of text.

The console and the text reports show an array in place of its elements, because a network has hundreds of them.

Parameters:

Name	Type	Description	Default
`label`	`str`	what the array is, e.g. `net1.layer1.weight`.	required
`elements`	`int`	number of elements of the array, estimated or not.	required
`members`	`Sequence[FitParameter]`	the parameters of the fit which are elements of the array. A versioned element has one parameter per version.	required
`values`	`Sequence[float \| None]`	the value of every member, e.g. its start value, `None` for a member without one.	required

Returns:

Type	Description
`str`	The number of estimated elements, the minimum, the maximum and the
`str`	norm of the values of the members and the bounds when the members
`str`	agree on them.

fit.objects¶

MappingKind ¶

NoiseDistribution ¶

is_log property ¶

PriorDistribution ¶

Prior dataclass ¶

log_density ¶

to_dict ¶

NoiseParameter dataclass ¶

NoiseModel dataclass ¶

formula_model cached property ¶

symbols property ¶

select ¶

ObservableModel dataclass ¶

symbols property ¶

select ¶

evaluate ¶

FitMappingCollection ¶

weights property writable ¶

to_dict ¶

resolve_mappings ¶

reduce staticmethod ¶

MappingMetaData dataclass ¶

to_dict ¶

FitMapping ¶

weight property ¶

FitParameter ¶

target_id property ¶

is_external property ¶

entity_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 ¶

describe_array ¶

is_log `property` ¶

Prior `dataclass` ¶

NoiseParameter `dataclass` ¶

NoiseModel `dataclass` ¶

formula_model `cached` `property` ¶

symbols `property` ¶

ObservableModel `dataclass` ¶

symbols `property` ¶

weights `property` `writable` ¶

reduce `staticmethod` ¶

MappingMetaData `dataclass` ¶

weight `property` ¶

target_id `property` ¶

is_external `property` ¶

entity_id `property` ¶

is_versioned `property` ¶

from_json `staticmethod` ¶

parameters_to_df `staticmethod` ¶

dtype `property` ¶

FitDataInitialized `dataclass` ¶