Generate Models with the Same Degrees of Freedom — eq_df

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

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. The screening is implemented by remove_x_y_ecov().
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.

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 f6b32a38
#> 2 12672c47
#> 3 45f61ccf
#> 4 b0a9b170
#> 5 efdeea17
#> 6 6f675f0c
#> 7 81fb9dff
#> 8 459cd495
#> 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.