Package 'gconsensus'

Title: Consensus Value Constructor
Description: An implementation of the International Bureau of Weights and Measures (BIPM) generalized consensus estimators used to assign the reference value in a key comparison exercise. This can also be applied to any interlaboratory study. Given a set of different sources, primary laboratories or measurement methods this package provides an evaluation of the variance components according to the selected statistical method for consensus building. It also implements the comparison among different consensus builders and evaluates the participating method or sources against the consensus reference value. Based on a diverse set of references, DerSimonian-Laird (1986) <doi:10.1016/0197-2456(86)90046-2>, for a complete list of references look at the reference section in the package documentation.
Authors: Hugo Gasca-Aragon
Maintainer: Hugo Gasca-Aragon <[email protected]>
License: GPL (>= 3)
Version: 0.3.2
Built: 2024-09-27 06:30:10 UTC
Source: CRAN

Help Index


Consensus Value Constructor

Description

An implementation of the International Bureau of Weights and Measures (BIPM) generalized consensus estimators used to assign the reference value in a key comparison exercise. This can also be applied to any interlaboratory study. Given a set of different sources, primary laboratories or measurement methods this package provides an evaluation of the variance components according to the selected statistical method for consensus building. It also implements the comparison among different consensus builders and evaluates the participating method or sources against the consensus reference value. Based on a diverse set of references, DerSimonian-Laird (1986) <doi:10.1016/0197-2456(86)90046-2>, for a complete list of references look at the reference section in the package documentation. Partially based on the results published in Control clinical trials (1985). <https://doi.org/10.1016/0197-2456(86)90046-2> For a complete list of references see the reference section.

Details

The DESCRIPTION file:

Package: gconsensus
Type: Package
Title: Consensus Value Constructor
Version: 0.3.2
Date: 2022-10-08
Author: Hugo Gasca-Aragon
Maintainer: Hugo Gasca-Aragon <[email protected]>
Description: An implementation of the International Bureau of Weights and Measures (BIPM) generalized consensus estimators used to assign the reference value in a key comparison exercise. This can also be applied to any interlaboratory study. Given a set of different sources, primary laboratories or measurement methods this package provides an evaluation of the variance components according to the selected statistical method for consensus building. It also implements the comparison among different consensus builders and evaluates the participating method or sources against the consensus reference value. Based on a diverse set of references, DerSimonian-Laird (1986) <doi:10.1016/0197-2456(86)90046-2>, for a complete list of references look at the reference section in the package documentation.
Depends: R (>= 3.4), graphics (>= 3.4), stats (>= 3.4), MASS (>= 7.0), utils (>= 3.4), rjags (>= 4-8), coda (>= 0.13)
License: GPL (>= 3)
Encoding: UTF-8
NeedsCompilation: no
Packaged: 2022-11-04 22:44:13 UTC; hgasca
Repository: CRAN
Date/Publication: 2022-11-04 23:50:02 UTC

Index of help topics:

comparison.gconsensus   Obtains a set of generalized consensus
                        estimates by different statistical methods for
                        comparison purposes.
doe.gconsensus          Obtains the unilateral degrees of equivalence
                        out of a generalized consensus object.
gconsensus              Generalized Consensus Contructor
gconsensus-package      Consensus Value Constructor
plot.comparison         Plot a gconsensus comparison object
plot.doe                Plot a "degrees of equivalence" object
plot.gconsensus         Plot a gconsensus object
print.comparison        Prints a Comparison Object.
print.doe               Prints a Doe Object.
print.gconsensus        Prints a gconsensus object
toString.comparison     Builds a detailed description string of the
                        comparison object.
toString.doe            Builds a detailed description string of the doe
                        object.
toString.gconsensus     Builds a detailed description string of the
                        gconsenus object.
vr.mle                  Finds the maximum likelihood estimate solution
                        described by Vangel-Rukhin for the one way
                        random effects model.

Author(s)

Hugo Gasca-Aragon

Maintainer: Hugo Gasca-Aragon <[email protected]>

References

1. Graybill and Deal (1959), Combining Unbiased Estimators, Biometrics, 15, pp. 543-550.

2. DerSimonian and Laird (1986), Meta-analysis in Clinical Trials, Controlled Clinical Trials, 7, pp. 177-188.

3. R. A. Horn, S. A. Horn and D. B. Duncan (1975), Estimating heteroscedastic variance in linear models. Journ. Amer. Statist. Assoc. 70, 380

4. M. S. Levenson, D. L. Banks, K. R. Eberhardt, L. M. Gill, W. F. Guthrie, H. K. Liu, M. G. Vangel, J. H. Yen, and N. F. Zhang (2000), An ISO GUM Approach to Combining Results from Multiple Methods, Journal of Research of the National Institute of Standards and Technology, Volume 105, Number 4.

5. John Mandel and Robert Paule (1970), Interlaboratory Evaluation of a Material with Unequal Number of Replicates, Analytical Chemistry, 42, pp. 1194-1197.

6. Robert Paule and John Mandel (1982), Consensus Values and Weighting Factors, Journal of Research of the National Bureau of Standards, 87, pp. 377-385.

7. Andrew Rukhin (2009), Weighted Means Statistics in Interlaboratory Studies, Metrologia, Vol. 46, pp. 323-331.

8. Andrew Ruhkin (2003), Two Procedures of Meta-analysis in Clinical Trials and Interlaboratory Studies, Tatra Mountains Mathematical Publications, 26, pp. 155-168.

9. Andrew Ruhkin and Mark Vangel (1998), Estimation of a Common Mean and Weighted Means Statistics, Journal of the American Statistical Association, Vol. 93, No. 441.

10. Andrew Ruhkin, B. Biggerstaff, and Mark Vangel (2000), Restricted Maximum Likelihood Estimation of a Common Mean and Mandel-Paule Algorithm, Journal of Statistical Planning and Inference, 83, pp. 319-330.

11. Mark Vangel and Andrew Ruhkin (1999), Maximum Likelihood Analysis for Heteroscedastic One-Way Random Effects ANOVA in Interlaboratory Studies, Biometrics 55, 129-136.

12. Susannah Schiller and Keith Eberhardt (1991), Combining Data from Independent Analysis Methods, Spectrochimica, ACTA 46 (12).

13. Bimal Kumar Sinha (1985), Unbiased Estimation of the Variance of the Graybill-Deal Estimator of the Common Mean of Several Normal Populations, The Canadian Journal of Statistics, Vol. 13, No. 3, pp. 243-247.

14. Nien-Fan Zhang (2006), The Uncertainty Associated with The Weighted Mean of Measurement Data, Metrologia, 43, PP. 195-204.

15. CCQM (2013), CCQM Guidance note: Estimation of a Consensus KCRV and associated Degrees of Equivalence, Version 10.

16. Knapp G. and Hartung J. (2003), Improved tests for a random effects meta-regression with a single covariate, Statistics in Medicine, Vol 22, Issue 17, pp 2693-2710

See Also

gconsensus

Examples

ilab <- list(
  data = data.frame(
    participant = c("BAM", "IRMM", "LGC", "NARL", "NIST", "NMIJ", "NRC"),
    code = paste0("p", c(1:7)),
    method = rep(1, 7), 
    value = c(10.21, 10.9, 10.94, 10.58, 10.81, 9.62, 10.8), 
    unit = rep("\\micro \\kilogram/\\kilogram", 7),
    expandedUnc = c(0.381, 0.250, 0.130, 0.410, 0.445, 0.196, 0.093), 
    n = rep(1, 7), 
    coverageFactor = rep(2, 7),
    coverageProbability = rep(0.95, 7), 
	method.type = rep("p", 7),
    included = rep(1, 7)),
	symbol = rep(1, 7),
	symbol.Fillcolor = rep(1, 7),
	comments = rep("", 7),
	info = list(variable = c("Software", "Institute", "Exercise", "Author", "Date", 
      "Measurand", "Units"), 
    value = c("consensus", "BIPM", "CCQM-K25", "Michele Schantz & Stephen Wise",
      "12-12-2003", "PCB 105", "\\micro \\kilogram/\\kilogram"))
)

aConsensus <- gconsensus(ilab,
  method = "DL1",
  config = list(
               signif.digits = 2,
			   display.order = "location",
			   display.orientation = "horizontal",
			   display.shownames = TRUE,
			   tab.size = 12,
			   alpha = 0.05,
               expansion.factor.type = "small.sample",
			   tau = mad(ilab$data$value),
               unreliable.uncertainties = FALSE,
               MC_samples = 1e5,
               MC_seed = 12345,
               MC_use.HKSJ.adjustment = TRUE,
			   MC_interval.type = "symmetric",
			   MC_use.parallel.computing = FALSE,
		       filename = "hb_consensus_model.txt"
          )
)

print(aConsensus)

Obtains a set of generalized consensus estimates by different statistical methods for comparison purposes.

Description

Obtains a set of generalized consensus estimates.

Usage

comparison.gconsensus(x, methods, build.model = NULL, get.samples = NULL)

Arguments

x

consensus object, containing the definition of the participants' information.

methods

vector of strings, containing the statistical methods to be used in obtaining the consensus values.

build.model

function, NULL by default, the current function to build a JAGS measurand model.

get.samples

function, NULL by default, the current function to obtain CORA samples out of the JAGS model.

Details

The default function requires the default parameters (x, ...), the next version will replace the formal parameters with the default signature.

Value

fit

a data.frame object, consensus value estimates by the specified methods

gconsensus

the current estimated gconsensus as provided in the x parameter

total.included.participants

a numeric, the current number of included participating sources

Author(s)

Hugo Gasca-Aragon

Maintainer: Hugo Gasca-Aragon <[email protected]>

See Also

gconsensus, print.comparison, plot.comparison


Obtains the unilateral degrees of equivalence out of a generalized consensus object.

Description

Obtains the unilateral degrees of equivalence from a generalized consensus object.

Usage

doe.gconsensus(x)

Arguments

x

A generalized consensus object

Details

The unilateral degrees of equivalence are obtained from the participants data and the estimated generalized consensus value described in the gconsensus value.

Value

A doe object containing the unilateral degrees of equivalence.

fit

a data.frame with the source code, source lab name, value, expanded uncertainty, unit, coverage factor, probability coverage and tau.

gconsensus

the generalized consensus object the evaluation is based on.

Author(s)

Hugo Gasca-Aragon

Maintainer: Hugo Gasca-Aragon <[email protected]>

See Also

gconsensus, print.doe, plot.doe


Generalized Consensus Contructor

Description

Compute a set of estimates for the generalized consensus value from a set of sources.

Usage

gconsensus(ilab, method = "mean", 
  build.model = NULL, get.samples = NULL,
  config = list(alpha = 0.05, 
    expansion.factor.type = "naive", 
    tau = mad(ilab$data$value),
    unreliable.uncertainties = FALSE, 
    MC_samples = 1e5,
    MC_burn_in = 1000,
    MC_seed = NA, 
    MC_use.HKSJ.adjustment = FALSE,
    filename = "hb_consensus_model.txt"))

Arguments

ilab

ilab object, containing the definition of the participating source/experts/laboratories.

method

string, the current statistical method for estimating the consensus value. The list of current valid methods is: mean [15], grand.mean [15], median [15], h15 for Huber estimator [15], MCM.mean for Monte Carlo mean, MCM.median for Monte Carlo median, GD1 for the original Graybill-Deal estimator [1], GD2 for the modified Graybill-Deal estimator as described by Sinha [13], GD3 for the modified Graybill-Deal estimator as described by Zhang [14], GD4 for the modified Graybill-Deal estimator as described by Zhang [14], DL1 for original DerSimonian-Laid estimator [2], DL2 for the modified DerSimonian-Laird estimator as described by Horn-Horn-Duncan [3], PM for original Paul-Mandel estimator [5], MPM for the modified Paul-Mandel estimator [6], VRMLE for Vangel-Rukhin MLE [7, 8, 9, 10, 11], BOB for the type B on Bias estimator [4], SE for the Schieller-Eberhardt [12], MCM.LP for linear pool, HB for Hierarchical Bayesian

build.model

a function (NULL by default) to build a JAGS model

get.samples

a function (NULL by dafault) to obtain the CODA samples based on the JAGS model

config

list, contains the configuration options used in the computational process. The complete list of options is: alpha for the significance level, default value = 0.05, expansion.factor.type for the type of coverage factor to be used: "naive" which use a coverage factor=2, "large sample" which uses a normal quantile, "small sample" which uses a t quantile, tau initial estimate of between source uncertainty, by default it takes the mad of the reported values, unreliable.uncertainties an indicator for unreliables uncertainties, if TRUE then adjustment is used [15], MC_samples the number of cycles used in the simple Monte Carlo simulation, MC_burn_in the number of initial cycles to be drop from Monte Carlo simulation. The Bayesian algorithm becomes stationary but in the begining it can be noisy, this is fixed by dropping the initial samples. MC_seed the seed used to initializing the random number generator in the Monte Carlo simulation, MC_use.HKSJ.adjustment a flag indicating if small sample adjustments are required [16], filename a string containing the name of the file for communication with JAGS package.

Details

The consensus estimation will vary with the specified method. Display can be customized by using the options mechanism. Available options are: display.signif.digits an integer representing the number of significant digits to be obtained in the adaptative approach of the Monte Carlo simulation, display.order a string ("name", "code", "location", "dispersion") representing the order to be used for displaying the uncertainty contribution, display.shownames a boolean, if true source names are used otherwise source codes are used, display.tab.size an integer representing the column width used in formating data tables, display.orientation a string ("horizontal", "vertical"), plot orientation. display.expandedUncertainty a boolean, plot standard uncertainties or expanded uncertainties.

Value

fit

a data.frame with the value, expanded uncertainty, unit, expansion factor, probability coverage and tau, the between effect uncertainty.

method

statistical method used to estimate the consensus value.

subset

the subset of included values in the consensus value estimation.

ilab

the current participants' information.

config

the current configuration options provided for the consensus value estimation process.

exercise

the exercise the consensus belongs to.

measurand

the measurand the consensus belongs to.

Author(s)

Hugo Gasca-Aragon

Maintainer: Hugo Gasca-Aragon <[email protected]>

See Also

doe.gconsensus, print.gconsensus, plot.gconsensus


Plot a gconsensus comparison object

Description

Shows the confidence intervals associated with the different gconsensus values specified in the comparison.

Usage

## S3 method for class 'comparison'
plot(x, ...)

Arguments

x

gconsensus comparison object, containing the estimates for a set of gconsensus value.

...

any additional graphical parameter.

Details

The plot contains the confidence intervals associated with the set of gconsensus values under comparison. Formating options of the plot: display.order a string, this is used to order the data source, valid values are: "location" for sorting based on the repoted means, "dispersion" for sorting based on reported variances, any other value for sorting based on typing order. Default value is "location". display.shownames a logical, if true then the participants names are used to identify the ploted values, otherwise the code value is used instead. Default value is FALSE. display.orientation a string, this is used to build the plot vertically or horizontally, valid values are: "horizontal" otherwise vertical is assumed, default value is "horizontal". display.expandedUncertainty a logical, if true then expanded uncertainty is used for plots, otherwise standard uncertainty is used. Default value is

Value

a plot object

Author(s)

Hugo Gasca-Aragon

Maintainer: Hugo Gasca-Aragon <[email protected]>

See Also

comparison.gconsensus, print.comparison, plot


Plot a "degrees of equivalence" object

Description

Plots a char showing the confidence interval for the unilateral degrees of equivalance associated to each participating laboratory.

Usage

## S3 method for class 'doe'
plot(x, ...)

Arguments

x

A doe object

...

Any additional graphical parameter

Details

Plot a unilateral degree of equivalence (doe) object. Formating options of the plot: display.order a string, this is used to order the data source, valid values are: "location" for sorting based on the repoted means, "dispersion" for sorting based on reported variances, any other value for sorting based on typing order. Default value is "location". display.shownames a logical, if true then the participants names are used to identify the ploted values, otherwise the code value is used instead. Default value is FALSE. display.orientation a string, this is used to build the plot vertically or horizontally, valid values are: "horizontal" otherwise vertical is assumed, default value is "horizontal". display.expandedUncertainty a logical, if true then expanded uncertainty is used for plots, otherwise standard uncertainty is used. Default value is FALSE.

Value

A plot of the doe object using the options displor.order and display.shownames, showing the confidence interval for the unilateral degree of equivalence attached to each participant.

Author(s)

Hugo Gasca-Aragon

Maintainer: Hugo Gasca-Aragon <[email protected]>

See Also

doe.gconsensus, plot, print.doe


Plot a gconsensus object

Description

Shows the probability distribution of the estimated gconsensus value.

Usage

## S3 method for class 'gconsensus'
plot(x, ...)

Arguments

x

gconsensus object, containing the estimated gconsensus value by the specified statistical method.

...

any additional graphical parameter

Details

The plot shows the confidence interval for each of the participants' values, the consensus value and its confidence interval, on the right side the probability distribution associated with the consensus value is showed and a normal distribution with the same expected value and variace. Formating options of the plot: display.order a string, this is used to order the data source, valid values are: "location" for sorting based on the repoted means, "dispersion" for sorting based on reported variances, any other value for sorting based on typing order. Default value is "location". display.shownames a logical, if true then the participants names are used to identify the ploted values, otherwise the code value is used instead. Default value is FALSE. display.orientation a string, this is used to build the plot vertically or horizontally, valid values are: "horizontal" otherwise vertical is assumed, default value is "horizontal". display.length.out a numeric, this represents the number of points to build the mixture distribution, default value = 101. display.expandedUncertainty a logical, if true then expanded uncertainty is used for plots, otherwise standard uncertainty is used. Default value is FALSE.

Value

a plot object.

Author(s)

Hugo Gasca-Aragon Maintainer: Hugo Gasca-Aragon <[email protected]>

See Also

gconsensus, print.gconsensus, plot


Prints a Comparison Object.

Description

Prints the consensus comparison object. One line for each selected gconsensus method.

Usage

## S3 method for class 'comparison'
print(x, ...)

Arguments

x

comparison, object to be described.

...

any additional parameters.

Value

A displayed text containing a summary of the selected gconsensus methods.

Author(s)

Hugo Gasca-Aragon

Maintainer: Hugo Gasca-Aragon <[email protected]>

See Also

comparison.gconsensus, plot.comparison, toString.comparison


Prints a Doe Object.

Description

Prints a doe (unilateral degrees of equivalence) object.

Usage

## S3 method for class 'doe'
print(x, ...)

Arguments

x

doe, object to be described.

...

any additional parameters.

Value

A displayed text containg a detailed description of the object.

Author(s)

Hugo Gasca-Aragon

Maintainer: Hugo Gasca-Aragon <[email protected]>

See Also

gconsensus, doe.gconsensus, toString.doe


Prints a gconsensus object

Description

Prints a gconsensus object

Usage

## S3 method for class 'gconsensus'
print(x, ...)

Arguments

x

a gconsensus object

...

any additional parameter

Details

option digits is used.

Value

A displayed text containing a detailed description of the object.

Author(s)

Hugo Gasca-Aragon

Maintainer: Hugo Gasca-Aragon <[email protected]>

See Also

gconsensus, plot.gconsensus, toString.gconsensus


Builds a detailed description string of the comparison object.

Description

This function converts a gconsensus comparison object into a string. The returned value contains a verbatim description of the object. This function is used to display the result of comparing several gconsensus values.

Usage

## S3 method for class 'comparison'
toString(x, ...)

Arguments

x

comparison, object to be described.

...

any additional parameters.

Value

string, it contains a verbatim description of the comparison object.

Author(s)

Hugo Gasca-Aragon

Maintainer: Hugo Gasca-Aragon <[email protected]>

See Also

comparison.gconsensus, print.comparison


Builds a detailed description string of the doe object.

Description

This function converts a unilateral degrees of equivalence object into a string. The returned value contains a verbatim description of the object. This function is used to display the result of estimating the unilateral degrees of equivalence.

Usage

## S3 method for class 'doe'
toString(x, ...)

Arguments

x

doe, object to be described.

...

any additional parameters.

Value

string, it contains a verbatim description of the unilateral degrees of equivalence object.

Author(s)

Hugo Gasca-Aragon

Maintainer: Hugo Gasca-Aragon <[email protected]>

See Also

doe.gconsensus, print.doe


Builds a detailed description string of the gconsenus object.

Description

This function converts a gconsensus object into a string. The returned value contains a verbatim description of the object. This function is used to display the result of estimating the gconsensus value.

Usage

## S3 method for class 'gconsensus'
toString(x, ...)

Arguments

x

gconsensus, object to be described.

...

any additional parameters.

Value

string, it contains a verbatim description of the gconsensus object.

Author(s)

Hugo Gasca-Aragon

Maintainer: Hugo Gasca-Aragon <[email protected]>

See Also

gconsensus, print.gconsensus


Finds the maximum likelihood estimate solution described by Vangel-Rukhin for the one way random effects model.

Description

This function finds the mle solution to the one way random effects model.

Usage

vr.mle(xi, si2, ni, labi=c(1:length(xi)), 
   max.iter=1000, tol=.Machine$double.eps^0.5, 
   init.mu=mean(xi), init.sigma2=var(xi), 
   trace=FALSE, alpha=0.05)

Arguments

xi

numeric vector, represents the mean values.

si2

numeric vector, represents the variances associated with a single measurement.

ni

integer vector, represents the number of observations associated with the reported mean values.

labi

vector, containing the associated labels of the participanting laboratories, source of the reported values (mean, variances, number of observations)

max.iter

integer, maximum number of iterations allowed.

tol

numeric, relative tolerance.

init.mu

numeric, initial consensus value.

init.sigma2

numeric, initial between variance.

trace

logic, indicates if traceable information must be shown during the execution.

alpha

numeric, significance level.

Value

mu

estimated consensus value by the method of maximum likelihood

u.mu

standard uncertainty estimation attached to the consensus value

kp

estimated expansion factor for the specified configuration options

Author(s)

Hugo Gasca-Aragon Maintainer: Hugo Gasca-Aragon <[email protected]>

See Also

See also gconsensus