---
output: github_document
---
<!-- markdownlint-disable-file -->
<!-- README.md needs to be generated from README.Rmd. Please edit that file -->

# mmrm  <img src="man/figures/logo.svg" align="right" width="175" />

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

<!-- badges: start -->
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![CRAN status](https://www.r-pkg.org/badges/version-last-release/mmrm)](https://www.r-pkg.org/badges/version-last-release/mmrm)
[![CRAN monthly downloads](https://cranlogs.r-pkg.org/badges/mmrm)](https://cranlogs.r-pkg.org/badges/mmrm)
[![CRAN total downloads](https://cranlogs.r-pkg.org/badges/grand-total/mmrm)](https://cranlogs.r-pkg.org/badges/grand-total/mmrm)
[![Code Coverage](https://raw.githubusercontent.com/openpharma/mmrm/_xml_coverage_reports/data/main/badge.svg)](https://openpharma.github.io/mmrm/latest-tag/coverage-report/)
<!-- badges: end -->
\

Mixed models for repeated measures (MMRM) are a popular
choice for analyzing longitudinal continuous outcomes in randomized
clinical trials and beyond; see
[Cnaan, Laird and Slasor (1997)](https://doi.org/10.1002%2f%28SICI%291097-0258%2819971030%2916%3a20%3c2349%3a%3aAID-SIM667%3e3.0.CO%3b2-E)
for a tutorial and
[Mallinckrodt, Lane and Schnell (2008)](https://doi.org/10.1177/009286150804200402)
for a review. This package implements
MMRM based on the marginal linear model without random effects using
Template Model Builder (`TMB`) which enables fast and robust model
fitting. Users can specify a variety of covariance matrices, weight
observations, fit models with restricted or standard maximum
likelihood inference, perform hypothesis testing with Satterthwaite
or Kenward-Roger adjustment, and extract least
square means estimates by using `emmeans`.

**Scope:**

* Continuous responses with normal (but potentially heteroscedastic) residuals.
* Marginal linear models (no individual-level random effects).

**Main Features:**

* Flexible covariance specification:
  * [Structures](https://openpharma.github.io/mmrm/main/articles/covariance.html): unstructured, Toeplitz, AR1, compound symmetry, ante-dependence, and spatial exponential.
  * Groups: shared covariance structure for all subjects or group-specific
covariance estimates.
  * Variances: homogeneous or heterogeneous across time points.
* Inference:
  * Supports REML and ML.
  * Supports weights.
* Hypothesis testing:
  * [Least square means](https://openpharma.github.io/mmrm/main/reference/emmeans_support.html):
    can be obtained with the `emmeans` package
  * One- and multi-dimensional linear contrasts of model parameters can be tested.
  * [Satterthwaite](https://openpharma.github.io/mmrm/main/articles/satterthwaite.html)
    adjusted degrees of freedom.
  * [Kenward-Roger](https://openpharma.github.io/mmrm/main/articles/kenward.html)
    adjusted degrees of freedom and coefficients covariance matrix.
  * [Coefficient Covariance](https://openpharma.github.io/mmrm/main/articles/coef_vcov.html)
* `C++` backend:
  * Fast implementation using `C++` and automatic differentiation to
    obtain precise gradient information for model fitting.
  * Model fitting algorithm [details](https://openpharma.github.io/mmrm/main/articles/algorithm.html) used in `mmrm`.
* Package ecosystems integration:
  * Integration with [tidymodels](https://www.tidymodels.org/) package ecosystem
    * Dedicated [parsnip](https://parsnip.tidymodels.org/) engine for linear regression
    * Integration with [recipes](https://recipes.tidymodels.org/)
  * Integration with [tern](https://insightsengineering.github.io/tern/) package ecosystems
    * The [tern.mmrm](https://insightsengineering.github.io/tern.mmrm/) package can be used to run the `mmrm` fit and generate tabulation and plots of least square means per visit and treatment arm, tabulation of model diagnostics, diagnostic graphs, and other standard model outputs.

## Installation

### Release

You can install the current release version from *CRAN* with:

```{r cran-installation, eval = FALSE}
install.packages("mmrm")
```

### Development

You can install the current development version from *R-Universe* with:

```{r ru-installation, eval = FALSE}
install.packages(
  "mmrm",
  repos = c("https://openpharma.r-universe.dev", "https://cloud.r-project.org")
)
```

This is preferred, because for Windows and MacOS systems you can install
pre-compiled binary versions of the packages, avoiding the need for compilation.

Alternatively, you can install the current development version from
*GitHub* with:

```{r gh-installation, eval = FALSE}
if (!require("remotes")) {
  install.packages("remotes")
}
remotes::install_github("openpharma/mmrm")
```

Note that this installation from source can take a substantial amount of time,
because compilation of the `C++` sources is required.

## Getting Started

See also the [introductory vignette](https://openpharma.github.io/mmrm/main/articles/introduction.html)
or get started by trying out the example:

```{r, child='vignettes/subsections/_intro-getting_started.Rmd'}
```

## Citing `mmrm`

To cite `mmrm` please see [here](https://openpharma.github.io/mmrm/main/authors.html#citation).
