Skip to contents

Pool analysis results obtained from the imputed datasets

Source: R/pool.R
pool.Rd

Pool analysis results obtained from the imputed datasets

Usage 

pool(
  results,
  conf.level = 0.95,
  alternative = c("two.sided", "less", "greater"),
  type = c("percentile", "normal")
)

# S3 method for class 'pool'
as.data.frame(x, ...)

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

mcse(x, results)

# S3 method for class 'mcse'
as.data.frame(x, ...)

# S3 method for class 'mcse'
print(x, ..., pval_digits = 2, pval_eps = 1e-06, pval_nsmall = 5)

Arguments

results

an analysis object created by analyse().

conf.level

confidence level of the returned confidence interval. Must be a single number between 0 and 1. Default is 0.95.

alternative

a character string specifying the alternative hypothesis, must be one of "two.sided" (default), "greater" or "less".

type

a character string of either "percentile" (default) or "normal". Determines what method should be used to calculate the bootstrap confidence intervals. See details. Only used if method_condmean(type = "bootstrap") was specified in the original call to draws().

x

a pool object generated by pool().

...

not used.

pval_digits

number of significant digits to print for p-values' MCSE.

pval_eps

the minimum p-values' MCSE to print.

pval_nsmall

the minimum number of digits to print for p-values' MCSE.

Value

A pool object; a list of class "pool" containing the pooled analysis results with the following elements:

  • pars: a named list with one entry per parameter, each itself a list containing the pooled point estimate (est), confidence interval (ci), standard error (se) and p-value (pvalue).

  • conf.level: the confidence level used for the confidence intervals.

  • alternative: the alternative hypothesis used to derive the p-values.

  • N: the number of analysis results that were combined.

  • method: the pooling method that was used.

The as.data.frame() method returns a data.frame with one row per parameter (columns parameter, est, se, lci, uci, pval) and the print() method returns its input invisibly.

mcse() returns an mcse object; a list of class "mcse" containing pars (the Monte Carlo standard errors of the pooled estimates, in the same structure as the pars element of a pool object) and N (the number of results combined).

Details

The calculation used to generate the point estimate, standard errors and confidence interval depends upon the method specified in the original call to draws(); In particular:

  • method_approxbayes() & method_bayes() both use Rubin's rules to pool estimates and variances across multiple imputed datasets, and the Barnard-Rubin rule to pool degree's of freedom; see Little & Rubin (2002). Here, the mcse() function can compute the Monte Carlo standard error (MCSE) of the pooled estimates, via a Jackknife variance estimator for all parameters; see Efron & Gong (1983) and Royston, Carlin & White (2009).

  • method_condmean(type = "bootstrap") uses percentile or normal approximation; see Efron & Tibshirani (1994). Note that for the percentile bootstrap, no standard error is calculated, i.e. the standard errors will be NA in the object / data.frame.

  • method_condmean(type = "jackknife") uses the standard jackknife variance formula; see Efron & Tibshirani (1994).

  • method_bmlmi uses pooling procedure for Bootstrapped Maximum Likelihood MI (BMLMI). See Von Hippel & Bartlett (2021).

References

Bradley Efron and Robert J Tibshirani. An introduction to the bootstrap. CRC press, 1994. [Section 11]

Bradley Efron and Gail Gong. A leisurely look at the bootstrap, the jackknife, and cross-validation. The American Statistician, 37(1):36-48, 1983.

Roderick J. A. Little and Donald B. Rubin. Statistical Analysis with Missing Data, Second Edition. John Wiley & Sons, Hoboken, New Jersey, 2002. [Section 5.4]

Royston, P., Carlin, J. B., & White, I. R. Multiple imputation of missing values: New features for mim. Stata Journal, 9(2): 252-264, 2009.

Von Hippel, Paul T and Bartlett, Jonathan W. Maximum likelihood multiple imputation: Faster imputations and consistent standard errors without posterior draws. 2021.

Examples 

# Prepare the data: expand to one row per subject and visit
dat <- expand_locf(
    antidepressant_data,
    PATIENT = levels(antidepressant_data$PATIENT),
    VISIT = levels(antidepressant_data$VISIT),
    vars = c("BASVAL", "THERAPY"),
    group = c("PATIENT"),
    order = c("PATIENT", "VISIT")
)

# Derive data_ice: first missing-outcome visit per patient, imputed under JR.
# Subject 3618 has only an intermittent missing value and is removed.
is_missing <- is.na(dat$CHANGE)
dat_ice <- dat[is_missing, c("PATIENT", "VISIT")]
dat_ice <- dat_ice[!duplicated(dat_ice$PATIENT), ]
dat_ice$strategy <- "JR"
dat_ice <- dat_ice[dat_ice$PATIENT != 3618, ]

vars <- set_vars(
    outcome = "CHANGE",
    visit = "VISIT",
    subjid = "PATIENT",
    group = "THERAPY",
    covariates = c("BASVAL*VISIT", "THERAPY*VISIT")
)

# \donttest{
# Approximate Bayesian imputation, so that pooling uses Rubin's rules
set.seed(987)
drawObj <- draws(
    data = dat,
    data_ice = dat_ice,
    vars = vars,
    method = method_approxbayes(n_samples = 20),
    quiet = TRUE
)
imputeObj <- impute(
    drawObj,
    references = c("DRUG" = "PLACEBO", "PLACEBO" = "PLACEBO")
)
anaObj <- analyse(
    imputeObj,
    ancova,
    vars = set_vars(
        subjid = "PATIENT",
        outcome = "CHANGE",
        visit = "VISIT",
        group = "THERAPY",
        covariates = "BASVAL"
    )
)

# Pool the analysis results across the imputed datasets
poolObj <- pool(anaObj)
poolObj
#> 
#> Pool Object
#> -----------
#> Number of Results Combined: 20
#> Method: rubin
#> Confidence Level: 0.95
#> Alternative: two.sided
#> 
#> Results:
#> 
#>   ==================================================
#>    parameter   est     se     lci     uci     pval  
#>   --------------------------------------------------
#>      trt_4    -0.092  0.683  -1.439  1.256   0.893  
#>    lsm_ref_4  -1.616  0.486  -2.576  -0.656  0.001  
#>    lsm_alt_4  -1.708  0.475  -2.645  -0.77   <0.001 
#>      trt_5    1.317   0.945  -0.552  3.185   0.166  
#>    lsm_ref_5  -4.127  0.674  -5.459  -2.795  <0.001 
#>    lsm_alt_5  -2.81   0.651  -4.095  -1.525  <0.001 
#>      trt_6    1.956   1.02   -0.06   3.973   0.057  
#>    lsm_ref_6  -6.122  0.722  -7.55   -4.694  <0.001 
#>    lsm_alt_6  -4.166  0.714  -5.579  -2.752  <0.001 
#>      trt_7    2.084   1.122  -0.136  4.303   0.066  
#>    lsm_ref_7  -7.058  0.857  -8.761  -5.355  <0.001 
#>    lsm_alt_7  -4.974  0.78   -6.518  -3.43   <0.001 
#>   --------------------------------------------------
#> 

# Monte Carlo standard errors of the pooled estimates
mcse(poolObj, anaObj)
#> 
#> Monte Carlo Standard Errors for Pooled Estimates (mcse Object)
#> -----------
#> Number of Results Combined: 20
#> 
#> Results:
#> 
#>   ===================================================
#>    parameter   est    se     lci    uci      pval    
#>   ---------------------------------------------------
#>      trt_4      0      0      0      0    < 0.000001 
#>    lsm_ref_4    0      0      0      0    < 0.000001 
#>    lsm_alt_4    0      0      0      0    < 0.000001 
#>      trt_5    0.061  0.017  0.076  0.063   0.02205   
#>    lsm_ref_5  0.044  0.011  0.04   0.057  < 0.000001 
#>    lsm_alt_5  0.037  0.008  0.035  0.044  0.0000098  
#>      trt_6    0.074  0.022  0.066  0.104   0.00818   
#>    lsm_ref_6  0.05   0.012  0.06   0.051  < 0.000001 
#>    lsm_alt_6  0.054  0.016  0.054  0.071  < 0.000001 
#>      trt_7    0.088  0.018  0.103  0.087   0.01287   
#>    lsm_ref_7  0.093  0.028  0.099  0.119  < 0.000001 
#>    lsm_alt_7  0.061  0.024  0.089  0.069  < 0.000001 
#>   ---------------------------------------------------
#> 
# }