study_parameters: Setup study parameters
In powerlmm: Power Analysis for Longitudinal Multilevel Models

Description Usage Arguments Details Value See Also Examples

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.

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)

`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.

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.

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

cohend, get_power, simulate.plcp

# 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)

     Power Analyis for Longitudinal Linear Mixed-Effects Models (three-level)
                  with missing data and unbalanced designs 

              n1 = 11
              n2 = 5 x 4 (treatment)
                   5 x 4 (control)
              n3 = 4     (treatment)
                   4     (control)
                   8     (total)
         total_n = 20    (control)
                   20    (treatment)
                   40    (total)
         dropout = No missing data
icc_pre_subjects = 0.5
icc_pre_clusters = 0
       icc_slope = 0.05
       var_ratio = 0.03
     effect_size = -0.8 (Cohen's d [SD: pretest_SD])
              df = 6
           alpha = 0.05
           power = 30%


     Power Analyis for Longitudinal Linear Mixed-Effects Models (three-level)
                  with missing data and unbalanced designs 

              n1 = 11
              n2 = 5 x 4 (treatment)
                   5 x 4 (control)
              n3 = 4     (treatment)
                   4     (control)
                   8     (total)
         total_n = 20    (control)
                   20    (treatment)
                   40    (total)
         dropout = No missing data
icc_pre_subjects = 0.5
icc_pre_clusters = 0
       icc_slope = 0.05
       var_ratio = 0.03
     effect_size = -0.8 (Cohen's d [SD: pretest_SD])
              df = 6
           alpha = 0.05
           power = 30%


     Power Analyis for Longitudinal Linear Mixed-Effects Models (three-level)
                  with missing data and unbalanced designs 

              n1 = 11
              n2 = 5 x 4 (treatment)
                   5 x 4 (control)
              n3 = 4     (treatment)
                   4     (control)
                   8     (total)
         total_n = 20    (control)
                   20    (treatment)
                   40    (total)
         dropout = No missing data
icc_pre_subjects = 0.54
icc_pre_clusters = 0.07
       icc_slope = 0.05
       var_ratio = 0.03
     effect_size = -0.8 (Cohen's d [SD: pretest_SD])
              df = 6
           alpha = 0.05
           power = 32%


     Power Analysis for Longitudinal Linear Mixed-Effects Models
            with missing data and unbalanced designs 

              n1 = 11
              n2 = 40 (treatment)
                   40 (control)
                   80 (total)
         dropout = No missing data
icc_pre_subjects = 0.5
       var_ratio = 0.03
     effect_size = -0.8 (Cohen's d [SD: pretest_SD])
              df = 78
           alpha = 0.05
           power = 71 %


     Power Analysis for Longitudinal Linear Mixed-Effects Models
            with missing data and unbalanced designs 

              n1 = 11
              n2 = 40 (treatment)
                   40 (control)
                   80 (total)
         dropout =  0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10 (time)
                    0,  2,  4,  6,  9, 11, 13, 14, 16, 18, 20 (%, control)
                    0,  2,  4,  6,  9, 11, 13, 14, 16, 18, 20 (%, treatment)
icc_pre_subjects = 0.5
       var_ratio = 0.03
     effect_size = -0.8 (Cohen's d [SD: pretest_SD])
              df = 78
           alpha = 0.05
           power = 66 %

# Power Analysis for Longitudinal Linear Mixed-Effect Models

   n1     n2 dropout icc_pre_subject icc_pre_cluster icc_slope var_ratio
1  11  5 x 2       0             0.5               0         0      0.03
2   . 10 x 2       .               .               .         .         .
3   .  5 x 4       .               .               .         .         .
4   . 10 x 4       .               .               .         .         .
5   .  5 x 2       .               .               .      0.05         .
6   . 10 x 2       .               .               .         .         .
7   .  5 x 4       .               .               .         .         .
8   . 10 x 4       .               .               .         .         .
9   .  5 x 2       .               .               .         0         .
10  . 10 x 2       .               .               .         .         .
11  .  5 x 4       .               .               .         .         .
12  . 10 x 4       .               .               .         .         .
13  .  5 x 2       .               .               .      0.05         .
14  . 10 x 2       .               .               .         .         .
15  .  5 x 4       .               .               .         .         .
16  . 10 x 4       .               .               .         .         .
   effect_size df  power
1         -0.5  2  7.9 %
2            .  2 10.7 %
3            .  6   16 %
4            .  6 27.2 %
5            .  2  7.5 %
6            .  2  9.3 %
7            .  6 14.5 %
8            .  6 21.5 %
9         -0.8  2 12.3 %
10           .  2   19 %
11           .  6 33.2 %
12           .  6 57.3 %
13           .  2 11.4 %
14           .  2 15.6 %
15           .  6 29.6 %
16           .  6 45.8 %
---
# alpha = 0.05; DFs = between; R = 1