resi function

Robust Effect Size Index (RESI) point and interval estimation for models

Robust Effect Size Index (RESI) point and interval estimation for models

This function will estimate the robust effect size (RESI) from Vandekar, Tao, & Blume (2020) and its confidence interval in various ways for a fitted model object. The overall RESI is estimated via a Wald test. RESI is (optionally) estimated for each factor in coefficients-style table. RESI is (optionally) estimated for each variable/interaction in an Anova-style table for models with existing Anova methods. CIs can be calculated using either non-parametric or Bayesian bootstrapping.

resi(model.full, ...)

## Default S3 method:
resi(
  model.full,
  model.reduced = NULL,
  data,
  anova = TRUE,
  coefficients = TRUE,
  overall = TRUE,
  nboot = 1000,
  boot.method = "nonparam",
  vcovfunc = sandwich::vcovHC,
  alpha = 0.05,
  store.boot = FALSE,
  Anova.args = list(),
  vcov.args = list(),
  unbiased = TRUE,
  parallel = c("no", "multicore", "snow"),
  ncpus = getOption("boot.ncpus", 1L),
  long = FALSE,
  clvar = NULL,
  ...
)

## S3 method for class 'glm'
resi(
  model.full,
  model.reduced = NULL,
  data,
  anova = TRUE,
  coefficients = TRUE,
  overall = TRUE,
  nboot = 1000,
  vcovfunc = sandwich::vcovHC,
  alpha = 0.05,
  store.boot = FALSE,
  Anova.args = list(),
  vcov.args = list(),
  unbiased = TRUE,
  parallel = c("no", "multicore", "snow"),
  ncpus = getOption("boot.ncpus", 1L),
  ...
)

## S3 method for class 'lm'
resi(
  model.full,
  model.reduced = NULL,
  data,
  anova = TRUE,
  coefficients = TRUE,
  overall = TRUE,
  nboot = 1000,
  boot.method = "nonparam",
  vcovfunc = sandwich::vcovHC,
  alpha = 0.05,
  store.boot = FALSE,
  Anova.args = list(),
  vcov.args = list(),
  unbiased = TRUE,
  parallel = c("no", "multicore", "snow"),
  ncpus = getOption("boot.ncpus", 1L),
  ...
)

## S3 method for class 'nls'
resi(
  model.full,
  model.reduced = NULL,
  data,
  coefficients = TRUE,
  overall = TRUE,
  nboot = 1000,
  boot.method = "nonparam",
  anova = FALSE,
  vcovfunc = r_nlshc,
  alpha = 0.05,
  store.boot = FALSE,
  vcov.args = list(),
  unbiased = TRUE,
  parallel = c("no", "multicore", "snow"),
  ncpus = getOption("boot.ncpus", 1L),
  ...
)

## S3 method for class 'survreg'
resi(
  model.full,
  model.reduced = NULL,
  data,
  anova = TRUE,
  coefficients = TRUE,
  overall = TRUE,
  nboot = 1000,
  vcovfunc = vcov,
  alpha = 0.05,
  store.boot = FALSE,
  Anova.args = list(),
  unbiased = TRUE,
  parallel = c("no", "multicore", "snow"),
  ncpus = getOption("boot.ncpus", 1L),
  ...
)

## S3 method for class 'coxph'
resi(
  model.full,
  model.reduced = NULL,
  data,
  anova = TRUE,
  coefficients = TRUE,
  overall = TRUE,
  nboot = 1000,
  vcovfunc = vcov,
  alpha = 0.05,
  store.boot = FALSE,
  Anova.args = list(),
  unbiased = TRUE,
  parallel = c("no", "multicore", "snow"),
  ncpus = getOption("boot.ncpus", 1L),
  ...
)

## S3 method for class 'hurdle'
resi(
  model.full,
  model.reduced = NULL,
  data,
  coefficients = TRUE,
  overall = TRUE,
  nboot = 1000,
  vcovfunc = sandwich::sandwich,
  anova = FALSE,
  alpha = 0.05,
  store.boot = FALSE,
  vcov.args = list(),
  unbiased = TRUE,
  parallel = c("no", "multicore", "snow"),
  ncpus = getOption("boot.ncpus", 1L),
  ...
)

## S3 method for class 'zeroinfl'
resi(
  model.full,
  model.reduced = NULL,
  data,
  coefficients = TRUE,
  overall = TRUE,
  nboot = 1000,
  vcovfunc = sandwich::sandwich,
  anova = FALSE,
  alpha = 0.05,
  store.boot = FALSE,
  vcov.args = list(),
  unbiased = TRUE,
  parallel = c("no", "multicore", "snow"),
  ncpus = getOption("boot.ncpus", 1L),
  ...
)

## S3 method for class 'geeglm'
resi(
  model.full,
  model.reduced = NULL,
  data,
  anova = TRUE,
  coefficients = TRUE,
  overall = TRUE,
  nboot = 1000,
  alpha = 0.05,
  store.boot = FALSE,
  unbiased = TRUE,
  parallel = c("no", "multicore", "snow"),
  ncpus = getOption("boot.ncpus", 1L),
  ...
)

## S3 method for class 'gee'
resi(
  model.full,
  data,
  nboot = 1000,
  alpha = 0.05,
  store.boot = FALSE,
  unbiased = TRUE,
  parallel = c("no", "multicore", "snow"),
  ncpus = getOption("boot.ncpus", 1L),
  ...
)

## S3 method for class 'lme'
resi(
  model.full,
  alpha = 0.05,
  nboot = 1000,
  anova = TRUE,
  vcovfunc = clubSandwich::vcovCR,
  vcov.args = list(),
  ...
)

## S3 method for class 'lmerMod'
resi(
  model.full,
  alpha = 0.05,
  nboot = 1000,
  anova = TRUE,
  vcovfunc = clubSandwich::vcovCR,
  vcov.args = list(),
  ...
)

Arguments

  • model.full: lm, glm, nls, survreg, coxph, hurdle, zeroinfl, gee, geeglm or lme model object.
  • ...: Ignored.
  • model.reduced: Fitted model object of same type as model.full. By default NULL; the same model as the full model but only having intercept.
  • data: Data.frame or object coercible to data.frame of model.full data (required for some model types).
  • anova: Logical, whether to produce an Anova table with the RESI columns added. By default = TRUE.
  • coefficients: Logical, whether to produce a coefficients (summary) table with the RESI columns added. By default = TRUE.
  • overall: Logical, whether to produce an overall Wald test comparing full to reduced model with RESI columns added. By default = TRUE.
  • nboot: Numeric, the number of bootstrap replicates. By default, 1000.
  • boot.method: String, which type of bootstrap to use: nonparam = non-parametric bootstrap (default); bayes = Bayesian bootstrap.
  • vcovfunc: The variance estimator function for constructing the Wald test statistic. By default, vcovHC (the robust (sandwich) variance estimator).
  • alpha: Numeric, significance level of the constructed CIs. By default, 0.05.
  • store.boot: Logical, whether to store all the bootstrapped estimates. By default, FALSE.
  • Anova.args: List, additional arguments to be passed to Anova function.
  • vcov.args: List, additional arguments to be passed to vcovfunc.
  • unbiased: Logical, whether to use the unbiased or alternative T/Z statistic to RESI conversion. By default, TRUE. See details.
  • parallel: See documentation for boot .
  • ncpus: See documentation for boot .
  • long: Logical, whether the data is longitudinal/clustered. By default, FALSE.
  • clvar: Character, the name of the cluster/id variable if data is clustered. By default, NULL.

Returns

Returns a list that includes function arguments, RESI point estimates, and confidence intervals in coefficients/anova-style tables

Details

The RESI, denoted as S, is applicable across many model types. It is a unitless index and can be easily be compared across models. The RESI can also be converted to Cohen's d (S2d) under model homoskedasticity.

This function computes the RESI point estimates and bootstrapped confidence intervals based on Chi-square, F, T, or Z statistics. The robust (sandwich) variance is used by default, allowing for consistency under model-misspecification. The RESI is related to the non-centrality parameter of the test statistic. The RESI estimate is consistent for all four (Chi-square, F, T, and Z) types of statistics used. The Chi-square and F-based calculations rely on asymptotic theory, so they may be biased in small samples. When possible, the T and Z statistics are used. There are two formulas for both the T and Z statistic conversion. The first (default, unbiased = TRUE) are based on solving the expected value of the T or Z statistic for the RESI. The alternative is based on squaring the T or Z statistic and using the F or Chi-square statistic conversion. Both of these methods are consistent, but the alternative exhibits a notable amount of finite sample bias. The alternative may be appealing because its absolute value will be equal to the RESI based on the F or Chi-square statistic. The RESI based on the Chi-Square and F statistics is always greater than or equal to 0. The type of statistic used is listed with the output. See f2S, chisq2S, t2S, and z2S for more details on the formulas.

For GEE (geeglm ) models, a longitudinal RESI (L-RESI) and a cross-sectional, per-measurement RESI (CS-RESI) is estimated. The longitudinal RESI takes the specified clustering into account, while the cross-sectional RESI is estimated using a model where each measurement is its own cluster.

For most lm and nls model types, there is a Bayesian bootstrap option available as an alternative to the default, standard non-parametric bootstrap. The interpretation of a Bayesian bootstrapped interval is similar to that of a credible interval.

Certain model types require the data used for the model be entered as an argument. These are: nls, survreg, and coxph. Additionally, if a model includes certain functions (splines, factor, I), the data needs to be provided.

If running into convergence issues with nls models, it is advised to refit the nls model with starting values equal to the estimates provided by the model and then try rerunning resi.

Methods (by class)

  • resi(default): RESI point and interval estimation for models
  • resi(glm): RESI point and interval estimation for models
  • resi(lm): RESI point and interval estimation for lm models
  • resi(nls): RESI point and interval estimation for nls models
  • resi(survreg): RESI point and interval estimation for survreg models
  • resi(coxph): RESI point and interval estimation for coxph models
  • resi(hurdle): RESI point and interval estimation for hurdle models
  • resi(zeroinfl): RESI point and interval estimation for zeroinfl models
  • resi(geeglm): RESI point and interval estimation for GEE models
  • resi(gee): RESI point and interval estimation for GEE models
  • resi(lme): RESI point and interval estimation for LME (nlme) models
  • resi(lmerMod): RESI point and interval estimation for lmerMod models

Examples

## for timing purposes, a small number of bootstrap replicates is used in the
## examples. Run them with a higher or default `nboot` argument for better performance

## RESI on a linear model
# fit linear model
mod = lm(charges ~ region * age + bmi + sex, data = RESI::insurance)

# run resi on fitted model with desired number of bootstrap replicates
# store bootstrap results for calculating different CIs later
resi_obj = resi(mod, nboot = 50, store.boot = TRUE)
# print output
resi_obj

# fit a reduced model for comparison
mod_red = lm(charges ~ bmi, data = RESI::insurance)

# running resi and including the reduced model will provide almost the exact same
# output as not including a reduced model. The difference is that the "overall"
# portion of the output will compare the full model to the reduced model.
# The "summary" and "anova" RESI estimates will be the same. (The bootstrapped
# confidence intervals may differ.)
resi(model.full = mod, model.reduced = mod_red, nboot = 10)

# used stored bootstrap results to get a different alpha-level confidence interval
summary(resi_obj, alpha = c(0.01, 0.1))
car::Anova(resi_obj, alpha = c(0.01, 0.1))

# the result of resi, as well as the summary or Anova of a `resi` object can be plotted
# if the resi object was created with the store.boot = `TRUE` option, any alpha
# can be specified
plot(resi_obj, alpha = 0.01)
# if the variable names on the y-axis are too long, you can reduce their size with
# the ycex.axis argument (or use regular common solutions like changing the margins)
plot(resi_obj, alpha = 0.01, ycex.axis = 0.5)

# for some model types and formula structures, data argument is required
if(requireNamespace("splines")){
  # fit logistic regression model with splines
  mod = glm(smoker ~ splines::ns(age, df = 3) + region, data = RESI::insurance,
    family = "binomial")

  # specify additional arguments to the variance-covariance function via vcov.args
  resi_obj = resi(mod, data = RESI::insurance, alpha = 0.01,
    vcov.args = list(type = "HC0"), nboot = 25)
  summary(resi_obj)
  car::Anova(resi_obj)}

## RESI on a survival model with alternate Z2S
if(requireNamespace("survival")){
  # fit coxph model on example data from survival package
  # Note: for survival models, you need to specify robust variance in the model
  # creation. resi will ignore the vcovfunc argument for this reason.
  mod.coxph =  survival::coxph(survival::Surv(time, status) ~ age + sex + wt.loss,
   data=survival::lung, robust = TRUE)

  # run resi on the model
  # to use the alternative Z to RESI formula (which is equal in absolute value to the
  # chi-square to RESI (S) formula), specify unbiased = FALSE.
  resi(mod.coxph, data = survival::lung, unbiased = FALSE, nboot = 10)}

References

Vandekar S, Tao R, Blume J. A Robust Effect Size Index. Psychometrika. 2020 Mar;85(1):232-246. doi: 10.1007/s11336-020-09698-2.

Kang, K., Armstrong, K., Avery, S., McHugo, M., Heckers, S., & Vandekar, S. (2021). Accurate confidence interval estimation for non-centrality parameters and effect size indices. arXiv preprint arXiv:2111.05966.

Jones, M., Kang, K., Vandekar, S. (2025). Journal of Statistical Software. RESI: An R Package for Robust Effect Sizes.doi:10.18637/jss.v112.i03

See Also

resi_pe, vcovHC , f2S, chisq2S, z2S, t2S

RESI packageRead PDF manual
  • Maintainer: Megan Jones
  • License: GPL-3
  • Last published: 2025-03-24

Useful links