uncertainty.statistics¶

The statistics of the draws of an uncertainty analysis, with their errors.

Every statistic of a Monte Carlo propagation has an error from the finite number of draws, which is reported with it. The functions ignore the draws which are NaN, i.e. of a point which failed, and return the number of draws they used; an infinite draw is a value (the mean of draws with one is infinite, their standard deviation NaN).

mean_se: the mean and its standard error s / sqrt(n)
sd_se: the standard deviation and its standard error by the delta method with the fourth central moment, sqrt((m4 - s^4) / n) / (2 s)
quantile_ci: a quantile and its distribution-free confidence interval of order statistics, the ranks of the binomial distribution of the number of draws below the quantile (Hahn & Meeker 1991)

For quasi-random draws these errors are conservative: their convergence is faster than that of random draws, which the errors assume.

Hahn GJ, Meeker WQ (1991). Statistical Intervals: A Guide for Practitioners. Wiley.

mean_se ¶

mean_se(x)

Get the mean, its standard error and the number of draws.

Parameters:

Name	Type	Description	Default
`x`	`ArrayLike`	the draws.	required

Returns:

Type	Description
`float`	The mean, its standard error and the number of draws which are not
`float`	`NaN`; `nan` without draws (the error without two of them).

sd_se ¶

sd_se(x)

Get the standard deviation, its standard error and the number of draws.

Parameters:

Name	Type	Description	Default
`x`	`ArrayLike`	the draws.	required

Returns:

Type	Description
`float`	The standard deviation, its standard error by the delta method and
`float`	the number of draws which are not `NaN`; `nan` without two draws.

quantile_ci ¶

quantile_ci(x, q, level=0.95)

Get a quantile and its distribution-free confidence interval.

The interval is the pair of order statistics x_(r) <= x_(s) whose ranks are the (1 - level) / 2 and (1 + level) / 2 quantiles of the binomial distribution B(n, q) of the number of draws below the quantile, which covers the quantile with at least about level for any continuous distribution (Hahn & Meeker 1991).

Parameters:

Name	Type	Description	Default
`x`	`ArrayLike`	the draws.	required
`q`	`float`	the probability of the quantile, in (0, 1).	required
`level`	`float`	the level of the interval.	`0.95`

Returns:

Type	Description
`float`	The quantile, the lower and the upper end of its interval and the
`float`	number of draws which are not `NaN`; an end beyond the draws is `nan`,
`float`	e.g. the upper end of the 99 % quantile of 10 draws.

first_order_given_data ¶

first_order_given_data(x, y, n_bins=None)

Get the first-order index of an input from given draws, by binning.

The draws are split into n_bins bins of equal probability of the input (max(2, sqrt(n) / 2) by default), and the index is the variance of the means of the output in the bins over the variance of the output, Var(E[y | bin]) / Var(y) (Plischke, Borgonovo & Smith 2013), less the variance the bin means have by chance, (n_bins - 1) / n of the variance of the output, so an input without an effect has an index near 0. It needs no simulations beyond the draws of the propagation. For inputs which are correlated, the index of an input includes the effect of the inputs it is correlated with; the indices do not add up to the variance.

Plischke E, Borgonovo E, Smith CL (2013). Global sensitivity measures from given data. Eur J Oper Res 226:536-550.

Parameters:

Name	Type	Description	Default
`x`	`ArrayLike`	the draws of the input.	required
`y`	`ArrayLike`	the draws of the output, of the same draws.	required
`n_bins`	`int \| None`	the number of bins.	`None`

Returns:

Type	Description
`float`	The index, between 0 and 1; `nan` with fewer than 8 finite pairs or
`float`	an output without variance.