Title: | Model BIC Posterior Probability |
Version: | 0.1.5 |
Description: | Fits the neighboring models of a fitted structural equation model and assesses the model uncertainty of the fitted model based on BIC posterior probabilities, using the method presented in Wu, Cheung, and Leung (2020) <doi:10.1080/00273171.2019.1574546>. |
License: | GPL (≥ 3) |
Encoding: | UTF-8 |
RoxygenNote: | 7.3.2 |
Suggests: | knitr, rmarkdown, tinytest |
Depends: | R (≥ 4.0.0) |
Imports: | lavaan, parallel, pbapply, igraph, manymome |
VignetteBuilder: | knitr |
URL: | https://sfcheung.github.io/modelbpp/ |
BugReports: | https://github.com/sfcheung/modelbpp/issues |
LazyData: | true |
NeedsCompilation: | no |
Packaged: | 2024-09-16 14:27:06 UTC; shufa |
Author: | Shu Fai Cheung |
Maintainer: | Shu Fai Cheung <shufai.cheung@gmail.com> |
Repository: | CRAN |
Date/Publication: | 2024-09-16 15:20:02 UTC |
modelbpp: Model BIC Posterior Probability
Description
Fits the neighboring models of a fitted structural equation model and assesses the model uncertainty of the fitted model based on BIC posterior probabilities, using the method presented in Wu, Cheung, and Leung (2020) doi:10.1080/00273171.2019.1574546.
Author(s)
Maintainer: Shu Fai Cheung shufai.cheung@gmail.com (ORCID)
Authors:
Huiping Wu
Shing On Leung (ORCID)
Other contributors:
Ivan Jacob Agaloos Pesigan r.jeksterslab@gmail.com (ORCID) [contributor]
See Also
Useful links:
Manipulate Parameter Tables
Description
Functions to manipulate
a partables
-class object
Usage
## S3 method for class 'partables'
c(...)
## S3 method for class 'model_set'
c(...)
partables_drop(x, model_names = NULL)
Arguments
... |
An arbitrary number of
objects. All invalid objects (see
details) will be discarded. If an
object is named and is not
|
x |
A |
model_names |
A character vector
of the names of models in a
|
Details
The partables
-class objects have
a c()
method that can be used to
combine parameter tables.
Each object must be
a. a partables
-class object,
b. a model_set
-class object,
c. a lavaan
-class object, or
d. a parameter table of
the class lavaan.data.frame()
,
usually generated by
lavaan::parameterTable()
.
Other objects will be discarded.
Names will be used when combining objects. If two objects have the same names, then only the first one will be retained. No warning message will be issued. Users are encouraged to explicitly name all objects carefully.
Note that, to invoke this method,
the first object must be a
partables
object.
The model_set
class also has a
c
-method. It
will replace the first object by the stored
partables and then call the c
-method of partables
objects.
The function partables_drop()
is
for dropping models from a
partables
-class object.
Value
A partables
-class objects with
all the objects supplied combined
together. If an object is
a lavaan
-class object, its
parameter table will be retrieved
by lavaan::parameterTable()
.
If an object is a model_set
-class
object, the stored partables
-class
object will be retrieved.
Author(s)
Shu Fai Cheung https://orcid.org/0000-0002-9871-9448
Examples
library(lavaan)
moda <-
"
x3 ~ a*x1 + b*x2
x4 ~ a*x1
ab := a*b
"
fita <- sem(moda, dat_path_model, fixed.x = TRUE)
outa <- model_set(fita,
progress = FALSE,
parallel = FALSE)
modb <-
"
x3 ~ a*x1 + b*x2
x4 ~ a*x2
ab := a*b
"
fitb <- sem(modb, dat_path_model, fixed.x = TRUE)
outb <- model_set(fitb,
progress = FALSE,
parallel = FALSE)
mod2 <-
"
x2 ~ 0*x3 + 0*x4
x1 ~ 0*x3
"
fit2 <- sem(mod2, dat_path_model)
mod3 <-
"
x2 ~ x3 + 0*x4
x1 ~ x3
"
fit3 <- sem(mod3, dat_path_model)
out <- c(outa$models, user2 = fit2, outb$models, user3 = fit3)
out
out2 <- c(outa, user2 = fit2, outb$models, user3 = fit3)
out2
out3 <- c(outa, user2 = fit2, outb, user3 = fit3)
out3
A Sample Dataset Based On a Confirmatory Factor Analysis Model (For Testing)
Description
Generated from a confirmatory factor analysis model (n = 200).
Usage
dat_cfa
Format
A data frame with six variables:
- x1
Indicator
- x2
Indicator
- x3
Indicator
- x4
Indicator
- x5
Indicator
- x6
Indicator
Details
The model used to generate this dataset:
f1 =~ x1 + x2 + x3 + x5 f2 =~ x3 + x4 + x5 + x6 f1 ~~ f2
A Sample Dataset Based on a Path Model (For Testing)
Description
Generated from the a path model (n = 100).
Usage
dat_path_model
Format
A data frame with four variables:
- x1
Predictor
- x2
Predictor
- x3
Mediator
- x4
Outcome
Details
The model used to generate this dataset:
x1 ~~ x2 x3 ~ x1 + x2 x4 ~ x3 + x1 + x2
A Sample Dataset Based On a Complex Path Model (For Testing)
Description
Generated from a complex path model (n = 200).
Usage
dat_path_model_p06
Format
A data frame with six variables:
- x1
Predictor
- x2
Predictor
- x3
Predictor
- y4
Mediator
- y5
Mediator
- y6
Outcome
Details
The model used to generate this dataset:
y4 ~ x1 + x2 + x3 y5 ~ y4 + x1 + x2 y6 ~ y4 + y5 + x1 + x2 + x3 x1 ~~ x2 + x3 x2 ~~ x3
A Sample Dataset Based On a Structural Model (For Testing)
Description
Generated from a structural model with latent variables (n = 250).
Usage
dat_sem
Format
An object of class data.frame
with 250 rows and 16 columns.
Details
The model to be fitted:
f1 =~ x1 + x2 + x3 + x4 f2 =~ x5 + x6 + x7 + x8 f3 =~ x9 + x10 + x11 + x12 f4 =~ x13 + x14 + x15 + x16 f3 ~ f1 + f2 f4 ~ f3
A Sample Dataset Based On a Serial Mediation Model (For Testing)
Description
Generated from a serial mediation model (n = 100).
Usage
dat_serial_4
Format
A data frame with four variables:
- x
Predictor
- m1
Mediator
- m2
Mediator
- y
Outcome
Details
The model used to generate this dataset:
m1 ~ x m2 ~ m1 y ~ m2
A Sample Dataset Based On a Serial Mediation Model With Weak Paths (For Testing)
Description
Generated from a serial mediation model (n = 100).
Usage
dat_serial_4_weak
Format
A data frame with four variables:
- x
Predictor
- m1
Mediator
- m2
Mediator
- y
Outcome
Details
The model to be fitted:
m1 ~ x m2 ~ m1 + x y ~ m2 + m1 + x
Fit a List of Models
Description
Fit a list of models to a dataset.
Usage
fit_many(
model_list,
sem_out,
original = NULL,
parallel = FALSE,
ncores = max(parallel::detectCores(logical = FALSE) - 1, 1),
make_cluster_args = list(),
progress = TRUE,
verbose = TRUE
)
Arguments
model_list |
A list of parameter
tables to be used by
|
sem_out |
The output from an
structural equation modeling
function. It currently supports
lavaan::lavaan objects
only. Usually
the one used in |
original |
String. If provided,
it should be a name of a model
in |
parallel |
If |
ncores |
Numeric. The number of
CPU cores to be used if |
make_cluster_args |
A list of
named arguments to be passed to
|
progress |
Whether a progress
bar will be displayed, implemented
by the |
verbose |
Whether additional
messages will be displayed, such
as the expected processing time.
Default is |
Details
It receives a list of
models, defined by lavaan
parameter
tables (usually generated by
model_set()
, get_add()
or
get_drop()
),
and fit them to a dataset stored
in a lavaan
-class object.
This function is called by
model_set()
and usually users do
not need to call it. It is exported
for advanced users.
Value
An object of the class
sem_outs
, a list with the
following major elements:
-
fit
: A named list oflavaan::lavaan()
output objects orupdate()
for fitting a model with the added parameters. -
change
: A numeric vector, of the same length asfit
. The change in model df for each fit compared to the original model. A positive number denotes one less free parameter. A negative number denotes one more free parameter or one less constraint. -
converged
: A named vector of boolean values, of the same length asfit
. Indicates whether each fit converged or not. -
post_check
: A named vector of boolean values, of the same length asfit
. Indicates whether the solution of each fit is admissible or not. Checked bylavaan::lavInspect()
with thewhat
argument set to"post.check"
.
Author(s)
Shu Fai Cheung https://orcid.org/0000-0002-9871-9448
Examples
library(lavaan)
dat <- dat_path_model
mod <-
"
x3 ~ a*x1 + b*x2
x4 ~ a*x1
ab := a*b
"
fit <- sem(mod, dat_path_model, fixed.x = TRUE)
mod_to_add <- get_add(fit)
fit_many(mod_to_add, fit)
Models That Are Less Restricted
Description
Generate a list of models with one or more fixed parameter freed.
Usage
get_add(
sem_out,
must_add = NULL,
must_not_add = NULL,
remove_constraints = TRUE,
exclude_error_cov = TRUE,
exclude_feedback = FALSE,
exclude_xy_cov = FALSE,
df_change = 1,
model_id = NA,
keep_correct_df_change = TRUE,
remove_duplicated = TRUE,
progress = FALSE
)
Arguments
sem_out |
The original model, which is the output from an structural equation modeling function. Currently support lavaan::lavaan objects only. |
must_add |
A character vector
of parameters, named in
|
must_not_add |
A character
vector of parameters, named in
|
remove_constraints |
Whether
equality constraints will be
removed. Default is |
exclude_error_cov |
Exclude
error covariances of indicators.
Default is |
exclude_feedback |
Exclude
paths that will result in a feedback
loop. For example, if there is
path from |
exclude_xy_cov |
Exclude
covariance between two variables,
in which one has a path to another.
For example, if there is
path from |
df_change |
How many degrees of freedom (df) away in the list. All models with df change less than or equal to this number will be included, taking into account requirements set by other arguments. Default is 1. |
model_id |
The identification
number of the starting model.
Default is |
keep_correct_df_change |
Keep only models with actual df change equal to expected df change. |
remove_duplicated |
If |
progress |
Whether a progress
bar will be displayed, implemented
by the |
Details
It generates a list of models with one or more fixed parameter freed (and the degrees of freedom, df, increases by one or more). If a model has equality constraints, models with one or more of the constraints between two free parameters released will also be included.
Graphically, paths or covariances are "added" to form the list of models.
The models to be included are
identified by
lavaan::modificationIndices()
.
The models will be checked by lavaan
to make sure that the decrease in
model degrees of freedom is of the
expected value.
This function is called by
model_set()
and usually users do
not need to call it. It is exported
for advanced users.
Value
An object of the class
partables
, a named list of parameter
tables, each of them to be used by
lavaan::lavaan()
or update()
for fitting a model with the added
parameters.
Author(s)
Shu Fai Cheung https://orcid.org/0000-0002-9871-9448
See Also
Examples
library(lavaan)
dat <- dat_path_model
mod <-
"
x3 ~ a*x1 + b*x2
x4 ~ a*x1
ab := a*b
"
fit <- sem(mod, dat_path_model, fixed.x = TRUE)
mod_to_add <- get_add(fit)
mod_to_add
Models That Are More Restricted
Description
Generate a list of models with one or more free parameter dropped (fixed to zero).
Usage
get_drop(
sem_out,
must_drop = NULL,
must_not_drop = NULL,
df_change = 1,
model_id = NA,
keep_correct_df_change = TRUE,
remove_duplicated = TRUE,
progress = FALSE
)
Arguments
sem_out |
The original model, which is the output from an structural equation modeling function. Currently support lavaan::lavaan objects only. |
must_drop |
A character vector
of parameters, named in
|
must_not_drop |
A character
vector of parameters, named in
|
df_change |
How many degrees of freedom away in the list. All models with df change less than or equal to this number will be included, taking into account requirements set by other arguments. Default is 1. |
model_id |
The identification
number of the starting model.
Default is |
keep_correct_df_change |
Keep only models with actual df change equal to expected df change. |
remove_duplicated |
If |
progress |
Whether a progress
bar will be displayed, implemented
by the |
Details
It generates a list of models with one or more free parameters dropped, that is, fixed to zero (with degrees of freedom, df, increases by one or more).
All free parameters are included in the pool of candidates, except for those explicitly requested to be kept.
The models will be checked by lavaan
to make sure that the increase in
model degrees of freedom is of the
expected value.
This function is called by
model_set()
and usually users do
not need to call it. It is exported
for advanced users.
Value
An object of the class
partables
, a named list of parameter
tables, each of them to be used by
lavaan::lavaan()
or update()
for fitting a model with the added
parameters.
Author(s)
Shu Fai Cheung https://orcid.org/0000-0002-9871-9448
See Also
Examples
library(lavaan)
dat <- dat_path_model
mod <-
"
x3 ~ a*x1 + b*x2
x4 ~ a*x1 + x2
ab := a*b
"
fit <- sem(mod, dat_path_model, fixed.x = TRUE)
mod_to_drop <- get_drop(fit)
mod_to_drop
Measurement Invariance Models
Description
Generate metric and scalar invariance models and their partial invariance versions.
Usage
measurement_invariance_models(
cfa_out,
max_free = 1,
metric = TRUE,
scalar = TRUE,
progress = TRUE
)
Arguments
cfa_out |
The output of
|
max_free |
The maximum number of constraints to be released when generating the partial invariance models. For example, if set to 1, then only the partial metric invariance model only has at most one item allowed to have different loadings across group. Default is 1. If set to zero, then no partial invariance models will be generated. |
metric |
Logical. If |
scalar |
Logical. If |
progress |
Logical. If |
Details
This a helper function to generate, based on a multigroup confirmatory factor analysis (CFA) model with no between-group equality constraints, the following models:
A metric invariance model (loadings constrained to be equal across groups).
A scalar invariance model (intercepts and loadings constrained to be equal across groups).
Partial invariance versions of the previous two models, such as a model with the loadings of all items, except for one, constrained to be equal across groups.
The models generated can then be used
in model_set()
to compute BPPs.
Requirements
The model used as the input needs to be fitted with no between group constrains, that is, it is a configural invariance model. Although not a must, it is advised to use the default way to identify each factor (that is, fixing a loading to one).
Implementation
This function simply use the
group.partial
and group.equal
argument of lavaan::cfa()
to
generate the models.
Value
A list of lavaan::cfa()
output. The names are automatically
generated to indicate whether a model
is configural, metric, or scalar
invariance, or the item(s) without
between-group constraints on the
loadings (for partial metric
invariance) or intercepts (for
partial scalar invariance).
Author(s)
Shu Fai Cheung https://orcid.org/0000-0002-9871-9448
See Also
Examples
library(lavaan)
# For illustration, only one factor is used,
# with one item from another factor added
# just to make the model not saturated.
HSmod <-
"
spatial =~ x1 + x2 + x3 + x4
"
fit_config <- cfa(model = HSmod,
data = HolzingerSwineford1939,
group = "school")
fit_mi <- measurement_invariance_models(fit_config)
names(fit_mi)
# Need to add 'skip_check_sem_out = TRUE' to use multigroup models.
out <- model_set(sem_out = fit_mi,
skip_check_sem_out = TRUE,
progress = FALSE,
parallel = FALSE)
print(out)
Minimum Prior
Description
Find the minimum prior probability required to achieve the desired BIC posterior probability.
Usage
min_prior(bic, bpp_target, target_name = "original")
Arguments
bic |
A named vector of BIC values for a set of models. |
bpp_target |
A value from zero to 1. The desired BIC posterior probability. |
target_name |
The name of the
original model, as appeared in the
names of |
Details
It assumes that all models other than the original model have the same prior probabilities.
This function is called by
model_set()
or print.model_set()
and usually users do
not need to call it. It is exported
for advanced users.
Value
A scalar. The required prior probability.
Author(s)
Shu Fai Cheung https://orcid.org/0000-0002-9871-9448
References
Wu, H., Cheung, S. F., & Leung, S. O. (2020). Simple use of BIC to assess model selection uncertainty: An illustration using mediation and moderation models. Multivariate Behavioral Research, 55(1), 1–16. doi:10.1080/00273171.2019.1574546
See Also
model_set()
and
print.model_set()
Examples
library(lavaan)
dat <- dat_path_model
mod <-
"
x3 ~ a*x1 + b*x2
x4 ~ a*x1
ab := a*b
"
fit <- sem(mod, dat_path_model, fixed.x = TRUE)
out <- model_set(fit)
min_prior(out$bic, bpp_target = .8)
Generate a Graph of Models
Description
Generate an 'igraph' object from a 'model_set' object.
Usage
model_graph(
object,
node_size_by_x = TRUE,
x = NULL,
node_size = 5,
min_size = 5,
max_size = 35,
color_original = "lightblue",
color_add = "burlywood1",
color_drop = "lightgreen",
color_others = "lightgrey",
color_label = "black",
node_label_size = 1,
original = "original",
drop_redundant_direct_paths = TRUE,
label_arrow_by_df = NULL,
arrow_label_size = 1,
weight_arrows_by_df = c("inverse", "normal", "none"),
arrow_min_width = 0.5,
arrow_max_width = 2,
progress = TRUE,
short_names = FALSE,
min_bpp_labelled = NULL,
...
)
Arguments
object |
Must be a
|
node_size_by_x |
Logical. Whether
node (vertex) sizes are determined
by a variable. Default is |
x |
If not |
node_size |
If |
min_size |
The minimum size of a node. Default is 5. |
max_size |
The maximum size of a node. Default is 35. |
color_original |
The color
of node of the original model.
Default is |
color_add |
The color of
the nodes of models formed by
adding one or more free parameters to
the original model.
Default is |
color_drop |
The color of
the nodes of models formed by
dropping one or more free parameters
from the original model.
Default is |
color_others |
The color
of other models not specified above.
Default is |
color_label |
The color of the
text labels of the nodes. Default
is |
node_label_size |
The size of the labels of the nodes. Default is 1. |
original |
String. The name
of the original model (target model).
Default is |
drop_redundant_direct_paths |
Logical. Whether the redundant direct
path between two models. A direct path
is redundant if two models are also
connected through at least one
another model. Default is |
label_arrow_by_df |
If |
arrow_label_size |
The size of the labels of the arrows (edges), if labelled. Default is 1. |
weight_arrows_by_df |
String.
Use if model df
differences are stored.
If |
arrow_min_width |
If
|
arrow_max_width |
If
|
progress |
Whether a progress
bar will be displayed for some
steps (e.g., checking for nested
relations). Default
is |
short_names |
If |
min_bpp_labelled |
If not |
... |
Optional arguments. Not used for now. |
Details
It extracts the model list stored
in object
, creates an adjacency
matrix, and then creates an igraph
object customized for visualizing
model relations.
Construction of the Graph
This is the default way to construct
the graph when the model set is
automatically by model_set()
.
Each model is connected by an arrow, pointing from one model to another model that
a. can be formed by adding one or more free parameter, or
b. can be formed by releasing one or more equality constraint between two parameters.
c. has nested relation with this model as determined by the method proposed by Bentler and Satorra (2010), if the models are not generated internally.
That is, it points to a model with more degrees of freedom (more complicated), and is nested within that model in either parameter sense or covariance sense.
By default, the size of the node for each model is scaled by its BIC posterior probability, if available. See The Size of a Node below.
If a model is designated as the original (target) model, than he original model, the models with more degrees of freedom than the original model, and the models with fewer degrees of freedom than the original models, are colored differently.
The default layout is the Sugiyama layout, with simpler models (models with fewer degrees of freedom) on the top. The lower a model is in the network, the more the degrees of freedom it has. This layout is suitable for showing the nested relations of the models. Models on the same level (layer) horizontally have the same model df.
The output is an igraph
object.
Users can customize it in any way
they want using functions from
the igraph
package.
If a model has no nested relation with all other model, it will not be connected to other models.
If no model is named original
(default is "original"
), then no
model is colored as the original model.
User-Provided Models
If object
contained one or more
user-provided models which are not
generated automatically by
model_set()
or similar functions
(e.g., gen_models()
), then the
method by Bentler and Satorra (2010)
will be used to determine model
relations. Models connected by an
arrow has a nested relation based on
the NET method by Bentler and Satorra
(2010). An internal function inspired
by the net
function from the
semTools
package is used to
implement the NET method.
The Size of a Node
When a model is scaled by x
,
which usually is the BIC posterior
probability, its size is determined
by:
max_size * (x - min(x))/(max(x) - min(x)) + min_size
Value
A model_graph
-class object that
can be used as as an igraph
-object,
with a plot method (plot.model_graph()
)
with settings
suitable for plotting a network
of models with BIC posterior probabilities
computed.
Author(s)
Shu Fai Cheung https://orcid.org/0000-0002-9871-9448
The internal function for nesting
inspired by the net
function
from the semTools
package,
which was developed by
Terrence D. Jorgensen.
References
Bentler, P. M., & Satorra, A. (2010). Testing model nesting and equivalence. Psychological Methods, 15(2), 111–123. doi:10.1037/a0019625 Asparouhov, T., & Muthén, B. (2019). Nesting and Equivalence Testing for Structural Equation Models. Structural Equation Modeling: A Multidisciplinary Journal, 26(2), 302–309. doi:10.1080/10705511.2018.1513795
Examples
library(lavaan)
mod <-
"
m1 ~ x
y ~ m1
"
fit <- sem(mod, dat_serial_4, fixed.x = TRUE)
out <- model_set(fit)
out
g <- model_graph(out)
plot(g)
BIC Posterior Probabilities of Neighboring Models
Description
Identify neighboring models, fit them, and return the BIC posterior probabilities.
Usage
model_set(
sem_out,
partables = NULL,
model_set_out = NULL,
prior_sem_out = NULL,
must_add = NULL,
must_not_add = NULL,
must_drop = NULL,
must_not_drop = NULL,
remove_constraints = TRUE,
exclude_error_cov = TRUE,
exclude_feedback = TRUE,
exclude_xy_cov = TRUE,
df_change_add = 1,
df_change_drop = 1,
remove_duplicated = TRUE,
fit_models = ifelse(!is.null(model_set_out$fit), FALSE, TRUE),
compute_bpp = TRUE,
original = "original",
parallel = FALSE,
ncores = max(parallel::detectCores(logical = FALSE) - 1, 1),
make_cluster_args = list(),
progress = TRUE,
verbose = TRUE,
skip_check_sem_out = FALSE,
drop_equivalent_models = TRUE
)
gen_models(
sem_out,
must_add = NULL,
must_not_add = NULL,
must_drop = NULL,
must_not_drop = NULL,
remove_constraints = TRUE,
exclude_error_cov = TRUE,
df_change_add = 1,
df_change_drop = 1,
remove_duplicated = TRUE,
progress = TRUE,
output = c("partables", "model_set")
)
Arguments
sem_out |
It can be the output from an SEM function. Currently it supports lavaan::lavaan objects only. If it is a named list of lavaan::lavaan objects, then all arguments for model generation will be ignored, and models will not be refitted. Users need to ensure that the models can be meaningfully compared because they will not be checked. |
partables |
A |
model_set_out |
If set to
the output of a previous call
to |
prior_sem_out |
The prior of the
model fitted in |
must_add |
A character vector
of parameters, named in
|
must_not_add |
A character
vector of parameters, named in
|
must_drop |
A character vector
of parameters, named in
|
must_not_drop |
A character
vector of parameters, named in
|
remove_constraints |
Whether equality constraints will be removed. Default is “TRUE'. |
exclude_error_cov |
Exclude
error covariances of indicators.
Default is |
exclude_feedback |
Exclude
paths that will result in a feedback
loop. For example, if there is
path from |
exclude_xy_cov |
Exclude
covariance between two variables,
in which one has a path to another.
For example, if there is
path from |
df_change_add |
How many degrees of freedom (df) away in the list. All models with df change less than or equal to this number will be included, taking into account requirements set by other arguments. Default is 1. |
df_change_drop |
How many degrees of freedom away in the list. All models with df change less than or equal to this number will be included, taking into account requirements set by other arguments. Default is 1. |
remove_duplicated |
If |
fit_models |
If |
compute_bpp |
If |
original |
String. The name of the
original (traget) model. Default is
|
parallel |
If |
ncores |
Numeric. The number of
CPU cores to be used if |
make_cluster_args |
A list of
named arguments to be passed to
|
progress |
Whether a progress
bar will be displayed, implemented
by the |
verbose |
Whether additional
messages will be displayed, such
as the expected processing time.
Default is |
skip_check_sem_out |
If |
drop_equivalent_models |
If
|
output |
If |
Details
It computes the BIC posterior probabilities of a set of models by the method presented in Wu, Cheung, and Leung (2020).
First, a list of model is identified
based on user-specified criteria.
By default, models differ from a fitted
model by one degree of freedom,
the 1-df-away neighboring models,
will be found using get_add()
and get_drop.
Second, these models will be fitted to the sample dataset, and their BICs will be computed.
Third, their BIC posterior
probabilities will be computed
using their BICs. By default,
equal prior
probabilities for all the models
being fitted will be assumed in
the current version. This can be
changed by prior_sem_out
.
The results can then be printed,
with the models sorted by descending
order of BIC posterior
probabilities. The results can
also be visualized using
model_graph()
.
Value
The function model_set()
returns an object of the class
model_set
, a list with the following
major elements:
-
models
: A named list of parameter tables. Each represent the models identified. -
bic
: A numeric vector, of the same length asmodel
. The BIC of each model. -
postprob
: A numeric vector, of the same length asmodel
. The BIC posterior probability of each model. -
fit
: A named list oflavaan::lavaan()
output objects orupdate()
for fitting a model with the added parameters, of the same length asmodel
. -
change
: A numeric vector, of the same length asmodel
. The change in model df for each fit. A positive number denotes one less free parameter. A negative number denotes one more free parameter or one less constraint. -
converged
: A named vector of boolean values, of the same length asmodel
. Indicates whether each fit converged or not. -
post_check
: A named vector of boolean values, of the same length asmodel
. Indicates whether the solution of each fit is admissible or not. Checked bylavaan::lavInspect()
.
The object returned by gen_models()
depends on the argument output
.
See the argument output
for the
details
Functions
-
model_set()
: Compute the BPPs of a list of models. Can generate the models and/or fit the models. Can also accept pregenerated models, or just update BPPs. -
gen_models()
: Generate a list of models (parameter tables).
Author(s)
Shu Fai Cheung https://orcid.org/0000-0002-9871-9448
References
Wu, H., Cheung, S. F., & Leung, S. O. (2020). Simple use of BIC to assess model selection uncertainty: An illustration using mediation and moderation models. Multivariate Behavioral Research, 55(1), 1–16. doi:10.1080/00273171.2019.1574546
See Also
Examples
library(lavaan)
dat <- dat_path_model
mod <-
"
x3 ~ a*x1 + b*x2
x4 ~ a*x1
ab := a*b
"
fit <- sem(mod, dat_path_model, fixed.x = TRUE)
out <- model_set(fit)
out
Helper Functions For partables
-Class Objects
Description
For tasks such as comparing two parameter
tables inside a partables
-class object.
Usage
identical_partables(object1, object2)
is_partable(x)
same_variables(x)
get_partables(x)
to_partables(...)
Arguments
object1 |
A |
object2 |
A |
x |
An object to be checked. |
... |
The objects to be combined. |
Details
The function identical_partables()
compare two
lavaan
parameter tables and see whether they
are identical. (Adapted from a similar function
in the package semhelpinghands
).
The function is_partable()
tries
to
check whether an object is "likely"
to be a parameter table that can be
used by lavaan::lavaan()
and its
wrappers, such as lavaan::sem()
.
Note that there is no guarantee the the parameter table makes sense or will not lead to error when fitted. It can only check whether it has the required columns.
The function same_variables()
check whether all parameter labels
in a partables
-class object use
the same observed variables.
The function get_partables()
extract the partable
object from
a model_set
-class object.
The function to_partables()
combine objects to create a
partables
-class object.
The objects to be combined can be
a lavaan
-class object (e.g.,
the output of lavaan::sem()
)
or a parameter table of lavaan
.
Value
The function identical_partables()
returns either TRUE
or FALSE
.
The function is_partable()
returns either TRUE
or FALSE
.
The function same_variables()
returns either TRUE
or FALSE
.
The function get_partables()
returns a partables
-class
object.
The function to_partables()
returns a partables
-class
object, created from the objects
supplied.
Examples
library(lavaan)
mod1 <-
"
x3 ~ x1
x2 ~ x4
"
mod2 <-
"
x2 ~ x4
x3 ~ x1
"
fit1 <- sem(mod1, dat_path_model)
fit2 <- sem(mod2, dat_path_model)
pt1 <- parameterTable(fit1)
pt2 <- parameterTable(fit2)
identical_partables(pt1, pt2)
is_partable(pt1)
out <- model_set(fit1,
fit_models = FALSE)
same_variables(get_partables(out))
out <- model_set(fit1,
fit_models = FALSE)
get_partables(out)
fit1 <- sem(mod1, dat_path_model)
fit2 <- sem(mod2, dat_path_model)
pt1 <- parameterTable(fit1)
pt2 <- parameterTable(fit2)
to_partables(fit1, fit2)
to_partables(pt1, pt2)
Plot a Network of Models
Description
Plot a network of models
generated by model_graph()
.
Usage
## S3 method for class 'model_graph'
plot(x, ...)
Arguments
x |
The output of
|
... |
Additional arguments,
passed to the |
Details
This function is the plot
method of model_graph
objects,
the output of
model_graph()
.
For now, it simply passes the object
to plot
-method of an igraph
object.
This function
is created for possible customization
of the plot in the future.
Value
NULL
. Called for its
side effect.
See Also
Examples
library(lavaan)
dat <- dat_path_model
mod <-
"
x3 ~ a*x1 + b*x2
x4 ~ a*x1
ab := a*b
"
fit <- sem(mod, dat_path_model, fixed.x = TRUE)
out <- model_set(fit)
out
g <- model_graph(out)
plot(g)
Print a model_set
-Class Object
Description
Print the content of
a model_set
-class object.
Usage
## S3 method for class 'model_set'
print(
x,
bic_digits = 3,
bpp_digits = 3,
sort_models = TRUE,
max_models = 20,
bpp_target = NULL,
target_name = "original",
more_fit_measures = c("cfi", "rmsea"),
fit_measures_digits = 3,
short_names = FALSE,
cumulative_bpp = FALSE,
...
)
Arguments
x |
A |
bic_digits |
The number of decimal places to be displayed for BIC. Default is 3. |
bpp_digits |
The number of decimal places to be displayed for BIC posterior probability and prior probabilities. Default is 3. |
sort_models |
Whether the models
will be sorted by BIC posterior
probability.
Default is |
max_models |
The maximum number of models to be printed. Default is 20. |
bpp_target |
The desired
BIC probability. Used to compute
and print
the minimum prior probability
of the target model required to
achieve |
target_name |
The name of the
target model as appeared in the
model list. Default is |
more_fit_measures |
Character
vector. To be passed to
|
fit_measures_digits |
The number of decimal places to be displayed for additional fit measures, if requested. Default is 3. |
short_names |
If |
cumulative_bpp |
If |
... |
Optional arguments. Ignored. |
Details
It is the print method of the
output of model_set()
.
Value
x
is returned invisibly.
Called for its side effect.
Author(s)
Shu Fai Cheung https://orcid.org/0000-0002-9871-9448
See Also
A model_set
-class object
is generated by model_set()
.
Examples
library(lavaan)
dat <- dat_path_model
mod <-
"
x3 ~ a*x1 + b*x2
x4 ~ a*x1
ab := a*b
"
fit <- sem(mod, dat_path_model, fixed.x = TRUE)
out <- model_set(fit)
out
Print a partables
-Class Object
Description
Print the content of
a partables
-class object.
Usage
## S3 method for class 'partables'
print(x, max_tables = 10, ...)
Arguments
x |
A |
max_tables |
The maximum number of models to be printed. Default is 10. |
... |
Optional arguments. Ignored. |
Details
The print method for the output
of gen_models()
, get_add()
,
and get_drop()
.
Value
x
is returned invisibly.
Called for its side effect.
Author(s)
Shu Fai Cheung https://orcid.org/0000-0002-9871-9448
See Also
gen_models()
, get_add()
,
and get_drop()
.
Examples
library(lavaan)
dat <- dat_path_model
mod <-
"
x3 ~ a*x1 + b*x2
x4 ~ a*x1
ab := a*b
"
fit <- sem(mod, dat_path_model, fixed.x = TRUE)
mod_to_add <- get_add(fit)
mod_to_add
print(mod_to_add, max_tables = 1)
mod_to_drop <- get_drop(fit)
mod_to_drop
print(mod_to_drop, max_tables = 1)
Print an sem_outs
-Class Object
Description
Print the content of
an sem_outs
-class object.
Usage
## S3 method for class 'sem_outs'
print(x, max_models = 20, ...)
Arguments
x |
An |
max_models |
The maximum number of models to be printed. Default is 20. |
... |
Optional arguments. Ignored. |
Details
The print method for the output
of fit_many()
.
Value
x
is returned invisibly.
Called for its side effect.
Author(s)
Shu Fai Cheung https://orcid.org/0000-0002-9871-9448
See Also
An sem_outs
-class object
is generated by fit_many()
.
Examples
library(lavaan)
dat <- dat_path_model
mod <-
"
x3 ~ a*x1 + b*x2
x4 ~ a*x1
ab := a*b
"
fit <- sem(mod, dat_path_model, fixed.x = TRUE)
mod_to_add <- get_add(fit)
out <- fit_many(mod_to_add, fit)
out
print(out, max_models = 1)