uncertainty pack¶

9 nodes, in noodlelab and in the tiers that build on it.

Uncertainty¶

Add Uncertainty (Type B)¶

uncertainty.add_uncertainty

Give a value an uncertainty from a certificate, a resolution or a tolerance (GUM Type B), in the value’s unit. A half-width a becomes a/√3 for a rectangular distribution (a resolution, a tolerance) and a/√6 for a triangular one. On a value that is already uncertain, this adds another independent component.

Inputs

Name	Type	Description
`value`	`float \| Quantity`
`uncertainty`	`float`	Default `0.0`.
`given_as`	`Literal['standard uncertainty', 'expanded, k = 2', 'half-width, rectangular', 'half-width, triangular', 'relative, %']`	Default `'standard uncertainty'`.
`name`	`str`	Names this input in uncertainty budgets Default `''`.

Outputs

Name	Type	Description
`result`	`Uncertain`

Correlate¶

uncertainty.correlate

Two values with the correlation coefficient r between them (GUM 5.2): each keeps its value and standard uncertainty (and unit), and u(a, b) = r·u(a)·u(b). Use it for inputs that share a cause, such as two readings of one instrument (r near 1) or a quantity and its complement.

Inputs

Name	Type	Description
`a`	`Uncertain`
`b`	`Uncertain`
`r`	`float`	-1 to 1 Default `0.0`.
`name_a`	`str`	Names this input in uncertainty budgets Default `''`.
`name_b`	`str`	Names this input in uncertainty budgets Default `''`.

Outputs

Name	Type	Description
`a`	`Uncertain`
`b`	`Uncertain`

Correlation Matrix Input¶

uncertainty.correlation_matrix

Give several values the correlations of a matrix (GUM 5.2): r(i, j) between value i and value j. The matrix must be symmetric, with ones on the diagonal, and positive semidefinite, which correlations that can all hold at once are. Each value keeps its value, standard uncertainty and unit; a set of named values (from Values) names them in budgets. Monte Carlo draws them jointly. Values that already depend on several sources keep only their total uncertainty (the node warns), as with Correlate.

Inputs

Name	Type	Description
`values`	`Any`	Uncertain values: a list, an uncertain array or a set of named values
`matrix`	`Any`	n×n correlation coefficients: rows of numbers, a table or text

Outputs

Name	Type	Description
`result`	`list[Any]`

Expanded Uncertainty¶

uncertainty.expanded_uncertainty

The expanded uncertainty U = k·u and the interval x ± U (GUM 6). k = 2 covers about 95 % for a normal distribution.

Inputs

Name	Type	Description
`value`	`Uncertain`
`k`	`float`	2 for about 95 % Default `2.0`.
`method`	`Literal['fixed k', 'from dof']`	From dof: k from Student’s t and the effective degrees of freedom Default `'fixed k'`.
`coverage`	`float`	Used with ‘from dof’ Default `0.95`.

Outputs

Name	Type	Description
`expanded`	`Any`
`lower`	`Any`
`upper`	`Any`
`k`	`float`
`dof`	`float \| None`

Mean of Repeats (Type A)¶

uncertainty.mean_of_repeats

The mean of repeated readings, with its standard uncertainty s/√n (GUM Type A, 4.2). std is the spread of single readings (s, n - 1). Readings that carry an uncertainty of their own (from an instrument’s calibration, say) pass it on to the mean too, combined with s/√n.

Inputs

Name	Type	Description
`values`	`ndarray \| list`
`name`	`str`	Names this input in uncertainty budgets Default `''`.
`unit`	`str`	Default `''`.

Outputs

Name	Type	Description
`mean`	`Uncertain`
`std`	`float`
`count`	`int`

Measurement¶

uncertainty.measurement

A measured value with its standard uncertainty, typed as text: 9.81 ± 0.02 m/s^2, 9.81 +/- 0.02 or 9.81(2).

Inputs

Name	Type	Description
`value`	`Uncertain`	Default `'9.810 ± 0.020 m/s**2'`.
`name`	`str`	Names this input in uncertainty budgets Default `''`.

Outputs

Name	Type	Description
`result`	`Uncertain`

Monte Carlo¶

uncertainty.monte_carlo

Propagate the distributions of the inputs by simulation (GUM Supplement 1, JCGM 101): everything upstream that depends on an uncertain input runs trials times, each input drawn from its own distribution (normal, rectangular, triangular, or Student’s t for a mean of few readings). Gives the mean and standard uncertainty, the coverage interval, the samples and a histogram, and says whether the linear (GUM) result agrees (JCGM 101, 8), which it may not for non-linear models. Arrays are handled element by element.

Inputs

Name	Type	Description
`value`	`Any`	The result to study: link it from any node
`trials`	`int`	Default `10000`.
`coverage`	`float`	Default `0.95`.
`seed`	`int`	Default `1`.
`mode`	`Literal['fixed', 'adaptive']`	Adaptive: batches of trials until two digits of u are stable Default `'fixed'`.
`max_trials`	`int`	The most an adaptive run Default `1000000`.
`interval`	`Literal['symmetric', 'shortest']`	The coverage interval: probabilistically symmetric or shortest Default `'symmetric'`.

Outputs

Name	Type	Description
`result`	`Any`
`uncertainty`	`Any`
`lower`	`Any`
`upper`	`Any`
`samples`	`Any`
`histogram`	`Any`
`agrees_with_gum`	`bool \| None`
`gum_comparison`	`str`
`trials`	`int`
`interval`	`str`

Uncertainty Budget¶

uncertainty.uncertainty_budget

Which inputs the uncertainty of a result comes from: each named input’s contribution |∂y/∂xᵢ|·u(xᵢ), in the result’s unit, and its share of the variance. Connect to Add Table for the report. For an array, each input’s largest contribution over the elements, and the element where it is.

Inputs

Name	Type	Description
`value`	`Uncertain`

Outputs

Name	Type	Description
`result`	`dict[str, list[Any]]`

Value and Uncertainty¶

uncertainty.value_and_uncertainty

Split a value into its best estimate, its standard uncertainty (in the value’s unit) and the relative uncertainty u/|x|. An array is split element by element.

Inputs

Name	Type	Description
`value`	`Uncertain`

Outputs

Name	Type	Description
`value`	`Any`
`uncertainty`	`Any`
`relative`	`Any`