boot.bs: Bollen-Stine Bootstrapping with Incomplete Data

Description

This function performs the model-based Bollen-Stine Bootstrapping with incomplete data of the chi-square statistic. By default, the function performs model-based bootstrapping based on transformation method 2 in Savalei and Yuan (2009).

Usage

boot.bs(object = NULL, data = NULL, model = NULL, sigma = NULL, mu = NULL,
        group = NULL, chisq = NULL, em.cov = NULL, trans = c(1, 2), nrep = 500,
        return = c("transdat", "bootsamp", "output"), seed = NULL,
        progress = TRUE, digits = 2, p.digits = 3, plot = FALSE, filename = NULL,
        width = NA, height = NA, dpi = 600, write = NULL, append = TRUE,
        check = TRUE, output = TRUE, ...)

Value

Returns an object of class misty.object when specifying return = "output":

call: function call
type: type of analysis
object: object of class lavaan specified in the argument object
args: specification of function arguments
plot: ggplot2 object when specifying plot = TRUE
result: result table

When specifying return = "transdat", the transformed data and when specifying return = "bootsamp", the bootstrap samples are returned.

Arguments

object: an object of class lavaan, i.e., a fitted latent variable model including mean structures, i.e., meanstructure = TRUE.
data: a data frame representing the target raw data set, optional argument if the argument object is not specified. Note that the data frame should only include variables that are used in the covariance matrix and mean vector specified in the arguments sigma and mu.
model: a character string. Optional argument representing the target model if the argument object is not specified.
sigma: a matrix. Optional argument representing the model-implied covariance matrix if the argument object is not specified.
mu: a numeric vector. Optional argument representing the model-implied mean vector if the argument object is not specified.
group: a character vector. Optional argument representing the name of the grouping variable in data if the argument object is not specified.
chisq: a numeric value. Optional argument representing the model's \(\chi^2\) test statistic if the argument object is not specified.
em.cov: a matrix. Optional argument representing the EM or Two-Stage ML estimated covariance matrix used to speed up the Transformation 2 algorithm.
trans: a character string representing the transformation method in Savalei and Yuan (2009). There are three methods presented in the article, but only the first two are currently implemented in the function, i.e., trans = 1 when there are few missing data patterns, each of which has a large size, such as in a planned missing data design, or trans = 2 (default) when there are more missing data patterns.
nrep: a numeric value indicating the number of bootstrap replicates (default is 500).
return: a character string indicating which results to return, i.e., "transdat" for only the transformed data, "bootsamp" for only the bootstrap samples, or "output" (default) for the output table for the Bollen-Stine Bootstrapping of the chi-square statistic.
seed: a numeric value specifying the seed of the pseudo-random numbers used when drawing bootstrap samples.
progress: logical: if TRUE (default), progress bar will be displayed while fitting the model to the bootstrap samples. Note that a for loop is used when progress = TRUE, while the sapply function is used when progress = FALSE.
digits: an integer value indicating the number of decimal places to be used for displaying the \(\chi^2\) test statistic.
p.digits: an integer value indicating the number of decimal places to be used for displaying the p-values.
plot: logical: if TRUE, bootstrap sampling distribution of the \(\chi^2\) test statistic is plotted with a histogram including a density curve.
filename: a character string indicating the filename argument including the file extension in the ggsave function. Note that one of ".eps", ".ps", ".tex", ".pdf" (default), ".jpeg", ".tiff", ".png", ".bmp", ".svg" or ".wmf" needs to be specified as file extension in the file
width: a numeric value indicating the width argument (default is the size of the current graphics device) in the ggsave function.
height: a numeric value indicating the height argument (default is the size of the current graphics device) in the ggsave function.
dpi: a numeric value indicating the dpi argument (default is 600) in the ggsave function.
write: a character string naming a file for writing the output into either a text file with file extension ".txt" (e.g., "Output.txt") or Excel file with file extension ".xlsx" (e.g., "Output.xlsx"). If the file name does not contain any file extension, an Excel file will be written.
append: logical: if TRUE (default), output will be appended to an existing text file with extension .txt specified in write, if FALSE existing text file will be overwritten.
check: logical: if TRUE (default), argument specification is checked.
output: logical: if TRUE (default), output is shown.
...: additional arguments in the lavaan::lavaan() function, see lavaan::lavOptions().

Author

Takuya Yanagida

References

Bollen, K. A., & Stine, R. A. (1992). Bootstrapping goodness-of-fit measures in structural equation models. Sociological Methods & Research, 21(2), 205-229. https://doi.org/10.1177/0049124192021002004

Jorgensen, T. D., Pornprasertmanit, S., Schoemann, A. M., & Rosseel, Y. (2026). semTools: Useful tools for structural equation modeling. R package version 0.5-8. Retrieved from https://CRAN.R-project.org/package=semTools

Savalei, V., & Yuan, K.-H. (2009). On the model-based bootstrap with missing data: Obtaining a p-value for a test of exact fit. Multivariate Behavioral Research, 44(6), 741-763. https://doi.org/10.1080/00273170903333590

Examples

Run this code

if (FALSE) {
# Load lavaan package
library(lavaan)

# Holzinger and Swineford data set
dat <- HolzingerSwineford1939

# Introduce missing data
dat$x5 <- ifelse(dat$x1 <= quantile(dat$x1, 0.3), NA, dat$x5)
dat$x9 <- ifelse(is.na(dat$x5), NA, dat$x9)

# Model specification
model <- 'visual  =~ x1 + x2 + x3
          textual =~ x4 + x5 + x6
          speed   =~ x7 + x8 + x9'

# Model estimation
fit <- sem(model, data = dat, meanstructure = TRUE, std.lv = TRUE,
           missing = "fiml", group = "school")

#————————————————————————————————————————————————————————————————————————————
# Bollen-Stine Bootstrapping with Incomplete Data

# Example 1: Default setting, transformation method 2, 500 replicates
# Plot bootstrap sampling distribution of the test statistic
boot.bs(fit, seed = 42, plot = TRUE)

#————————————————————————————————————————————————————————————————————————————
# Transformed Data and Bootstrap Samples

# Example 2: Return transformed data only
transdat <- boot.bs(fit, return = "transdat")

# Example 3: Return bootstrap samples only
bootsamp <- boot.bs(fit, return = "bootsamp")

#————————————————————————————————————————————————————————————————————————————
# Plot Bootstrap Sampling Distribution of Chi-Square Test Statistic

# Bollen-Stine Bootstrapping
object <- boot.bs(fit, seed = 42)

# Load ggplot2 package
library(ggplot2)

# Plot data
plotdat <- data.frame(chisq = object$boot.chisq)

# Example 3: Plot bootstrap sampling distribution, create plot manually
ggplot(plotdat, aes(chisq)) +
  geom_histogram(aes(y = after_stat(density)), color = "black", alpha = 0.4, fill = "gray85") +
  geom_density(color = "#0072B2") +
  geom_vline(aes(xintercept = object$result$chisq, color = "Observed Test Statistic")) +
  scale_x_continuous(name = expression(paste(chi^2, " Test Statistic")),
                     limits = c(0, max(c(plotdat$chisq, object$result$chisq), na.rm = TRUE))) +
  scale_y_continuous(name = "Probability Density, f(x)", expand = expansion(mult = c(0, 0.05))) +
  scale_color_manual(values = c("Observed Test Statistic" = "#CC79A7")) +
  theme_bw() +
  theme(legend.position = "bottom", legend.box.margin = margin(-12, 0, 0, 0),
        legend.title = element_blank())
}

Run the code above in your browser using DataLab