fit.optimization¶

Optimization of parameter fitting problem.

ObservationKind ¶

Bases: StrEnum

What the observable of a fit mapping is, see OptimizationProblem.initialize.

The kind is decided from the dimensions of the observable after its sel: a timecourse over the time (or another selection), a value per simulation of a plain simulation or of a scan with every dimension selected, or values over the one dimension of a scan which is left, which are matched to the reference data by the values of the dimension.

GroupResult `dataclass` ¶

GroupResult(
    time,
    outputs,
    changes=(lambda: empty(0))(),
    tolerance=0.0,
)

The simulation of a group of fit mappings which keeps its output.

The output has the states before and after a change after the start at its time, see sbmlsim.simulator.executor, also at a change between the output times of explicit times, which the plan of a group with a timecourse gets (OptimizationProblem._compile_plans).

Attributes:

Name	Type	Description
`time`	`ndarray`	the time points of every simulated point of the group, `(n_points, n_rows)`, padded with `NaN`.
`outputs`	`dict[str, ndarray]`	the observables and selections the mappings of the group read, a timecourse `(n_points, n_rows)`, a value per simulation `(n_points,)`, see `sbmlsim.simulator.worker.observe`.
`changes`	`ndarray`	the times of the changes after the start of the first point in the time of the output, see `_interpolate_after_jumps`.
`tolerance`	`float`	the resolution of the time of the simulation, time points of the output closer than it are a jump, see `_interpolate_after_jumps`.

DataTimesResult `dataclass` ¶

DataTimesResult(output)

The simulation of a group of fit mappings which outputs the times of its data.

Attributes:

Name	Type	Description
`output`	`TimecourseResult`	a row per output time of the data and per time of a change within them, two rows at a change after the start: the state before the change and the state after it; the data takes one of them, see `OptimizationProblem._compile_plans`.

MappingEvaluation `dataclass` ¶

MappingEvaluation(prediction, selections)

The simulation of a fit mapping at its reference data.

Attributes:

Name	Type	Description
`prediction`	`ndarray`	the observable at every data point.
`selections`	`dict[str, ndarray]`	the selections the noise model of the mapping reads, at every data point, see `OptimizationProblem.noise_selections`.

FitTimeout ¶

Bases: Exception

A single optimization ran longer than its budget.

The optimizers of scipy cannot be interrupted, so the objective raises this once the budget is spent, which ends the optimization. The runs which finished are kept, see OptimizationProblem.optimize.

RuntimeErrorOptimizeResult ¶

RuntimeErrorOptimizeResult(
    x=None,
    x0=None,
    cost=inf,
    message="RuntimeError in ODE integration.",
    duration=-1.0,
)

Bases: OptimizeResult

Result of an optimization which did not finish.

An optimization fails with an error of the integrator, with a timeout or with any other error of the objective. This is a scipy.optimize.OptimizeResult, i.e., a dictionary with attribute access, so that a failed run is stored, serialized and reported like a successful one and a fit keeps the runs which worked.

Initialize the result of an optimization which did not finish.

Parameters:

Name	Type	Description	Default
`x`	`ndarray \| None`	parameters the optimization reached.	`None`
`x0`	`ndarray \| None`	parameters it started from.	`None`
`cost`	`float`	cost of `x`.	`inf`
`message`	`str`	what went wrong.	`'RuntimeError in ODE integration.'`
`duration`	`float`	seconds the optimization ran.	`-1.0`

OptimizationProblem ¶

OptimizationProblem(
    opid,
    mapping_collections,
    fit_parameters,
    base_path=None,
    data_path=None,
    hybridizations=None,
)

Bases: ObjectJSONEncoder

Parameter optimization problem.

Optimization problem.

The problem must be pickable for parallelization ! So initialize must be run to create the non-pickable instances.

Parameters:

Name	Type	Description	Default
`opid`	`str`	id for optimization problem.	required
`mapping_collections`	`list[FitMappingCollection]`	the fit mappings of the problem.	required
`fit_parameters`	`list[FitParameter]`	the parameters of the fit.	required
`base_path`	`Path \| None`	directory the models of the experiments are relative to.	`None`
`data_path`	`Path \| Sequence[Path] \| None`	directory or directories of the data of the experiments.	`None`
`hybridizations`	`Sequence[DerivedChanges] \| None`	the derived changes of the problem, i.e. changes of a simulation which are calculated from the parameters of the fit, see `sbmlsim.fit.derived`. The hybridizations of the neural networks of a hybrid problem are what implements them. They are part of the definition and are pickled with it.	`None`

Raises:

Type	Description
`ValueError`	if the problem has no parameters or two parameters of one id.
`TypeError`	if a hybridization does not provide the derived changes.

x0 `property` `writable` ¶

x0

Current start values of the parameter definitions.

training_indices `property` ¶

training_indices

Indices of the fit mappings which are fitted.

validation_indices `property` ¶

validation_indices

Indices of the fit mappings which are only evaluated.

outlier_indices `property` ¶

outlier_indices

Indices of the fit mappings whose data a fit dropped as unusable.

is_initialized `property` ¶

is_initialized

Check if the problem was initialized, i.e., the data is resolved.

settings_initialized `property` ¶

settings_initialized

Settings of the problem, set in initialize.

Raises:

Type	Description
`ValueError`	if the problem was not initialized.

residual `property` ¶

residual

Handling of the residuals, see FitSettings.

loss_function `property` ¶

loss_function

Loss function of the fit, see FitSettings.

weighting_curves `property` ¶

weighting_curves

Weighting of the curves, see FitSettings.

weighting_points `property` ¶

weighting_points

Weighting of the data points, see FitSettings.

parameter_scale `property` ¶

parameter_scale

Get the space the optimizer searches the parameters in.

scales_initialized `property` ¶

scales_initialized

Get the space the optimizer searches every parameter in.

The scale of a parameter is its FitParameter.scale and the parameter_scale of the settings for a parameter without one.

Raises:

Type	Description
`ValueError`	if the problem was not initialized.

parameter_units `property` ¶

parameter_units

Get the unit of every parameter in the units of pint, by parameter id.

A unit id of the model of the target of a parameter is replaced by its expression, see ParameterMapping.parameter_units, so the units are the ones of the values of the parameter sets, the Fisher information and the designs of sbmlsim.simulation.sampling, which have no model. None is the unit of the model.

Raises:

Type	Description
`ValueError`	if the problem was not initialized.

runner_initialized `property` ¶

runner_initialized

Runner of the problem, created in initialize.

parameter_mapping_initialized `property` ¶

parameter_mapping_initialized

Binding of the parameters to the simulations, created in initialize.

Raises:

Type	Description
`ValueError`	if the problem was not initialized.

files ¶

files()

Get the files a fit of the problem reads, the models and the data.

The models are the SBML files of the experiments, the data are the files below data_path without python code and caches (data_files). An uninitialized problem is initialized first, with the settings of the problem or the default settings.

Returns:

Type	Description
`list[Path]`	The sorted paths of the files.

indices ¶

indices(kind=None)

Get the indices of the fit mappings of a kind.

Parameters:

Name	Type	Description	Default
`kind`	`MappingKind \| None`	kind of the mappings, all mappings if `None`.	`None`

Returns:

Type	Description
`list[int]`	Indices into the resolved data of the mappings.

mapping_counts ¶

mapping_counts()

Get the number of resolved fit mappings per kind.

times_before_changes ¶

times_before_changes(k)

Get the times of the data of a mapping compared before a change.

A data point of a timecourse over the time whose time is the time of a change after the start of its simulation, up to the resolution of the time (sbmlsim.simulator.plan.time_tolerance), is compared with the state before the change, except the first point of the curve, see FitSettings.data_at_change.

Parameters:

Name	Type	Description	Default
`k`	`int`	index of the fit mapping.	required

Returns:

Type	Description
`ndarray`	The times of the reference data which are compared with the state
`ndarray`	before a change, in the time of the data; empty for a mapping
`ndarray`	which is no timecourse over the time and with
`ndarray`	`DataAtChangeType.AFTER`.

Raises:

Type	Description
`ValueError`	if the problem is not initialized.

to_dict ¶

to_dict()

Convert to dictionary.

to_json ¶

to_json(path=None)

Store OptimizationResult as json.

Uses the to_dict method.

report ¶

report(path=None, print_output=True)

Print and write report.

Can only be called after initialization.

initialize ¶

initialize(settings, force=False)

Initialize the optimization problem for the given settings.

Resolves the data of the fit mappings, converts it to the units of the model, calculates the weights and attaches a simulator. The problem is only initialized once for a given set of settings. New runtime state is committed after initialization succeeds. Reports copy the definition and initialize their own runtime, preserving the original fit session.

Every fit mapping is one of three kinds, see ObservationKind, decided from the dimensions of its observable after its sel (observation_kinds, observation_dims): a timecourse, whose reference x are times; a value per simulation, whose reference has no x (x_references is NaN) and every row of which compares with the one simulated value; or values over one dimension of a scan, whose reference x are values of the target of the dimension, which the values of the dimension must cover. The groups, the plans of the points of a scan and the observables are built here, also in every worker of a parallel fit, which initializes the pickled definition.

Parameters:

Name	Type	Description	Default
`settings`	`FitSettings`	settings of the fit, they decide how the residuals and the weights are calculated.	required
`force`	`bool`	initialize again even if the settings did not change.	`False`

Raises:

Type	Description
`TypeError`	if the settings are not a `FitSettings`.
`ValueError`	if a mapping is none of the kinds (see `_observation_of`), a baseline residual is asked for a mapping which is no timecourse, or the reference x of a mapping over a dimension are outside of the values of the dimension.

to_scale ¶

to_scale(x)

Transform parameters of the model into the space of the optimizer.

Parameters:

Name	Type	Description	Default
`x`	`Any`	one value per parameter, in the units of the model.	required

Returns:

Type	Description
`ndarray`	The values in the space the optimizer searches, every parameter
`ndarray`	with its own scale.

Raises:

Type	Description
`ValueError`	if `x` does not have one value per parameter.

from_scale ¶

from_scale(x)

Transform parameters of the optimizer into the units of the model.

Parameters:

Name	Type	Description	Default
`x`	`Any`	one value per parameter, in the space the optimizer searches.	required

Returns:

Type	Description
`ndarray`	The values in the units of the model.

Raises:

Type	Description
`ValueError`	if `x` does not have one value per parameter.

parameter_set_model ¶

parameter_set_model(sid='model')

Get the initial values of the fitted parameters in the model.

The set is the reference a fitted set is compared against in a report.

Parameters:

Name	Type	Description	Default
`sid`	`str`	identifier of the set.	`'model'`

Returns:

Type	Description
`ParameterSet`	Parameter set of the values the models start from.

bind_parameter_set ¶

bind_parameter_set(parameter_set)

Convert a set to fit units, resolving declared model unit aliases.

set_simulator ¶

set_simulator(simulator)

Set the simulator on the runner and the experiments.

optimize ¶

optimize(
    size=5,
    algorithm=LEAST_SQUARE,
    sampling=UNIFORM,
    seed=None,
    timeout=None,
    on_run_finished=None,
    **kwargs,
)

Run parameter optimization.

The problem must be initialized, i.e., the settings of the fit are the settings it was initialized with.

Parameters:

Name	Type	Description	Default
`size`	`int`	number of optimizations, every one starts from its own sample.	`5`
`algorithm`	`OptimizationAlgorithmType`	optimization algorithm.	`LEAST_SQUARE`
`sampling`	`SamplingType`	sampling of the start values of the local optimizer.	`UNIFORM`
`seed`	`int \| None`	seed of the sampling.	`None`
`timeout`	`float \| None`	seconds a single optimization may run, no limit if `None`. A run which is out of time keeps the parameters it reached.	`None`
`on_run_finished`	`Callable[[int, OptimizeResult, list[float]], None] \| None`	called with the index, the fit and the trajectory of every finished optimization, i.e., to report the progress of a fit and to store the runs while it runs.	`None`
`**kwargs`	`Any`	additional arguments of the optimizer.	`{}`

Returns:

Type	Description
`list[OptimizeResult]`	The fits and the trajectories of the optimizations. A run which
`list[list[float]]`	failed is a `RuntimeErrorOptimizeResult` with its message, the
`tuple[list[OptimizeResult], list[list[float]]]`	other runs are unaffected.

start_values ¶

start_values(
    size,
    algorithm=LEAST_SQUARE,
    sampling=UNIFORM,
    seed=None,
)

Create the start values of the optimization runs.

The start values are created for all runs at once, so that they only depend on the seed and the number of runs and not on how the runs are distributed over the workers of a parallel fit.

Parameters:

Name	Type	Description	Default
`size`	`int`	number of optimizations.	required
`algorithm`	`OptimizationAlgorithmType`	optimization algorithm. The global optimizer draws its own samples, its runs start from `None`.	`LEAST_SQUARE`
`sampling`	`SamplingType`	sampling of the start values of the local optimizer.	`UNIFORM`
`seed`	`int \| None`	seed of the sampling.	`None`

Returns:

Type	Description
`list[ndarray \| None]`	One start vector per run, `None` for the global optimizer.

run_seeds `staticmethod` ¶

run_seeds(size, algorithm=LEAST_SQUARE, seed=None)

Create the seed of every optimization run.

The global optimizer draws its own population, so every run needs its own seed: with one seed for all runs they all return the same result. The local optimizer is deterministic, its runs differ in the start values and do not need a seed.

Parameters:

Name	Type	Description	Default
`size`	`int`	number of optimizations.	required
`algorithm`	`OptimizationAlgorithmType`	optimization algorithm.	`LEAST_SQUARE`
`seed`	`int \| None`	seed of the fit, `None` for runs which are not reproducible.	`None`

Returns:

Type	Description
`list[int \| None]`	One seed per run, `None` if the runs do not need one.

check_optimizer_arguments `staticmethod` ¶

check_optimizer_arguments(algorithm, arguments)

Check that the optimizer of the algorithm accepts the arguments.

The additional arguments of a fit are handed to scipy.optimize.least_squares or scipy.optimize.differential_evolution in every run. An argument they do not accept would fail every run, so it is found before the first run. What the problem passes itself, i.e., the objective, the start values and the bounds, is not an additional argument.

Parameters:

Name	Type	Description	Default
`algorithm`	`OptimizationAlgorithmType`	optimization algorithm.	required
`arguments`	`Iterable[str] \| Mapping[str, Any]`	names of the additional arguments of the optimizer.	required

Raises:

Type	Description
`TypeError`	if an argument is not an argument of the optimizer.

optimize_run ¶

optimize_run(
    x0=None,
    algorithm=LEAST_SQUARE,
    timeout=None,
    run=0,
    size=1,
    run_seed=None,
    **kwargs,
)

Run a single optimization, which never raises.

This is one repeat of a fit, i.e., what the serial runner loops over and what a worker of a parallel fit executes. An optimization which fails is a RuntimeErrorOptimizeResult with its message, so that the repeat is stored and reported like a successful one and the other repeats are unaffected.

Parameters:

Name	Type	Description	Default
`x0`	`ndarray \| None`	start values of the run, `None` for the global optimizer.	`None`
`algorithm`	`OptimizationAlgorithmType`	optimization algorithm.	`LEAST_SQUARE`
`timeout`	`float \| None`	seconds the optimization may run, no limit if `None`.	`None`
`run`	`int`	index of the run, for the log messages.	`0`
`size`	`int`	number of runs, for the log messages.	`1`
`run_seed`	`int \| None`	seed of the run, `None` if it does not need one.	`None`
`**kwargs`	`Any`	additional arguments of the optimizer.	`{}`

Returns:

Type	Description
`tuple[OptimizeResult, list[float]]`	The fit and the cost of every step of the optimization.

evaluated_plan ¶

evaluated_plan(k_group, x, quantities=None, point=0)

Get the plan a group is simulated with for the given parameters.

The values of the parameters are applied first; for a group of a scan the values of the point follow, so a dimension wins over a fitted value of its target; the derived changes come last and read the values of the point, e.g. a covariate of a population dimension.

Parameters:

Name	Type	Description	Default
`k_group`	`int`	index of the simulation group.	required
`x`	`ndarray`	parameter values in the units of the parameters.	required
`quantities`	`Sequence[Quantity] \| None`	the quantity of every parameter, built from `x` if a group has derived changes and they are not given.	`None`
`point`	`int`	the point of a group of a scan, in the order of its points; a group of a simulation has one.	`0`

Returns:

Type	Description
`Plan`	The plan of the group with the values of the parameters, of the
`Plan`	point and the derived changes in the units of the model.

predictions ¶

predictions(x, indices=None)

Get the simulation of fit mappings at their reference data.

See evaluations, whose predictions these are; a prediction without a value is NaN.

Parameters:

Name	Type	Description	Default
`x`	`ndarray`	values of the parameters in the units of the model.	required
`indices`	`Sequence[int] \| None`	indices of the fit mappings, the training data by default.	`None`

Returns:

Type	Description
`dict[int, ndarray]`	The prediction at the reference data of every mapping, by the
`dict[int, ndarray]`	index of the mapping.

evaluations ¶

evaluations(x, indices=None)

Get the simulation of fit mappings at their reference data.

The predictions are the values of the observable as they are simulated, i.e. the baseline of a curve is not subtracted, whatever the residual of the settings is. A prediction without a value, e.g. a PK parameter of a point without a terminal phase, stays NaN here, so that a likelihood sees it, while residuals gives the failure residual for it, which keeps an optimizer going.

Parameters:

Name	Type	Description	Default
`x`	`ndarray`	values of the parameters in the units of the model, i.e. on the linear scale, in the order of the parameters of the problem.	required
`indices`	`Sequence[int] \| None`	indices of the fit mappings, the training data by default.	`None`

Returns:

Type	Description
`dict[int, MappingEvaluation]`	The prediction and the selections of the noise model at the
`dict[int, MappingEvaluation]`	reference data of every mapping, by the index of the mapping.

Raises:

Type	Description
`ValueError`	if the problem is not initialized, if no simulator is set, if `x` does not have a value for every parameter, if an index is not the index of a fit mapping or if the integration of a simulation failed.

cost_least_square ¶

cost_least_square(xlog)

Get least square costs for parameters.

residuals ¶

residuals(xlog, complete_data=False)

Calculate residuals for given parameter vector.

Optimization is performed in logarithmic parameter space to account for xtol in largely varying parameters. see https://github.com/scipy/scipy/issues/7632

Parameters:

Name	Type	Description	Default
`xlog`	`ndarray`	logarithmic parameter vector.	required
`complete_data`	`bool`	return the simulations, residuals and costs of every fit mapping instead of the vector of weighted residuals.	`False`

Returns:

Type	Description
`ndarray \| dict[str, list[Any]]`	Vector of weighted residuals, or the complete data of the mappings.

Raises:

Type	Description
`ValueError`	if no simulator is set or the residuals are not supported.

apply_loss_function ¶

apply_loss_function(residuals, loss_function)

Apply the loss function to the residuals.

The cost of the optimization is 0.5 * sum(rho(residuals**2)) with rho the loss function. The optimizers minimize 0.5 * sum(f**2), so the residuals are transformed to sign(r) * sqrt(rho(r**2)), which gives exactly this cost and keeps the sign of the residual. The loss functions are the loss functions of scipy.optimize.least_squares.

Parameters:

Name	Type	Description	Default
`residuals`	`ndarray`	weighted residuals of a fit mapping.	required
`loss_function`	`LossFunctionType`	loss function to apply.	required

Returns:

Type	Description
`ndarray`	Transformed residuals.

Raises:

Type	Description
`ValueError`	if the loss function is not supported.

minimal_result ¶

minimal_result(opt_result)

Reduce the result of an optimization to what is reported.

Parameters:

Name	Type	Description	Default
`opt_result`	`OptimizeResult`	result of one of the optimizers of scipy.	required

Returns:

Type	Description
`OptimizeResult`	A result with the keys of `RESULT_KEYS` which are present.

fit.optimization¶

ObservationKind ¶

GroupResult dataclass ¶

DataTimesResult dataclass ¶

MappingEvaluation dataclass ¶

FitTimeout ¶

RuntimeErrorOptimizeResult ¶

OptimizationProblem ¶

x0 property writable ¶

training_indices property ¶

validation_indices property ¶

outlier_indices property ¶

is_initialized property ¶

settings_initialized property ¶

residual property ¶

loss_function property ¶

weighting_curves property ¶

weighting_points property ¶

parameter_scale property ¶

scales_initialized property ¶

parameter_units property ¶

runner_initialized property ¶

parameter_mapping_initialized property ¶

files ¶

indices ¶

mapping_counts ¶

times_before_changes ¶

to_dict ¶

to_json ¶

report ¶

initialize ¶

to_scale ¶

from_scale ¶

parameter_set_model ¶

bind_parameter_set ¶

set_simulator ¶

optimize ¶

start_values ¶

run_seeds staticmethod ¶

check_optimizer_arguments staticmethod ¶

optimize_run ¶

evaluated_plan ¶

predictions ¶

evaluations ¶

cost_least_square ¶

residuals ¶

apply_loss_function ¶

minimal_result ¶

GroupResult `dataclass` ¶

DataTimesResult `dataclass` ¶

MappingEvaluation `dataclass` ¶

x0 `property` `writable` ¶

training_indices `property` ¶

validation_indices `property` ¶

outlier_indices `property` ¶

is_initialized `property` ¶

settings_initialized `property` ¶

residual `property` ¶

loss_function `property` ¶

weighting_curves `property` ¶

weighting_points `property` ¶

parameter_scale `property` ¶

scales_initialized `property` ¶

parameter_units `property` ¶

runner_initialized `property` ¶

parameter_mapping_initialized `property` ¶

run_seeds `staticmethod` ¶

check_optimizer_arguments `staticmethod` ¶