fit.options¶

Bases: StrEnum

Strategy for fitting a set of fit experiments.

ALL : fit all experiments together, i.e., one parameter set describes every experiment.

SINGLE : fit every experiment on its own, i.e., one parameter set per experiment. These are the individual parameters, see sbmlsim.fit.metrics.

Bases: Enum

Type of optimization.

least square : Least square is a local optimization method and works well in combination with many start values, i.e., many repeats of the optimization problem. See https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.least_squares.html for more information.

differential evolution : Differential evolution is a global optimization method and normally is run with a limited number of repeats. See https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.differential_evolution.html#scipy.optimize.differential_evolution for more information.

Bases: Enum

Handling of the residuals.

How are the residuals calculated? Are the absolute residuals used, or are the residuals normalized based on the data points, i.e., relative residuals.

absolute (default) : uses the absolute data values for calculation of the residuals::

r(i,k) = y(i,k) - f(xi,k)

normalized : normalizing residuals of curve with 1/mean of the timecourse::

r(i,k) = (y(i,k) - f(xi,k))/mean(y(k))

This allows to use time courses with very different absolute values in a single optimization problem.

absolute_to_baseline (experimental) : uses the absolute changes to baseline with baseline being the first data point. This requires appropriate pre-simulations for the model to reach a baseline. Data and fits have to be checked carefully. Residuals are calculated as::

r(i,k) = (y(i,k) - ybase(k)) - (f(xi,k) - fbase(k))

normalized changes baseline (experimental): Uses the normalized changes to baseline with baseline being the first data point. This requires appropriate pre-simulations for the model to reach a baseline. Data and fits have to be checked carefully. The residuals are calculated as::

r(i,k) = (y(i,k) - ybase(k)) - (f(xi,k) - fbase(k))/mean(y(k))

Bases: Enum

Determines the loss function.

minimize F(x) = 0.5 * sum(rho(residuals_weighted(x)**2)

The following loss functions are supported are allowed:

‘linear’ (default) : rho(z) = z. Gives a standard least-squares problem.

‘soft_l1’ : rho(z) = 2 * ((1 + z)**0.5 - 1). The smooth approximation of l1 (absolute value) loss. Usually a good choice for robust least squares.

‘cauchy’ : rho(z) = ln(1 + z). Severely weakens outliers influence, but may cause difficulties in optimization process.

‘arctan’ : rho(z) = arctan(z). Limits a maximum loss on a single residual, has properties similar to ‘cauchy’.

Bases: Enum

Weighting w_{k} of the curves k.

Users can provide set of weightings for the individual curves. By default no weightings are applied, i.e. all curves are weighted equally if no weighting option is provided::

w_{k} = 1.0

mapping : curves k are weighted with the provided user weights in the fit mappings, e.g., counts::

w_{k} = wu_{k}

points : weighting with the number of data points. Often time courses contain different number of data points. The residuals should contribute equally per data point::

w_{k} = 1.0/count{k}

The various options can be combined, e.g. mapping and points results in::

w_{k} = wu_{k}/count{k}/mean{y(k)}

Bases: Enum

Space the optimizer searches the parameters in.

A parameter of a model is a positive quantity which often spans orders of magnitude, e.g. a rate constant, and an optimizer which searches it on the linear scale spends its steps on the largest of them. Searching the logarithm makes the steps relative, which is what such a parameter needs.

The scale is a property of the optimization and not of the model or of the data: PEtab v2 removed the parameterScale of its parameter table for that reason, so it is part of the FitSettings here and is stored with them.

The bounds and the start value of a FitParameter are always on the linear scale, i.e. in the units of the model, and so are the fitted parameters a fit reports; only the search happens in the scaled space.

is_log

to_scale(x)

from_scale(x)

Bases: Enum

Weighting w_{i,k} of the data points i within a single fit mapping k.

This decides how the data points within a single fit mapping are weighted.

no weighting (default) : all data points are weighted equally::

w_{i,k} = 1.0

error_weighting: data points are weighted as ~1/error

# FIXME: update documentation, These must probably be normalized also. if yerr{i,k}: w_{i,k} = 1.0/yerr{i,k} else: w_{i,k} = 1.0/yerr{i,k}

Bases: StrEnum

The state a data point at the time of a change is compared with.

At the time of a Change a simulation has two states, the one before the change and the one after it, which the output of a run has both, in two rows of that time; PEtab v2 compares a measurement at that time with the state after it. A measurement at that time is mostly taken before: cumulative urine data which ends at a collection reset, i.e. a change which empties the urine, is the amount collected until then, not 0, and a sample at the time of a dose is a pre-dose sample.

With before a time is at the time of a change if they differ by at most the resolution of the time of the simulation, on either side of the change, see sbmlsim.simulator.plan.time_tolerance. after takes the time of a data point as it is, as PEtab does: a time a little before a change, e.g. 23.9999999999 for a reset at 24, is before the change and is compared with the state before it. A change at the start of the simulation is the initial condition of the experiment and no change of its output: data at the start sees the state after the changes at the start, whatever the setting.

before (default) : a data point at the time of a change after the start is compared with the state before the change, also at the end of the simulation, except the first point of a curve, i.e. the data point or points with the smallest time of a fit mapping (replicates included) which has data at a later time, which is compared with the state after the change: it is the start of a collection, e.g. a cumulative amount which starts at 0 at a reset after the start. A curve of a single time is no start of a collection, e.g. a total amount at the end of a collection or a pre-dose trough, and is compared with the state before the change. The observables of a simulation, e.g. the parameters of a PK observable, are computed on its timecourse as a run has it.

after : a data point at the time of a change is compared with the state after it, the semantics of PEtab v2, which a PEtab problem without the sbmlsim extension has.

Settings of a parameter fit.

The settings decide how the residuals of an optimization problem are calculated, so the same settings are needed to run a fit and to report it afterwards. They are stored with the result of a fit and read back by the report, see sbmlsim.fit.report.FitReport.

Attributes:

to_dict()

from_dict(d)