sensitivity.indices¶

The sensitivity analyses: indices computed on the result of a scan.

A scan with a design of sbmlsim.simulation.sampling (local, sobol, fast, morris) runs with Simulator.run and its observables; an analysis reads the record of the design from the result, moves the dimension of the design to the front of every kept observable and computes the indices of every remaining array element: every label of the other dimensions of the scan (doses, conditions) and every time point of a timecourse on a grid. A ragged timecourse has no common time points; run the scan with time=.

local: central differences at the reference, raw (the change of the observable per change of the parameter) and normalized (d ln y / d ln p);
sobol: the first order and total Sobol indices S1, ST (and S2) with their confidence intervals, SALib;
fast: S1, ST of the extended FAST, SALib;
morris: the elementary effects mu, mu_star, sigma, mu_star_conf, SALib on the unit cube the record recreates.

An element whose points contain a failed simulation (NaN) has NaN indices, one warning counts them. An element of a global analysis which is constant, i.e. whose values vary by no more than the error of the integrator, has NaN indices of variance (Sobol, FAST) and zero effects (Morris), see constant_tolerance.

design_of ¶

design_of(result, methods, dim=None)

Find the dimension of a design of a method in a result.

Parameters:

Name	Type	Description	Default
`result`	`ScanResult`	the result of a scan with a design of `sbmlsim.simulation.sampling`.	required
`methods`	`Collection[str]`	the methods an analysis takes, e.g. `{"sobol"}`.	required
`dim`	`str \| None`	the id of the dimension, needed when there are several.	`None`

Returns:

Type	Description
`tuple[str, Design]`	The id of the dimension and its record.

Raises:

Type	Description
`ValueError`	if no dimension has a design of the methods, several have and `dim` is not given, or `dim` has none.

local ¶

local(result, *, dim=None, observables=None)

Compute the local sensitivities of a scan with a local design, see the module.

raw = (y(+) - y(-)) / (2 delta p_ref) in the unit of the observable per unit of the parameter and normalized = (y(+) - y(-)) / (2 delta y_ref), with y_ref the value at the reference. A zero y_ref gives a NaN normalized; a parameter whose reference is zero is not moved by the design, so both of its indices are NaN. A variable has one unit, so raw has one only when all targets share a unit (else ""). An element whose points contain a failed simulation (NaN) has NaN indices where they use such a point, one warning counts the elements.

Parameters:

Name	Type	Description	Default
`result`	`ScanResult`	the result of a scan with a `sampling.local` design.	required
`dim`	`str \| None`	the dimension of the design, needed when there are several.	`None`
`observables`	`Sequence[str] \| None`	the observables, every variable of the result by default.	`None`

Returns:

Type	Description
`SensitivityResult`	The indices `raw` and `normalized` of every observable.

Raises:

Type	Description
`ValueError`	if the result has no local design or several without `dim`, an observable is a ragged timecourse, or the labels of the dimension are not the ones of the design (a cut result).

constant_tolerance ¶

constant_tolerance(result, tolerance=None)

Get the relative range up to which an element of a result is constant.

An element of a global analysis is constant when the range of its values is at most tolerance * max|y|: the integrator solves a value only up to its error, so an element which is constant except for that error (a saturated or a conserved value, a steady state) has no variance a Sobol or FAST index could share out. The tolerance is CONSTANT_FACTOR times the relative tolerance of the integrator, which the result records in attrs["integrator_settings"], at least SMALLEST_RELATIVE_TOLERANCE; the default of Simulator, 1e-10, gives 1e-7. A result without the record takes RELATIVE_TOLERANCE. A value near zero, at the level of the absolute tolerance (a species which has decayed), varies by its error relative to itself and is not caught.

Parameters:

Name	Type	Description	Default
`result`	`ScanResult`	the result of the scan.	required
`tolerance`	`float \| None`	the tolerance, which wins over the record; `0` keeps every element which is not exactly constant.	`None`

Returns:

Type	Description
`float`	The tolerance.

Raises:

Type	Description
`ValueError`	if the tolerance is negative or not finite.

sobol ¶

sobol(
    result,
    *,
    dim=None,
    observables=None,
    conf_level=0.95,
    num_resamples=100,
    tolerance=None,
)

Compute the Sobol indices of a scan with a Sobol design, see the module.

The indices are S1 and ST (and S2 over (parameter, parameter_2) when the design has second order) with their bootstrap intervals <index>_conf, computed by SALib on the unit cube the record recreates. The bootstrap is seeded with the seed of the design for every element, so the intervals are reproducible for every seed, and the global random state is not touched. S2 is the upper triangle of SALib: NaN on and below the diagonal, so S2 of x1 and x3 is at (x1, x3) only. A constant element (within tolerance) has NaN indices. The options of the result are those of the design and the arguments of the analysis (conf_level, num_resamples, bootstrap_seed, tolerance).

Parameters:

Name	Type	Description	Default
`result`	`ScanResult`	the result of a scan with a `sampling.sobol` design.	required
`dim`	`str \| None`	the dimension of the design, needed when there are several.	`None`
`observables`	`Sequence[str] \| None`	the observables, every variable of the result by default.	`None`
`conf_level`	`float`	the level of the confidence intervals, in (0, 1).	`0.95`
`num_resamples`	`int`	the number of bootstrap resamples, at least 1.	`100`
`tolerance`	`float \| None`	the relative range up to which an element is constant, derived from the relative tolerance of the integrator by default, see `constant_tolerance`.	`None`

Returns:

Type	Description
`SensitivityResult`	The indices of every observable.

Raises:

Type	Description
`ValueError`	if the result has no Sobol design or several without `dim`, an observable is a ragged timecourse, the dimension has another number of points than its record or labels other than `0..n-1`, or an argument is out of range.

fast ¶

fast(
    result,
    *,
    dim=None,
    observables=None,
    conf_level=0.95,
    num_resamples=100,
    tolerance=None,
)

Compute the FAST indices of a scan with a FAST design, see the module.

The indices are S1 and ST with S1_conf and ST_conf, computed by SALib on the unit cube the record recreates. SALib draws the bootstrap from the global random state, so a call seeds it with a seed derived from the seed of the design (bootstrap_seed) and restores the state of the caller afterwards; the intervals are reproducible for every seed. A constant element (within tolerance) has NaN indices. SALib documents that the bootstrap intervals of FAST are unreliable, so S1_conf and ST_conf are indicative only.

Parameters:

Name	Type	Description	Default
`result`	`ScanResult`	the result of a scan with a `sampling.fast` design.	required
`dim`	`str \| None`	the dimension of the design, needed when there are several.	`None`
`observables`	`Sequence[str] \| None`	the observables, every variable of the result by default.	`None`
`conf_level`	`float`	the level of the confidence intervals, in (0, 1).	`0.95`
`num_resamples`	`int`	the number of bootstrap resamples, at least 1.	`100`
`tolerance`	`float \| None`	the relative range up to which an element is constant, derived from the relative tolerance of the integrator by default, see `constant_tolerance`.	`None`

Returns:

Type	Description
`SensitivityResult`	The indices of every observable.

Raises:

Type	Description
`ValueError`	if the result has no FAST design or several without `dim`, an observable is a ragged timecourse, the dimension has another number of points than its record or labels other than `0..n-1`, or an argument is out of range.

morris ¶

morris(
    result,
    *,
    dim=None,
    observables=None,
    conf_level=0.95,
    num_resamples=100,
    tolerance=None,
)

Compute the elementary effects of a scan with a Morris design, see the module.

The indices are mu, mu_star, sigma and mu_star_conf, computed by SALib on the unit cube the record recreates (scaled=False). They are the change of the observable divided by the jump levels / (2 (levels - 1)) of SALib's grid of levels on [0, 1], i.e. per unit of that grid, so they have the unit of the observable: an effect is 2 (levels - 1) / levels times the change of the observable over one step of a trajectory, which moves the probability of one parameter by 1/2 (1.5 times for 4 levels). A constant element (within tolerance) has zero effects.

Parameters:

Name	Type	Description	Default
`result`	`ScanResult`	the result of a scan with a `sampling.morris` design.	required
`dim`	`str \| None`	the dimension of the design, needed when there are several.	`None`
`observables`	`Sequence[str] \| None`	the observables, every variable of the result by default.	`None`
`conf_level`	`float`	the level of the confidence interval, in (0, 1).	`0.95`
`num_resamples`	`int`	the number of bootstrap resamples, at least 1.	`100`
`tolerance`	`float \| None`	the relative range up to which an element is constant, derived from the relative tolerance of the integrator by default, see `constant_tolerance`.	`None`

Returns:

Type	Description
`SensitivityResult`	The indices of every observable.

Raises:

Type	Description
`ValueError`	if the result has no Morris design or several without `dim`, an observable is a ragged timecourse, the dimension has another number of points than its record or labels other than `0..n-1`, or an argument is out of range.