uncertainty.sources¶

The sources of an uncertainty analysis: what is uncertain and how.

An UncertaintyModel collects the uncertain values of an analysis, apart from the simulations it is applied to: the inputs, i.e. the Uncertain values of the simulations (inputs=True), the parameters with their distributions or uncertain values (parameters), and the dependence between them (covariance, see sbmlsim.uncertainty.Covariance).

A Variable is one random variable of the analysis: an uncertain value used for one or several targets (the same object, or objects of the same name), with its distribution. The uncertain values of one key in several scenarios are one variable, also with distributions which differ between the scenarios, e.g. a dose of 100 mg and of 200 mg: a draw takes the same quantile of the distribution of every scenario, so the scenarios are paired (common random numbers); within one scenario a key has one distribution. A draw of the analysis gives every variable a value, which replaces each of its targets wherever a simulation sets it (the rule of Simulation.with_values). A target which a simulation sets to an uncertain value and elsewhere to another value cannot be replaced in one place alone and raises, and so does a parameter which a simulation sets: its draw would replace the value of the simulation, e.g. the inhibition of a scenario.

Variable `dataclass` ¶

Variable(
    key,
    targets,
    distribution,
    kind,
    source,
    by_scenario=dict(),
)

A random variable of an uncertainty analysis.

Attributes:

Name	Type	Description
`key`	`str`	the key of the variable: the name of its uncertain value, else its first target.
`targets`	`tuple[str, ...]`	the targets the value of the variable replaces.
`distribution`	`Distribution`	the distribution.
`kind`	`str`	`uncertainty` or `variability`.
`source`	`Literal['input', 'parameter']`	`input` (an uncertain value of a simulation) or `parameter`.
`by_scenario`	`Mapping[str, Distribution]`	scenario -> its distribution where it differs from `distribution`, the one of the first scenario: an input of one key whose distribution differs between scenarios, e.g. a dose of 100 mg in one and of 200 mg in another, is drawn at the same quantile in every scenario (common random numbers) from its own marginal.

marginal ¶

marginal(scenario=None)

Get the distribution of the variable in a scenario.

UncertaintyModel `dataclass` ¶

UncertaintyModel(
    parameters=dict(), covariance=(), inputs=True
)

What is uncertain in an analysis, see the module.

Attributes:

Name	Type	Description
`parameters`	`Mapping[str, Uncertain \| Distribution]`	target -> its uncertain value or distribution.
`covariance`	`Sequence[Covariance]`	the dependence between the variables, by their keys.
`inputs`	`bool`	whether the uncertain values of the simulations are variables.

variables ¶

variables(simulations)

Get the variables of the simulations of an analysis.

Parameters:

Name	Type	Description	Default
`simulations`	`Mapping[str, Simulation]`	the simulations by their name, e.g. the scenarios of a comparison.	required

Returns:

Type	Description
`list[Variable]`	The variables: the inputs in the order of their first use, then
`list[Variable]`	the parameters.

Raises:

Type	Description
`ValueError`	for a target set to an uncertain value and to another value, two uncertain values of one name and different distributions, a parameter which is an input as well, or a parameter which a simulation sets.

from_covariance `classmethod` ¶

from_covariance(
    means, covariance, *, shape="auto", **kwargs
)

Create the uncertainty of parameters of their means and their covariance.

A covariance on the log scale gives log-normal parameters with the means as medians and the variances of the logarithms of its diagonal; a covariance on the linear scale gives the uncertain values of the means and the standard deviations of its diagonal (shape="auto": log-normal for a positive mean, see Uncertain).