Generate the complete population model using the model syntax and user-specified effect sizes (population parameter values).
ptable_pop(
model = NULL,
pop_es = NULL,
es1 = c(n = 0, nil = 0, s = 0.1, m = 0.3, l = 0.5, si = 0.141, mi = 0.361, li = 0.51),
es2 = c(n = 0, nil = 0, s = 0.05, m = 0.1, l = 0.15),
es_ind = c("si", "mi", "li"),
standardized = TRUE,
n_std = 1e+05,
std_force_monte_carlo = FALSE,
add_cov_for_moderation = TRUE
)model_matrices_pop(x, ..., drop_list_single_group = TRUE)
The function ptable_pop() returns
a lavaan parameter table of the
model, with the column start set to the
population values.
The function model_matrices_pop()
returns a lavaan LISREL-style model
matrices (like the output of
lavaan::lavInspect() with what
set to "free"), with matrix elements
set to the population values. If
x is the model syntax, it will be
stored in the attributes model.
If the model is a multigroup model
with k groups (k greater than 1),
then it returns a list of k lists
of lavaan LISREL-style model
matrices unless drop_list_single_group
is TRUE.
String. The model defined
by lavaan model syntax. See 'Details'.
It can be a data frame
with these columns: lhs, op,
rhs, and pop. The first three
columns correspond to those in a
lavaan parameter table. The column
pop stores the population values.
The column es stores the original
labels, for reference. It can also be
a named character vector (named list
for multigroup models) or a multiline string,
which are
the preferred approaches. See the
help page
on how to specify this vector.
Set the
values for each label of the effect
size (population value) for correlations and regression
paths.
Used only if pop_es is a named
vector or a multiline string.
See the help page on how to specify
this argument.
Set the
values for each label of the effect
size (population value) for product term.
Used only if pop_es is a named
vector or a multiline string.
See the help page on how to specify
this argument.
The names of labels denoting the effect size of an indirect effect. They will be used to determine the population values of the component paths along an indirect path.
Logical. If
TRUE, the default, variances and
error variances are scaled to ensure
the population variances of the
endogenous variables are close to
one, and hence the effect sizes
(population values) are
standardized effect sizes if the
variances of the continuous exogenous
variables are also equal to one.
The sample size used to
determine the error variances by
simulation when std_force_monte_carlo
is TRUE.
Logical.
If FALSE, the default,
standardization is done analytically
if the model has no product terms,
and by simulation if the model has
product terms. That is, error variances
required to ensure implied variances equal
to one are determined by simulation.
If TRUE, simulation
will be used whether the model has
product terms or not. Always fall
back to simulation if
analytical standardization failed.
Logical. If TRUE, the default, for
a model in which one or product terms
for moderation involve one or more
mediator, covariances between their
error terms and the product terms
will be added automatically. If these
covariances are not added, the model
may not be invariant to linear
transformation of some variables in
the model.
It can be a 'lavaan' model
syntax, to be passed to ptable_pop(),
or a parameter table with the column
start set to the population values,
such as the output of ptable_pop().
If x is a model syntax,
these are arguments to be passed to
ptable_pop().
If
TRUE and the number of groups is
equal to one, the output will be
a list of matrices of one group
only. Default if TRUE.
The function ptable_pop() is used by
the all-in-one function
power4test(). Users usually do not
call this function directly, though
developers can use this function to
develop other functions for power
analysis, or to build their own
workflows to do the power analysis.
For a single-group model, model
should be a lavaan model syntax
string of the form of the model.
The population values of the model
parameters are to be determined by
pop_es.
If the model has latent factors,
the syntax in model should specify
only the structural model for the
latent factors. There is no
need to specify the measurement
part. Other functions will generate
the measurement part on top of this
model.
For example, this is a simple mediation model:
"m ~ x
y ~ m + x"Whether m, x, and y denote
observed variables or latent factors
are determined by other functions,
such as power4test().
Because the model is the population
model, equality constraints are
irrelevant and the model syntax
specifies only the form of the
model. Therefore, model is
specified as in the case of single
group models.
The argument pop_es is for specifying
the population values of model
parameters. This section describes
how to do this using named vectors.
If pop_es is specified by a named
vector, it must follow the convention
below.
The names of the vectors are
lavaan names for the selected
parameters. For example, m ~ x
denotes the path from x to m.
Alternatively, the names can be
either ".beta." or ".cov.".
Use ".beta." to set the default
values for all regression coefficients.
Use ".cov." to set the default
values for all correlations of
exogenous variables (e.g., predictors).
The names can also be of this form:
".ind.(<path>)", whether <path>
denote path in the model. For
example, ".ind.(x->m->y)" denotes
the path from x through m to
y. Alternatively, the lavaan
symbol ~ can also be used:
".ind.(y~m~x)". This form is used
to set the indirect effect (standardized,
by default) along this path. The
value for this name will override
other settings.
If using lavaan names, can
specify more than one parameter
using +. For example, y ~ m + x
denotes the two paths from m and
x to y.
The value of each element can be
the label for the effect size: n
for nil, s for small, m for
medium, and l for large. The
value for each label is determined
by es1 and es2. See the section
on specifying these two arguments.
The value of pop_es can also be
set to a value, but it must be
quoted as a string, such as "y ~ x" = ".31".
This is an example:
c(".beta." = "s",
"m1 ~ x" = "-m",
"m2 ~ m1" = "l",
"y ~ x:w" = "s")In this example,
All regression coefficients are
set to small (s) by default, unless
specified otherwise.
The path from x to m1 is
set to medium and negative (-m).
The path from m1 to m2 is set
to large (l).
The coefficient of the product
term x:w when predicting y is
set to small (s).
When setting an indirect effect to
a symbol (default: "si", "mi",
"li", with "i" added to differentiate
them from the labels for a direct path),
the corresponding value is used to
determine the population values of
all component paths along the pathway.
All the values are assumed to be equal.
Therefore, ".ind.(x->m->y)" = ".20"
is equivalent to setting m ~ x
and y ~ m to the square root of
.20, such that the corresponding
indirect effect is equal to the
designated value.
This behavior, though restricted, is for quick manipulation of the indirect effect. If different values along a pathway, set the value for each path directly.
Only nonnegative value is supported.
Therefore, ".ind.(x->m->y)" = "-si"
and ".ind.(x->m->y)" = "-.20" will
throw an error.
The argument pop_es also supports multigroup
models.
For pop_es, instead of
named vectors, named list of
named vectors should be used.
The names are the parameters, or
keywords such as .beta. and
.cov., like specifying the
population values for a single
group model.
The elements are character vectors. If it has only one element (e.g., a single string), then it is the the population value for all groups. If it has more than one element (e.g., a vector of three strings), then they are the population values of the groups. For a model of k groups, each vector must have either k elements or one element.
This is an example:
list("m ~ x" = "m",
"y ~ m" = c("s", "m", "l"))In this model, the population value
of the path m ~ x is medium (m) for
all groups, while the population
values for the path y ~ m are
small (s), medium (m), and large (l),
respectively.
When setting the argument pop_es,
instead of using a named vector
or named list for
pop_es, the population values of
model parameters can also be
specified using a multiline string,
as illustrated below, to be parsed
by pop_es_yaml().
This is an example of the multiline string for a single-group model:
y ~ m: l
m ~ x: m
y ~ x: nilThe string must follow this format:
Each line starts with tag:.
tag can be the name of a
parameter, in lavaan model
syntax format.
For example, m ~ x
denotes the path from x to m.
A tag in lavaan model syntax can
specify more than one parameter
using +.
For example, y ~ m + x
denotes the two paths from m and
x to y.
Alternatively, the tag can be
either .beta. or .cov..
Use .beta. to set the default
values for all regression coefficients.
Use .cov. to set the default
values for all correlations of
exogenous variables (e.g., predictors).
After each tag is the value of the population value:
-nil for nil (zero),
s for small,
m for medium, and
l for large.
si, mi, and li for
small, medium, and large a
standardized indirect effect,
respectively.
Note: n cannot be used in this mode.
The
value for each label is determined
by es1 and es2 as described
in ptable_pop().
The value can also be
set to a numeric value, such as
.30 or -.30.
This is another example:
.beta.: s
y ~ m: lIn this example, all regression
coefficients are small, while
the path from m to y is large.
This is an example of the string for a multigroup model:
y ~ m: l
m ~ x:
- nil
- s
y ~ x: nilThe format is similar to that for
a single-group model. If a parameter
has the same value for all groups,
then the line can be specified
as in the case of a single-group
model: tag: value.
If a parameter has different values across groups, then it must be in this format:
A line starts with the tag, followed
by two or more lines. Each line
starts with a hyphen - and the
value for a group.
For example:
m ~ x:
- nil
- sThis denotes that the model has
two groups. The values of the path
from x to m for the two
groups are 0 (nil) and
small (s), respectively.
Another equivalent way to specify
the values are using [], on
the same line of a tag.
For example:
m ~ x: [nil, s]The number of groups is inferred from the number of values for a parameter. Therefore, if a tag has more than one value, each tag must has the same number of value, or only one value.
The tag .beta. and .cov. can
also be used for multigroup models.
Note that using named vectors or named lists is more reliable. However, using a multiline string is more user-friendly. If this method failed, please use named vectors or named list instead.
The multiline string is parsed by yaml::read_yaml().
Therefore, the format requirement
is actually that of YAML. Users
knowledgeable of YAML can use other
equivalent way to specify the string.
The vector es1 is for correlations,
regression coefficients, and
indirect effect, and the
vector es2 is for for standardized
moderation effect, the coefficients
of a product term. These labels
are to be used in interpreting
the specification in pop_es.
The function model_matrices_pop()
generates models matrices with
population values, used by ptable_pop().
Users usually do not
call this function directly, though
developers can use this build their own
workflows to generate the data.
The function ptable_pop() generates a lavaan
parameter table that can be used
to generate data based on the population
values of model parameters.
power4test(), and
pop_es_yaml() on an alternative
way to specify population values.
# Specify the model
model1 <-
"
m1 ~ x + c1
m2 ~ m1 + x2 + c1
y ~ m2 + m1 + x + w + x:w + c1
"
# Specify the population values
model1_es <- c("m1 ~ x" = "-m",
"m2 ~ m1" = "s",
"y ~ m2" = "l",
"y ~ x" = "m",
"y ~ w" = "s",
"y ~ x:w" = "s",
"x ~~ w" = "s")
ptable_final1 <- ptable_pop(model1,
pop_es = model1_es)
ptable_final1
# Use a multiline string, illustrated by a simpler model
model2 <-
"
m ~ x
y ~ m + x
"
model2_es_a <- c("m ~ x" = "s",
"y ~ m" = "m",
"y ~ x" = "nil")
model2_es_b <-
"
m ~ x: s
y ~ m: m
y ~ x: nil
"
ptable_model2_a <- ptable_pop(model2,
pop_es = model2_es_a)
ptable_model2_b <- ptable_pop(model2,
pop_es = model2_es_b)
ptable_model2_a
ptable_model2_b
identical(ptable_model2_a,
ptable_model2_b)
# model_matrices_pop
model_matrices_pop(ptable_final1)
model_matrices_pop(model1,
pop_es = model1_es)
Run the code above in your browser using DataLab