contribs calculates the contribution matrix \(C\) where
\(C_{i,j}=(c_iu_i)(c_ju_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_{ij}\)
are returned unchanged. For the diagonal elements of \(C\) (contributions for
individual individual terms), this form corresponds to squared standard uncertainties
\(u_i^2(y)\) in GUM notation.
If as.sd=TRUE, the magnitude of the value returned is \(\sqrt{|C_{ij}|}\).
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}\sqrt{|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_{ij}, C_{ji}), j \neq 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.