lavResidualsY: Compute residuals for the y-variables given the values of the x-variables

Description

This function can be used to compute the (case-wise) residuals for the (observed) y-variables in a structural equation model, defined as the difference between the observed values and the (model-based) predicted values that are returned by lavPredictY.

Usage

lavResidualsY(object, newdata = NULL,
              ynames = lav_object_vnames(object, "ov.y"),
              xnames = lav_object_vnames(object, "ov.x"),
              method = "conditional.mean",
              label = TRUE, assemble = TRUE,
              force_zero_mean = FALSE,
              lambda = 0,
              ...)

Arguments

object: An object of class lavaan.
newdata: An optional data.frame, containing the same variables as the data.frame that was used when fitting the model in object. This data.frame should also include the y-variables (their observed values are used to compute the residuals). Note that if no meanstructure was used in the original fit, we will use the saturated sample means of the original fit as substitutes for the model-implied means. Alternatively, refit the model using meanstructure = TRUE. For a multiple-group model, newdata can also be a list with one data.frame per group (in the same order as the groups in object). An element may be NULL to skip that group. This is useful when the groups have a different set of variables, so that ynames and xnames can be specified per group (as a list). In that case, the result contains residuals only for the groups for which data were provided (a single matrix if only one group was requested, otherwise a named list).
ynames: The names of the observed variables that should be treated as the y-variables. It is for these variables that the function will compute the (model-based) residuals for each observation. Can also be a list to allow for a separate set of variable names per group (or block).
xnames: The names of the observed variables that should be treated as the x-variables. Can also be a list to allow for a separate set of variable names per group (or block).
method: A character string. The only available option for now is "conditional.mean". See Details.
label: Logical. If TRUE, the columns of the output are labeled.
assemble: Logical. If TRUE, the residuals for the separate groups in the output are reassembled into a single data.frame with a group column, having the same dimensions as the original (or newdata) dataset.
force_zero_mean: Logical. Only relevant if there is no mean structure. If TRUE, the (model-implied) mean vector is set to the zero vector. If FALSE, the (model-implied) mean vector is set to the (unrestricted) sample mean vector.
lambda: Numeric. A lambda regularization penalty term.
...: To support old argument names.

Details

The residuals are computed as observed - predicted, where the predicted values are obtained by lavPredictY using the same arguments. See the help page of lavPredictY for more details about how the predictions are computed.

These residuals can be used, for example, to diagnose the (SEM-based) out-of-sample prediction of outcome (y) variables, or to check the distributional assumptions (for example, multivariate normality) for the y-variables given the x-variables.

References

de Rooij, M., Karch, J.D., Fokkema, M., Bakk, Z., Pratiwi, B.C, and Kelderman, H. (2022) SEM-Based Out-of-Sample Predictions, Structural Equation Modeling: A Multidisciplinary Journal. tools:::Rd_expr_doi("10.1080/10705511.2022.2061494")

Examples

Run this code

model <- '
  # latent variable definitions
     ind60 =~ x1 + x2 + x3
     dem60 =~ y1 + a*y2 + b*y3 + c*y4
     dem65 =~ y5 + a*y6 + b*y7 + c*y8

  # regressions
    dem60 ~ ind60
    dem65 ~ ind60 + dem60

  # residual correlations
    y1 ~~ y5
    y2 ~~ y4 + y6
    y3 ~~ y7
    y4 ~~ y8
    y6 ~~ y8
'
fit <- sem(model, data = PoliticalDemocracy)

lavResidualsY(fit, ynames = c("y5", "y6", "y7", "y8"),
                   xnames = c("x1", "x2", "x3", "y1", "y2", "y3", "y4"))