| makeDat | R Documentation |
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.
makeDat(expr = NULL, file = NULL, data = NULL, layout = c("auto", "columns", "budget"),
output = c("stat", "sim"), nsim = 1E6, sheet = 1, envir = parent.frame(), ...)
expr |
an expression to be used in |
file |
the name of a file to import ( |
data |
alternatively to |
layout |
|
output |
for |
nsim |
the number of samples for |
sheet |
the sheet of an Excel file, by number or name. |
envir |
the environment in which the variables of |
... |
further arguments to |
(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".
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).
Andrej-Nikolai Spiess
propagate, cor2cov
## (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
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.