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.
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.
Value
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.
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) ).
See Also
uncert-class, uncert.
Examples
#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)