# uncertainty: Uncertainty estimation functions In metRology: Support for Metrological Applications

## Description

Functions for estimating measurement uncertainty from standard uncertainties and either sensitivity coefficients or (for some methods) expressions or functions. Correlation is supported via either a correlation or covariance matrix.

## Usage

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21``` ``` uncert(obj, ...) ## Default S3 method: uncert(obj, c, method = c("GUM", "MC"), cor, cov, distrib=NULL, distrib.pars=NULL, B=200, x=NULL, keep.x = TRUE, u=obj, ...) ## S3 method for class 'expression' uncert(obj, x, u, method=c("GUM", "NUM", "kragten", "k2", "MC"), cor, cov, distrib=NULL, distrib.pars=NULL, B=200, delta=0.01, keep.x = TRUE, ...) ## S3 method for class 'function' uncert(obj, x, u, method=c("NUM", "kragten", "k2", "MC"), cor, cov, distrib=NULL, distrib.pars=NULL, B=200, delta=0.01, keep.x = TRUE, ...) ## S3 method for class 'formula' uncert(obj, x, u, method=c("GUM", "NUM", "kragten", "k2", "MC"), cor, cov, distrib=NULL, distrib.pars=NULL, B=200, delta=0.01, keep.x = TRUE, ...) ```

## Arguments

 `obj` An R object used for method dispatch; see below. Methods currently exist for numeric vector, expression, function, or formula `u` For the default method, a numeric vector of standard uncertainties. For the formula or expression methods, a named list of standard uncertainties.Note that for the default method, `u` is set to the value of `obj`, allowing specification of either as the first argument `c` A numeric vector of senstivity coefficients. `x` For the expression or formula methods, an R object which can be used as an environment by `eval`. For the function method, a list of parameters supplied to FUN via `do.call`. `method` Method of uncertainty evaluation. The current list of methods is: GUMFirst-order error propagation (the “law of propagation of uncertainty”) as implemented by the GUM. NUMNumerical differentiation using a simple small step size. kragtenNumerical estimation of uncertainty following Kragten (Kragten (1994). k2A symmetric modification of Kragten's approach described by Ellison (Ellison (2005)). MCMonte Carlo simulation. `cor, cov` A (square, symmetric) correlation or covariance matrix, respectively. If neither is specified, `cor` is set to the identity matrix. `distrib` For `method="MC"`, a character vector of length `length(x)` or a named list of names of distribution functions associated with `u`. See Details for defaults. The list format may include user-specified functions. Silently ignored for other methods. `distrib.pars` For `method="MC"`, a list of lists of parameters describing the distributions associated with `u` to be passed to the relevant distribution function. If `distrib` is present but `distrib.pars` is not, neither are included in the return value unless `method="MC"`. See Details for defaults when `method="MC"`. Silently ignored for other methods. `B` Number of Monte Carlo replicates. `delta` Step size for numerical differentiation. `keep.x` For `method="MC"`, if `keepx=TRUE`, the simulated replicates of `x` are included in the return object. `...` Additional parameters to be passed to a function (for the function method) or used in an expression (for expression or formula method).

## Details

The default “GUM” method applies first-order error propagation principles to estimate a combined standard uncertainty from a set of sensitivity coefficients and either a set of standard uncertainties and a correlation matrix (which defaults to an identity matrix) or a covariance matrix. Both options use the same calculation, which is simply ` (t(c) %*% cov) %*% c `; standard uncertainties are first combined with the correlation matrix provided to form the covariance matrix. Since the correlation matrix defaults to the identity matrix, the default is combination without correlation.

The default method takes `obj` as a vector of uncertainty contributions unless `u` is specified, in which case `u` is used. It is not necessary to specify both. The expression method requires `obj` to be a differentiable R expression which can be evaluated in the environment `x` to provide a numeric value. For the function method, `obj` must be an R function which takes parameters from x and returns a numeric value. For the formula method, `obj` must be a formula with no left-hand side (e.g. `~a*x+b*x^2`) which can be evaluated in the environment `x` to provide a numeric value.

The formula and expression methods first calculate derivatives for the expression or formula, evaluate them using the supplied values of `x` and then pass the resulting sensitivity coefficients, with supplied `u`, `cor` or `cov` to uncert.default.

The derivatives for the “GUM” method (formula and expression methods only) are algorithmic derivatives (that is, algebraic or analytical derivatives) obtained using `deriv` applied to `expr` and `formula`.

Numerical derivatives are computed in different ways depending on the method specified:

- For `method="NUM"`, the derivatives are calculated as (f(x+delta*u)-f(x-delta*u))/(2*delta*u).

- For `method="kragten"`, derivatives are calculated as (f(x+u*sign(delta))-f(x))/u.

- For `method="k2"`, derivatives are calculated as (f(x+u)-f(x-u))/(2*u).

`"NUM"` is likely to give a close approximation to analytical differentiation provided that `delta` is appreciably less than 1 but not so small as to give step sizes near machine precision. `"k2"` is equivalent to `"NUM"` with `delta=1.0`. Both will give zero coefficients at stationary points (e.g minima), leading to under-estimation of uncertainty if the curvature is large. `"kragten"` uses a deliberately one-sided (and large) step to avoid this problem; as a result, `"kragten"` is a poorer (sometimes much poorer) estimate of the analytical differential but likely a better approximation to the truth.

Since these methods rely on `u`, if `u` is unspecified and `cov` is provided, `u` is extracted from `cov` (using `sqrt(diag(cov))`). It is assumed that the row and column order in `cov` is identical to the order of named parameters in `x`.

Derivatives (and uncertainty contributions) are computed for all parameters in `x`. Additional parameters used in `FUN`, `expr` or `formula` may be included in `...`; these will be treated as constants in the uncertainty calculation.

If `distrib` is missing, or if it is a list with some members missing, the distribution is assumed Normal and `distrib\$name` is set to `"norm"`. Similarly, if `distrib.pars` or a member of it is missing, the default parameters for `x\$name` are `list(mean=x\$name, sd=u\$name)`. If the list is not named, `names(x)` are used (so the list must be in order of `names(x)`).

If `method="MC"`, `uncert` calls `uncertMC`. Distributions and distribution parameters are required and B must be present and >1. See `uncertMC` for details of distribution specification.

For other evaluation methods, the distributions are silently ignored.

## Value

An object of class ‘uncert’ or, for `method="MC"` of class ‘uncertMC’. See `uncert-class` and `uncertMC-class` for details.

## Author(s)

S. L. R. Ellison s.ellison@lgc.co.uk

## References

JCGM 100 (2008) Evaluation of measurement data - Guide to the expression of uncertainty in measurement. http://www.bipm.org/utils/common/documents/jcgm/JCGM_100_2008_E.pdf. (JCGM 100:2008 is a public domain copy of ISO/IEC Guide to the expression of uncertainty in measurement (1995) ).

Kragten, J. (1994) Calculating standard deviations and confidence intervals with a universally applicable spreadsheet technique, Analyst, 119, 2161-2166.

Ellison, S. L. R. (2005) Including correlation effects in an improved spreadsheet calculation of combined standard uncertainties, Accred. Qual. Assur. 10, 338-343.

`uncert-class`, `deriv`
For `method="MC"` see `uncertMC` and `uncertMC-class`.
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28``` ``` expr <- expression(a+b*2+c*3+d/2) x <- list(a=1, b=3, c=2, d=11) u <- lapply(x, function(x) x/10) u.expr<-uncert(expr, x, u, method="NUM") u.expr #Compare with default: uncert(u=c(0.1, 0.3, 0.2, 1.1), c=c(1.0, 2.0, 3.0, 0.5)) #... or with function method f <- function(a,b,c,d) a+b*2+c*3+d/2 u.fun<-uncert(f, x, u, method="NUM") u.fun #.. or with the formula method u.form<-uncert(~a+b*2+c*3+d/2, x, u, method="NUM") u.form #An example with correlation u.cor<-diag(1,4) u.cor[3,4]<-u.cor[4,3]<-0.5 u.formc<-uncert(~a+b*2+c*3+d/2, x, u, method="NUM", cor=u.cor) u.formc #A Monte Carlo example #See uncertMC for a less linear example u.formc.MC<-uncert(~a+b*2+c*3+d/2, x, u, method="MC", cor=u.cor, B=200) u.formc.MC ```