boot_ses_calc: Bootstrapped Standardized Effect Size (SES) Calculation

View source: R/boot_ses_calc.R

boot_ses_calcR Documentation

Bootstrapped Standardized Effect Size (SES) Calculation

Description

[Maturing]

Calculates non-SMD standardized effect sizes with bootstrap confidence intervals. This function provides more robust confidence intervals for rank-based and probability-based effect size measures through resampling methods.

Usage

boot_ses_calc(
  x,
  ...,
  paired = FALSE,
  ses = "rb",
  alpha = 0.05,
  boot_ci = c("basic", "stud", "perc"),
  R = 1999
)

## Default S3 method:
boot_ses_calc(
  x,
  y = NULL,
  paired = FALSE,
  ses = c("rb", "odds", "logodds", "cstat"),
  alpha = 0.05,
  boot_ci = c("basic", "stud", "perc"),
  R = 1999,
  ...
)

## S3 method for class 'formula'
boot_ses_calc(formula, data, subset, na.action, ...)

Arguments

x

a (non-empty) numeric vector of data values.

...

further arguments to be passed to or from methods.

paired

a logical indicating whether you want a paired t-test.

ses

a character string specifying the effect size measure to calculate: - "rb": rank-biserial correlation (default) - "odds": Wilcoxon-Mann-Whitney odds - "logodds": Wilcoxon-Mann-Whitney log-odds - "cstat": concordance statistic (C-statistic/AUC)

alpha

alpha level (default = 0.05)

boot_ci

method for bootstrap confidence interval calculation: "stud" (studentized, default), "basic" (basic bootstrap), or "perc" (percentile bootstrap).

R

number of bootstrap replications (default = 1999).

y

an optional (non-empty) numeric vector of data values.

formula

a formula of the form lhs ~ rhs where lhs is a numeric variable giving the data values and rhs either 1 for a one-sample or paired test or a factor with two levels giving the corresponding groups. If lhs is of class "Pair" and rhs is 1, a paired test is done.

data

an optional matrix or data frame (or similar: see model.frame) containing the variables in the formula formula. By default the variables are taken from environment(formula).

subset

an optional vector specifying a subset of observations to be used.

na.action

a function which indicates what should happen when the data contain NAs. Defaults to getOption("na.action").

Details

This function calculates bootstrapped confidence intervals for rank-based and probability-based effect size measures. It is an extension of the ses_calc() function that uses resampling to provide more robust confidence intervals, especially for small sample sizes.

The function implements the following bootstrap approach:

  • Calculate the raw effect size using the original data

  • Create R bootstrap samples by resampling with replacement from the original data

  • Calculate the effect size for each bootstrap sample

  • Apply the Fisher z-transformation to stabilize variance for rank-biserial correlation values

  • Calculate confidence intervals using the specified method

  • Back-transform the confidence intervals to the original scale

  • Convert to the requested effect size measure (if not rank-biserial)

Three bootstrap confidence interval methods are available:

  • Basic bootstrap ("basic"): Uses the empirical distribution of bootstrap estimates

  • Studentized bootstrap ("stud"): Accounts for the variability in standard error estimates

  • Percentile bootstrap ("perc"): Uses percentiles of the bootstrap distribution directly

The function supports three study designs:

  • One-sample design: Compares a single sample to a specified value

  • Two-sample independent design: Compares two independent groups

  • Paired samples design: Compares paired observations

Note that extreme values (perfect separation between groups) can produce infinite values during the bootstrapping process. This happens often if the sample size is very small. The function will issue a warning if this occurs, as it may affect the accuracy of the confidence intervals. Additionally, this affects the ability to calculate bias and SE estimates from the bootstrap samples. If the number of infinite values is small (less than 10% of the bootstrap samples) then the infinite values are replaced with the nearest next value (only for the SE and bias estimates, not confidence intervals).

For detailed information on calculation methods, see vignette("robustTOST").

Value

A data frame containing the following information:

  • estimate: The effect size estimate calculated from the original data

  • bias: Estimated bias (difference between original estimate and median of bootstrap estimates)

  • SE: Standard error estimated from the bootstrap distribution

  • lower.ci: Lower bound of the bootstrap confidence interval

  • upper.ci: Upper bound of the bootstrap confidence interval

  • conf.level: Confidence level (1-alpha)

  • boot_ci: The bootstrap confidence interval method used

Purpose

Use this function when:

  • You need more robust confidence intervals for non-parametric effect sizes

  • You prefer resampling-based confidence intervals over asymptotic approximations

  • You need to quantify uncertainty in rank-based effect sizes more accurately

See Also

Other effect sizes: boot_smd_calc(), ses_calc(), smd_calc()

Examples

# Example 1: Independent groups comparison with basic bootstrap CI
set.seed(123)
group1 <- c(1.2, 2.3, 3.1, 4.6, 5.2, 6.7)
group2 <- c(3.5, 4.8, 5.6, 6.9, 7.2, 8.5)

# Use fewer bootstrap replicates for a quick example
result <- boot_ses_calc(x = group1, y = group2,
                        ses = "rb",
                        boot_ci = "basic",
                        R = 99)

# Example 2: Using formula notation to calculate concordance statistic
data(mtcars)
result <- boot_ses_calc(formula = mpg ~ am,
                        data = mtcars,
                        ses = "cstat",
                        boot_ci = "perc",
                        R = 99)

# Example 3: Paired samples with studentized bootstrap CI
data(sleep)
with(sleep, boot_ses_calc(x = extra[group == 1],
                          y = extra[group == 2],
                          paired = TRUE,
                          ses = "rb",
                          boot_ci = "stud",
                          R = 99))

# Example 4: Comparing different bootstrap CI methods
## Not run: 
# Basic bootstrap
basic_ci <- boot_ses_calc(x = group1, y = group2, boot_ci = "basic")

# Percentile bootstrap
perc_ci <- boot_ses_calc(x = group1, y = group2, boot_ci = "perc")

# Studentized bootstrap
stud_ci <- boot_ses_calc(x = group1, y = group2, boot_ci = "stud")

# Compare the results
rbind(basic_ci, perc_ci, stud_ci)

## End(Not run)


TOSTER documentation built on Aug. 23, 2025, 1:13 a.m.