Modified Models

Generate a list of models with a certain number of degrees different from an original model.

Usage

drop_k(
  object,
  ...,
  sem_out = NULL,
  loadings_to_exclude_from_drop = "all",
  df_change_drop = 1,
  must_not_drop = NULL,
  se = "none",
  progress = interactive(),
  fit_models = FALSE,
  parallel = TRUE,
  ncores = max(parallel::detectCores(logical = FALSE) - 1, 1),
  make_cluster_args = list(),
  drop_original = TRUE,
  add_digest = TRUE,
  dat = NULL
)

add_k(
  object,
  ...,
  sem_out = NULL,
  df_change_add = 1,
  must_not_add = NULL,
  exclude_x_y_ecov = TRUE,
  partable_name = NULL,
  se = "none",
  progress = interactive(),
  fit_models = FALSE,
  parallel = TRUE,
  ncores = max(parallel::detectCores(logical = FALSE) - 1, 1),
  make_cluster_args = list(),
  remove_dropped = TRUE,
  remove_zeros = FALSE,
  add_name = FALSE,
  add_digest = TRUE,
  dat = NULL,
  return_error_msg = FALSE
)

Arguments

object: The original model. It can be a lavaan-class object (the output of lavaan::lavaan() or its wrappers, such as lavaan::sem()). It can also be a parameter table generated in lavaan.
...: Optional arguments to be passed to modelbpp::gen_models().
sem_out: A lavaan object. If supplied and fit_models is TRUE, the generate models will be fitted by updating this object.
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.
df_change_drop: The change in the degrees of freedom when generating simplified models. Default is one. To be passed to modelbpp::gen_models().
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().
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.
progress: Whether the model generation process will be displayed on screen.
fit_models: Whether the models will be fitted to the data.
parallel: Whether parallel processing will be used when fitting the models. To be passed to modelbpp::fit_many().
ncores: The number of CPU cores to be used if parallel is TRUE. To be passed to modelbpp::fit_many().
make_cluster_args: An optional named list of arguments to be used in parallel::makeCluster(). To be passed to modelbpp::fit_many().
drop_original: Logical. Whether the original model will be dropped from the output. Default is TRUE.
add_digest: Logical. If TRUE, add_digest() will be called to add hash values to the parameter table.
dat: The dataset to be used when sem_out is NULL and object is not a lavaan output with data.
df_change_add: The change in the degrees of freedom when adding free parameters. To be passed to modelbpp::gen_models(). Default to one. Should not be changed except for experimental use of this function.
must_not_add: A character vector of parameters that must not be added. To be passed to modelbpp::gen_models().
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().
partable_name: The name of the original model. Used only if it cannot be generated from object.
remove_dropped: Whether the previously dropped parameter, if stored, will be removed from the original parameter table. This is necessary for reversing a path. For internal use. Should not be changed.
remove_zeros: Whether a parameter explicitly fixed to zero will be removed before generating modified models. For internal use. Should not be changed.
add_name: Whether the name of the original model will be added as a prefix to the names of the generated models.
return_error_msg: If an error occurred when calling modelbpp::gen_models(), whether it will throw an error or return the error message. Set to TRUE when being called by some functions, to defer error handling to the calling function.

Value

The function drop_k() returns a list of the class eq_partables, a subclass of partables. It is an output of modelbpp::gen_models(), which are simplified versions of the original model, usually with one or more paths removed (fixed to zero).

The function add_k() returns a list of the class eq_partables, a subclass of the output of modelbpp::gen_models(), which are more complicated versions of the original model, usually with one or more paths added (set to free).

Details

The function drop_k() is a helper to generate a list of models k more degrees of freedom different from an original model fitted by lavaan, such as lavaan::sem().

The function add_k() is a helper to generate a list of models k less degrees of freedom different from an original model fitted by lavaan, such as lavaan::sem().

References

Pesigan, I. J. A., Cheung, S. F., Wu, H., Chang, F., & Leung, S. O. (2026). How plausible is my model? Assessing model plausibility of structural equation models using Bayesian posterior probabilities (BPP). Behavior Research Methods, 58(3), 73. doi:10.3758/s13428-025-02921-x

Examples