# uncertainty pack

7 nodes, in `noodlelab` and above.

## Uncertainty

(node-uncertainty.add_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` |  |

(node-uncertainty.expanded_uncertainty)=
### 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`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `expanded` | `Any` |  |
| `lower` | `Any` |  |
| `upper` | `Any` |  |

(node-uncertainty.mean_of_repeats)=
### 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` |  |

(node-uncertainty.measurement)=
### 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` |  |

(node-uncertainty.monte_carlo)=
### 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`. |

**Outputs**

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

(node-uncertainty.uncertainty_budget)=
### 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]]` |  |

(node-uncertainty.value_and_uncertainty)=
### 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` |  |