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

In lavaan: Latent Variable Analysis

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. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1080/10705511.2022.2061494")}

See Also

lavPredictY to compute the (model-based) predicted values for the y-variables given the x-variables.

Examples

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"))

lavaan documentation built on Oct. 8, 2026, 5:06 p.m.