Skip to contents

Generate a list of models with df equal to a fitted model.

Usage

eq_df_models(
  sem_out,
  fit_models = FALSE,
  loadings_to_exclude_from_drop = "all",
  must_not_drop = NULL,
  must_not_add = NULL,
  se = "none",
  exclude_x_y_ecov = TRUE,
  exclude_x_y_ecov_interim = FALSE,
  exclude_x_y_ecov_add_drop = FALSE,
  keep_covs = c("all_covs", "all_x_covs", "no"),
  parallel = TRUE,
  ncores = max(parallel::detectCores(logical = FALSE) - 1, 1),
  progress = interactive(),
  gen_models_progress = FALSE,
  short_names = TRUE,
  must_not_add_nil_parameters = TRUE,
  save_history = FALSE,
  use_mi = FALSE,
  mi_tolerance = 1e-04
)

Arguments

sem_out

A lavaan object, which is usually the output of lavaan::sem() or similar wrappers. Models will be generated from this model.

fit_models

Whether the models will be fitted to the data. To be passed to drop_k() and add_k(). Usually should be left as FALSE, the default, to speed up the search because usually only the final set of models need to be fitted.

loadings_to_exclude_from_drop

How factor loadings will be handled. Default is "all" and no factor loadings will be dropped. To be passed to modelbpp::gen_models(). This argument should not be changed. Included for internal use.

must_not_drop

A character vector of parameters that must not be removed, and so will not be modified. To be passed to modelbpp::gen_models().

must_not_add

A character vector of parameters that must not be added. To be passed to modelbpp::gen_models().

se

Whether standard error will be computed. This argument will be passed to lavaan::lavaan(). Default is "none", and this setting overrides the setting in object. The standard errors are irrelevant in checking whether two models are equivalent.

exclude_x_y_ecov

If TRUE, models with a covariance between a variable (latent or observed) and the error term of another variable it predicts, either directly or indirectly, will be excluded after the search is finished. The screening is implemented by remove_x_y_ecov().

exclude_x_y_ecov_interim

If TRUE, models with a covariance between a variable (latent or observed) and the error term of another variable it predicts, either directly or indirectly, will be excluded during each iteration, after calling drop_k() and before calling add_k(). The screening is implemented by remove_x_y_ecov().

exclude_x_y_ecov_add_drop

To be passed to argument exclude_x_y_ecov of drop_k() and add_k(). For excluding models when generating +1df and -1df models.

keep_covs

Whether covariances will be kept in all models. If "no", covariances may be changed to direct paths. If "keep_covs", then all covariances will not be changed, and will be kept in all models. If "keep_x_covs", then all covariances between exogenous variables will not be changed, and will be kept in all models.

parallel

Whether parallel processing will be used. If possible, should be set to TRUE to speed up the search.

ncores

The number of CPU cores to be used if parallel is TRUE.

progress

If TRUE, messages will be displayed to report the progress of the search.

gen_models_progress

If TRUE, then progress in each call to drop_k() or add_k() will also be displayed.

short_names

If TRUE, then short names (from the digests generated by digest_partable()) will be used to name the models. Though these names are not meaningful words, the full names describing the changes can be very long.

must_not_add_nil_parameters

If TRUE, nil parameters (paths or covariances fixed to zero) will not be added in the search, implemented by including these parameters in must_not_add.

save_history

Logical. If TRUE, the search history will be saved.

use_mi

If TRUE, modification indices will be used to determine whether a model with a parameter added is likely to be equivalent to the original model before used to generate object (determined by the attribute parameter_dropped).

mi_tolerance

The tolerance use to determine whether two modification indices are considered to be equal. Used when use_mi is TRUE.

Value

The function eq_df_models() returns an eq_partables object (a subclass of partables), which is a list of models represented by parameter tables.

Details

The following steps will be repeated to generate models with the same df as a fitted model:

First, models with one more df than the fitted model will be generated, by fixing more free parameters to zero. This step is conducted by drop_k().

Second, for each of the one-more-df model, models with one less df will be generated, usually by setting one fixed parameter to free (e.g., adding a regression path). These models will then have the same model df as the fitted model. This step is conducted by add_k().

These two steps will be repeated until no more new models are found.

Examples


library(lavaan)

# Model 1

mod1 <-
"
fm ~ fx
fy ~ fm
"
fit1 <- sem(
          model = mod1,
          data = data_test_3obvs,
          fixed.x = FALSE
        )

# Remove 'parallel = FALSE' or set parallel to TRUE
# for faster generation.
out <- eq_df_models(
  sem_out = fit1,
  parallel = FALSE
)
out
#> 
#> Number of models: 9
#> 
#> The models:
#> 
#>   Model   
#> 1 efdeea17
#> 2 f6b32a38
#> 3 12672c47
#> 4 b0a9b170
#> 5 459cd495
#> 6 45f61ccf
#> 7 81fb9dff
#> 8 6f675f0c
#> 9 c02043f3 
#> 
#> NOTE: 'default' names are used. Call 'print()' and add 'names_to_use =
#> "long"' to use the long descriptive names, if available, for the
#> models.