The test function (test_fun)
The function set to test_fun,
the test function, usually
should work
on the output of lavaan::sem(),
lmhelprs::many_lm(), or
stats::lm(), but can also be a
function that works on the output
of the function set to fit_function
when calling fit_model() or
power4test() (see fit_model_args).
The function has two default
requirements.
First, it has an argument fit, to
be set to the output of
lavaan::sem() or another output
stored in the element extra$fit of
a replication in the sim_all
object. (This requirement can be
relaxed; see the section on map_names.)
That is, the function definition
should be of this from: FUN(fit, ...). This is the form of all
test_* functions in power4mome.
If other arguments are to be passed
to the test function, they can be set
to test_args as a named list.
Second, the test function must
returns an output that (a) can be
processed by the results function
(see below), or (b) is of
the required format for the output of
a results function (see the next
section). If it already returns
an output of the required format,
then there is no need to set the
results function.
The results function (results_fun)
The test results will be extracted
from the output of test_fun by the
function set to results_fun,
the results function. If
the test_fun already returns an
output of the expected format
(see below), then set results_fun
to NULL, the default. The output
of test_fun will be used for
estimating power.
The function set to results_fun
must accept the output of test_fun,
as the first argument, and return a
named list (which can be a data frame)
or a named vector with some
of the following
elements:
est: Optional. The estimate of a
parameter, if applicable.
se: Optional. The standard error
of the estimate, if applicable.
cilo: Optional. The lower limit of the
confidence interval, if applicable.
cihi: Optional. The upper limit of the
confidence interval, if applicable.
sig: Required. If 1, the test is
significant. If 0, the test is not
significant. If the test cannot be
done for any reason, it should be
NA.
The results can then be used to
estimate the power or Type I
error of the test.
For example, if
the null hypothesis is false, then
the proportion of significant, that
is, the mean of the values of sig
across replications, is the power.
Built-in test functions
The package power4mome has some ready-to-use
test functions:
Please refer to their help pages
for examples.
The argument map_names
This argument is for developers using
a test function that has a different
name for the argument of the fit
object ("fit", the default).
If test_fun is set to a function
that works on an output of, say,
lavaan::sem() but the argument name
for the output is not fit, the
mapping can be changed by
map_names.
For example,
lavaan::parameterEstimates()
receives an output of lavaan::sem()
and reports the test results of model
parameters. However, the argument
name for the lavaan output is
object. To instruct do_test() to
do the test correctly when setting
test_fun to
lavaan::parameterEstimates, add
map_names = c(object = "fit"). The
element fit in a replication will
then set to the argument object of
lavaan::parameterEstimates().