contribs: Extract contributions from an 'uncert' object.
In metRology: Support for Metrological Applications

Description Usage Arguments Details Value Author(s) References See Also Examples

Extracts the individual nonzero contributions to the combined uncertainty in an 'uncert' object.

1 2	contribs(object, scope, as.sd = FALSE, keep.sign = TRUE, simplify = TRUE, expand.dot=TRUE)

`object`	An object of class `uncert` returned by `uncert` or `uncertMC`
`scope`	An expression, one-sided formula or character vector describing the particular variables for which contributions are desired. If missing, contributions for all variables are returned.
`as.sd`	logical; controls whether values are returned in the form of standard uncertainties or variance contributions. See Details.
`keep.sign`	logical; controls whether the sign of the cobntributions is appended to the return value when `as.sd=TRUE`. See Details.
`simplify`	logical. If `simplify=FALSE` the contribution matrix itself is returned. If `simplify=TRUE`, only the requested (by `scope`) nonzero elements of the contribution matrix are returned, as a vector. See Details for the treatment of off-diagonal terms
`expand.dot`	logical; if `TRUE`, ‘.’ in a formula `scope` is expanded to all contributions including pairwise contributions. If `FALSE`, the dot operator implies only the single-variable terms. See Details.

contribs calculates the contribution matrix C where C[i,j]=c[i]u[i]*c[j]u[j]*r[i,j]. In general, these values are possibly negative (co)variance contributions to the variance (squared standard uncertainty) in y. In GUM notation (‘the GUM’ is JCGM 100 (2008) - see references), the diagonal elements of C are squared standard uncertainties in y. The form of the return value depends on simplify, as.sd and keep.sign.

If as.sd is FALSE (the default), contributions C[i,j] are returned unchanged. For the diagonal elements of C (contributions for individual individual terms), this form corresponds to squared standard uncertainties (u[i]{y})^2 in GUM notation.

If as.sd=TRUE, the magnitude of the value returned is sqrt( abs(C[i,j] ) ). For the diagonal elements of C this corresponds to standard uncertainties u[i]{y} in GUM notation.

If as.sd=TRUE, keep.sign controls whether the values are signed or returned as absolute values. If keep.sign=TRUE, the value returned is sign(C_{ij}√{|C_{ij}|}{sign(C[i,j]sqrt( abs(C[i,j] ) )}. If false, the absolute value is returned. Note that the sign is returned solely to indicate the direction of the original contribution. keep.sign has no effect if as.sd=FALSE.

If simplify=FALSE (the default), the requested elements of the contribution matrix C are returned as a matrix. If simplify=FALSE, the return value is a vector containing only those terms with nonzero values in the associated correlation matrix. The threshold for deciding a correlation is nonzero is that its magnitude is greater than 2*.Machine$double.eps.

Off-diagonal terms for the same pair of variables are summed, that is, for the pair (C[i,j], C[j,i]), j != i the (single) value returned is C[i,j]+C[j,i]=2C[i,j].

The contributions returned can be limited to a chosen subset using scope; only the terms involving variables included in scope are returned. scope can be an expression, formula or character vector of variable names. If an expression or formula, only those contributions involving variables in the expression or formula are returned.

Any variable names in scope which are not present in row.names(object$budget) are silently ignored except for the formula specification which will return an error.

If simplify=FALSE, the matrix returned always contains all contributions involving individual variables in scope. If simplify=TRUE, however, specifying scope as a formula provides additional control over the returned contributions:

If a formula, scope accepts the usual model formula operators ‘.’, ‘+’, ‘-’, ‘*’ and ‘^’, but the interpretation is not quite identical to lm.

First, if present, ‘.’ is taken by default as ‘all contributions’, implying all single terms and all pairwise terms (like ‘.^2)’ in other formula specifications). This can be disabled by specifying expand.dot=FALSE.

The negation operator ‘-’ removes terms, but removing a single variable also removes any associated covariance contributions. For example, scope=~.-A is expanded to all single and pairwise contributions to the uncertanty budget that do not involve A.

Interaction-like terms of the form A:B are interpreted as indicating the total off-diagonal contribution, that is, A:B is equivalent to B:A and the associated value returned is based on C[i,j]+C[j,i].

Cross-terms like ~A*B are supported and expand, as usual, to ~A+B+A:B.

Unlike the two other scope specifications, single terms in the formula do not automatically imply off-diagonal terms; A+B will not return the off-diagonal contribution for A and B. Use A*B or (A+B)^2 etc. to get off-diagonal contributions. Cross-terms of order above two are ignored so A*B*C safely returns only the set of individual and pairwise terms, but it is perhaps more precise to use (A+B+C)^2.

I() and other operators or functions are not supported.

A named vector or matrix of contributions. Names for off-diagonal contributions in the vector format are constructed from the names of the two contributing variables.

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

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) ).

uncert-class, uncert.

  #Example with negative correlation
  x <- list(a=1, b=3, c=2, d=11)
  u <- lapply(x, function(x) x/10)
  u.cor<-diag(1,4)
  u.cor[3,4]<-u.cor[4,3]<- -0.5
  u.form.c<-uncert(~a+b*2+c*3+d/2, x, u, method="NUM", cor=u.cor)

  contribs(u.form.c, simplify=FALSE)
  contribs(u.form.c)
  contribs(u.form.c, as.sd=TRUE)
  contribs(u.form.c, as.sd=TRUE, keep.sign=FALSE)

  contribs(u.form.c, scope=c("a", "c", "d") )

  #Effects of formula specification for scope:
  contribs(u.form.c, ~.)           #All contributions
  contribs(u.form.c, ~(a+b+c+d)^2) #same as ~.
  contribs(u.form.c, ~a+b+c+d )    #single-variable contributions only
  contribs(u.form.c, ~., expand.dot=FALSE )    # as ~a+b+c+d
  contribs(u.form.c, ~.-d)         #Drops d and c:d
  contribs(u.form.c, ~.-c:d)
  contribs(u.form.c, ~c+d)
  contribs(u.form.c, ~c*d)