powerlmm (version 0.4.0)

get_power: Calculate power for two- and three-level models with missing data.

Description

Calculate power for two- and three-level models with missing data.

Usage

get_power(object, df = "between", alpha = 0.05, progress = TRUE,
  R = 1L, cores = 1L, ...)

Arguments

object

An object created by study_parameters

df

Either "between" or, "satterth" for Satterthwaite's DF approximation. Also accepts a numeric value which will be used as DF.

alpha

The alpha level, defaults to 0.05.

progress

logical; displays a progress bar when > 1 power analysis is performed.

R

An integer indicating how many realizations to base power on. Useful when dropout or cluster sizes are sampled (i.e. are random variables).

cores

An integer indicating how many CPU cores to use.

...

Other potential arguments; currently used to pass progress bar from Shiny

Value

a list or data.frame depending if power is calculated for a single set of parameters or a combination of multiple values. Has class plcp_power_3lvl for fully- and partially nested three-level designs, and class plcp_power_2lvl for two-level designs.

Details

Calculation of the standard errors

Designs with equal cluster sizes, and with no missing data, uses standard closed form equations to calculate standard errors. Designs with missing data or unequal cluster sizes uses more computationally intensive linear algebra solutions.

To see a more detailed explanation of the calculations, type vignette("technical", package = "powerlmm").

Degrees of freedom

Power is calculated using the t distribution with non-centrality parameter \(b/se\), and dfs are either based on a the between-subjects or between-cluster dfs, or using Satterthwaite's approximation. For the "between" method, \(N_3 - 2\) is used for three-level models, and \(N_2 - 2\) for two-level models, where \(N_3\) and \(N_2\) is the total number of clusters and subjects in both arms.

N.B Satterthwaite's method will be RAM and CPU intensive for large sample sizes. The computation time will depend mostly on n1 and n2. For instance, for a fully nested model with n1 = 10, n2 = 100, n3 = 4, computations will likely take 30-60 seconds.

Cluster sizes or dropout pattern that are random (sampled)

If deterministic_dropout = FALSE the proportion that dropout at each time point will be sampled from a multinomial distribution. However, if it is TRUE, the proportion of subjects that dropout will be non-random, but which subjects dropout will still be random. Both scenarios often lead to small variations in the estimated power. Moreover, using cluster sizes that are random, unequal_clusters(func = ...), can lead to large variations in power for a single realization of cluster sizes. In both scenarios the expected power can be calculated by repeatedly recalculating power for different new realizations of the random variables. This is done be using the argument R -- power, sample size, and DFs, is then reported by averaging over the R realizations.

If power varies over the R realization then the Monte Carlo SE is also reported. The SE is based on the normal approximation, i.e. sd(power_i)/sqrt(R).

See Also

study_parameters, simulate.plcp, get_power_table

Examples

# NOT RUN {
# Two-level model
paras <- study_parameters(n1 = 11,
                          n2 = 40,
                          T_end = 10,
                          icc_pre_subject = 0.5,
                          var_ratio = 0.02,
                          cohend = -0.8)

get_power(paras)

# With missing data
paras <- study_parameters(n1 = 11,
                          n2 = 40,
                          T_end = 10,
                          icc_pre_subject = 0.5,
                          var_ratio = 0.02,
                          dropout = dropout_weibull(0.3, 2),
                          cohend = -0.8)


get_power(paras)


# Three-level model
paras <- study_parameters(n1 = 11,
                          n2 = 10,
                          n3 = 5,
                          T_end = 10,
                          icc_pre_subject = 0.5,
                          icc_pre_cluster = 0,
                          icc_slope = 0.05,
                          var_ratio = 0.02,
                          cohend = -0.8)

get_power(paras)

# With missing data
paras <- study_parameters(n1 = 11,
                          n2 = 10,
                          n3 = 5,
                          T_end = 10,
                          icc_pre_subject = 0.5,
                          icc_pre_cluster = 0,
                          icc_slope = 0.05,
                          var_ratio = 0.02,
                          dropout = dropout_weibull(0.3, 2),
                          cohend = -0.8)

get_power(paras)

# Satterthwaite DFs
get_power(paras, df = "satterthwaite")
# }