simulation.sampling¶

The sampler: distributions and the designs of a scan.

A design is a dimension of a scan whose values are drawn from distributions, see sbmlsim.simulation.sampling.designs; it carries the record of how it was drawn, Design, which the result keeps as its provenance. A distribution gives the values of a target at probabilities of the unit cube, so every design works with every marginal; a distribution without a location is relative to the reference of its target, see references.

The distributions of the sampler.

A distribution gives the values of a target at probabilities u of the unit cube, ppf(u, reference), the inverse of its cumulative distribution function, so every design (random draws, Latin hypercubes, the designs of SALib) works with every marginal. Its numbers are floats in the unit of the target in the model or quantities; a plain number next to a quantity is in the unit of the quantity. A distribution without a location (Uniform(relative=), LogUniform(factor=), Normal(cv=), LogNormal(cv=)) is relative to the reference of its target, the value the model gives it after the pre-initialization, see sbmlsim.simulation.sampling.references.

The values are a quantity when the distribution has a unit (of a quantity or of its reference) and plain floats otherwise. The probabilities 0 and 1 of an unbounded distribution are clipped to EPS from the bounds of the unit interval, so its values are finite.

Distribution ¶

Bases: ABC

A distribution of the values of a target, see the module.

is_relative `property` ¶

is_relative

Check whether the location is the reference of the target.

ppf `abstractmethod` ¶

ppf(u, reference=None)

Get the values at probabilities of the unit interval.

Parameters:

Name	Type	Description	Default
`u`	`Any`	the probabilities, an array.	required
`reference`	`Number \| None`	the reference of the target, which a relative distribution needs.	`None`

Returns:

Type	Description
`ndarray \| Quantity`	The values, a quantity where the distribution has a unit.

Raises:

Type	Description
`ValueError`	if a relative distribution has no reference or its reference does not fit.

cdf `abstractmethod` ¶

cdf(x, reference=None)

Get the probabilities of values, the inverse of ppf.

Parameters:

Name	Type	Description	Default
`x`	`Any`	the values, numbers in the unit of the distribution or quantities converted into it.	required
`reference`	`Number \| None`	the reference of the target.	`None`

Returns:

Type	Description
`ndarray`	The probabilities.

to_dict `abstractmethod` ¶

to_dict()

Get the distribution as a dictionary of JSON types.

Uniform `dataclass` ¶

Uniform(lower=None, upper=None, relative=None)

Bases: Distribution

Uniform in [lower, upper], or in the reference times [1 - relative, 1 + relative].

Attributes:

Name	Type	Description
`lower`	`Number \| None`	the lower bound.
`upper`	`Number \| None`	the upper bound, not below `lower`.
`relative`	`float \| None`	the relative half width around the reference.

is_relative `property` ¶

is_relative

Check whether the bounds are relative to the reference.

ppf ¶

ppf(u, reference=None)

Get the values, lower + u (upper - lower).

cdf ¶

cdf(x, reference=None)

Get the probabilities of values.

to_dict ¶

to_dict()

Get the distribution as a dictionary of JSON types.

LogUniform `dataclass` ¶

LogUniform(lower=None, upper=None, factor=None)

Bases: Distribution

Uniform in the decadic logarithm, in [lower, upper] or in the reference divided and multiplied by factor.

Attributes:

Name	Type	Description
`lower`	`Number \| None`	the positive lower bound.
`upper`	`Number \| None`	the upper bound, not below `lower`.
`factor`	`float \| None`	the factor above 1 around the (positive) reference.

is_relative `property` ¶

is_relative

Check whether the bounds are relative to the reference.

ppf ¶

ppf(u, reference=None)

Get the values, 10 ** (log10(lower) + u (log10(upper) - log10(lower))).

cdf ¶

cdf(x, reference=None)

Get the probabilities of values.

to_dict ¶

to_dict()

Get the distribution as a dictionary of JSON types.

Normal `dataclass` ¶

Normal(mean=None, sd=None, cv=None)

Bases: Distribution

Normal with a standard deviation or a coefficient of variation.

Without a mean the mean is the reference of the target.

Attributes:

Name	Type	Description
`mean`	`Number \| None`	the mean.
`sd`	`Number \| None`	the positive standard deviation.
`cv`	`float \| None`	the positive coefficient of variation, `sd = cv \|mean\|`.

is_relative `property` ¶

is_relative

Check whether the mean is the reference.

ppf ¶

ppf(u, reference=None)

Get the values, mean + sd z(u).

cdf ¶

cdf(x, reference=None)

Get the probabilities of values.

to_dict ¶

to_dict()

Get the distribution as a dictionary of JSON types.

LogNormal `dataclass` ¶

LogNormal(median=None, cv=None)

Bases: Distribution

Log-normal with a median and a coefficient of variation.

Without a median the median is the reference of the target.

Attributes:

Name	Type	Description
`median`	`Number \| None`	the positive median.
`cv`	`float \| None`	the positive coefficient of variation of the distribution, the sigma of the logarithm is `sqrt(ln(1 + cv^2))`.

is_relative `property` ¶

is_relative

Check whether the median is the reference.

ppf ¶

ppf(u, reference=None)

Get the values, median exp(sigma z(u)).

cdf ¶

cdf(x, reference=None)

Get the probabilities of values.

to_dict ¶

to_dict()

Get the distribution as a dictionary of JSON types.

Truncated `dataclass` ¶

Truncated(distribution, lower=None, upper=None)

Bases: Distribution

Another distribution restricted to [lower, upper].

The probabilities are mapped onto the part of the inner distribution between the bounds, so the values keep its shape. The bounds are numbers in the unit of the inner distribution or quantities.

Attributes:

Name	Type	Description
`distribution`	`Distribution`	the inner distribution.
`lower`	`Number \| None`	the lower bound, unbounded below without.
`upper`	`Number \| None`	the upper bound, unbounded above without.

is_relative `property` ¶

is_relative

Check whether the inner distribution is relative.

ppf ¶

ppf(u, reference=None)

Get the values, the inner ppf at F(lower) + u (F(upper) - F(lower)).

cdf ¶

cdf(x, reference=None)

Get the probabilities of values.

to_dict ¶

to_dict()

Get the distribution as a dictionary of JSON types.

Empirical `dataclass` ¶

Empirical(values)

Bases: Distribution

The sorted values of a sample, each with the same probability.

Attributes:

Name	Type	Description
`values`	`Sequence[float] \| Quantity`	the values, a sequence of numbers or a quantity array; sorted and kept as a tuple of floats.
`unit`	`str \| None`	the unit of the values, `None` for plain numbers.

ppf ¶

ppf(u, reference=None)

Get the values, the one at the position floor(u n).

cdf ¶

cdf(x, reference=None)

Get the probabilities of values, the share of the values up to them.

to_dict ¶

to_dict()

Get the distribution as a dictionary of JSON types.

Fixed `dataclass` ¶

Fixed(value)

Bases: Distribution

A single value, for a target which a design keeps at a value.

Attributes:

Name	Type	Description
`value`	`Number`	the value.

ppf ¶

ppf(u, reference=None)

Get the value for every probability.

cdf ¶

cdf(x, reference=None)

Get the probabilities of values, 1 from the value on.

to_dict ¶

to_dict()

Get the distribution as a dictionary of JSON types.

The references of the targets of a design.

The reference of a target is the value the model gives it after the pre-initialization of a simulation: the changes of the model and of the simulation are set, and the initial assignments which read them are evaluated again. A relative distribution is centred on it, and a local design varies around it.

references ¶

references(model, targets, simulation=None)

Get the value every target has after the pre-initialization.

The simulation is compiled with the changes of the model as defaults and the model is initialized with its plan, as every simulation of the model is; the model is reset after the values are read, so it keeps no value of the pre-initialization, which e.g. the start values of a fit would read (#315).

Parameters:

Name	Type	Description	Default
`model`	`ModelLike`	the model, loaded or a source.	required
`targets`	`Sequence[str]`	the targets, selections of roadrunner, e.g. `k1`, `S` or `[S]`.	required
`simulation`	`Simulation \| None`	the simulation whose pre-initialization counts, `Simulation(end=1)` by default.	`None`

Returns:

Type	Description
`dict[str, Number]`	Target -> its value, a quantity in the unit of the target in the model
`dict[str, Number]`	or a float without a unit.

Raises:

Type	Description
`ValueError`	if a target is no selection of the model.

parameters_of ¶

parameters_of(
    model,
    *,
    species=False,
    exclude=None,
    exclude_zero=True,
    simulation=None,
)

List the constant parameters of a model, which an analysis of all parameters varies.

Parameters:

Name	Type	Description	Default
`model`	`ModelLike`	the model, loaded or a source.	required
`species`	`bool`	list the species as well (their amounts), except the species of an assignment rule, which a change cannot set.	`False`
`exclude`	`Callable[[str], bool] \| Collection[str] \| str \| None`	an id, ids, or a function which is true for an id, to leave out.	`None`
`exclude_zero`	`bool`	leave out a target whose reference is below `ZERO` in magnitude, which a relative change does not change.	`True`
`simulation`	`Simulation \| None`	the simulation whose pre-initialization gives the references of `exclude_zero`.	`None`

Returns:

Type	Description
`list[str]`	The ids, sorted, without the helper parameters sbmlsim adds.

The designs of a scan: dimensions whose values follow a design.

Every design returns a Dimension of values with a Design record, which a scan writes into the provenance of its result:

local: the reference point and every target alone at 1 + delta and 1 - delta times its reference;
random: independent draws, with a correlation a Gaussian copula; correlation is the Spearman rank correlation of the values
lhs: a Latin hypercube, with a correlation the rank reordering of Iman and Conover, which keeps one point per stratum;
sobol, fast, morris: the designs of SALib for the sensitivity analyses.

A design draws points of the unit cube and maps them through the inverse CDF of the distribution of every target, see sbmlsim.simulation.sampling.distributions. A relative distribution reads the reference of its target from the model, see references. Every random design takes seed; None draws a seed, which the record keeps.

MAX_REDRAWS `module-attribute` ¶

MAX_REDRAWS = 100

How often the orders of the scores of a correlated hypercube are drawn again.

local ¶

local(
    targets,
    delta=0.1,
    *,
    model,
    simulation=None,
    id="local",
)

Get the local design: the reference and every target alone at 1 ± delta times it.

Parameters:

Name	Type	Description	Default
`targets`	`Sequence[str]`	the targets, e.g. the parameters of `parameters_of`.	required
`delta`	`float`	the relative change, `0 < delta < 1`.	`0.1`
`model`	`ModelLike`	the model, whose references the design varies.	required
`simulation`	`Simulation \| None`	the simulation whose pre-initialization gives the references.	`None`
`id`	`str`	the id of the dimension.	`'local'`

Returns:

Type	Description
`Dimension`	The dimension of `2 k + 1` points, labelled `reference`, `<target>+`,
`Dimension`	`<target>-`.

Raises:

Type	Description
`ValueError`	if `delta` is not in `(0, 1)`, there is no target or a target is no target of the model.

random ¶

random(
    distributions,
    n,
    *,
    seed=None,
    correlation=None,
    model=None,
    simulation=None,
    id="random",
)

Get n random draws of the distributions.

Without a correlation the points of the unit cube are rng.random((n, d)); with one they are standard normals with the Cholesky factor of the correlation of normal scores which has the asked rank correlation, mapped through the normal CDF (a Gaussian copula), so the Spearman rank correlation of the values is the asked one for any marginals.

Parameters:

Name	Type	Description	Default
`distributions`	`Mapping[str, Distribution]`	target -> its distribution.	required
`n`	`int`	the number of points.	required
`seed`	`int \| None`	the seed, not negative; `None` draws one, which the record keeps.	`None`
`correlation`	`ArrayLike \| None`	the Spearman rank correlation of the values of the targets, in the order of `distributions`.	`None`
`model`	`ModelLike \| None`	the model, which a relative distribution needs.	`None`
`simulation`	`Simulation \| None`	the simulation whose pre-initialization gives the references.	`None`
`id`	`str`	the id of the dimension.	`'random'`

Returns:

Type	Description
`Dimension`	The dimension.

Raises:

Type	Description
`TypeError`	if the distributions or the seed have the wrong type.
`ValueError`	if `n` is no positive integer, the seed is negative, the correlation is not valid, or a relative distribution has no model.

lhs ¶

lhs(
    distributions,
    n,
    *,
    seed=None,
    correlation=None,
    model=None,
    simulation=None,
    id="lhs",
)

Get a Latin hypercube of n points of the distributions.

The points of the unit cube are qmc.LatinHypercube(d, rng=rng).random(n), one point per stratum of every target; with a correlation the columns are reordered by the method of Iman and Conover, which keeps the strata, so the Spearman rank correlation of the values is the asked one.

Parameters:

Name	Type	Description	Default
`distributions`	`Mapping[str, Distribution]`	target -> its distribution.	required
`n`	`int`	the number of points, more than the number of targets with a correlation.	required
`seed`	`int \| None`	the seed, not negative; `None` draws one, which the record keeps.	`None`
`correlation`	`ArrayLike \| None`	the Spearman rank correlation of the values of the targets, in the order of `distributions`.	`None`
`model`	`ModelLike \| None`	the model, which a relative distribution needs.	`None`
`simulation`	`Simulation \| None`	the simulation whose pre-initialization gives the references.	`None`
`id`	`str`	the id of the dimension.	`'lhs'`

Returns:

Type	Description
`Dimension`	The dimension.

Raises:

Type	Description
`TypeError`	if the distributions or the seed have the wrong type.
`ValueError`	see `random`, and a correlated hypercube with too few points.

unit_problem ¶

unit_problem(d)

Get the problem of SALib on the unit cube of d dimensions.

Parameters:

Name	Type	Description	Default
`d`	`int`	the number of targets.	required

Returns:

Type	Description
`dict[str, Any]`	The problem, `d` variables with the bounds `[0, 1]`; the analyses of
`dict[str, Any]`	`sbmlsim.sensitivity` use it as well.

unit_cube ¶

unit_cube(design, d)

Get the points of the unit cube of a recorded design of SALib.

The points follow from the method, the options and the seed of the record, so a result of the design needs not store them; phase 2 creates them again for the analysis.

Parameters:

Name	Type	Description	Default
`design`	`Design`	the record of a `sobol`, `fast` or `morris` design.	required
`d`	`int`	the number of targets.	required

Returns:

Type	Description
`ndarray`	The points, a row per point of the dimension.

Raises:

Type	Description
`ValueError`	if the record is of another method.

sobol ¶

sobol(
    distributions,
    n,
    *,
    seed=None,
    second_order=False,
    model=None,
    simulation=None,
    id="sobol",
)

Get the design of Saltelli for the Sobol indices.

SALib.sample.sobol.sample on the unit cube, scrambled, mapped through the distributions: n (d + 2) points, n (2 d + 2) with second order. The targets are independent, a correlation is not taken.

Parameters:

Name	Type	Description	Default
`distributions`	`Mapping[str, Distribution]`	target -> its distribution.	required
`n`	`int`	the base number of points, a power of two.	required
`seed`	`int \| None`	the seed, not negative; `None` draws one, which the record keeps.	`None`
`second_order`	`bool`	include the points of the second order indices.	`False`
`model`	`ModelLike \| None`	the model, which a relative distribution needs.	`None`
`simulation`	`Simulation \| None`	the simulation whose pre-initialization gives the references.	`None`
`id`	`str`	the id of the dimension.	`'sobol'`

Returns:

Type	Description
`Dimension`	The dimension.

Raises:

Type	Description
`TypeError`	if the distributions or the seed have the wrong type.
`ValueError`	if `n` is no power of two, or see `random`.

fast ¶

fast(
    distributions,
    n,
    *,
    m=4,
    seed=None,
    model=None,
    simulation=None,
    id="fast",
)

Get the design of the extended FAST.

SALib.sample.fast_sampler.sample on the unit cube, mapped through the distributions: n d points. The targets are independent, a correlation is not taken.

Parameters:

Name	Type	Description	Default
`distributions`	`Mapping[str, Distribution]`	target -> its distribution.	required
`n`	`int`	the number of points per target, more than `4 m^2`.	required
`m`	`int`	the interference factor of SALib.	`4`
`seed`	`int \| None`	the seed, not negative; `None` draws one, which the record keeps.	`None`
`model`	`ModelLike \| None`	the model, which a relative distribution needs.	`None`
`simulation`	`Simulation \| None`	the simulation whose pre-initialization gives the references.	`None`
`id`	`str`	the id of the dimension.	`'fast'`

Returns:

Type	Description
`Dimension`	The dimension.

Raises:

Type	Description
`TypeError`	if the distributions or the seed have the wrong type.
`ValueError`	if `n` is not more than `4 m^2`, or see `random`.

morris ¶

morris(
    distributions,
    trajectories,
    *,
    levels=4,
    seed=None,
    model=None,
    simulation=None,
    id="morris",
)

Get the design of Morris for the elementary effects.

SALib.sample.morris.sample on the unit cube: trajectories (d + 1) points. The level k of the grid of SALib (0 to 1 in levels - 1 steps) is mapped to (k + 0.5) / levels, the centre of the stratum of that level, so an unbounded marginal stays finite. The targets are independent, a correlation is not taken.

Parameters:

Name	Type	Description	Default
`distributions`	`Mapping[str, Distribution]`	target -> its distribution.	required
`trajectories`	`int`	the number of trajectories.	required
`levels`	`int`	the number of levels of the grid, at least two.	`4`
`seed`	`int \| None`	the seed, not negative; `None` draws one, which the record keeps.	`None`
`model`	`ModelLike \| None`	the model, which a relative distribution needs.	`None`
`simulation`	`Simulation \| None`	the simulation whose pre-initialization gives the references.	`None`
`id`	`str`	the id of the dimension.	`'morris'`

Returns:

Type	Description
`Dimension`	The dimension.

Raises:

Type	Description
`TypeError`	if the distributions or the seed have the wrong type.
`ValueError`	if `levels` is below two, or see `random`.

The designs of a fit: draws of what a fit knows about its parameters.

fit_parameters: the multivariate normal of the Fisher covariance around the fitted values, in the space of the parameter_scale (correlated, a local approximation);
profile_parameters: every parameter from its profile likelihood (follows asymmetric and open profiles, independent across parameters, since the profiles carry no joint information);
fit_repeats: the best parameter sets of the repeats of a fit.

A fitted parameter is written to its pid unless targets maps it to another target; two parameters of one target (the versions of a parameter) raise, since a scan sets a target once per point.

fit_parameters ¶

fit_parameters(
    fisher, n, *, seed=None, targets=None, id="fit"
)

Draw the fitted parameters from the normal of their Fisher covariance.

The draws are normal around the fitted values in the space of the parameter_scale with the covariance of the Fisher information, drawn in the directions the information constrains only (the eigenvalues of J'J above the rank tolerance, with the variance sigma2 / eigenvalue), so a direction the data does not constrain has no spread, and transformed back into the units of the model. An information which is rank deficient warns once, see FisherInformation.covariance. The target of a parameter is the one of the information (FitParameter.target_id) unless targets maps it.

Parameters:

Name	Type	Description	Default
`fisher`	`FisherInformation`	the Fisher information of the fitted parameters.	required
`n`	`int`	the number of points.	required
`seed`	`int \| None`	the seed; `None` draws one, which the record keeps.	`None`
`targets`	`Mapping[str, str] \| None`	pid -> the target of the model, overrides `FitParameter.target_id`.	`None`
`id`	`str`	the id of the dimension.	`'fit'`

Returns:

Type	Description
`Dimension`	The dimension.

Raises:

Type	Description
`ValueError`	if `n` is no positive integer, the information has no degrees of freedom or constrains no direction, the draws are not finite in the units of the model, a key of `targets` is no parameter or two parameters have one target.

profile_parameters ¶

profile_parameters(
    identifiability,
    n,
    *,
    seed=None,
    targets=None,
    id="profile",
)

Draw every parameter from the likelihood of its profile.

The density of a parameter is exp(-(cost - cost_min)) along its profile, with the smallest cost of the profile, linear between its points in the space of the parameter_scale, so asymmetric and open profiles are followed. A side which stays below the threshold reaches the bound of the parameter, a closed side (the profile stops at the threshold) is continued by its quadratic tail, see TAIL_RISE. The parameters are independent, since the profiles carry no joint information.

Parameters:

Name	Type	Description	Default
`identifiability`	`IdentifiabilityResult`	the profile likelihood of a fit.	required
`n`	`int`	the number of points.	required
`seed`	`int \| None`	the seed; `None` draws one, which the record keeps.	`None`
`targets`	`Mapping[str, str] \| None`	pid -> the target of the model, overrides `FitParameter.target_id`.	`None`
`id`	`str`	the id of the dimension.	`'profile'`

Returns:

Type	Description
`Dimension`	The dimension.

Raises:

Type	Description
`ValueError`	if `n` is no positive integer, two parameters have one target or a profile has no converged optimum.

fit_repeats ¶

fit_repeats(result, size, *, targets=None, id='repeats')

Take the best parameter sets of the repeats of a fit.

Parameters:

Name	Type	Description	Default
`result`	`_Repeats`	the result of a fit.	required
`size`	`int`	the number of parameter sets.	required
`targets`	`Mapping[str, str] \| None`	pid -> the target of the model, overrides `FitParameter.target_id`.	`None`
`id`	`str`	the id of the dimension.	`'repeats'`

Returns:

Type	Description
`Dimension`	The dimension, its points labelled with the ids of the sets.

Raises:

Type	Description
`ValueError`	if `size` is no positive integer, the fit has no parameter set, a key of `targets` is no parameter or two parameters have one target.

Virtual populations: covariates drawn and mapped to the values of targets.

The covariates (e.g. the body weight, the age) are drawn by random or lhs, and a function of a module maps them to the values of targets of the model, function(covariates) -> {target: values}, vectorized over the points. The covariates are coordinates of the dimension, which the result carries and no model sees, so an observable can be plotted against them.

population ¶

population(
    function,
    covariates,
    n,
    *,
    seed=None,
    method="random",
    model=None,
    simulation=None,
    id="population",
)

Get a virtual population, see the module.

Parameters:

Name	Type	Description	Default
`function`	`Callable[[dict[str, Any]], Mapping[str, Any]]`	a function of a module, `covariates -> {target: values}`, the values of every target for every point.	required
`covariates`	`Mapping[str, Distribution]`	covariate -> its distribution.	required
`n`	`int`	the number of individuals.	required
`seed`	`int \| None`	the seed; `None` draws one, which the record keeps.	`None`
`method`	`str`	`random` or `lhs`, the design of the covariates.	`'random'`
`model`	`ModelLike \| None`	the model, which a relative distribution of a covariate needs.	`None`
`simulation`	`Simulation \| None`	the simulation whose pre-initialization gives the references.	`None`
`id`	`str`	the id of the dimension.	`'population'`

Returns:

Type	Description
`Dimension`	The dimension, the targets as its values and the covariates as its
`Dimension`	coordinates.

Raises:

Type	Description
`ValueError`	if the function is no function of a module or returns no mapping of targets to `n` values, a covariate as a target, or the method is unknown.

simulation.sampling¶

Distribution ¶

is_relative property ¶

ppf abstractmethod ¶

cdf abstractmethod ¶

to_dict abstractmethod ¶

Uniform dataclass ¶

is_relative property ¶

ppf ¶

cdf ¶

to_dict ¶

LogUniform dataclass ¶

is_relative property ¶

ppf ¶

cdf ¶

to_dict ¶

Normal dataclass ¶

is_relative property ¶

ppf ¶

cdf ¶

to_dict ¶

LogNormal dataclass ¶

is_relative property ¶

ppf ¶

cdf ¶

to_dict ¶

Truncated dataclass ¶

is_relative property ¶

ppf ¶

cdf ¶

to_dict ¶

Empirical dataclass ¶

ppf ¶

cdf ¶

to_dict ¶

Fixed dataclass ¶

ppf ¶

cdf ¶

to_dict ¶

references ¶

parameters_of ¶

MAX_REDRAWS module-attribute ¶

local ¶

random ¶

lhs ¶

unit_problem ¶

unit_cube ¶

sobol ¶

fast ¶

morris ¶

fit_parameters ¶

profile_parameters ¶

fit_repeats ¶

population ¶

is_relative `property` ¶

ppf `abstractmethod` ¶

cdf `abstractmethod` ¶

to_dict `abstractmethod` ¶

Uniform `dataclass` ¶

is_relative `property` ¶

LogUniform `dataclass` ¶

is_relative `property` ¶

Normal `dataclass` ¶

is_relative `property` ¶

LogNormal `dataclass` ¶

is_relative `property` ¶

Truncated `dataclass` ¶

is_relative `property` ¶

Empirical `dataclass` ¶

Fixed `dataclass` ¶

MAX_REDRAWS `module-attribute` ¶