---
output:
  md_document:
    variant: markdown_github
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-"
)
```

# powerlmm
[![Travis-CI Build Status](https://travis-ci.org/rpsychologist/powerlmm.svg?branch=master)](https://travis-ci.org/rpsychologist/powerlmm)
[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/powerlmm)](https://cran.r-project.org/package=powerlmm)

Power Analysis for Longitudinal Multilevel/Linear Mixed-Effects Models.

## Overview
The purpose of `powerlmm` is to help design longitudinal treatment studies (parallel groups), with
or without higher-level clustering (e.g. longitudinally clustered by therapists, 
groups, or physician), and missing data. The main features of the package are:

* Longitudinal two- and three-level (nested) linear mixed-effects models, and partially nested designs.
* Random slopes at the subject- and cluster-level. 
* Missing data.
* Unbalanced designs (both unequal cluster sizes, and treatment groups).
* Design effect, and estimated type I error when the third-level is ignored.
* Fast analytical power calculations for all designs.
* Power for small samples sizes using Satterthwaite's degrees of freedom approximation.
* Explore bias, Type I errors, model misspecification, and LRT model selection 
  using convenient simulation methods.

## Installation
`powerlmm` can be installed from CRAN and GitHub. 
```{r, eval = FALSE}
# CRAN, version 0.4.0
install.packages("powerlmm")

# GitHub, dev version
devtools::install_github("rpsychologist/powerlmm")
```

## Example usage
This is an example of setting up a three-level longitudinal model with random slopes at both the subject- 
and cluster-level, with different missing data patterns per treatment arm. Relative standardized inputs are used,
but unstandardized raw parameters values can also be used. 

```{r three-level-setup, fig.width=9}
library(powerlmm)
d <- per_treatment(control = dropout_weibull(0.3, 2),
               treatment = dropout_weibull(0.2, 2))
p <- study_parameters(n1 = 11,
                      n2 = 10,
                      n3 = 5,
                      icc_pre_subject = 0.5,
                      icc_pre_cluster = 0,
                      icc_slope = 0.05,
                      var_ratio = 0.02,
                      dropout = d,
                      effect_size = cohend(-0.8, 
                                           standardizer = "pretest_SD"))

p
```

```{r, eval=FALSE}
plot(p)
```
![](http://rpsychologist.com/img/powerlmm/README-three-level-setup-1.png)

```{r three-level-power, message= FALSE, warning=FALSE}
get_power(p, df = "satterthwaite")
```

### Unequal cluster sizes
Unequal cluster sizes is also supported, the cluster sizes can either be random (sampled), or the marginal distribution can be specified. 

```{r three-level-power-unequal, message= FALSE, warning=FALSE}
p <- study_parameters(n1 = 11,
                      n2 = unequal_clusters(2, 3, 5, 20),
                      icc_pre_subject = 0.5,
                      icc_pre_cluster = 0,
                      icc_slope = 0.05,
                      var_ratio = 0.02,
                      effect_size = cohend(-0.8, 
                                           standardizer = "pretest_SD"))

get_power(p)
```

Cluster sizes follow a Poisson distribution
```{r three-level-power-unequal-random, message= FALSE, warning=FALSE}
p <- study_parameters(n1 = 11,
                      n2 = unequal_clusters(func = rpois(5, 5)), # sample from Poisson
                      icc_pre_subject = 0.5,
                      icc_pre_cluster = 0,
                      icc_slope = 0.05,
                      var_ratio = 0.02,
                      effect_size = cohend(-0.8, 
                                           standardizer = "pretest_SD"))

get_power(p, R = 100, progress = FALSE) # expected power by averaging over R realizations
```

### Convenience functions
Several convenience functions are also included, e.g. for creating power curves.

```{r three-level-power-curve, eval = FALSE}
x <- get_power_table(p, 
                     n2 = 5:10, 
                     n3 = c(4, 8, 12), 
                     effect_size = cohend(c(0.5, 0.8), standardizer = "pretest_SD"))
```

```{r, eval = FALSE}
plot(x)
```
![](http://rpsychologist.com/img/powerlmm/README-three-level-power-curve-1.png)

## Simulation
The package includes a flexible simulation method that makes it easy to investigate the performance of different models. As an example, let's compare the power difference
between the 2-level LMM with 11 repeated measures, to doing an ANCOVA at posttest. Using `sim_formula` different models can be fit to the same data set during the simulation.
```{r}
p <- study_parameters(n1 = 11,
                      n2 = 40, 
                      icc_pre_subject = 0.5,
                      cor_subject = -0.4,
                      var_ratio = 0.02,
                      effect_size = cohend(-0.8, 
                                           standardizer = "pretest_SD"))

# 2-lvl LMM
f0 <- sim_formula("y ~ time + time:treatment + (1 + time | subject)")

# ANCOVA, formulas with no random effects are with using lm()
f1 <- sim_formula("y ~ treatment + pretest", 
                  data_transform = transform_to_posttest, 
                  test = "treatment")

f <- sim_formula_compare("LMM" = f0, 
                         "ANCOVA" = f1)

res <- simulate(p, 
                nsim = 2000, 
                formula = f, 
                cores = parallel::detectCores(logical = FALSE))
```

We then summarize the results using `summary`. Let's look specifically at the treatment effects.

```{r}
summary(res, para = list("LMM" = "time:treatment",
                         "ANCOVA" = "treatment"))
```


We can also look at a specific model, here's the results for the 2-lvl LMM.

```{r}
summary(res, model = "LMM")
```


## Launch interactive web application
The package's basic functionality is also implemented in a Shiny web application, 
aimed at users that are less familiar with R. Launch the application by typing
```{r, eval = FALSE}
library(powerlmm)
shiny_powerlmm()
```

![](http://rpsychologist.com/img/powerlmm/README-shiny-screenshot1.png)

![](http://rpsychologist.com/img/powerlmm/README-shiny-screenshot2.png)
