propagate: Propagation of uncertainty using higher-order Taylor...

View source: R/propagate.R

propagateR Documentation

Propagation of uncertainty using higher-order Taylor expansion and Monte Carlo simulation

Description

A general function for the calculation of uncertainty propagation by first-/second-order Taylor expansion and Monte Carlo (MC) simulation including covariances. Input data can be any symbolic/numeric differentiable expression and data based on summaries (Mean/SEM/DOF), experimental measurements or sampled from distributions. Uncertainty propagation is based completely on matrix calculus accounting for full covariance structure. Monte Carlo simulation is conducted using either a Gaussian copula with marginal t-distributions, each with its own degrees of freedom, so that correlated input quantities with different degrees of freedom can be propagated jointly (scaled and shifted according to JCGM 101:2008, 6.4.9), or the multivariate t-distribution of JCGM 102:2011 (see mc.margins). Coverage intervals are calculated from the expanded uncertainties by WelchSatter's effective degrees of freedom or from the order statistics of the MC evaluations. The demos JCGM100, JCGM101, JCGM102, JCGM106, EMUE, NIST1900 and QUAM reproduce published examples of these documents, and COPULA checks the Gaussian copula against published and exact results; see doGauge.

Usage

propagate(expr, data, type = c("stat", "raw", "sim"), cov = c("diag", "full"), 
          df.tot = NULL, k = NULL, nsim = 1000000, alpha = 0.05, 
          exp.uc = c("1st", "2nd"), mc.margins = c("S1", "mvt"), ws.group = NULL,
          adaptive = FALSE, ndig = 2, max.nsim = 1E7,
          ad.interval = c("symmetric", "shortest"), check = TRUE, ...)

Arguments

expr

an expression, such as expression(x/y).

data

a dataframe or matrix containing either a) the means (1^{st} row), standard uncertainties (2^{nd} row; SEMs for Type A) and optional degrees of freedom (3^{rd} row), b) raw measurement values or c) sampled distribution data generated from any of R's distributions or those implemented in this package (rDistr).

type

type of input data. Either stat for summary data, raw for experimental measurements or sim for distribution data. See 'Details'.

cov

use only "diag"onal variances, the "full" covariance matrix with off-diagonals or an external covariance matrix with the same column names as data. Like data, an external matrix is reduced to the variables of expr. See 'Details'.

df.tot

an optional total (effective) degrees of freedom \nu_{\mathrm{tot}} of the output that overrides the one obtained from WelchSatter. Only affects the coverage factor k, not the Monte Carlo sampling. See 'Details'.

k

an optional coverage factor that overrides the one obtained from WelchSatter.

nsim

the number of Monte Carlo trials M, minimum is 10000.

alpha

1 - coverage probability p of the coverage intervals.

exp.uc

Should the expanded uncertainty and coverage interval be calculated from the "1st"-order or "2nd"-order uncertainty?

mc.margins

the probability distribution assigned to the input quantities for Monte Carlo simulation with type = "stat" or "raw": "S1" (default) for scaled and shifted t-distributions according to JCGM 101:2008, 6.4.9, each with the degrees of freedom of its own input quantity, joined by a Gaussian copula with the input correlation matrix; "mvt" for the multivariate t-distribution of JCGM 102:2011, 5.3.2, for jointly observed quantities (type = "raw", cov = "full"), or for summary data whose finite degrees of freedom are equal and share one variance estimate (type = "stat", as in predictNLS). Ignored for type = "sim". The variance-matched margins of versions up to 1.2-0 ("GUF") were removed in 1.3-0; see 'Details'.

ws.group

an optional vector that labels input quantities estimated jointly from the same n observations, passed to WelchSatter as group (Willink 2007, Result 1). For type = "raw" with cov = "full" and complete data, all inputs are grouped automatically.

adaptive

FALSE (default), TRUE or "validation": adaptive Monte Carlo procedure of JCGM 101:2008, 7.9.4, with the numerical tolerance \delta or, for "validation", \delta/5 as recommended for the validation of the GUM uncertainty framework (8.2). nsim is then ignored. See 'Details'.

ndig

the number of significant decimal digits of u(y) that defines the numerical tolerance \delta of the adaptive procedure (7.9.2).

max.nsim

the maximum number of Monte Carlo trials of the adaptive procedure.

ad.interval

the coverage interval whose endpoints enter the stopping rule of the adaptive procedure: probabilistically symmetric (default) or shortest.

check

logical. If TRUE, the Monte Carlo margins are fitted with a scaled/shifted t-distribution to check for proper construction, see summary.propagate.

...

other parameters to be supplied to future methods.

Details

The different type definitions are the following:

1) "stat", GUM 4.2: Statistical summary data (Mean, SEM, DOF), Type A evaluation

     V1            V2
|------------|------------|
|   Mean_1   |   Mean_2   |  => Means in 1st row
|------------|------------|
|   SEM_1    |   SEM_2    |  => SEMs (uncertainties) in 2nd row
|------------|------------|
|  (DOF_1)   |  (DOF_2)   |  => optional DOFs in 3rd row 
|------------|------------|

Covariance matrix: from \text{SEMs}^2 as diagonals (cov = "diag") or supplied externally.

2) "raw", GUM 4.2: Raw measurement values in rows, Type A evaluation

      V1           V2
|------------|------------| -- 
|    x_1     |    y_1     |   \
|------------|------------|    \
|    x_2     |    y_2     |     |
|------------|------------|     |- Single raw values in rows 1...n 
|    x_3     |    y_3     |     |
|------------|------------|    /
|    x_n     |    y_n     |   /
|------------|------------| --

Mean, SEM and DOF are estimated from the data.
Covariance matrix: from estimated \text{SEMs}^2 as diagonals (cov = "diag"), full covariance matrix \mathrm{cov}(\mathrm{data})/n (cov = "full") or supplied externally.

3) "sim", GUM 4.3: Random samples from distributions x_i, y_i, ... \sim F_1, F_2, ..., Type B evaluation

      F1           F2
|------------|------------| -- 
|     x_1    |    y_1     |   \
|------------|------------|    \
|     x_2    |    y_2     |     |
|------------|------------|     |- MC samples in rows 1...M 
|     x_3    |    y_3     |     |
|------------|------------|    /
|     x_M    |    y_M     |   /
|------------|------------| --

Mean, SD and DOF are estimated from the data. The latter will be high (M - 1) and approximate a normal distribution.
Covariance matrix: from estimated \text{SDs}^2 as diagonals (cov = "diag"), full covariance matrix \mathrm{cov}(\mathrm{data}) (cov = "full") or supplied externally.

For all types: Expanded uncertainty U and coverage intervals from U = k \cdot u, k = t_{\mathrm{ws.df}}(1-\alpha/2), \mathrm{CI} = [\hat{y} - U, \hat{y} + U], and empirical [\alpha/2, 1-\alpha/2] quantiles of the MC output distribution.

propagate tries "hard" to guess the data type and gives a comment (no change in settings!), i.e. Type A summary => 2/3 rows, Type A raw measurement => 3 < rows < 1000, Type B distributions => rows >= 1000.

The implemented methods are:
1) Uncertainty propagation:
The propagated uncertainties are calculated by first-/second-order Taylor expansion of f around the input means \bar{\mathbf{x}}, accounting for the full covariance structure by matrix algebra. With N input quantities, {\color{red}\nabla} is the 1 \times N gradient with elements {\color{red}j_i} = \partial f/\partial x_i, {\color{blue}\mathbf{H}} the symmetric N \times N Hessian with elements {\color{blue}h_{ik}} = \partial^2 f/\partial x_i \partial x_k, and \mathbf{\Sigma} the N \times N covariance matrix with variances \sigma_i^2 and covariances \sigma_{ik} = \rho_{ik}\sigma_i\sigma_k. All derivatives are evaluated at \bar{\mathbf{x}}. For two inputs x_1, x_2, the matrix expressions reduce to the classical notation as follows:

{\color{red}\nabla} = \left[ \begin{array}{cc} {\color{red}j_1} & {\color{red}j_2} \end{array} \right], \quad {\color{blue}\mathbf{H}} = \left[ \begin{array}{cc} {\color{blue}h_{11}} & {\color{blue}h_{12}} \\ {\color{blue}h_{12}} & {\color{blue}h_{22}} \end{array} \right], \quad \mathbf{\Sigma} = \left[ \begin{array}{cc} \sigma_1^2 & \sigma_{12} \\ \sigma_{12} & \sigma_2^2 \end{array} \right]

First-order mean:

\mathrm{E}[y] = f(\bar{\mathbf{x}})

First-order variance:

\sigma_y^2 = {\color{red}\nabla}\,\mathbf{\Sigma}\,{\color{red}\nabla}^T = {\color{red}j_1}^2 \sigma_1^2 + 2\,{\color{red}j_1 j_2}\,\sigma_{12} + {\color{red}j_2}^2 \sigma_2^2 = \underbrace{\sum_{i=1}^{N} {\color{red}j_i}^2 \sigma_i^2 + 2 \sum_{i=1}^{N-1} \sum_{k=i+1}^{N} {\color{red}j_i j_k}\, \sigma_{ik}}_{\mathrm{classical\;notation}}

This is the law of propagation of uncertainty, JCGM 100:2008, Eq. (13); for uncorrelated inputs it reduces to \sum_i j_i^2 \sigma_i^2 (Eq. (10)). Only for fully correlated inputs (\rho_{ik} = +1 for all pairs) does it become \sigma_y^2 = \left(\sum_i j_i \sigma_i\right)^2, the linear sum of uncertainty contributions (JCGM 100:2008, 5.2.2, Note 1).

Second-order mean:

\mathrm{E}[y] = f(\bar{\mathbf{x}}) + {\color{blue}\frac{1}{2}\,\mathrm{tr}(\mathbf{H}\mathbf{\Sigma})} = f(\bar{\mathbf{x}}) + \frac{1}{2}\left( {\color{blue}h_{11}}\sigma_1^2 + 2\,{\color{blue}h_{12}}\,\sigma_{12} + {\color{blue}h_{22}}\sigma_2^2 \right) = f(\bar{\mathbf{x}}) + \frac{1}{2} \sum_{i=1}^{N} \sum_{k=1}^{N} {\color{blue}h_{ik}}\, \sigma_{ik}

with \sigma_{ii} = \sigma_i^2. The term \frac{1}{2}\mathrm{tr}(\mathbf{H}\mathbf{\Sigma}) corrects the bias of f(\bar{\mathbf{x}}) for nonlinear f, as the first-order expansion assumes linearity around \bar{\mathbf{x}}.

Second-order variance:

\sigma_y^2 = {\color{red}\nabla\,\mathbf{\Sigma}\,\nabla^T} + {\color{blue}\frac{1}{2}\,\mathrm{tr}(\mathbf{H}\mathbf{\Sigma}\mathbf{H}\mathbf{\Sigma})}

For two inputs, with \mathbf{A} = \mathbf{H}\mathbf{\Sigma} and \mathrm{tr}(\mathbf{A}^2) = a_{11}^2 + 2a_{12}a_{21} + a_{22}^2:

{\color{blue}\frac{1}{2}\,\mathrm{tr}(\mathbf{H}\mathbf{\Sigma}\mathbf{H}\mathbf{\Sigma})} = \frac{1}{2}\left( {\color{blue}h_{11}}\sigma_1^2 + {\color{blue}h_{12}}\sigma_{12} \right)^2 + \left( {\color{blue}h_{11}}\sigma_{12} + {\color{blue}h_{12}}\sigma_2^2 \right)\left( {\color{blue}h_{12}}\sigma_1^2 + {\color{blue}h_{22}}\sigma_{12} \right) + \frac{1}{2}\left( {\color{blue}h_{12}}\sigma_{12} + {\color{blue}h_{22}}\sigma_2^2 \right)^2

which, for uncorrelated inputs (\sigma_{12} = 0), reduces to

{\color{blue}\frac{1}{2}\,\mathrm{tr}(\mathbf{H}\mathbf{\Sigma}\mathbf{H}\mathbf{\Sigma})} = \frac{1}{2}{\color{blue}h_{11}}^2\sigma_1^4 + {\color{blue}h_{12}}^2\sigma_1^2\sigma_2^2 + \frac{1}{2}{\color{blue}h_{22}}^2\sigma_2^4 = \sum_{i=1}^{N} \sum_{k=1}^{N} \frac{1}{2}\,{\color{blue}h_{ik}}^2\, \sigma_i^2 \sigma_k^2

In general, \mathrm{tr}(\mathbf{H}\mathbf{\Sigma}\mathbf{H}\mathbf{\Sigma}) \neq \left[\mathrm{tr}(\mathbf{H}\mathbf{\Sigma})\right]^2; equality holds, e.g., if \mathbf{\Sigma} has rank one (all |\rho_{ik}| = 1) or if \mathbf{H} has rank one. Likewise, the operator notation \frac{1}{n!}\left(\sum_i \sigma_i \frac{\partial}{\partial x_i}\right)^n f is valid only for fully correlated inputs and is not used here.

Assumptions: The second-order mean and variance are the exact moments of the second-order Taylor polynomial of f if the inputs are Gaussian (zero third central moments, fourth central moments 3\sigma_i^4), see Wang & Iyer (2005). For non-Gaussian inputs (e.g. rectangular or t-distributed), u.2 is an approximation; the moments extension below (u.2m) removes this restriction. The Note to JCGM 100:2008, 5.1.2, additionally contains terms with third derivatives \frac{\partial f}{\partial x_i}\frac{\partial^3 f}{\partial x_i \partial x_k^2}, which are not part of the second-order Taylor polynomial. They vanish for models that are linear in each input separately, such as the end gauge model of JCGM 100:2008, H.1 (see 'Examples'), but not in general. The Taylor expansion uses \mathbf{\Sigma} as given, i.e. the standard uncertainties u_i of the GUM uncertainty framework, independent of mc.margins.

Moments extension: second-order variance with the input moments (u.2m). u.2 uses Gaussian input moments (third central moment 0, fourth 3u_i^4). Since version 1.3-0, propagate also returns u.2m, the second-order variance with the actual skewness \gamma_{1,i} and excess kurtosis \gamma_{2,i} of each input (Cox 1979; Mekid & Vaja 2008). For independent inputs, the variance of the second-order Taylor polynomial is

u_{2m}^2(y) = u_2^2(y) + \sum_i \left(\frac{1}{4} h_{ii}^2 \gamma_{2,i} u_i^4 + c_i h_{ii} \gamma_{1,i} u_i^3\right),

i.e. the main second-order term of each input becomes \frac{1}{4} h_{ii}^2 (\gamma_{2,i} + 2) u_i^4 + c_i h_{ii} \gamma_{1,i} u_i^3 instead of \frac{1}{2} h_{ii}^2 u_i^4; the interaction terms h_{ik}^2 u_i^2 u_k^2 are unchanged. \gamma_1 and \gamma_2 are taken from the stated distributions of a budget from makeDat or corDist (skewness and excess kurtosis: normal 0 and 0, rectangular 0 and -1.2, triangular 0 and -0.6, arcsine 0 and -1.5, t_\nu 0 and 6/(\nu-4)), from the sample moments for other samples with type = "sim", and from the t_\nu-distribution for type = "raw" and "stat" with finite degrees of freedom (Gaussian for \nu = \infty; for \nu \le 4 the kurtosis is infinite and the Gaussian value is used). They are returned in the component moments. The second-order mean does not depend on these moments, so there is no mean.2m.
u.2m is exact for quadratic models with independent inputs; for correlated pairs, the Gaussian joint moments are kept. For models with strong higher-order terms, u.2m need not be closer to the Monte Carlo value than u.2; the difference u.2m - u.MC then measures these terms. With mc.margins = "S1", u.MC of Type A inputs also contains the factor \nu/(\nu-2) of the t-distribution (see below). summary.propagate prints u.1, u.2, u.2m and u.MC side by side.
For setups in which no symbolic derivative is available (e.g. e <- expression(abs(x)) => "Function 'abs' is not in the derivatives table", or atan2) the function automatically switches from symbolic (using makeGrad or makeHess) to numeric (numGrad or numHess) differentiation and gives a message.
The function will try to evaluate the expression in an environment using eval which results in a significant speed enhancement (~ 10-fold). If that fails, evaluation is done over the rows of the simulated data using apply.

2) Monte Carlo simulation:
For type = "stat" and type = "raw", nsim input vectors are drawn from a joint distribution constructed from the means \bar{x}_i, standard uncertainties u_i (2nd row of data or SEMs estimated from raw data), degrees of freedom \nu_i and the covariance matrix \mathbf{\Sigma}.

For type = "sim", the supplied samples are used directly and mc.margins has no effect. The GUM uncertainty framework uses the sample means and standard deviations, unless the samples carry the attribute "budget" from makeDat; then the estimates, standard uncertainties and degrees of freedom of that budget are used, as in JCGM 101:2008 (a message is given). The expression is evaluated for each input vector. The mean and standard deviation of the M = nsim results give mean.MC and u.MC. Coverage intervals for coverage probability p = 1 - \alpha are formed from the order statistics y_{(1)} \le \ldots \le y_{(M)} exactly as in JCGM 101:2008, 7.7: with q = pM if pM is an integer, and the integer part of pM + 1/2 otherwise, [y_{(r)}, y_{(r+q)}] is a 100p% coverage interval. The probabilistically symmetric interval (in sim, 7.7.1) takes r = (M-q)/2 if this is an integer, and the integer part of (M-q+1)/2 otherwise. The shortest interval (in ci.short, 7.7.2) takes the r^* that minimises y_{(r+q)} - y_{(r)}; it is preferable for asymmetric output distributions, but its coverage probability is marginally below 100p% for finite M (7.7.2, Note).

Adaptive Monte Carlo procedure. With adaptive = TRUE, blocks of M = \max(\lceil 100/\alpha \rceil, 10^4) trials are generated until twice the standard deviations associated with the averages of the h block values of y, u(y) and of both coverage interval endpoints (ad.interval) are not larger than the numerical tolerance \delta = \frac{1}{2} 10^l, with u(y) = c \times 10^l and c having ndig digits (JCGM 101:2008, 7.9.2 and 7.9.4). All hM trials are then used for the results. adaptive = "validation" replaces \delta by \delta/5 (8.2), which needs about 25 times more trials; with this setting, the adaptive procedure reproduces the numbers of trials reported in JCGM 101:2008, 9.2.2, 9.3 and 9.5. For type = "sim", the adaptive procedure needs samples from makeDat(..., output = "sim"), whose uncertainty budget is used to draw the further blocks.

The two t-distribution models (mc.margins):
Both models describe the state of knowledge about an input quantity from a Type A evaluation, i.e. from n indications with sample mean \bar{x} and standard uncertainty u = s/\sqrt{n} with \nu = n - 1 degrees of freedom (JCGM 100:2008, 4.2 and G.3). They differ in how the t-distribution is scaled and in how several inputs are joined.

mc.margins Marginal of X_i Var(X_i) Reference
"S1" (default) t_{\nu_i}(\bar{x}_i, u_i^2) \frac{\nu_i}{\nu_i-2} u_i^2 JCGM 101:2008, 6.4.9
"mvt" t_{\nu}\left(\bar{x}_i, \frac{n-1}{n-N} u_i^2\right), \nu = n - N \frac{n-1}{n-N-2} u_i^2 JCGM 102:2011, 5.3.2

Correlated inputs with individual degrees of freedom ("S1").
A common situation in practice is a set of correlated input quantities whose standard uncertainties are based on different numbers of observations, e.g. two quantities evaluated from 4 and 20 indications with a known correlation. The JCGM documents do not provide a joint input distribution for this case:

  • the GUM uncertainty framework uses the degrees of freedom only for the output quantity, through the Welch-Satterthwaite formula, which assumes independent inputs (JCGM 100:2008, G.4.2);

  • JCGM 101:2008 assigns a t-distribution with its own \nu_i to each input (6.4.9), but independently, without a joint distribution for correlated inputs;

  • the multivariate t-distribution of JCGM 102:2011, 5.3.2, allows correlation, but forces one common \nu = n - N on all inputs, because they are assumed to be observed jointly.

propagate closes this gap with a Gaussian copula (Sklar's theorem; Possolo 2010): the dependence structure is that of a multivariate Gaussian with the input correlation matrix \mathbf{R}, and each margin is the scaled and shifted t-distribution t_{\nu_i}(\bar{x}_i, u_i^2) with its own \nu_i. Inputs from few observations thus keep their heavy tails, inputs from many observations stay close to Gaussian, and the correlation is preserved, all in one joint distribution. Because the margins are obtained by strictly increasing transformations of the Gaussian copula, the rank correlations equal those of the Gaussian copula exactly (Spearman \rho_S = \frac{6}{\pi}\arcsin\frac{\rho}{2}) for any combination of \nu_i; the Pearson correlation is somewhat smaller for heavy-tailed margins (see 'Checks'). For uncorrelated inputs, the construction reduces exactly to the independent t-distributions of JCGM 101:2008. The individual \nu_i used are returned in df.MC and are verified by fitting each margin in summary.propagate (check = TRUE). The margins and correlations can be checked against published examples with doGauge or demo("COPULA", package = "propagate").

a) mc.margins = "S1": scaled and shifted t-distributions as margins (JCGM 101:2008, 6.4.9), joined by a Gaussian copula (Possolo 2010; the copula is not part of JCGM 101).
Assigning a non-informative prior to the unknown mean and variance of Gaussian indications, Bayes' theorem gives the scaled and shifted t-distribution t_\nu(\bar{x}, s^2/n) with \nu = n - 1 for the input quantity (6.4.9.2). Its scale parameter is the standard uncertainty u = s/\sqrt{n} itself, so that its variance \frac{\nu}{\nu-2} u^2 is larger than u^2 and exists only for \nu > 2, i.e. n > 3 (6.4.9.4). A draw is made as \xi = \bar{x} + u \cdot t with t from the standard t-distribution t_\nu (6.4.9.5). The same distribution is assigned when a calibration certificate states a best estimate x, an expanded uncertainty U_p, a coverage factor k_p and an effective degrees of freedom \nu_{\mathrm{eff}}: t_{\nu_{\mathrm{eff}}}(x, (U_p/k_p)^2) (6.4.9.7). For type = "stat", enter x, U_p/k_p and \nu_{\mathrm{eff}} as the three rows of data. For \nu \to \infty the distribution becomes the Gaussian of 6.4.7. For a linear model Y = X, the MC coverage interval \bar{x} \pm t_{\nu}(1-\alpha/2) \, u then coincides with the GUM coverage interval, while u.MC exceeds u.1 by a factor of \sqrt{\nu/(\nu-2)}.

Removed in 1.3-0: variance-matched t-distributions (mc.margins = "GUF", the only behaviour up to version 1.2-0).
Each margin was the t-distribution of a), divided by \sqrt{\nu_i/(\nu_i-2)}, so that \mathrm{Var}(X_i) = u_i^2. This rescaling removes the additional dispersion that the t-distribution assigns to an input estimated from few indications, which the GUM uncertainty framework accounts for by the coverage factor t_\nu and JCGM 101:2008 by the scale of the t-distribution. The Monte Carlo coverage interval was therefore about \pm 2u for all \nu (for a single input from n = 5 indications \pm 1.96u instead of \pm 2.78u), with an actual coverage probability of about 88 % instead of 95 % for n = 5 and 92 % for n = 10. Monte Carlo coverage intervals of versions up to 1.2-0 for Type A inputs with few indications should therefore be recomputed; the results of the GUM uncertainty framework (prop) are not affected.

b) mc.margins = "mvt": multivariate t-distribution (JCGM 102:2011, 5.3.2).
If N input quantities are observed jointly n times, with n > N, assigning a non-informative prior to their unknown expectation and covariance matrix gives the multivariate t-distribution t_\nu(\bar{\mathbf{x}}, \mathbf{S}/n) with \nu = n - N and \mathbf{S} = \frac{1}{\nu}\sum_{r=1}^{n}(\mathbf{x}_r - \bar{\mathbf{x}})(\mathbf{x}_r - \bar{\mathbf{x}})^T (5.3.2.1). Note the divisor \nu = n - N instead of n - 1. The expectation \bar{\mathbf{x}} exists for \nu > 1 and the covariance matrix \frac{\nu}{\nu-2}\,\mathbf{S}/n for \nu > 2 (5.3.2.3). A draw is made as \boldsymbol{\xi} = \bar{\mathbf{x}} + \mathbf{L}\mathbf{z}\sqrt{\nu/w}, with \mathbf{z} a vector of N standard Gaussian draws, a single draw w from \chi^2_\nu and \mathbf{L} the lower Cholesky factor of \mathbf{S}/n = \mathbf{L}\mathbf{L}^T (5.3.2.4). In terms of the covariance matrix of the means used for the Taylor expansion, \mathbf{\Sigma} = \mathrm{cov}(\mathrm{data})/n, the scale matrix is \mathbf{S}/n = \frac{n-1}{n-N}\,\mathbf{\Sigma}. For N = 1 this reduces exactly to a).
All inputs share one \nu, which decreases with the number of jointly observed quantities, and all inputs are coupled through the common variable w: they are dependent even when uncorrelated, and extreme values occur jointly (tail dependence), unlike the Gaussian copula of a). For type = "raw", it requires cov = "full" and complete joint observations (no NAs). For type = "stat", all inputs with finite degrees of freedom (3rd row of data) must have the same \nu and share one \chi^2_\nu variable, with the supplied covariance matrix as scale matrix; inputs with degrees of freedom Inf are sampled from independent Gaussian distributions and must be uncorrelated with the others. This is the joint distribution of regression coefficients that share one residual variance estimate (see predictNLS). As noted in 5.3.2.1 of JCGM 102:2011, a different prior would change the degrees of freedom or even the distribution; a) and b) are therefore both defensible models for correlated Type A inputs, which can give different results for nonlinear models.

Sampling procedure for mc.margins = "S1":

  1. Convert the covariance matrix \mathbf{\Sigma} to the correlation matrix \mathbf{R}: \mathbf{R}_{ij} = \mathbf{\Sigma}_{ij}/\sqrt{\mathbf{\Sigma}_{ii}\mathbf{\Sigma}_{jj}}.

  2. Generate \mathbf{v} \sim C_{\mathbf{R}}^{\text{Gauss}} from the Gaussian copula (uniform marginals on [0,1]). According to Sklar's theorem, F(x_1, \ldots, x_N) = C_{\mathbf{R}}^{\text{Gauss}}(F_1(x_1), \ldots, F_N(x_N)).

  3. Transform each margin: z_i = F_{t,\nu_i}^{-1}(v_i), with F_{t,\nu_i} the CDF of the standard t-distribution with \nu_i degrees of freedom.

  4. Scale and shift: X_i = \bar{x}_i + u_i \cdot z_i, giving the MC-simulated matrix \mathbf{X}^\text{MC}.

In the univariate case, rt(nsim, df) replaces steps 1-3. For "mvt", steps 1-4 are replaced by the draw of 5.3.2.4 given in b).

Degrees of freedom: The margins always use the per-input degrees of freedom: the 3rd row of data for type = "stat" (Inf if absent, i.e. Gaussian margins as in JCGM 101:2008, 6.4.7), n_i - 1 for type = "raw", and, for "mvt", n - N with type = "raw" or the common \nu of the 3rd row of data with type = "stat". The degrees of freedom actually used are returned in df.MC. df.tot is an effective degrees of freedom of the output and only enters the coverage factor k (JCGM 100:2008, G.4); it is not used for sampling. For \nu \le 2, the variance of the t-distribution does not exist: "S1" and "mvt" proceed with a message that u.MC is not meaningful. For \nu = 1, the expectation does not exist either, so median.MC and the MC coverage interval should be used.

Checks: The function conducts the following three additional checks, visible in summary.propagate. They compare the MC input with the covariance matrix it should have under the chosen model, \mathbf{\Sigma}^{\text{target}} (returned as covMat.target): \mathbf{D}\mathbf{\Sigma}\mathbf{D} with \mathbf{D} = \mathrm{diag}\left(\sqrt{\nu_i/(\nu_i-2)}\right) for "S1", \frac{n-1}{n-N-2}\mathbf{\Sigma} for "mvt" with type = "raw", and \frac{\nu}{\nu-2}\mathbf{\Sigma} for "mvt" with type = "stat".

  1. Relative Frobenius norm of the difference between the MC-derived covariance matrix \mathbf{\hat{\Sigma}}^{\text{MC}} and the target covariance matrix \mathbf{\Sigma}^{\text{target}}:

    \varepsilon_F = \frac{\sqrt{\sum_{i=1}^{N}\sum_{j=1}^{N}\left(\mathbf{\hat{\Sigma}}_{ij}^{\text{MC}}-\mathbf{\Sigma}_{ij}^{\text{target}}\right)^2}}{\sqrt{\sum_{i=1}^{N}\sum_{j=1}^{N}\left(\mathbf{\Sigma}_{ij}^{\text{target}}\right)^2}}

  2. Relative Frobenius norm of the difference between the MC-derived correlation matrix \mathbf{\hat{R}}^{\text{MC}} and the input correlation matrix \mathbf{R}:

    \varepsilon_F = \frac{\sqrt{\sum_{i=1}^{N}\sum_{j=1}^{N}\left(\hat{\mathbf{R}}_{ij}^{\text{MC}}-\mathbf{R}_{ij}\right)^2}}{\sqrt{\sum_{i=1}^{N}\sum_{j=1}^{N}\mathbf{R}_{ij}^2}}

  3. For each marginal component X_i, a shifted and scaled t-distribution is fitted independently by estimating \hat{\mu}_i, \hat{\sigma}_i and \hat{\nu}_i. \hat{\sigma}_i is reported on the scale of u_i and \hat{\nu}_i should be compared with df.MC.

For "mvt", both norms tend to zero with increasing nsim. For "S1", the Pearson correlation of t-margins is smaller than the copula parameter when \nu_i is small (e.g. 0.65 instead of 0.70 for \nu = (3, 10), while the rank correlation is preserved exactly), so that both norms keep a small, \nu-dependent floor for correlated inputs that does not vanish with nsim. The t-distribution has heavy tails for small \nu, so all norms converge slowly in that case.

Value

A short printed output of the results (for a more detailed output use summary(object)) and a list with the following components:

gradient

the symbolic gradient vector \nabla of partial first-order derivatives.

evalGrad

the evaluated gradient vector \nabla of partial first-order derivatives, also known as "sensitivities". See summary.propagate.

hessian

the symbolic Hessian matrix \mathbf{H} of partial second-order derivatives.

evalHess

the evaluated Hessian matrix \mathbf{H} of partial second-order derivatives.

rel.contr

the relative contributions, \text{RC}_i, see summary.propagate.

covMat

the covariance matrix \mathbf{\Sigma} used for Monte Carlo simulation and uncertainty propagation (input).

covMat.MC

the estimated covariance matrix \mathbf{\hat{\Sigma}}^{\text{MC}} derived from the Monte Carlo simulation (output).

covMat.target

the covariance matrix \mathbf{\Sigma}^{\text{target}} that the Monte Carlo input should have under the chosen mc.margins model, see 'Details'. Contains Inf for \nu \le 2.

corMat

the \mathbf{\Sigma}-converted correlation matrix \mathbf{R} used for Monte Carlo simulation (input).

corMat.MC

the estimated correlation matrix \mathbf{\hat{R}}^{\text{MC}} derived from the Monte Carlo simulation (output).

frobCOV

the relative Frobenius norm \varepsilon_F of the target and MC-derived covariance matrices (NA if the target covariance does not exist).

frobCOR

the relative Frobenius norm \varepsilon_F of the input and MC-derived correlation matrices.

ws.df

the Welch-Satterthwaite degrees of freedom \nu_{\mathrm{ws}}, as obtained from WelchSatter.

k

the coverage factor k, as calculated by t(1-(\alpha/2), \nu_{\mathrm{ws}}).

u.exp

the expanded uncertainty, U = k \cdot u, where u is derived from the first- or second-order propagation, depending on the setting of exp.uc.

resSIM

a vector containing the nsim values obtained from the expression evaluations f(x_{m, i}) of the simulated data in datSIM.

datSIM

a matrix containing the nsim simulated multivariate values for each variable in column format.

datSIM2

a second, independent MC simulation from the same input distribution, used as matrix \mathbf{B} for Sobol' sensitivity analysis, see sobol. NULL for type = "sim".

prop

a summary vector containing first-/second-order expectations and uncertainties from propagation (mean.1, mean.2, u.1, u.2 and u.2m, the second-order uncertainty with the input moments, see 'Details') as well as the coverage interval of the GUM uncertainty framework based on the t-distribution.

sim

a summary vector containing the mean, standard deviation, median and MAD from MC evaluation, as well as the probabilistically symmetric coverage interval (JCGM 101:2008, 7.7.1).

expr

the original expression expr.

data

a matrix containing the given (type = "stat") or estimated (type = "raw/sim") means, uncertainties and degrees of freedom.

alpha

the original \alpha-level.

nsim

the number of Monte Carlo trials M (hM for the adaptive procedure).

check

a matrix containing the means, uncertainties (on the scale of u_i) and degrees of freedom derived from fitting the MC margins with a scaled/shifted t-distribution. The degrees of freedom are to be compared with df.MC.

type

the original type definition, important for, e.g., sobol.

mc.margins

the mc.margins model used (NA for type = "sim").

df.MC

the degrees of freedom used for the Monte Carlo sampling (NULL for type = "sim").

input

a list of the settings used by report: the input data (NULL for type = "sim"), type, cov, df.tot, k, exp.uc, ws.group, the method used by WelchSatter (ws.method) and the uncertainty budget of samples from makeDat (budget).

moments

a data frame with the skewness, excess kurtosis and their source for each input quantity, used for u.2m.

ci.short

the shortest 100(1-\alpha)% coverage interval from MC evaluation (JCGM 101:2008, 7.7.2).

sim.se

the numerical standard uncertainties of mean.MC, u.MC and of the endpoints of both coverage intervals: the standard deviation of these results over h blocks divided by \sqrt{h} (h = 10 equal parts of the M results, or the blocks of the adaptive procedure).

adaptive

present only for adaptive = TRUE or "validation": the number of blocks, the block size, the total number of trials, \delta, the tolerance used, ndig, the interval type and whether the procedure converged.

call

the matched call.

Note

Why u.MC is larger than u.1 for Type A inputs. With mc.margins = "S1", an input estimated from n indications is assigned the scaled and shifted t-distribution t_{\nu_i}(\bar{x}_i, u_i^2) with \nu_i = n - 1 (JCGM 101:2008, 6.4.9), whose variance is

\mathrm{Var}(X_i) = \frac{\nu_i}{\nu_i - 2}\, u_i^2.

For uncorrelated inputs and a model that is approximately linear over the ranges of the inputs, the Monte Carlo variance of the output is therefore

u_{\mathrm{MC}}^2 \approx \sum_i c_i^2\, \mathrm{Var}(X_i) = \sum_i c_i^2\, \frac{\nu_i}{\nu_i - 2}\, u_i^2,

with the sensitivity coefficients c_i. If all inputs have the same \nu, this is \frac{\nu}{\nu - 2}\, u_1^2, where u_1^2 = \sum_i c_i^2 u_i^2 is the first-order GUF variance. For the GUM example H.2 with n = 5 (\nu = 4) and cov = "diag",

u_{\mathrm{MC}}^2 \approx \sum_i c_i^2 \cdot 2\, u_i^2 = 2\, u_1^2, \qquad u_{\mathrm{MC}} \approx \sqrt{2}\, u_1.

This is not a discrepancy: the GUM uncertainty framework keeps u_1 and accounts for the few indications by the coverage factor k = t_{\nu_{\mathrm{eff}}}, the Monte Carlo method by the wider distribution of the inputs. Compare the coverage intervals of both methods, not the standard uncertainties. For \nu_i \le 2 the variance does not exist and u.MC is not meaningful.

Worked examples and their comparison with published values: see doGauge.

Author(s)

Andrej-Nikolai Spiess

References

Uncertainty propagation (in general):
An Introduction to error analysis.
Taylor JR.
University Science Books (1996), New York.

Effective degrees of freedom for correlated inputs:
A generalization of the Welch-Satterthwaite formula for use with correlated uncertainty components.
Willink R.
Metrologia (2007), 44: 340-349.
\Sexpr[results=rd]{tools:::Rd_expr_doi("10.1088/0026-1394/44/5/010")}

GUM, GUM Supplements and conformity assessment:
Evaluation of measurement data - Guide to the expression of uncertainty in measurement.
JCGM 100:2008. Joint Committee for Guides in Metrology (2008).
\Sexpr[results=rd]{tools:::Rd_expr_doi("10.59161/JCGM100-2008E")}

Evaluation of measurement data - Supplement 1 to the "Guide to the expression of uncertainty in measurement" - Propagation of distributions using a Monte Carlo method.
JCGM 101:2008. Joint Committee for Guides in Metrology (2008).
\Sexpr[results=rd]{tools:::Rd_expr_doi("10.59161/JCGM101-2008")}

Evaluation of measurement data - Supplement 2 to the "Guide to the expression of uncertainty in measurement" - Extension to any number of output quantities.
JCGM 102:2011. Joint Committee for Guides in Metrology (2011).
\Sexpr[results=rd]{tools:::Rd_expr_doi("10.59161/JCGM102-2011")}

Evaluation of measurement data - The role of measurement uncertainty in conformity assessment.
JCGM 106:2012. Joint Committee for Guides in Metrology (2012).
\Sexpr[results=rd]{tools:::Rd_expr_doi("10.59161/JCGM106-2012")}

Collections of worked examples:
Compendium of examples: Good practice in evaluating measurement uncertainty (EMUE), version 2.
van der Veen AMH, Cox MG (Eds.).
Zenodo (2021).
\Sexpr[results=rd]{tools:::Rd_expr_doi("10.5281/zenodo.5142180")}

Quantifying Uncertainty in Analytical Measurement (QUAM:2012.P1), 3rd edition.
Ellison SLR, Williams A (Eds.).
EURACHEM/CITAC Guide CG 4 (2012). ISBN 978-0-948926-30-3.
https://www.eurachem.org/index.php/publications/guides/quam

Simple Guide for Evaluating and Expressing the Uncertainty of NIST Measurement Results.
Possolo A.
NIST Technical Note 1900, National Institute of Standards and Technology (2015).
\Sexpr[results=rd]{tools:::Rd_expr_doi("10.6028/NIST.TN.1900")}

Higher-order Taylor expansion:
Tolerance analysis by computer.
Cox ND.
Journal of Quality Technology (1979), 11: 80-87.

On higher-order corrections for propagating uncertainties.
Wang CM & Iyer HK.
Metrologia (2005), 42: 406-410.

Propagation of uncertainty: Expressions of second and third order uncertainty with third and fourth moments.
Mekid S & Vaja D.
Measurement (2008), 41: 600-609.

Matrix algebra for uncertainty propagation:
An Introduction to Error Propagation: Derivation, Meaning and Examples of Equation Cy = FxCxFx^t.
\Sexpr[results=rd]{tools:::Rd_expr_doi("10.3929/ethz-a-010113668")}.

Second order nonlinear uncertainty modeling in strapdown integration using MEMS IMUs.
Zhang M, Hol JD, Slot L, Luinge H.
2011 Proceedings of the 14th International Conference on Information Fusion (FUSION) (2011).

Uncertainty propagation in non-linear measurement equations.
Mana G & Pennecchi F.
Metrologia (2007), 44: 246-251.

A compact tensor algebra expression of the law of propagation of uncertainty.
Bouchot C, Quilantan JLC, Ochoa JCS.
Metrologia (2011), 48: L22-L28.

Nonlinear error propagation law.
Kubacek L.
Appl Math (1996), 41: 329-345.

Monte Carlo simulation (normal- and t-distribution):
MUSE: computational aspects of a GUM supplement 1 implementation.
Mueller M, Wolf M, Roesslein M.
Metrologia (2008), 45: 586-594.

Copulas for uncertainty analysis.
Possolo A.
Metrologia (2010), 47: 262-271.
\Sexpr[results=rd]{tools:::Rd_expr_doi("10.1088/0026-1394/47/3/017")}

Random variables, joint distribution functions, and copulas.
Sklar A.
Kybernetika (1973), 9: 449-460.

Examples

## ATTENTION: all examples with nsim = 10000
## and check = FALSE for reduced CRAN check time.
## It is advised to use nsim = 1000000 (default)
## and check = TRUE in real-life setup.

## Example without given degrees of freedom.
EXPR1 <- expression(x/y)
x <- c(5, 0.01)
y <- c(1, 0.01)
DF1 <- cbind(x, y)
propagate(expr = EXPR1, data = DF1, type = "stat", 
          nsim = 10000, check = FALSE)

## Same example with given degrees of freedom
## => third row in input 'data'.
EXPR2 <- expression(x/y)
x <- c(5, 0.01, 12)
y <- c(1, 0.01, 5)
DF2 <- cbind(x, y)
propagate(expr = EXPR2, data = DF2, type = "stat", 
          nsim = 10000, check = FALSE)

## A single Type A input from n = 5 indications (nu = 4), Y = X:
## the MC coverage interval equals the GUM interval xbar +/- t_4(0.975) u,
## Var(X) = nu/(nu-2) u^2 = 2 u^2, hence u.MC = sqrt(2) * u.1
## (JCGM 101:2008, 6.4.9).
set.seed(1)
X <- c(10.1, 9.8, 10.3, 10.0, 9.9)
propagate(expression(X), cbind(X), type = "raw", 
          nsim = 1E5, check = FALSE)

## JCGM 100:2008, H.1, end-gauge calibration (l - 50 mm in nm):
## u.1 = 32 nm; with the second-order terms u.2 = 34 nm (both as in H.1).
## As the Hessian has no diagonal terms (linear in each input), u.2m = u.2 here.
## The model is linear in each input separately, so the third-derivative
## terms of the Note to 5.1.2 vanish. dt has nu = 2 (message: u.MC not meaningful).
data(H.1)
propagate(expression(Ls + d - Ls * (da * theta + as * dt) - 50000000), H.1,
          type = "stat", alpha = 0.01, nsim = 1E4, check = FALSE)


propagate documentation built on Nov. 10, 2026, 9:07 a.m.