powerlmm (version 0.4.0)

study_parameters: Setup study parameters

Description

Setup the parameters for calculating power for longitudinal multilevel studies comparing two groups. Ordinary two-level models (subjects with repeated measures), and longitudinal three-level models with clustering due to therapists, schools, provider etc, are supported. Random slopes at the subject level and cluster level are possible. Cluster sizes can be unbalanced, and vary by treatment. Partially nested designs are supported. Missing data can also be accounted for.

Usage

study_parameters(n1, n2, n3 = 1, T_end = NULL, fixed_intercept = 0L,
  fixed_slope = 0L, sigma_subject_intercept = NULL,
  sigma_subject_slope = NULL, sigma_cluster_intercept = NULL,
  sigma_cluster_slope = NULL, sigma_error = 10, cor_subject = 0L,
  cor_cluster = 0L, cor_within = 0L, var_ratio = NULL,
  icc_slope = NULL, icc_pre_subject = NULL, icc_pre_cluster = NULL,
  effect_size = 0L, cohend = NULL, partially_nested = FALSE,
  dropout = 0L, deterministic_dropout = TRUE)

Arguments

n1

Number of level 1 units, e.g. measurements per subject.

n2

Number of level 2 units per level 3 unit, e.g. subjects per cluster. Unbalanced cluster sizes are supported, see unequal_clusters.

n3

Number of level 3 units per treatment, can be different in each treatment arm, see per_treatment.

T_end

Time point of the last measurement. If NULL it will be set to n1 - 1.

fixed_intercept

Average baseline value, assumed to be equal for both groups.

fixed_slope

Overall change per unit time, in the control group.

sigma_subject_intercept

Subject-level random intercept.

sigma_subject_slope

Subject-level random slope.

sigma_cluster_intercept

Cluster-level random intercept.

sigma_cluster_slope

Cluster-level random slope.

sigma_error

Within-subjects (residual) variation.

cor_subject

Correlation between the subject-level random intercept and slopes.

cor_cluster

Correlation between the cluster-level random intercept and slopes.

cor_within

Correlation of the level 1 residual. Currently ignored in the analytical power calculations.

var_ratio

Ratio of the random slope variance to the within-subject variance.

icc_slope

Proportion of slope variance at the cluster level.

icc_pre_subject

Amount of baseline variance at the subject level. N.B. the variance at the subject-level also included the cluster-level variance. If there's no random slopes, this would be the subject-level ICC, i.e. correlation between time points.

icc_pre_cluster

Amount of baseline variance at the cluster level.

effect_size

The treatment effect. Either a numeric indicating the mean difference (unstandardized) between the treatments at posttest, or a standardized effect using the cohend helper function.

cohend

Deprecated; now act as a shortcut to cohend helper function. Equivalent to using effect_size = cohend(cohend, standardizer = "pretest_SD", treatment = "control")

partially_nested

logical; indicates if there's clustering in both arms or only in the treatment arm.

dropout

Dropout process, see dropout_weibull or dropout_manual. Assumed to be 0 if NULL.

deterministic_dropout

logical; if FALSE the input to dropout will be treated as random and dropout will be sampled from a multinomial distribution. N.B.: the random dropout will be sampled independently in both treatment arms.

Value

A list or data.frame of parameters values, either of class plcp or plcp_multi if multiple parameters are compared.

Details

Comparing a combination of parameter values

It is possible to setup a grid of parameter combinations by entering the values as vectors. All unique combinations of the inputs will be returned. This is useful if you want see how different values of the parameters affect power. See also the convenience function get_power_table.

Standardized and unstandardized inputs

All parameters of the models can be specified. However, many of the raw parameter values in a multilevel/LMM do no directly affect the power of the test of the treatment:time-coefficient. Power will depend greatly on the relative size of the parameters, therefore, it is possible to setup your calculations using only standardized inputs, or by a combination of raw inputs and standardized inputs. For instance, if sigma_subject_slope and icc_slope is specified, the sigma_cluster_slope will be solved for. Only the cluster-level parameters can be solved when standardized and raw values are mixed. sigma_error is 10 by default. More information regarding the standardized inputs are available in the two-level and three-level vignettes.

Difference between 0 and NA

For the variance components 0 and NA/NULL have different meanings. A parameter that is 0 is still kept in the model, e.g. if icc_pre_cluster = 0 a random intercept is estimated at the cluster level, but the true value is 0. If the argument is either NULL or NA it is excluded from the model. This choice will matter when running simulations, or if Satterthwaite dfs are used.

The default behavior if a parameters is not specified is that cor_subject and cor_cluster is 0, and the other variance components are NULL.

Effect size and Cohen's d

The argument effect_size let's you specify the average difference in change between the treatment groups. You can either pass a numeric value to define the raw difference in means at posttest, or use a standardized effect size, see cohend for more details on the standardized effects.

The argument cohend is kept for legacy reasons, and is equivalent to using effect_size = cohend(cohend, standardizer = "pretest_SD", treatment = "control").

Two- or three-level models

If either sigma_cluster_slope or icc_slope and sigma_cluster_intercept or icc_pre_cluster is NULL it will be assumed a two-level design is wanted.

Unequal cluster sizes and unbalanced allocation

It is possible to specify different cluster sizes using unequal_clusters. Cluster sizes can vary between treatment arms by also using per_treatment. The number of clusters per treatment can also be set by using per_treatment. Moreover, cluster sizes can be sampled from a distribution, and treated as a random variable. See per_treatment and unequal_clusters for examples of their use.

Missing data and dropout

Accounting for missing data in the power calculations is possible. Currently, dropout can be specified using either dropout_weibull or dropout_manual. It is possible to have different dropout patterns per treatment group using per_treatment. See their respective help pages for examples of their use.

If deterministic_dropout = TRUE then the proportion of dropout is treated is fixed. However, exactly which subjects dropout is randomly sampled within treatments. Thus, clusters can become slightly unbalanced, but generally power varies little over realizations.

For random dropout, deterministic_dropout = FALSE, the proportion of dropout is converted to the probability of having exactly i measurements, and the actual dropout is sampled from a multinomial distribution. In this case, the proportion of dropout varies over the realizations from the multinomial distribution, but will match the dropout proportions in expectation. The random dropout in each treatment group is sampled from independent multinomial distributions.

Generally, power based on fixed dropout is a good approximation of random dropout.

See Also

cohend, get_power, simulate.plcp

Examples

# NOT RUN {
# Three level model with both subject- and cluster-level random slope
# Power calculation using standardized inputs
p <- study_parameters(n1 = 11,
                      n2 = 5,
                      n3 = 4,
                      icc_pre_subject = 0.5,
                      icc_pre_cluster = 0,
                      var_ratio = 0.03,
                      icc_slope = 0.05,
                      effect_size = cohend(-0.8))

get_power(p)

# The same calculation with all parameters specified directly
p <- study_parameters(n1 = 11,
                      n2 = 5,
                      n3 = 4,
                      T_end = 10,
                      fixed_intercept = 37,
                      fixed_slope = -0.65,
                      sigma_subject_intercept = 2.8,
                      sigma_subject_slope = 0.4726944,
                      sigma_cluster_intercept = 0,
                      sigma_cluster_slope = 0.1084435,
                      sigma_error = 2.8,
                      cor_subject = -0.5,
                      cor_cluster = 0,
                      effect_size = cohend(-0.8))
get_power(p)

# Standardized and unstandardized inputs
p <- study_parameters(n1 = 11,
                      n2 = 5,
                      n3 = 4,
                      sigma_subject_intercept = 2.8,
                      icc_pre_cluster = 0.07,
                      sigma_subject_slope = 0.47,
                      icc_slope = 0.05,
                      sigma_error = 2.8,
                      effect_size = cohend(-0.8))

get_power(p)

## Two-level model with subject-level random slope
p <- study_parameters(n1 = 11,
                      n2 = 40,
                      icc_pre_subject = 0.5,
                      var_ratio = 0.03,
                      effect_size = cohend(-0.8))
get_power(p)

# add missing data
p <- update(p, dropout = dropout_weibull(0.2, 1))
get_power(p)

## Comparing a combination of values
p <- study_parameters(n1 = 11,
                      n2 = c(5, 10),
                      n3 = c(2, 4),
                      icc_pre_subject = 0.5,
                      icc_pre_cluster = 0,
                      var_ratio = 0.03,
                      icc_slope = c(0, 0.05),
                      effect_size = cohend(c(-0.5, -0.8))
                      )

get_power(p)
# }