% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/boot.bs.R
\name{boot.bs}
\alias{boot.bs}
\title{Bollen-Stine Bootstrapping with Incomplete Data}
\usage{
boot.bs(object = NULL, data = NULL, model = NULL, sigma = NULL, mu = NULL,
        group = NULL, chisq = NULL, em.cov = NULL, trans = c(1, 2), R = 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, ...)
}
\arguments{
\item{object}{an object of class lavaan, i.e., a fitted latent variable model
including mean structures, i.e., \code{meanstructure = TRUE}.}

\item{data}{a data frame representing the target raw data set, optional
argument if the argument \code{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 \code{sigma} and \code{mu}.}

\item{model}{a character string. Optional argument representing the target
model if the argument \code{object} is not specified.}

\item{sigma}{a matrix. Optional argument representing the model-implied
covariance matrix if the argument \code{object} is not specified.}

\item{mu}{a numeric vector. Optional argument representing the model-implied
mean vector if the argument \code{object} is not specified.}

\item{group}{a character vector. Optional argument representing the name of
the grouping variable in \code{data} if the argument \code{object}
is not specified.}

\item{chisq}{a numeric value. Optional argument representing the model's
\eqn{\chi^2} test statistic if the argument \code{object} is
not specified.}

\item{em.cov}{a matrix. Optional argument representing the EM or Two-Stage
ML estimated covariance matrix used to speed up the Transformation
2 algorithm.}

\item{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., \code{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 \code{trans = 2} (default)
when there are more missing data patterns.}

\item{R}{a numeric value indicating the number of bootstrap replicates
(default is 500).}

\item{return}{a character string indicating which results to return, i.e.,
\code{"transdat"} for only the transformed data, \code{"bootsamp"}
for only the bootstrap samples, or \code{"output"} (default)
for the output table for the Bollen-Stine Bootstrapping of the
chi-square statistic.}

\item{seed}{a numeric value specifying the seed of the pseudo-random numbers
used when drawing bootstrap samples.}

\item{progress}{logical: if \code{TRUE} (default), progress bar will be displayed
while fitting the model to the bootstrap samples. Note that
a \code{for} loop is used when \code{progress = TRUE}, while
the \code{sapply} function is used when \code{progress = FALSE}.}

\item{digits}{an integer value indicating the number of decimal places
to be used for displaying the \eqn{\chi^2} test statistic.}

\item{p.digits}{an integer value indicating the number of decimal places
to be used for displaying the \emph{p}-values.}

\item{plot}{logical: if \code{TRUE}, bootstrap sampling distribution of
the \eqn{\chi^2} test statistic is plotted with a histogram
including a density curve.}

\item{filename}{a character string indicating the \code{filename} argument
including the file extension in the \code{ggsave} function.
Note that one of \code{".eps"}, \code{".ps"}, \code{".tex"},
\code{".pdf"} (default), \code{".jpeg"}, \code{".tiff"},
\code{".png"}, \code{".bmp"}, \code{".svg"} or \code{".wmf"}
needs to be specified as file extension in the \code{file}}

\item{width}{a numeric value indicating the \code{width} argument (default
is the size of the current graphics device) in the \code{ggsave}
function.}

\item{height}{a numeric value indicating the \code{height} argument (default
is the size of the current graphics device) in the \code{ggsave}
function.}

\item{dpi}{a numeric value indicating the \code{dpi} argument
(default is \code{600}) in the \code{ggsave} function.}

\item{write}{a character string naming a file for writing the output into
either a text file with file extension \code{".txt"} (e.g.,
\code{"Output.txt"}) or Excel file with file extension
\code{".xlsx"} (e.g., \code{"Output.xlsx"}). If the file name
does not contain any file extension, an Excel file will be
written.}

\item{append}{logical: if \code{TRUE} (default), output will be appended to
an existing text file with extension \code{.txt} specified in
\code{write}, if \code{FALSE} existing text file will be
overwritten.}

\item{check}{logical: if \code{TRUE} (default), argument specification
is checked.}

\item{output}{logical: if \code{TRUE} (default), output is shown.}

\item{...}{additional arguments in the lavaan::lavaan() function, see
lavaan::lavOptions().}
}
\value{
Returns an object of class \code{misty.object} when specifying \code{return = "output"}:

\item{\code{call}}{function call}
\item{\code{type}}{type of analysis}
\item{\code{object}}{object of class lavaan specified in the argument \code{object}}
\item{\code{args}}{specification of function arguments}
\item{\code{plot}}{ggplot2 object when specifying \code{plot = TRUE}}
\item{\code{result}}{result table}

When specifying \code{return = "transdat"}, the transformed data and when
specifying \code{return = "bootsamp"}, the bootstrap samples are returned.
}
\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).
}
\note{
This function is based on modified copies of the functions \code{bsBootMiss}
from the \pkg{semTools} package by Terrence D. Jorgensen et al. (2026).
}
\examples{
\dontrun{
# 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, R = 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())
}
}
\references{
Bollen, K. A., & Stine, R. A. (1992). Bootstrapping goodness-of-fit measures
in structural equation models. \emph{Sociological Methods & Research, 21}(2),
205-229. https://doi.org/10.1177/0049124192021002004

Jorgensen, T. D., Pornprasertmanit, S., Schoemann, A. M., & Rosseel, Y. (2026).
\emph{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. \emph{Multivariate Behavioral
Research, 44}(6), 741-763. https://doi.org/10.1080/00273170903333590
}
\author{
Takuya Yanagida
}
