power_analysis: Conduct a Power Analysis Based on `mp_model`

Description

This function will construct a multilevel power analysis via a Monte Carlo Simulation based on a constructed mp_model.

Usage

power_analysis(model, replications, n_within, n_between, ...)

Value

A mp_power object that contains the results. See print.mp_power for more information. The object has the following slots:

sim: The information about the simulation
power: The power power results per condition.
estimates: The simulation summaries of the parameter estimates per condition.
mean_parameters: The average population parameter per condition.

Arguments

model: a mp_model.
replications: a single positive integer of the number of replications per condition.
n_within: an integer vector of the desired within cluster observations.
n_between: an integer vector of the desired between cluster observations.
...: other arguments passed to analyze().

Details

Specifying multiple n_within and n_between will produce a full factorial simulation design.

Specify a mechanism argument to pass down to the generate function. See the details of generate for more information about specifying missing data mechanisms. See mechanisms for predefined missing data mechanisms.

Specify an analyze argument to use custom analysis functions. These functions should map onto analyze's structure, but can allow for things like specifying multiple imputations etc. This is considered an advance usage that requires extreme care and caution.

Examples

Run this code

# Create Model
model <- (
    outcome('Y')
    + within_predictor('X')
    + effect_size(icc = 0.1)
)
# Set seed
set.seed(19723)
# Create data set and analyze
# Note: Generally Use more than 50 replications
model |> power_analysis(50, 5, 50)

# Induce missing data on outcome with built in mechanisms
set.seed(19723)
model |> power_analysis(50, 5, 50, mechanism = MCAR(0.25)) -> powersim_mcar