Skip to content

uncertainty.quantity

Uncertain values: a nominal value with its distribution.

An Uncertain is given wherever a value is given, e.g. the value of a Change, of a pre-initialization change or the prior of a FitParameter. A simulation simulates its nominal value, so declaring a value uncertain changes nothing until it is propagated, see sbmlsim.uncertainty.propagate.

The spread is given as reported:

given distribution nominal
sd= or cv= of a positive value (shape="auto") log-normal with the mean and the SD matched the value, the mean
sd=/cv= with shape="normal", or a value which may be negative normal the mean
low=/high= with them the distribution above, truncated the mean
Uncertain.range(low, high) uniform (log=True: log-uniform) the (geometric) midpoint
Uncertain.interval(low, high, level) log-normal (positive) or normal with these quantiles the median
Uncertain.se(mean, se, n) the SD se * sqrt(n), as the fit converts it the mean
distribution= the given one the value

A log-normal with the arithmetic mean m and the coefficient of variation cv has the median m / sqrt(1 + cv^2) and the standard deviation of the logarithm sqrt(ln(1 + cv^2)) (Limpert et al. 2001). It is the default of a positive quantity, e.g. a dose, a body weight, a volume or a rate, which a normal distribution of a large CV would give negative values.

kind is uncertainty (epistemic: what is not known about the value) or variability (aleatory: the value differs between subjects); it matters for a nested propagation and for virtual trials. name makes two uses one random variable: one object used twice, or two objects of one name, are one variable of an analysis; different objects are independent unless a Covariance correlates them.

Limpert E, Stahel WA, Abbt M (2001). Log-normal distributions across the sciences: keys and clues. BioScience 51:341-352.

Uncertain dataclass 

Uncertain(
    value,
    *,
    sd=None,
    cv=None,
    low=None,
    high=None,
    shape="auto",
    distribution=None,
    kind="uncertainty",
    name=None,
)

A value with its distribution, see the module.

Attributes:

Name Type Description
nominal Number

the value a simulation simulates, a quantity or a number.
distribution Distribution

the distribution of the sampler.
shape str

log-normal, normal, uniform, log-uniform or given.
kind Literal['uncertainty', 'variability']

uncertainty or variability.
name str | None

the name of the random variable, None for the object itself.

Create an uncertain value from its mean and spread, see the module.

Parameters:

Name Type Description Default
value Number

the nominal value, the mean of sd and cv.

 required
sd Number | None

the standard deviation.

 None
cv float | None

the coefficient of variation, sd / |mean|.

 None
low Number | None

the lower bound of a truncation.

 None
high Number | None

the upper bound of a truncation.

 None
shape Literal['auto', 'normal', 'log-normal']

auto (log-normal for a positive value, else normal), normal or log-normal.

 'auto'
distribution Distribution | None

the distribution, instead of sd and cv.

 None
kind Literal['uncertainty', 'variability']

uncertainty or variability.

 'uncertainty'
name str | None

the name of the random variable.

 None

Raises:

Type Description
ValueError

unless exactly one of sd, cv and distribution is given, for a log-normal of a value which is not positive, or for units which do not fit.

unit property 

unit

Get the unit of the value, None for a number.

range classmethod 

range(
    low, high, *, log=False, kind="uncertainty", name=None
)

Create an uncertain value which lies between a minimum and a maximum.

Parameters:

Name Type Description Default
low Number

the minimum.

 required
high Number

the maximum, larger than the minimum.

 required
log bool

log-uniform instead of uniform, for a positive range of orders of magnitude.

 False
kind Literal['uncertainty', 'variability']

uncertainty or variability.

 'uncertainty'
name str | None

the name of the random variable.

 None

Returns:

Type Description
Uncertain

The uncertain value, its nominal the midpoint (the geometric one
Uncertain

for log).

Raises:

Type Description
ValueError

for a range which is empty or, for log, not positive.

interval classmethod 

interval(
    low,
    high,
    *,
    level=0.95,
    shape="auto",
    kind="uncertainty",
    name=None,
)

Create an uncertain value of a reported interval.

The quantiles (1 - level) / 2 and (1 + level) / 2 of the distribution are the bounds of the interval: of a log-normal for a positive interval (shape="auto"), of a normal otherwise.

Parameters:

Name Type Description Default
low Number

the lower bound of the interval.

 required
high Number

the upper bound.

 required
level float

the level of the interval, e.g. 0.95.

 0.95
shape Literal['auto', 'normal', 'log-normal']

auto, normal or log-normal.

 'auto'
kind Literal['uncertainty', 'variability']

uncertainty or variability.

 'uncertainty'
name str | None

the name of the random variable.

 None

Returns:

Type Description
Uncertain

The uncertain value, its nominal the median.

Raises:

Type Description
ValueError

for an empty interval, a level outside (0, 1) or a log-normal interval which is not positive.

se classmethod 

se(mean, se, n, **kwargs)

Create an uncertain value of a mean, its standard error and the count.

The standard deviation is se * sqrt(n), as a fit converts the standard errors of its data.

Parameters:

Name Type Description Default
mean Number

the mean.

 required
se Number

the standard error of the mean.

 required
n float

the count, the number of subjects.

 required
kwargs Any

the other arguments of Uncertain.

 {}

Returns:

Type Description
Uncertain

The uncertain value.

Raises:

Type Description
ValueError

for a count which is not positive.

mean 

mean()

Get the mean of the distribution, in the unit of the value.

sd 

sd()

Get the standard deviation of the distribution, in the unit of the value.

to_dict 

to_dict()

Get the uncertain value as a dictionary of JSON types.

from_dict classmethod 

from_dict(d)

Create an uncertain value of to_dict.