semboottools (version 0.1.1)

hist_qq_boot: Diagnostic Plots of Bootstrap Estimates in 'lavaan'

Description

Plots for examining the distribution of bootstrap estimates in a model fitted by lavaan.

Usage

hist_qq_boot(
  object,
  param,
  standardized = NULL,
  nclass = NULL,
  hist_color = "#5DADE233",
  hist_linewidth = 1.5,
  hist_border_color = "#1B4F72",
  density_line_type = "solid",
  density_line_color = "#8B0000CC",
  density_line_linewidth = 2,
  est_line_color = "#154360",
  est_line_type = "dashed",
  est_line_linewidth = 2,
  qq_dot_pch = 21,
  qq_dot_color = "#1B4F72",
  qq_dot_fill = "#5DADE233",
  qq_dot_size = 1.3,
  qq_line_color = "#8B0000CC",
  qq_line_linewidth = 2.1,
  qq_line_linetype = "solid"
)
scatter_boot(
  object,
  params,
  standardized = NULL,
  main = "Bootstrap Estimates",
  ...
)

Value

Return the original lavaan::lavaan object invisibly. Called for its side-effect (plotting the graphs).

Arguments

object

Either a lavaan-class object with bootstrap estimates stored, or the output of standardizedSolution_boot(). For standardized solution and user-defined parameters, if the object is a `lavaan-class`` object, the estimates need to be stored by store_boot().

param

String. The name of the parameter to be plotted, which should be the name as appeared in a call to coef().

standardized

Logical. Whether the estimates from the standardized solution are to be plotted. Default is NULL. If object is a lavaan object, then this is a required parameter and users need to explicitly set it to TRUE or FALSE. If object is the output of standardizedSolution_boot(), then this argument is ignored ( forced to be TRUE internally).

nclass

The number of breaks. This argument will be passed to hist(). Default is NULL.

hist_color

String. The color of the bars in the histogram. It will be passed to hist() for the argument col. Default is light blue (scales::alpha("#5DADE2", 0.2)).

hist_linewidth

The width of the borders of the bars in the histogram. Default is 1.5.

hist_border_color

String. The color of the borders (outline) of the bars in the histogram. It will be passed to hist() for the argument border. Default is a dark blue color ("#1B4F72").

density_line_type

String. The type of the line of the density curve in the histogram. It will be passed to lines() for the argument lty. Default is "solid".

density_line_color

String. The color of the density curve in the histogram. It will be passed to lines() for the argument col. Default is "blue".

density_line_linewidth

The width of the density curve in the histogram. It will be passed to lines() for the argument lwd. Default is 2.

est_line_color

String. The color of the vertical line showing the point estimate in the histogram. It will be passed to abline() for the argument col.

est_line_type

String. The type of the vertical line in the histogram showing the point estimate of the parameter. It will be passed to abline() for the argument lty. Default is "dashed",

est_line_linewidth

The width of the vertical line showing the point estimate in the histogram. It will be passed to hist() for the argument lwd. Default is 2.

qq_dot_pch

Numeric. The shape of the points in the normal QQ-plot. It will be passed to qqnorm() for the argument pch. Default is 21.

qq_dot_color

String. The color of the points in the normal QQ-plot. It will be passed to qqnorm() for the argument col.

qq_dot_fill

String. The fill color of the points in the normal QQ-plot. Only applicable when qq_dot_pch is set to a symbol that allows fill color (e.g., pch = 21). It will be passed to qqnorm() for the argument bg. Default is a semi-transparent light blue (scales::alpha("#5DADE2", 0.2)).

qq_dot_size

The size of the points in the normal QQ-plot. It will be passed to qqnorm() for the argument cex. Default is 2.

qq_line_color

String. The color of the diagonal line to be drawn in the normal QQ-plot. It will be passed to qqline() for the argument col.

qq_line_linewidth

The width of the diagonal line to be drawn in the normal QQ-plot. It will be passed to qqline() for the argument lwd. Default is 2.1.

qq_line_linetype

The type of the diagonal line to be drawn in the normal QQ-plot. Default is "solid".

params

The vector of the names of the parameters to be plotted, which should be the names as appeared in a call to coef(). The function scatter_boot() requires two or more parameters selected by this argument.

main

The title of the scatterplot matrix. Default is "Bootstrap Estimates".

...

Arguments to be passed to psych::pairs.panels(). Please refer to the help page of psych::pairs.panels() for arguments to customize the plot.

Author

Shu Fai Cheung https://orcid.org/0000-0002-9871-9448

Details

Rousselet, Pernet, and Wilcox (2021) argued that when using bootstrapping, it is necessary to examine the distribution of bootstrap estimates. This can be done when boot::boot() is used because it has a plot method for its output. This cannot be easily done in model fitted by lavaan::lavaan(), such as lavaan::sem() and lavaan::cfa().

The function hist_qq_boot() is used for plotting the distribution of bootstrap estimates for a model fitted by lavaan in a format similar to that of the output of boot::boot(), with a histogram on the left and a normal QQ-plot on the right.

For free parameters in a model (unstandardized), it can be called directly on the output of lavaan and retrieves the stored estimates.

For estimates of user-defined parameters, call store_boot() first to compute and store the bootstrap estimates first.

For estimates in standardized solution, for both free and user-defined parameters, call store_boot() first to compute and store the bootstrap estimates in the standardized solution.

It can also plot bootstrap estimates in the output of standardizedSolution_boot() or parameterEstimates_boot().

The function scatter_boot() is used to generate a scatterplot matrix of the bootstrap estimates of two or more parameters. The function psych::pairs.panels() from the package psych is used.

Like hist_qq_boot(), it can also be used on the output of standardizedSolution_boot() or parameterEstimates_boot().

References

Rousselet, G. A., Pernet, C. R., & Wilcox, R. R. (2021). The percentile bootstrap: A primer with step-by-step instructions in R. Advances in Methods and Practices in Psychological Science, 4(1), 1--10. tools:::Rd_expr_doi("10.1177/2515245920911881")

See Also

store_boot() and standardizedSolution_boot().

Examples

library(lavaan)

set.seed(5478374)
n <- 50
x <- runif(n) - .5
m <- .40 * x + rnorm(n, 0, sqrt(1 - .40))
y <- .30 * m + rnorm(n, 0, sqrt(1 - .30))
dat <- data.frame(x = x, y = y, m = m)

mod <-
"
m ~ a * x
y ~ b * m + x
ab := a * b
"
fit <- sem(mod,
           data = dat,
           se = "bootstrap",
           bootstrap = 50,
           iseed = 985714)

# Can plot bootstrap estimates for
# free parameters directly
# Note that 'standardized' must be always be set to
# either TRUE or FALSE. No default value.
hist_qq_boot(fit, "a", standardized = FALSE)

# For estimates of user-defined parameters,
# call store_boot() first.
fit <- store_boot(fit)
hist_qq_boot(fit, "ab", standardized = FALSE)

# For estimates in standardized solution,
# call store_boot() first.
fit <- store_boot(fit)
hist_qq_boot(fit, "a", standardized = TRUE)
hist_qq_boot(fit, "ab", standardized = TRUE)

# It can also plot the estimates stored
# in the output of standardizedSolution_boot().
std_boot <- standardizedSolution_boot(fit)
hist_qq_boot(std_boot, "ab")
hist_qq_boot(fit, "ab", standardized = TRUE)



# Scatterplot matrix of bootstrap estimates for
# two or more free parameters
scatter_boot(fit, c("a", "b", "ab"), standardized = FALSE)

# Can include user-defined parameters in
# scatterplot matrix, if their bootstrap
# estimates have been stored
scatter_boot(fit, c("ab", "a", "b"), standardized = FALSE)

# scatter_boot also supports the
# standardized solution
scatter_boot(fit, c("a", "b", "ab"), standardized = TRUE)