sim_apply()
applies a function, FUN
, to each set of simulated
coefficients, similar to apply()
. This function should return a numeric
vector containing one or more estimated quantities. This should be a named
vector to more easily keep track of the meaning of each estimated quantity.
Care should be taken to ensure that the returned vector is the same length
each time FUN
is called. NA
s are allowed in the output but should be
avoided if possible.
The arguments to FUN
can be specified in a few ways. If FUN
has an
argument called coefs
, a simulated set of coefficients will be passed to
this argument, and FUN
should compute and return a quantity based on the
coefficients (e.g., the difference between two coefficients if one wants to
test whether two coefficients are equal). If FUN
has an argument called
fit
, a model fit object of the same type as the one originally supplied
to sim()
(e.g., an lm
or glm
object) will be passed to this argument,
where the coefficients of the fit object have been replaced by the
simulated coefficients generated by sim()
, and FUN
should compute and
return a quantity based on the model fit (e.g., a computation based on the
output of predict()
). If neither coefs
nor fit
are the names of
arguments to FUN
, the model fit object with replaced coefficients will be
supplied to the first argument of FUN
.
When custom coefficients are supplied to sim()
, i.e., when the coefs
argument to sim()
is not left at its default value, FUN
must accept a
coefs
argument and a warning will be thrown if it accepts a fit
argument. This is because sim_apply()
does not know how to reconstruct
the original fit object with the new coefficients inserted. The quantities
computed by sim_apply()
must therefore be computed directly from the
coefficients.
If FUN
is not supplied at all, the simulated values of the coefficients will be returned in the output with a warning. Set FUN
to NULL
or verbose
to FALSE
to suppress this warning.
sim_apply()
with multiply imputed data
When using misim()
and sim_apply()
with multiply imputed data, the
coefficients are supplied to the model fit corresponding to the imputation
identifier associated with each set of coefficients, which means if FUN
uses a dataset extracted from a model (e.g., using insight::get_data()
), it will do so from the model fit in
the corresponding imputation.
The original estimates (see Value below) are computed as the mean of the
estimates across the imputations using the original coefficients averaged
across imputations. That is, first, the coefficients estimated in the
models in the imputed datasets are combined to form a single set of pooled
coefficients; then, for each imputation, the quantities of interest are
computed using the pooled coefficients; finally, the mean of the resulting
estimates across the imputations are taken as the "original" estimates.
Note this procedure is only valid for quantities with symmetric sampling
distributions, which excludes quantities like risk ratios and odds ratios,
but includes log risk ratios and log odds ratios. The desired quantities
can be transformed from their log versions using
transform()
.