Residuals

‘lavResiduals’ provides model residuals and standardized residuals from a fitted lavaan object, as well as various summaries of these residuals.

The ‘residuals()’ (and ‘resid()’) methods are just shortcuts to this function with a limited set of arguments.

Usage

lavResiduals(object, type = "cor.bentler", h1 = NULL,
    se = FALSE, zstat = TRUE, summary = TRUE, elementwise = TRUE,
    combine = FALSE, usrmr_ci_level = 0.90, usrmr_close_h0 = 0.05,
    h1_acov = "unstructured",
    add_type = TRUE, add_labels = TRUE, add_class = TRUE,
    drop_list_single_group = TRUE,
    maximum_number = 0L, n_largest = 5L, output = "list", ...)

Arguments

object

An object of class lavaan.

type

Character. If type = "raw", this function returns the raw (= unscaled) difference between the observed and the expected (model-implied) summary statistics, as well as the standardized version of these residuals. If type = "cor", or type = "cor.bollen", the observed and model implied covariance matrices are first transformed to a correlation matrix (using cov2cor()), before the residuals are computed. If type = "cor.bentler", both the observed and model implied covariance matrices are rescaled by dividing the elements by the square roots of the corresponding variances of the observed covariance matrix.

h1

Optional. A user-provided saturated (unrestricted) model supplying the observed summary statistics against which the model-implied statistics are compared. It can be a fitted lavaan object (its h1 slot is used), a lavh1 list (a list with an implied element), or an implied-moments list (a list with a cov or res.cov element, per block). It must be compatible with object (same number of blocks and same dimensions). If NULL (the default), the saturated statistics of object itself are used.

se

Logical. If TRUE, show the estimated standard errors for the residuals.

zstat

Logical. If TRUE, show the standardized residuals, which are the raw residuals divided by the corresponding (estimated) standard errors.

summary

Logical. If TRUE, show various summaries of the (possibly scaled) residuals. When type = "raw", we compute the RMR. When type = "cor.bentler", we compute the SRMR. When type = "cor.bollen", we compute the CRMR. An unbiased version of these summaries (the URMR, USRMR and UCRMR) is also computed (Maydeu-Olivares, 2017).

The two versions are reported with different inferential statistics, and this asymmetry is intentional. The sample RMR/SRMR/CRMR overestimate (are positively biased for) their population values. For these (biased) statistics, we report a standard error and a test of exact fit (the null hypothesis that the population value equals zero). This test relies on the known sampling distribution of the (biased) sample statistic under exact fit (Maydeu-Olivares, 2017, Eqs. 28–30), where the bias is explicitly accounted for. For the (approximately) unbiased URMR/USRMR/UCRMR, we report a standard error, a confidence interval, and a test of close fit (the null hypothesis that the population value equals a small nonzero cutoff, e.g. 0.05). The confidence interval and the close-fit test require an (approximately) unbiased and normally distributed estimator, which is precisely why the unbiased version is used here. Conversely, no test of exact fit is reported for the unbiased estimator: because it is truncated at zero, its sampling distribution is degenerate at the exact-fit boundary, so the test of exact fit is (correctly) only based on the biased statistic.

elementwise

Logical. If TRUE (the default), the element-wise residuals are included: the (residualized) summary statistics when output = "list", or the largest-residuals table(s) when output = "text". If FALSE, these are omitted and only the summary information is returned/shown (provided summary = TRUE). Combined with summary = FALSE, this gives full control over which parts are produced.

combine

Logical. Only relevant when multiple blocks are involved (multiple groups, or multiple levels). If FALSE (the default), a separate summary table is shown for each block. If TRUE, the block-specific summary tables are replaced by a single overall summary table in which the residual elements are pooled across all blocks (so, e.g., the SRMR is computed from the residuals of all groups or all levels at once). The combined table is returned as the summary element at the top level of the result. The pooling correctly accounts for the (block-diagonal) independence of separate groups and for the (joint) sampling covariance across the levels of a multilevel model.

usrmr_ci_level

Numeric. The confidence level of the confidence interval that is reported (in the summary) for the unbiased URMR/USRMR/UCRMR. The default is 0.90.

usrmr_close_h0

Numeric. The value of the population URMR/USRMR/UCRMR under the null hypothesis of the test of close fit that is reported (in the summary) for the unbiased estimator. The default is 0.05.

h1_acov

Character. If "unstructured", the observed summary statistics are used as consistent estimates of the corresponding (unrestricted) population statistics. If "structured", the model-implied summary statistics are used as consistent estimates of the corresponding (unrestricted) population statistics. This affects the way the asymptotic variance matrix of the summary statistics is computed.

add_type

Logical. If TRUE, show the type of residuals in the output.

add_labels

If TRUE, variable names are added to the vectors and/or matrices.

add_class

If TRUE, vectors are given the ‘lavaan.vector’ class; matrices are given the ‘lavaan.matrix’ class, and symmetric matrices are given the ‘lavaan.matrix.symmetric’ class. This only affects the way they are printed on the screen.

drop_list_single_group

If FALSE, the results are returned as a list, where each element corresponds to a group (even if there is only a single group). If TRUE, the list will be unlisted if there is only a single group.

maximum_number

Integer. Only used if output = "table". If larger than zero, show only the first maximum_number rows of the data.frame. The default (0L) shows all rows.

n_largest

Integer. Only used if output = "text". The number of largest (in absolute value) residuals that are shown, per element group (covariances, variances, intercepts, thresholds, regression slopes) and per block.

output

Character. By default, output = "list", and the output is a list of elements. If output = "table", the residuals are shown in a single data.frame, one row per residual element, sorted from high (in absolute value) to low. All residual elements are included: the (co)variances (lhs~~rhs), the means/intercepts (lhs~1), the thresholds (lhs|t1) and, when conditional.x = TRUE, the regression slopes (lhs~rhs). Variances (the diagonal) are only shown for the raw-style metrics (type = "raw", "normalized" or "standardized"), not for the correlation metrics where they are structurally zero. Structurally fixed moments (e.g. saturated means or just-identified thresholds) are omitted. If se = TRUE, a se column with the standard errors is added; if zstat = TRUE, a z column with the z-statistics is added. If output = "text" (or, equivalently, "pretty"), the output is printed in the same style as the fit measures (e.g.\ the RMSEA). First, a table with the n_largest largest residuals (per element group, and per block) is shown, formatted like parameterEstimates(., output = "text") but with a ‘Residual’ column (and, if available, ‘Std.Err’ and ‘Z-value’ columns); its header reflects the residual type (e.g.\ “Largest Standardized Residuals (Cor.Bentler)” or “Largest Raw Residuals”). Next, the residual summary table(s) are shown. When multiple blocks are involved and combine = FALSE, one summary is printed per block; otherwise a single (combined) summary is printed.

...

To support old argument names.

Value

If drop_list_single_group = TRUE, a list of (residualized) summary statistics, including type, standardized residuals, and summaries. If drop_list_single_group = FALSE, the list of summary statistics is nested within a list for each group.

References

Bentler, P.M. and Dijkstra, T. (1985). Efficient estimation via linearization in structural models. In Krishnaiah, P.R. (Ed.), Multivariate analysis - VI, (pp. 9–42). New York, NY: Elsevier.

Ogasawara, H. (2001). Standard errors of fit indices using residuals in structural equation modeling. Psychometrika, 66(3), 421–436. doi:10.1007/BF02294443

Maydeu-Olivares, A. (2017). Assessing the size of model misfit in structural equation models. Psychometrika, 82(3), 533–558. doi:10.1007/s11336-016-9552-7

Standardized Residuals in Mplus. Document retrieved from URL http://www.statmodel.com/download/StandardizedResiduals.pdf

Examples

HS.model <- ' visual  =~ x1 + x2 + x3
              textual =~ x4 + x5 + x6
              speed   =~ x7 + x8 + x9 '

fit <- cfa(HS.model, data = HolzingerSwineford1939)
lavResiduals(fit)
#> $type
#> [1] "cor.bentler"
#> 
#> $cov
#>        x1     x2     x3     x4     x5     x6     x7     x8     x9
#> x1  0.000                                                        
#> x2 -0.030  0.000                                                 
#> x3 -0.008  0.094  0.000                                          
#> x4  0.071 -0.012 -0.068  0.000                                   
#> x5 -0.009 -0.027 -0.151  0.005  0.000                            
#> x6  0.060  0.030 -0.026 -0.009  0.003  0.000                     
#> x7 -0.140 -0.189 -0.084  0.037 -0.036 -0.014  0.000              
#> x8 -0.039 -0.052 -0.012 -0.067 -0.036 -0.022  0.075  0.000       
#> x9  0.149  0.073  0.147  0.048  0.067  0.056 -0.038 -0.032  0.000
#> 
#> $cov.z
#>        x1     x2     x3     x4     x5     x6     x7     x8     x9
#> x1  0.000                                                        
#> x2 -1.996  0.000                                                 
#> x3 -0.997  2.689  0.000                                          
#> x4  2.679 -0.284 -1.899  0.000                                   
#> x5 -0.359 -0.591 -4.157  1.545  0.000                            
#> x6  2.155  0.681 -0.711 -2.588  0.942  0.000                     
#> x7 -3.773 -3.654 -1.858  0.865 -0.842 -0.326  0.000              
#> x8 -1.380 -1.119 -0.300 -2.021 -1.099 -0.641  4.823  0.000       
#> x9  4.077  1.606  3.518  1.225  1.701  1.423 -2.325 -4.132  0.000
#> 
#> $summary
#>                           cov
#> srmr                    0.065
#> srmr.se                 0.006
#> srmr.exactfit.z         6.063
#> srmr.exactfit.pvalue    0.000
#> usrmr                   0.058
#> usrmr.se                0.010
#> usrmr.ci.lower          0.042
#> usrmr.ci.upper          0.074
#> usrmr.closefit.h0.value 0.050
#> usrmr.closefit.z        0.832
#> usrmr.closefit.pvalue   0.203
#>