makeDat: Create the input data for 'propagate' from the workspace, a file or an uncertainty budget

Description

Creates the data matrix for propagate from (a) variables in the workspace, (b) a file or data frame with one column per input quantity (repeated observations, mean/\(u\)/degrees of freedom, or samples), or (c) a file or data frame in the form of an uncertainty budget, with one row per input quantity. Files can be .csv, .txt, .tsv, .dat, .xlsx or .xls.

Usage

makeDat(expr = NULL, file = NULL, data = NULL, layout = c("auto", "columns", "budget"),
        output = c("stat", "sim"), nsim = 1E6, sheet = 1, envir = parent.frame(), ...)

Value

A matrix with one named column per input quantity and the attribute "type". For layout = "budget", the attribute "budget" contains the interpreted budget (name, mean, u, df, distribution and half-width).

Arguments

expr: an expression to be used in propagate. Its variables select and order the columns of the result. Required for the workspace mode; optional otherwise.
file: the name of a file to import (.csv, .txt, .tsv, .dat, .xlsx, .xls). Excel files require package 'readxl'.
data: alternatively to file, a data frame or matrix already in R.
layout: "columns": one column per input quantity; "budget": one row per input quantity; "auto": "budget" if there is a column name and a column value (or mean, x, estimate), otherwise "columns".
output: for layout = "budget" only: "stat" returns means, standard uncertainties and degrees of freedom (type = "stat"); "sim" returns nsim samples from the stated distributions (type = "sim").
nsim: the number of samples for output = "sim".
sheet: the sheet of an Excel file, by number or name.
envir: the environment in which the variables of expr are looked up in workspace mode (default: the calling environment).
...: further arguments to read.table or read_excel of package 'readxl'.

Author

Andrej-Nikolai Spiess

Details

(a) Workspace. Without file and data, the variables of expr are taken from envir and combined column-wise. Variables of different length (e.g. repeated observations with different numbers of observations) are padded with NA.

(b) Columns layout. Each column is one input quantity, named as in expr; additional columns are dropped. The rows contain either repeated observations (type = "raw"), the mean, standard uncertainty and optional degrees of freedom (type = "stat"), or samples (type = "sim"). Missing observations may be left empty (NA).

(c) Budget layout. Each row is one input quantity, as in an uncertainty budget. Recognised columns (case-insensitive, except u/U):

`name`	name of the quantity, as in `expr` (required)
`value`	estimate (aliases `mean`, `x`, `estimate`; required)
`u`	standard uncertainty
`U`, `k`	expanded uncertainty and coverage factor: \(u = U/k\)
`a`	half-width of a rectangular, triangular, arcsine or curvilinear trapezoidal distribution
`d`	curvilinear trapezoidal distribution only: half-width of the inexactness of the limits
`dist`	`normal`, `t`, `rect`, `tri`, `arcsine` or `ctrap` (aliases `gaussian`, `norm`; `rectangular`, `uniform`, `unif`; `triangular`, `triang`; `arcsin`, `u-shaped`; `curvilinear trapezoid`, `curvilinear trapezoidal`)
`df`	degrees of freedom (aliases `nu`, `dof`); empty = `Inf`

The standard uncertainty is taken from u, else from U/k, else from the half-width: \(u = a/\sqrt{3}\) (rectangular), \(a/\sqrt{6}\) (triangular), \(a/\sqrt{2}\) (arcsine), \(\sqrt{a^2/3 + d^2/9}\) (curvilinear trapezoidal). Degrees of freedom given for Type B inputs (e.g. from the reliability of the limits, JCGM 100:2008, G.4.2) are kept; they enter only the effective degrees of freedom of the GUF. If dist is empty, an input is normal for df = Inf and t for finite df. For a calibration certificate stating \(U_p\), \(k_p\) and \(\nu_{\mathrm{eff}}\), enter U, k and df: this is the t-distribution \(t_{\nu_{\mathrm{eff}}}(x, (U_p/k_p)^2)\) of JCGM 101:2008, 6.4.9.7.

With output = "stat", the result has the three rows mean, \(u\) and \(\nu\) of type = "stat". propagate then samples every input from a t or Gaussian margin with this mean and \(u\), so that rectangular, triangular and arcsine inputs are represented only by their first two moments (a message is given). With output = "sim", every input is sampled from its stated distribution (JCGM 101:2008, 6.4): Gaussian, scaled and shifted t with scale \(u\) (6.4.9), rectangular, triangular, arcsine or curvilinear trapezoidal (6.4.3). The samples carry the interpreted budget as attribute "budget"; propagate with type = "sim" then uses its estimates, standard uncertainties and degrees of freedom for the GUM uncertainty framework, so that one call gives both the GUF and the Monte Carlo results of JCGM 101:2008 (for t-distributed inputs, the sample variance would be \(\nu/(\nu - 2)\,u^2\) instead of \(u^2\)). The samples are independent; correlations between inputs can be supplied to propagate only for output = "stat", e.g. with cov = cor2cov(R, u^2) using the u of the attribute "budget".

CSV formats. The separator is detected from the header line: ";" (with decimal comma, as written by spreadsheet programs in many European locales), tab, or "," (with decimal point).

Type. The result carries an attribute "type" with the suggested type for propagate ("stat" for at most 3 rows, "raw" for up to 999 rows, "sim" otherwise; "stat"/"sim" for budgets), which is also reported in a message. Check it: raw data with at most three repeated observations also have at most 3 rows and are then reported as "stat".

Examples

Run this code

## (a) Workspace: simulated inputs
EXPR1 <- expression(a + b^d)
a <- rnorm(10000, 12, 1)
b <- rnorm(10000, 5, 0.1)
d <- runif(10000, 6, 7)
DAT1 <- makeDat(EXPR1)

## (b) Repeated observations from a CSV file (JCGM 100:2008, H.2)
f <- tempfile(fileext = ".csv")
write.csv(data.frame(V = c(5.007, 4.994, 5.005, 4.990, 4.999),
                     I = c(19.663, 19.639, 19.640, 19.685, 19.678),
                     phi = c(1.0456, 1.0438, 1.0468, 1.0428, 1.0433)), f, row.names = FALSE)
EXPR2 <- expression((V/I) * cos(phi))
DAT2 <- makeDat(EXPR2, file = f)
RES2 <- propagate(EXPR2, DAT2, type = "raw", cov = "full", nsim = 1E5, check = FALSE)

## (c) Uncertainty budget, mass calibration of EA 4/02
## (EMUE Compendium, section 3.6)
BUD <- data.frame(name  = c("mS", "dmD", "dm", "dmC", "dB"),
                  value = c(10000.005, 0, 0.020, 0, 0),
                  ## dm: standard uncertainty of the mean of 3 observations, s = 0.025 g
                  u     = c(NA, NA, 0.025/sqrt(3), NA, NA),
                  U     = c(0.045, NA, NA, NA, NA),
                  k     = c(2, NA, NA, NA, NA),
                  a     = c(NA, 0.015, NA, 0.010, 0.010),
                  dist  = c("normal", "rect", "normal", "rect", "rect"))
EXPR3 <- expression(mS + dmD + dm + dmC + dB)
## means, u, df for type = "stat" ...
DAT3 <- makeDat(EXPR3, data = BUD)
attr(DAT3, "budget")
## ... or samples from the stated distributions for type = "sim"
DAT4 <- makeDat(EXPR3, data = BUD, output = "sim", nsim = 1E5)
RES4 <- propagate(EXPR3, DAT4, type = "sim", check = FALSE)
RES4$sim   ## u = 0.029 g, 95 % coverage interval [9999.967, 10000.082] g

Run the code above in your browser using DataLab