lavOptions: lavaan Options

In lavaan: Latent Variable Analysis

lavaan Options

Description

Show the default options used by the lavaan() function. The options can be changed by passing 'name = value' arguments to the lavaan() function call, where they are added to the '...' argument.

Option names are documented in snake_case (for example std_lv). Dots and underscores are interchangeable when an option is specified: the dotted spelling (std.lv), which was the only documented spelling in lavaan versions before 0.7, remains fully supported. The dotted spelling is the one stored in the Options slot of a fitted object and returned by lavOptions() and lavInspect(fit, "options").

Usage

lavOptions(x = NULL, default = NULL, mimic = "lavaan")

Arguments

x	Character. A character string holding an option name, or a character string vector holding multiple option names. All option names are converted to lower case, and underscores are converted to dots.
default	If a single option is specified but not available, this value is returned.
mimic	Not used for now.

Details

This is the full list of options that are accepted by the lavaan() function, organized in several sections:

Model features:

meanstructure:

If TRUE, the means of the observed variables enter the model. If "default", the value is set based on the user-specified model, and/or the values of other arguments.

int_ov_free:

If FALSE, the intercepts of the observed variables are fixed to zero.

int_lv_free:

If FALSE, the intercepts of the latent variables are fixed to zero.

conditional_x:

If TRUE, we set up the model conditional on the exogenous ‘x’ covariates; the model-implied sample statistics only include the non-x variables. If FALSE, the exogenous ‘x’ variables are modeled jointly with the other variables, and the model-implied statistics reflect both sets of variables. If "default", the value is set depending on the estimator, and whether or not the model involves categorical endogenous variables.

fixed_x:

If TRUE, the exogenous ‘x’ covariates are considered fixed variables and the means, variances and covariances of these variables are fixed to their sample values. If FALSE, they are considered random, and the means, variances and covariances are free parameters. If "default", the value is set depending on the mimic option.

orthogonal:

If TRUE, all covariances among latent variables are set to zero.

orthogonal_y:

If TRUE, all covariances among endogenous latent variables only are set to zero.

orthogonal_x:

If TRUE, all covariances among exogenous latent variables only are set to zero.

std_lv:

If TRUE, the metric of each latent variable is determined by fixing their (residual) variances to 1.0. If FALSE, the metric of each latent variable is determined by fixing the factor loading of the first indicator to 1.0. If there are multiple groups, std_lv = TRUE and "loadings" is included in the group_equal argument, then only the latent variances of the first group will be fixed to 1.0, while the latent variances of other groups are set free.

effect_coding:

Can be logical or character string. If logical and TRUE, this implies effect_coding = c("loadings", "intercepts"). If logical and FALSE, it is set equal to the empty string. If "loadings" is included, equality constraints are used so that the average of the factor loadings (per latent variable) equals 1. Note that this should not be used together with std_lv = TRUE. If "intercepts" is included, equality constraints are used so that the sum of the intercepts (belonging to the indicators of a single latent variable) equals zero. As a result, the latent mean is freely estimated and usually equals the average of the means of the involved indicators.

ceq_simple:

Logical. If TRUE, and no other general (equality or inequality) constraints are used in the model, simple equality constraints are represented in the parameter table as duplicated free parameters (instead of extra rows with op = "=="). The default is FALSE.

parameterization:

Currently only used if data is categorical. If "delta", the delta parameterization is used. If "theta", the theta parameterization is used.

correlation:

Only used for (single-level) continuous data. If TRUE, analyze a correlation matrix (instead of a (co)variance matrix). This implies that the residual observed variances are no longer free parameters. Instead, they are set to values that ensure the model-implied variances are unity. This also affects the standard errors. Since 0.7-2, the default estimator is ML (before: GLS): the model is fit as the covariance structure \Sigma = \Delta P(\theta) \Delta with free scale parameters \Delta (the ~*~ rows in the output) and unit-diagonal P(\theta), by ordinary maximum likelihood in the full moment space. Because this augmented model is exactly scale-equivariant, the correlation-metric estimates, standard errors and test statistic are identical whether the input is raw data, a covariance matrix, or a correlation matrix. The other ML-family estimators ("MLM", "MLR", ...) work the same way (raw data needed). A meanstructure is supported: the mean parameters (intercepts, latent means) live in the standardized metric, mirroring the covariance side – the implied mean is \mu = \Delta (\nu + \Lambda (I - B)^{-1} \alpha), so a saturated intercept equals the standardized sample mean (mean/sd), and the model-implied means (see lavInspect(fit, "implied")) reproduce the raw sample means. The (saturated) mean structure does not affect the correlation structure. missing = "ml" (FIML) is supported as well: the pattern-based likelihood simply consumes the augmented moments, so correlation structures can be fit to incomplete data by full-information maximum likelihood (use estimator = "MLR" for sandwich standard errors under MAR). conditional_x = TRUE is supported on the ML route as well: the exogenous x are standardized internally (a fixed transformation – the analysis conditions on x), the y-side scales are free ~*~ parameters, and the unit-variance constraint applies to the marginal variances; the result is identical (same conditional likelihood) to the joint fixed_x = TRUE analysis. Composite models (the <~ operator) are supported as well (since 0.7-2, on both the ML and the GLS route): the composite-indicator covariances are fixed in the correlation metric, and the indicator variances are absorbed by the ~*~ scales. The ML route requires single-level data (and missing = "ml" requires conditional_x = FALSE); in all other settings, a defaulted estimator quietly falls back to GLS. Estimator WLS (= ADF weights in the correlation metric) covers the non-normal case. Both fixed_x = FALSE and fixed_x = TRUE are supported (the latter affects the way the standard errors are computed), and (since 0.7-2) also conditional_x = TRUE: the exogenous covariates are then standardized along with the outcomes, the input sample_cov (if used) must be the joint (correlation or covariance) matrix including the x-variables (it is standardized internally), and the unit-variance constraint applies to the marginal (not the residual) variances of the outcomes. Alternatively, correlation may be a character vector of (observed) variable names (for example correlation = c("x1", "x2", "x3")). In that case only the listed variables are standardized to unit variance (their residual variances are fixed accordingly), while all remaining observed variables keep their original metric (a 'partial' correlation structure). This also works with conditional_x = TRUE: the listed exogenous variables are standardized along with the listed outcomes, and non-listed outcomes keep a free (residual) variance. If the model contains observed product (interaction) terms (for example x1:y1) and correlation = TRUE, the product terms are automatically excluded from the correlation set: the product of standardized variables does not have unit variance, so their (co)variances remain free parameters. Note that product terms are typically highly non-normal, so the normal-theory (GLS) standard errors for their (co)variances may be too small; consider se = "robust.sem". Some combinations are not supported (yet) and fail with an error: the two-stage missing data approach (missing = "two.stage" or "robust.two.stage"), the estimators with their own moment machinery ("IV", "JS", "MGM", "DLS", "NTRLS", ...), models that mix ordered and continuous (endogenous) variables, and sam(). For models where all endogenous variables are declared ordered, the fitted moments are already correlations, and correlation = TRUE is redundant (but harmless).

composites_cov:

Character string. Only used if the model contains composites. Controls whether the composite-indicator (co)variances (the elements of the T matrix) are fixed to their sample values or estimated as free parameters. If "fixed", the T matrix is fixed to the sample (co)variances. If "free", the T matrix is estimated as free parameters. If "default", the value is resolved to "free" for multilevel models (which makes composites at every level identified) and "fixed" otherwise. For a single-level model, freeing T is fit-invariant (the degrees of freedom are unchanged).

auto_fix_first:

If TRUE, the factor loading of the first indicator is set to 1.0 for every latent variable.

bad_marker_crit:

Only used if auto_fix_first = TRUE. A single number (default 0.1). If larger than zero, lavaan checks – once the unrestricted (h1) sample statistics are available – whether the first indicator of each latent variable is a poor item, in the sense that it correlates weakly with the other indicators of the same factor (more precisely: the absolute value of its corrected item-total correlation is below bad_marker_crit). If so (and a clearly better indicator is available), a warning is issued, because a (very) poor marker item often leads to convergence problems. The check is based on the (pooled) unrestricted (h1) covariance matrix, so it behaves consistently with or without missing data, categorical data, multiple groups, etc. Before the item-total correlations are computed, the indicators are aligned with their dominant common direction, so that reverse-coded indicators do not affect the check. The check is only performed in the clean default situation: the model was given as model syntax, and none of the loadings of the latent variable carry user modifiers (labels, start values, priors, bounds) or are referenced in user-specified constraints. Larger values make the check more aggressive; a value of 0 disables the check and silences the warning.

bad_marker_switch:

Logical (default FALSE). Only used if the bad_marker_crit check flagged the first indicator of a latent variable as a poor marker item. If FALSE, lavaan only warns, and the model is estimated exactly as specified. If TRUE, the loading of the best available indicator is fixed to 1.0 instead of the loading of the first indicator, in order to set the metric of that latent variable; if the model with the switched marker(s) does not converge, lavaan falls back to the original marker(s). (In lavaan 0.7-1 and 0.7-2, switching was the default behavior; it now must be requested explicitly.)

auto_fix_single:

If TRUE, the residual variance (if included) of an observed indicator is set to zero if it is the only indicator of a latent variable.

auto_var:

If TRUE, the (residual) variances of both observed and latent variables are set free.

auto_cov_lv_x:

If TRUE, the covariances of exogenous latent variables are included in the model and set free.

auto_cov_x:

If TRUE, the covariances between exogenous latent variables and observed exogenous covariates are also included in the model and set free (this implies auto_cov_lv_x = TRUE). Ignored if conditional_x = TRUE, as these covariances cannot be represented when the model is conditioned on the exogenous covariates.

auto_cov_y:

If TRUE, the covariances of dependent variables (both observed and latent) are included in the model and set free.

auto_th:

If TRUE, thresholds for limited dependent variables are included in the model and set free.

auto_delta:

If TRUE, response scaling parameters for limited dependent variables are included in the model and set free.

auto_efa:

If TRUE, the necessary constraints are imposed to make the (unrotated) exploratory factor analysis blocks identifiable: for each block, factor variances are set to 1, factor covariances are constrained to be zero, and factor loadings are constrained to follow an echelon pattern.

Data options:

std_ov:

If TRUE, observed variables are standardized before entering the analysis. By default, these are only the non-exogenous observed variables, unless fixed_x = FALSE. Use this option with caution; it can be used to test whether (for example) nonconvergence was due to scaling issues. Note that this is still a covariance-based analysis: no constraints are imposed to ensure the model-implied (co)variance matrix has unit variances, and the standard errors still assume that the input was unstandardized. See also the correlation option.

rescale_data:

Internal rescaling of badly scaled variables (new in 0.7-2). When the observed standard deviations are very heterogeneous or extreme (roughly: a max/min sd ratio beyond 1000, or sds outside [0.001, 1000]), the optimizer often fails or needs thousands of iterations, and the classical advice is to rescale the offending variables before the analysis. With rescale_data = "auto" (the default), lavaan automates this advice exactly: each model variable is internally divided by a power of two close to its standard deviation (lossless in floating point), the model is fitted in the well-scaled metric, and the solution – estimates, standard errors, tests – is mapped back to the original metric through the exact reparameterization; fixed parameter values and starting values are transformed along, so the fitted model (and all output) is exactly the user's model in the original units. TRUE forces the rescaling; FALSE (or "none") disables it. The rescaling is skipped (with a warning if forced) for settings it does not support: summary-statistics input, multilevel or categorical data, composites, EFA blocks, product terms, estimator ULS, inequality constraints, and equality constraints that tie parameters with different scaling factors (e.g., equal loadings across indicators with very different variances – such constraints would not survive a change of units).

missing:

The default setting is "listwise": all cases with missing values are removed listwise from the data before the analysis starts. This is only valid if the data are missing completely at random (MCAR). Therefore, it may not be the optimal choice, but it can be useful for a first run. If the estimator belongs to the ML family, another option is "ml" (alias: "fiml" or "direct"). This corresponds to the so-called full information maximum likelihood approach (fiml), where we compute the likelihood case by case, using all available data from that case. Note that if the model contains exogenous observed covariates, and fixed_x = TRUE (the default), all cases with any missing values on these covariates will be deleted first. The option "ml.x" (alias: "fiml.x" or "direct.x") is similar to "ml", but does not delete any cases with missing values for the exogenous covariates, even if fixed_x = TRUE. (Note: all lavaan versions < 0.6 used "ml.x" instead of "ml"). Since version 0.7-2, "ml" can also be combined with conditional_x = TRUE (single-level, continuous data): the likelihood of the observed non-x variables is then computed case by case, conditional on the (complete) exogenous covariates of that case. Cases with missing values on the exogenous covariates are deleted first, and "ml.x" is not available in this setting. Note that the robust (missing-data corrected) versions of RMSEA/CFI are not (yet) available when conditional_x = TRUE. If you wish to use multiple imputation, you need to use an external package (e.g., mice) to generate imputed datasets, which can then be analyzed using the semList function. The semTools package contains several functions to do this automatically. Another option (with continuous data) is to use "two.stage" or "robust.two.stage". In this approach, we first estimate the sample statistics (mean vector, variance-covariance matrix) using an EM algorithm. Then, we use these estimated sample statistics as input for a regular analysis (as if the data were complete). The standard errors and test statistics are adjusted correctly to reflect the two-step procedure. The "robust.two.stage" option produces standard errors and a test statistic that are robust against non-normality. Both options are available for the ML estimator (since version 0.7-2 also in combination with conditional_x = TRUE), and also for the (continuous-data) least-squares estimators "ULS", "GLS", "WLS", "DWLS" and "DLS"; for the latter, lavaan automatically switches to se = "robust.sem" and test = "satorra.bentler", using the two-stage variance-covariance matrix of the EM-based sample statistics (which also provides the "WLS"/"DWLS" weight matrix). In addition, for these least-squares estimators, requesting missing = "ml" (or "fiml") is interpreted as a generic request to handle the missing values, and is silently treated as missing = "two.stage". Both options can be combined with sampling weights (since version 0.7-3); because the plain two-stage standard errors do not account for the variability of the weights, missing = "two.stage" is then silently treated as missing = "robust.two.stage". If (part of) the data is categorical, and the estimator is from the (W)LS family, the only option (besides listwise deletion) is "pairwise". In this three-step approach, missingness is only an issue in the first two steps. In the first step, we compute thresholds (for categorical variables) and means or intercepts (for continuous variables) using univariate information only. In this step, we simply ignore the missing values just like in mean(x, na.rm = TRUE). In the second step, we compute polychoric/polyserial/pearson correlations using (only) two variables at a time. Here we use pairwise deletion: we only keep those observations for which both values are observed (not missing), and this set may change from pair to pair. By default, in the categorical case we use conditional_x = TRUE. Therefore, any cases with missing values on the exogenous covariates will be deleted listwise from the data first. For continuous data, "pairwise" fits the pairwise-complete sample moments; for the (D)WLS/ULS estimators, the robust standard errors and scaled test statistics use the Gamma matrix of these pairwise-complete moments, but for the ML/GLS estimators, no robust standard errors or scaled test statistics are available when the data contain missing values (only se = "standard" and test = "standard", or bootstrapping). Finally, if the estimator is "PML", the available options are "pairwise", "available.cases" and "doubly.robust". See the PML tutorial on the lavaan website for more information about these approaches.

sampling_weights_normalization:

If "none", the sampling weights (if provided) will not be transformed. If "total", the sampling weights are normalized by dividing by the total sum of the weights, and multiplying again by the total sample size. If "group", the sampling weights are normalized per group: by dividing by the sum of the weights (in each group), and multiplying again by the group size. The default is "group". (For a single group, "group" and "total" are identical; they only differ when there are multiple groups, in which case "group" keeps each group's relative contribution proportional to its sample size, matching the behavior of Mplus.)

sampling_weights_type:

Only used when sampling weights are provided and the estimator relies on a weight matrix or sandwich variance: the least-squares family (GLS/WLS/DWLS/ULS/DLS, both continuous and categorical) and PML. Determines how the sampling weights enter the asymptotic variance (the Gamma / nacov matrix, or the PML first-order information), and hence the (robust) standard errors and the scaled test statistic. For GLS and ULS only the standard errors are affected; for WLS/DWLS/DLS the Gamma also feeds the weight matrix, so the point estimates shift as well. If "design" (the default), the weights are treated as sampling (design) weights and a design-based sandwich is used (the meat is weighted by the sum of the squared weights), matching the behavior of Mplus. If "frequency", the weights are treated as frequency (replication) counts (the meat is weighted by the sum of the weights), so that the results match a fit on the row-replicated data. Without sampling weights the two are identical.

samplestats:

Logical. If FALSE, no sample statistics will be computed (and no estimation can take place). This can be useful when only a dummy lavaan object is requested, without any computations. The default is TRUE.

Data summary options:

sample_cov_rescale:

If TRUE, the sample covariance matrix provided by the user is internally rescaled by multiplying it with a factor (N-1)/N. If "default", the value is set depending on the estimator and the likelihood option: it is set to TRUE if maximum likelihood estimation is used and likelihood="normal", and FALSE otherwise.

ridge:

Logical. If TRUE, a small constant value is added to the diagonal elements of the covariance (or correlation) matrix before analysis. The value can be set using the ridge_constant option.

ridge_constant:

Numeric. Small constant used for ridging. The default value is 1e-05.

Multiple group options:

group_label:

A character vector. The user can specify which group (or factor) levels need to be selected from the grouping variable, and in which order. If missing, all grouping levels are selected, in the order as they appear in the data.

group_equal:

A vector of character strings. Only used in a multiple group analysis. Can be one or more of the following: "loadings", "composite.weights", "intercepts", "means", "thresholds", "regressions", "residuals", "residual.covariances", "lv.variances" or "lv.covariances", specifying the pattern of equality constraints across multiple groups. As a shortcut, the single value "all" can be used to constrain all (free) parameters to be equal across groups; it is equivalent to listing all of the values above, except when meanstructure = FALSE was explicitly requested: in that case, the model contains no mean-structure parameters, and "intercepts" and "means" are not included. When the model is not the same across groups (for example when the group: modifier is used to specify a different model per group), only parameters that are present in two or more groups are constrained to be equal; a parameter that occurs in a single group only is always left free. The constraints are symmetric and do not depend on the first group: a parameter that is shared by (say) the second and third group is constrained to be equal across those two groups, even if it does not appear in the first group.

group_partial:

A vector of character strings containing the labels of the parameters which should be free in all groups (thereby overriding the group_equal argument for some specific parameters).

group_w_free:

Logical. If TRUE, the group frequencies are considered to be free parameters in the model. In this case, a Poisson model is fitted to estimate the group frequencies. If FALSE (the default), the group frequencies are fixed to their observed values.

Estimation options:

estimator:

The estimator to be used. Can be one of the following: "ML" for maximum likelihood, "GLS" for (normal theory) generalized least squares, "WLS" for weighted least squares (sometimes called ADF estimation), "ULS" for unweighted least squares, "DWLS" for diagonally weighted least squares, and "DLS" for distributionally-weighted least squares. These are the main options that affect the estimation. For convenience, the "ML" option can be extended as "MLM", "MLMV", "MLMVS", "MLF", and "MLR". The estimation will still be plain "ML", but now with robust standard errors and a robust (scaled) test statistic. For "MLM", "MLMV", "MLMVS", classic robust standard errors are used (se="robust.sem"); for "MLF", standard errors are based on first-order derivatives (information = "first.order"); for "MLR", ‘Huber-White’ robust standard errors are used (se="robust.huber.white"). In addition, "MLM" will compute a Satorra-Bentler scaled (mean adjusted) test statistic (test="satorra.bentler"), "MLMVS" will compute a mean and variance adjusted test statistic (Satterthwaite style) (test="mean.var.adjusted"), "MLMV" will compute a mean and variance adjusted test statistic (scaled and shifted) (test="scaled.shifted"), and "MLR" will compute a test statistic which is asymptotically equivalent to the Yuan-Bentler T2-star test statistic (test="yuan.bentler.mplus"). Analogously, the estimators "WLSM" and "WLSMV" imply the "DWLS" estimator (not the "WLS" estimator) with robust standard errors and a mean or mean and variance adjusted test statistic. Estimators "ULSM" and "ULSMV" imply the "ULS" estimator with robust standard errors and a mean or mean and variance adjusted test statistic. Finally, "RBM" requests reduced-bias M-estimation (penalized maximum likelihood; continuous-outcome models for now). By default sandwich standard errors are used (se = "robust.huber.white"). The type of bias reduction is controlled by the rbm_method element of estimator_args (either "implicit" (default) or "explicit"), for example estimator = list(estimator = "RBM", rbm_method = "explicit"). The "explicit" method is much faster for models with many parameters (it requires a single ML fit plus a one-step correction), and is recommended in that case.

likelihood:

Only relevant for ML estimation. If "wishart", the Wishart likelihood approach is used. In this approach, the covariance matrix has been divided by N-1, and both standard errors and test statistics are based on N-1. If "normal", the normal likelihood approach is used. Here, the covariance matrix has been divided by N, and both standard errors and test statistics are based on N. If "default", it depends on the mimic option: if mimic="lavaan" or mimic="Mplus", normal likelihood is used; otherwise, Wishart likelihood is used.

link:

Not used yet. This is just a placeholder until the MML estimator is back.

information:

If "expected", the expected information matrix is used (to compute the standard errors). If "observed", the observed information matrix is used. If "first.order", the information matrix is based on the outer product of the casewise scores. See also the options h1_information and observed_information for further control. If "default", the value is set depending on the estimator, the missing argument, and the mimic option. If the argument is a vector with two elements, the first element is used for the computation of the standard errors, while the second element is used for the (robust) test statistic.

h1_missing_method:

Character. Only used for multilevel models with missing data (and missing = "ml"). If "em" (the default since 0.7-1), the means and (co)variances of the unrestricted (h1) model are estimated using the EM algorithm, integrating over both the cluster random effects and the missing values (this mimics Mplus). If "fiml", the unrestricted model is estimated using quasi-Newton optimization (nlminb) with a cholesky parameterization of the covariance matrices (this was the default in versions < 0.7-1). See the em_h1_args option to control the EM algorithm.

em_h1_args:

List. Options related to the EM algorithm that is used to estimate the means and (co)variances of the unrestricted (h1) model. This is only relevant for multilevel models, and for single-level models with missing data (and missing = "ml" or missing = "two.stage"). The default values are em_h1_args = list(max_iter = "default", tol = "default", min_variance = 1e-05, warn = TRUE, non_pd_action = "stop", non_pd_tol = 1e-05, acceleration = "squarem", fused = TRUE). The max_iter element sets the maximum number of EM iterations; the tol element sets the tolerance used to determine convergence. If "default", they are set to 500 and 1e-05 respectively in the single-level setting (where the EM algorithm stops when the largest absolute change in the parameter values is smaller than tol), and to 5000 and 1e-04 respectively in the multilevel setting (where the EM algorithm stops when the change in the loglikelihood is smaller than tol). The min_variance element sets the minimum value a variance can take during the EM iterations (multilevel only): whenever a within-level variance drops below this value, it is fixed to this value (and the corresponding covariances are set to zero). If the warn element is TRUE (the default), a warning is produced if the EM algorithm reaches max_iter iterations without converging. The non_pd_action element controls what happens if an EM estimated variance-covariance matrix is (near) singular: if any variance is (near) zero, or if the smallest eigenvalue of the matrix is smaller than the non_pd_tol element. This typically happens when a (within or between) variance of an observed variable approaches zero, but the full matrix may also be (near) singular. If non_pd_action = "stop" (the default), estimation stops with an error message; if "warn", a warning is produced, and estimation continues; if "none", estimation continues silently. The acceleration element controls whether the EM iterations are accelerated. If "squarem" (the default), the SQUAREM scheme (Varadhan & Roland, 2008) is used: every cycle takes two EM steps, extrapolates, and takes one stabilizing EM step from the extrapolated point, with a loglikelihood safeguard; this typically reduces the number of EM steps considerably (in particular when some variances approach zero), and converges to the same solution. If "qn", a quasi-Newton scheme (Zhou, Alexander & Lange, 2011; the "qn" method of the turboEM package) is used instead: a low-rank secant approximation of the EM map is used to take a quasi-Newton step towards the fixed point, again with a loglikelihood safeguard. If "none", the plain (unaccelerated) EM iterations are used. If the fused element is TRUE (the default), the loglikelihood is computed as a cheap byproduct of the E-step quantities (only used in the two-level setting with missing data, for the plain EM iterations); if FALSE, a separate (stand-alone) loglikelihood evaluation is used in every iteration; both give identical results.

h1_information:

If "structured" (the default), the unrestricted (h1) information part of the (expected, first.order or observed if h1 is used) information matrix is based on the structured, or model-implied statistics (model-implied covariance matrix, model-implied mean vector, etc.). If "unstructured", the unrestricted (h1) information part is based on sample-based statistics (observed covariance matrix, observed mean vector, etc.) If the argument is a vector with two elements, the first element is used for the computation of the standard errors, while the second element is used for the (robust) test statistic.

observed_information:

If "hessian", the observed information matrix is based on the hessian of the objective function. If "h1", an approximation is used that is based on the observed information matrix of the unrestricted (h1) model. If the argument is a vector with two elements, the first element is used for the computation of the standard errors, while the second element is used for the (robust) test statistic.

information_bread:

Only used when the standard errors are based on a sandwich-type (robust) covariance matrix (se = "robust.sem" or se = "robust.huber.white"). If set to "expected" or "observed", this type of information matrix is used for the bread (the outer matrices) of the sandwich only, while all the ingredients of the meat (the inner matrix) remain based on the (first element of the) information option. If "default", the (first element of the) information option is used for the bread as well, with two exceptions (both new in 0.7-2). First, for categorical data (single-level or two-level) estimated with DWLS or ULS and se = "robust.sem" (e.g., estimator "WLSMV" or "ULSMV"), "default" resolves to "observed": the bread is then based on the full hessian of the (D)WLS/ULS fit function, which (unlike the expected-information bread) remains consistent when the model does not fit perfectly. When the model fits well, both versions are virtually identical; the classic standard errors remain available with information_bread = "expected". The point estimates and all test statistics are not affected. Second, for the structural part of a sam model with se = "local", "default" resolves to "observed" as well; see the struc_args argument in sam. The summary header shows an additional Information bread line whenever the bread deviates from the (first element of the) information option.

information_meat_hc:

Character. Small-sample correction of the first-order (casewise) sandwich standard errors (new in 0.7-3). Only used when the standard errors are based on the crossproduct of casewise contributions: se = "robust.huber.white" (casewise scores), se = "robust.sem" (casewise moment contributions), and the se = "local" and se = "twostep.huber.white" standard errors of sam. These sandwiches are the analogue of the "HC0" estimator of a regression model and inherit its small-sample downward bias. The possible values mirror the regression corrections: "HC0" (the default; no correction), "HC1" (the whole covariance matrix is multiplied by n/(n - p), with p the number of free parameters – for sam, the number of free structural parameters, not counting the (co)variances of the exogenous variables), "HC2" and "HC3". For "HC2" and "HC3", the casewise influence values of the regression coefficients (including the intercept) of each regression equation are multiplied by (1 - h_{ij})^{-1/2} ("HC2") or (1 - h_{ij})^{-1} ("HC3"), where h_{ij} is the leverage of case i in the design matrix (intercept plus predictors) of equation j; observed predictors are taken from the data, latent predictors are replaced by their Bartlett factor scores (in local SAM: the step-1 factor scores, with products for latent interaction terms). For an observed-variable regression with fixed_x = TRUE, this reproduces the classical HC2/HC3 estimators (e.g., sandwich::vcovHC()) exactly. All other parameters (factor loadings, (residual) variances, ...) keep their uncorrected (HC0) contributions; only "HC1" affects them. A parameter constrained equal across groups is adjusted with the leverage of each group's own equation; a coefficient that appears in several equations of the same group takes the leverage of the first equation. Simulation evidence (see the references in the source) suggests "HC2" for regressions on observed variables and for local SAM (with or without latent interactions) below N = 500, and "HC3" for latent regressions in a joint SEM with small samples and heavy-tailed predictors, where it tracks the delete-one jackknife; "HC1" tends to overcorrect badly for latent variable models with many parameters. The corrections are available for single-level, independent observations only (not for clustered or multilevel data); "HC2"/"HC3" need continuous data (raw data for se = "robust.sem", which must be complete), and are not available for se = "local.nt" or with across-group equality constraints in the measurement part of a sam model. Point estimates and test statistics are not affected. The summary header shows an additional Information meat small-sample correction line whenever the correction is not "HC0". For the local standard errors of sam, the correction is not applied ("HC0" is used, and the summary says so) whenever a lambda truncation engaged in one of the measurement blocks (see the lambda1_floor and lambda2_floor local options in sam): the local standard errors are already conservative in that regime, and the correction would only stack on top of that.

se:

If "standard", conventional standard errors are computed based on inverting the (expected, observed or first.order) information matrix. If "robust.sem", conventional robust standard errors are computed. If "robust.huber.white", standard errors are computed based on the 'mlr' (aka pseudo ML, Huber-White) approach. If "robust", either "robust.sem" or "robust.huber.white" is used depending on the estimator, the mimic option, and whether the data are complete or not. For the non-iterative estimators with delta-method standard errors over the sample moments ("MGM", "JS"/"JSA"), "robust" selects the ADF (distribution-free) moment covariance, which equals the infinitesimal-jackknife (sandwich) covariance of the estimator. If "boot" or "bootstrap", bootstrap standard errors are computed using standard bootstrapping (unless Bollen-Stine bootstrapping is requested for the test statistic; in this case bootstrap standard errors are computed using model-based bootstrapping). If "none", no standard errors are computed.

test:

Character vector. See the documentation of the lavTest function for a full list. Multiple names of test statistics can be provided. If "default", the value depends on the values of other arguments. For estimator = "ML" (since 0.7-3), the default is c("standard", "browne.residual.nt.model"): in addition to the standard LRT chi-square statistic, Browne's residual-based (NT, model-based) test statistic (also known as the reweighted least-squares (RLS) statistic) is computed, as its type I error rates are much closer to the nominal level. With sampling weights, the ADF version ("browne.residual.adf") is used instead; for multilevel data (and a few other settings where no suitable Gamma matrix is available), only the standard statistic is computed. See also the lavTest function to extract (alternative) test statistics from a fitted lavaan object. FMG test names such as "peba4", "pols3", "pall", and "all" can be requested here for supported ML-family models. The convenience value "fmg" resolves to "peba4_rls" for one-model tests.

standard_test:

Character. Choose the test statistic that will be used to compute fit measures (like CFI or RMSEA). The default is "standard", but it could also be (for example) "Browne.residual.nt", or an FMG test name such as "peba4" or "fmg".

scaled_test:

Character. Choose the test statistic that will be scaled (if a scaled test statistic is requested). The default is "standard", but it could also be (for example) "Browne.residual.nt".

gamma_n_minus_one

Logical. If TRUE, we divide the Gamma matrix by N-1 (instead of the default N).

gamma_unbiased

Logical. If TRUE, we compute an unbiased version for the Gamma matrix. Only available for single-level complete data and when conditional_x = FALSE and fixed_x = FALSE (for now). Suffixless FMG test names use this option to choose between biased and unbiased Gamma.

se_delta_second_order

Logical. If FALSE (the default), the standard errors of defined parameters (introduced with the := operator) and of standardized parameters (as returned by standardizedSolution() or lavInspect(., "vcov.std.*")) are computed using the first-order delta method. If TRUE, the second-order delta method is used, which adds the term \frac{1}{2}\textrm{tr}(H V H V) (where H is the Hessian of the transformed parameter and V is the parameter covariance matrix) to the first-order variance approximation. This may improve accuracy when the transformation is a strongly non-linear function of the model parameters. Has no effect when standard errors are obtained by bootstrapping or by the Monte Carlo method.

se_def

Character. Method for computing standard errors (and confidence intervals) of defined parameters (introduced with the := operator). The default is "default" (or equivalently "delta"), which uses the delta method (respecting se_delta_second_order). Set to "monte.carlo" to use the Monte Carlo method of Preacher and Selig (2012). Under this method, R draws are taken from \textit{MVN}(\hat{\theta}, \widehat{\textit{Var}}(\hat{\theta})), the defined parameter is evaluated for each draw, and standard errors are obtained as the standard deviation of these realizations. Confidence intervals (in parameterEstimates() and standardizedSolution()) are based on percentile bounds of the Monte Carlo distribution, and therefore can be asymmetric (just like bootstrap intervals). Has no effect when se = "bootstrap".

monte_carlo

List of settings for the Monte Carlo method (used when se_def = "monte.carlo"). Currently recognizes: R (integer; number of Monte Carlo draws; default 20000) and seed (integer or NULL; optional seed for reproducibility).

bootstrap:

Number of bootstrap draws, if bootstrapping is used.

do_fit:

If FALSE, the model is not fit, and the current starting values of the model parameters are preserved.

Optimization options:

integration_ngh:

Integer. The number of Gauss-Hermite quadrature points (per dimension) used for numerical integration. The default is 21. Numerical integration is used when estimator = "MML", and for two-level models with random slopes for latent covariates (the rv() modifier; only the latent-covariate slopes are integrated numerically, all other random effects are handled in closed form).

control:

A list containing control parameters passed to the external optimizer. By default, lavaan uses "nlminb". See the manpage of nlminb for an overview of the control parameters. If another (external) optimizer is selected, see the manpage for that optimizer to see the possible control parameters.

optim_method:

Character. The optimizer that should be used. For unconstrained optimization or models with only linear equality constraints (i.e., the model syntax does not include any "==", ">" or "<" operators), the available options are "nlminb" (the default), "BFGS", "L-BFGS-B". These are all quasi-newton methods. A Gauss-Newton (Fisher scoring) method with Levenberg-Marquardt damping is also available (optim_method = "GN"); it can be used with the "ML", "GLS", "WLS", "DWLS", "ULS", "DLS", "NTRLS" and "catML" estimators, and is the default when estimator = "DLS". For multilevel models, an EM algorithm is also available (optim_method = "em"); this is the default for two-level models with missing = "ml" (as the EM algorithm is more robust in that setting; this also mimics Mplus); see the em_args option to control the EM algorithm. For two-level models with random slopes (the rv() modifier), optim_method = "em" uses a dedicated EM algorithm. Note that for any optim_method = "em" fit, variances that are fixed to zero are replaced by the (small) value em_args$zerovar_offset (as in Mplus, which uses the same 'minimum variance' device); as a result, the reported loglikelihood may differ slightly from an optim_method = "nlminb" fit of the same model (which uses the exact zero values). For constrained optimization, the only available option is "nlminb_constr", which uses an augmented Lagrangian minimization algorithm.

optim_force_converged:

Logical. If TRUE, pretend the model has converged, no matter what.

optim_fix_saturated:

Logical. Only used for multilevel models. If TRUE (the default), and one or more blocks (levels) of the model are saturated (i.e., all variances/covariances and means/intercepts of the observed variables of that block are free and unconstrained), the free parameters of these blocks are (temporarily) fixed to their h1 (unrestricted model) estimates during optimization, as their estimated values are already known. This often helps convergence. After the optimization, they are treated as free parameters again (e.g., when standard errors are computed).

optim_dx_tol

Numeric. Tolerance used for checking if the elements of the (unscaled) gradient are all zero (in absolute value). The default value is 0.001.

gn_args:

List. Options related to the Gauss-Newton optimizer (optim_method = "GN"). The default values are gn_args = list(max_iter = 200, tol_x = 1e-05, tol_g = 1e-06). The max_iter element sets the maximum number of Gauss-Newton iterations. Optimization stops when either the (scaled) gradient of the discrepancy function is smaller than tol_g, or the root mean square of the difference between the old and new parameter values is smaller than tol_x.

bounds:

Only used if optim_method = "nlminb". If logical: FALSE implies no bounds are imposed on the parameters. If TRUE, this implies bounds = "wide". If character, possible options are "none" (the default), "standard", "wide", "pos.var", "pos.ov.var", and "pos.lv.var". If bounds = "pos.ov.var", the observed variances are forced to be nonnegative. If bounds = "pos.lv.var", the latent variances are forced to be nonnegative. If bounds = "pos.var", both observed and latent variances are forced to be nonnegative. If bounds = "standard", lower and upper bounds are computed for observed and latent variances, and factor loadings. If bounds = "wide", lower and upper bounds are computed for observed and latent variances, and factor loadings; but the range of the bounds is enlarged (allowing again for slightly negative variances).

optim_bounds:

List. This can be used instead of the bounds argument to allow more control. Possible elements of the list are lower, upper, lower_factor and upper_factor. All of these accept a vector. The lower and upper elements indicate for which type of parameters bounds should be computed. Possible choices are "ov.var", "lv.var", "loadings" and "covariances". The lower_factor and upper_factor elements should have the same length as the lower and upper elements respectively. They indicate the factor by which the range of the bounds should be enlarged (for example, 1.1 or 1.2; the default is 1.0). Other elements are min_reliability_marker which sets the lower bound for the reliability of the marker indicator (if any) of each factor (default is 0.1). Finally, the min_var_lv_endo element indicates the lower bound of the variance of any endogenous latent variable (default is 0.0).

em_args:

List. Options related to the EM algorithm that is used to estimate the model parameters when optim_method = "em" (currently only available for multilevel models, with complete or missing data). The default values are em_args = list(max_iter = 10000, fx_tol = 1e-08, dx_tol = 1e-04, zerovar_offset = 1e-04, acceleration = "squarem", fused = TRUE). The max_iter element sets the maximum number of EM iterations. The EM algorithm stops when either the change in the loglikelihood is smaller than fx_tol, or the largest absolute change in the parameter values is smaller than dx_tol. The zerovar_offset element is used as the starting value for variances that are fixed to zero, as the EM algorithm cannot handle exact zero variances. The acceleration element controls whether the EM iterations are accelerated by the SQUAREM scheme, and the fused element controls whether the loglikelihood is computed as a byproduct of the E-step (see the em_h1_args option for details on both). If the nlminb_handoff element is TRUE (the default), and the EM iterations end with a non-negligible gradient (larger than dx_tol; this typically happens when the loglikelihood stalls before the gradient has converged), the solution is refined by a quasi-Newton (nlminb) run, warm-started at the EM values; the refined solution is only accepted if nlminb converges to an (at least) equally good solution; otherwise, the EM solution is retained. If, in addition, the early_handoff element is TRUE (the default), the EM phase stops early (using a loosened tolerance, max(fx_tol, 0.001)), as it only needs to provide a reliable warm start for nlminb; this is usually considerably faster, and gives the same solution; if nlminb fails from the early start, a safety net resumes the EM iterations with the strict fx_tol (and tries the hand-off once more), reproducing the non-early behavior. If verbose = TRUE, only the EM (or SQUAREM) cycles are shown; set the verbose element to TRUE to also show the optimizer output of each (inner) M-step.

Parallelization options (currently only used for bootstrapping):

parallel

The type of parallel operation to be used (if any). If missing, the default is "no".

ncpus

Integer: number of processes to be used in parallel operation: typically one would set this to the number of available CPUs. By default this is 2 (following CRAN policy); you may set this to a higher value (for example, the number of cores as detected by parallel::detectCores() minus one) if you wish to use more processes.

cl

An optional parallel or snow cluster for use if parallel = "snow". If not supplied, a cluster on the local machine is created for the duration of the lavBootstrap call.

iseed

An integer to set the seed. Or NULL if no reproducible results are needed. This works for both serial (non-parallel) and parallel settings. Internally, RNGkind() is set to "L'Ecuyer-CMRG" if parallel = "multicore". If parallel = "snow" (under windows), parallel::clusterSetRNGStream() is called which automatically switches to "L'Ecuyer-CMRG". When iseed is not NULL, .Random.seed (if it exists) in the global environment is left untouched.

Categorical estimation options:

zero_add:

A numeric vector containing two values. These values affect the calculation of polychoric correlations when some frequencies in the bivariate table are zero. The first value only applies for 2x2 tables. The second value for larger tables. This value is added to the zero frequency in the bivariate table. If "default", the value is set depending on the "mimic" option. By default, lavaan uses zero_add = c(0.5, 0.0).

zero_keep_margins:

Logical. This argument only affects the computation of polychoric correlations for 2x2 tables with an empty cell, and where a value is added to the empty cell. If TRUE, the other values of the frequency table are adjusted so that all margins are unaffected. If "default", the value is set depending on the "mimic" option. The default is TRUE.

zero_cell_warn:

Logical. Only used if some observed endogenous variables are categorical. If TRUE, give a warning if one or more cells of a bivariate frequency table are empty.

allow_empty_cell:

Logical. If TRUE, ignore situations where an ordinal variable has fewer categories than expected, or where a category is empty in a specific group. This argument is currently used by the blavaan package (which uses lavaan to set up the model). The argument is not expected to salvage a lavaan model that results in errors.

Starting values options:

start:

If it is a character string, the two options are currently "simple" and "default". In the first case, all parameter values are set to zero, except the factor loadings and (residual) variances, which are set to 0.7 and 1.0 respectively. When start is "default", the factor loadings are estimated using the fabin3 estimator (tsls) per factor. The residual variances of observed variables are set to half the observed variance, and all other (residual) variances are set to 0.05. The remaining parameters (regression coefficients, covariances) are set to zero. If start is a numerical vector, it should contain the starting values for all the free parameters (in the same order as the parameter table). If start is a fitted object of class lavaan, the estimated values of the corresponding parameters will be extracted. If it is a parameter table, for example the output of the parameterEstimates() function, the values of the est or start or ustart column (whichever is found first) will be extracted.

rstarts:

Integer. The number of refits that lavaan should try with random starting values. Random starting values are computed by drawing random numbers from a uniform distribution. Correlations are drawn from the interval [-0.5, +0.5] and then converted to covariances. Lower and upper bounds for (residual) variances are computed just like the standard bounds in bounded estimation. Random starting values are not computed for regression coefficients (which are always zero) and factor loadings of higher-order constructs (which are always unity). From all the runs that converged, the final solution is the one that resulted in the smallest value for the discrepancy function.

Check options:

check_start:

Logical. If TRUE, the starting values are checked for possibly inconsistent values (for example values implying correlations larger than one). If needed, a warning is given.

check_sigma_pd:

Character. If "chol", a Cholesky decomposition is used to check if the model implied covariance matrix (Sigma) is positive definite. If "eigen", an eigen decomposition is used to check if Sigma is positive definite. The latter was the default until 0.6-20. From 0.6-21 onwards, "chol" became the default (as it is much faster).

check_gradient:

Logical. If TRUE, and the model converged, a warning is given if the optimizer reported a (local) solution while not all elements of the (unscaled) gradient (as seen by the optimizer) are (near) zero, as they should be (the tolerance used is 0.001).

check_post:

Logical. If TRUE, and the model converged, a check is performed after (post) fitting, to verify if the solution is admissible. This implies that all variances are non-negative, and that the model-implied covariance matrix of the latent variables (cov_lv), the covariance matrix of the residuals in the structural part of the model (psi, which also contains the residual (co)variances of the observed endogenous variables), and the covariance matrix of the residuals of the (numeric) observed variables (theta) are positive (semi-)definite. For the latter tests, we tolerate a tiny negative eigenvalue that is smaller than .Machine$double.eps^(3/4) (relative to the largest eigenvalue), treating it as being zero.

check_vcov:

Logical. If TRUE, and the model converged, we check if the variance-covariance matrix of the free parameters is positive definite. We take into account possible equality and active inequality constraints. If needed, a warning is given.

check_lv_names:

Logical. If TRUE, and latent variables are defined in the model, lavaan will stop with an error message if a latent variable name also occurs in the data (implying it is also an observed variable).

Verbosity options:

verbose:

If TRUE, show what lavaan is doing. During estimation, the function value is printed out during each iteration.

warn:

If FALSE, suppress all lavaan-specific warning messages.

debug:

If TRUE, debugging information is printed out.

Miscellaneous:

model_type:

Set the model type: possible values are "cfa", "sem" or "growth". This may affect how starting values are computed, and may be used to alter the terminology used in the summary output, or the layout of path diagrams that are based on a fitted lavaan object.

mimic:

If "Mplus", an attempt is made to mimic the Mplus program. If "EQS", an attempt is made to mimic the EQS program. If "default", the value is (currently) set to "lavaan", which is very close to "Mplus". See mimic for the list of options that are affected by each setting.

representation:

If "LISREL" the classical LISREL matrix representation is used to represent the model (using the all-y variant). No other options are available (for now).

implied:

Logical. If TRUE, compute the model-implied statistics, and store them in the implied slot.

h1:

Logical. If TRUE, compute the unrestricted model and store the unrestricted summary statistics (and perhaps a loglikelihood) in the h1 slot.

baseline:

Logical. If TRUE, compute a baseline model (currently always the independence model, assuming all variables are uncorrelated) and store the results in the baseline slot.

baseline_conditional_x_free_slopes:

Logical. If TRUE, and conditional_x = TRUE, the (default) baseline model will allow the slope structure to be unrestricted.

baseline_fixed_x_free_cov:

Logical. If TRUE (the default), and the model contains exogenous covariates (and conditional_x = FALSE), the covariances among the exogenous covariates are retained in the baseline (independence) model: they are freely estimated if fixed_x = FALSE, and fixed to their sample values if fixed_x = TRUE (which yields the same baseline chi-square statistic). If FALSE, these covariances are constrained to zero in the baseline model, just like all other covariances, which leads to a larger baseline chi-square statistic (and hence higher values for incremental fit indices like the CFI). The variances of the exogenous covariates are always retained.

fit_by_level:

Logical. Only used for multilevel models. If TRUE, fit (and store) the partially saturated models that are needed to compute level-specific fit measures: for each level, an auxiliary model is fitted where the model at that level is retained, while the model at the other level is saturated (in addition, level-specific baseline models are fitted as well). See the level argument of fitMeasures. Set to FALSE to skip these additional model fits.

store_vcov

Logical. If TRUE, and se= is not set to "none", store the full variance-covariance matrix of the model parameters in the vcov slot of the fitted lavaan object.

parser

Character. If "new" (the default), the new parser is used to parse the model syntax. If "old", the original (pre 0.6-18) parser is used.

See Also

lavaan, mimic, estimator_iv, estimator_js

Examples

lavOptions()
lavOptions("std_lv")
lavOptions(c("std_lv", "orthogonal"))
# the dotted spelling is accepted too
lavOptions("std.lv")

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