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 |

`object` |
An object of class |

`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 |

`simplify` |
logical. If |

`expand.dot` |
logical; if |

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | ```
#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)
``` |

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.