| propagate | R Documentation |
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.
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, ...)
expr |
an expression, such as |
data |
a dataframe or matrix containing either a) the means ( |
type |
type of input data. Either |
cov |
use only |
df.tot |
an optional total (effective) degrees of freedom |
k |
an optional coverage factor that overrides the one obtained from |
nsim |
the number of Monte Carlo trials |
alpha |
1 - coverage probability |
exp.uc |
Should the expanded uncertainty and coverage interval be calculated from the |
mc.margins |
the probability distribution assigned to the input quantities for Monte Carlo simulation with |
ws.group |
an optional vector that labels input quantities estimated jointly from the same |
adaptive |
|
ndig |
the number of significant decimal digits of |
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 |
... |
other parameters to be supplied to future methods. |
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":
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}}.
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)).
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.
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".
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}}
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}}
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.
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 |
evalGrad |
the evaluated gradient vector |
hessian |
the symbolic Hessian matrix |
evalHess |
the evaluated Hessian matrix |
rel.contr |
the relative contributions, |
covMat |
the covariance matrix |
covMat.MC |
the estimated covariance matrix |
covMat.target |
the covariance matrix |
corMat |
the |
corMat.MC |
the estimated correlation matrix |
frobCOV |
the relative Frobenius norm |
frobCOR |
the relative Frobenius norm |
ws.df |
the Welch-Satterthwaite degrees of freedom |
k |
the coverage factor |
u.exp |
the expanded uncertainty, |
resSIM |
a vector containing the |
datSIM |
a matrix containing the |
datSIM2 |
a second, independent MC simulation from the same input distribution, used as matrix |
prop |
a summary vector containing first-/second-order expectations and uncertainties from propagation ( |
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 |
data |
a matrix containing the given ( |
alpha |
the original |
nsim |
the number of Monte Carlo trials |
check |
a matrix containing the means, uncertainties (on the scale of |
type |
the original |
mc.margins |
the |
df.MC |
the degrees of freedom used for the Monte Carlo sampling ( |
input |
a list of the settings used by |
moments |
a data frame with the skewness, excess kurtosis and their source for each input quantity, used for |
ci.short |
the shortest |
sim.se |
the numerical standard uncertainties of |
adaptive |
present only for |
call |
the matched call. |
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.
Andrej-Nikolai Spiess
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.
## 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)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.