README.Rmd

---
output: 
  github_document:
    # toc: true
---

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

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = NA,
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

<img src="man/figures/package_logo.png" style="margin: 0 auto; width: 120px; valign: top" align = 'right'  alt="mixedup Logo" width = 120><br>

# mixedup 

##### a package for extracting clean results from mixed models 

<br>
<br>

<!-- badges: start -->

[![Codecov test coverage](https://codecov.io/gh/m-clark/mixedup/branch/master/graph/badge.svg)](https://codecov.io/gh/m-clark/mixedup?branch=master)
[![R-CMD-check](https://github.com/m-clark/mixedup/actions/workflows/check-standard.yaml/badge.svg)](https://github.com/m-clark/mixedup/actions/workflows/check-standard.yaml)
[![pkgdown](https://github.com/m-clark/mixedup/actions/workflows/pkgdown.yaml/badge.svg)](https://github.com/m-clark/mixedup/actions/workflows/pkgdown.yaml)
[![test-coverage](https://github.com/m-clark/mixedup/actions/workflows/test-coverage.yaml/badge.svg)](https://github.com/m-clark/mixedup/actions/workflows/test-coverage.yaml)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- badges: end -->



This package provides extended functionality for mixed models. The goal of `mixedup` is to solve little problems I have had that slip through the cracks from the various modeling packages and others in trying to get presentable output.  Basically the idea is to create (tidy) objects that are easy to use and essentially ready for presentation, as well as *consistent* across packages and across functions.  Such objects would be things like  variance components and random effects.  I use several of these packages (including mgcv) for mixed models, and typically have to do some notable post processing to get some viable output even with `broom::tidy`, and this effort often isn't applicable if I switch to another package for the same type of model.  These functions attempt to address this issue.

For more details and examples see https://m-clark.github.io/mixedup/.


## Installation

You can install mixedup from GitHub with `remotes`.  Use the second approach if you don't already have `rstanarm` or `brms` (they aren't required to use in general).

``` r
remotes::install_github('m-clark/mixedup')

# if you don't already have rstanarm and/or brms

withr::with_envvar(c(R_REMOTES_NO_ERRORS_FROM_WARNINGS = "true"), 
  remotes::install_github('m-clark/mixedup')
)
```


## Supported models

- `lme4`
- `glmmTMB`
- `nlme`
- `mgcv`
- `rstanarm`
- `brms`


## Feature list

- Extract Variance Components
- Extract Random Effects
- Extract Fixed Effects
- Extract Random Coefficients
- Extract Heterogeneous Variances
- Extract Correlation Structure
- Extract Model Data
- Summarize Model
- Find Typical


Not all features are available to the various modeling packages (e.g. autocorrelation for `lme4`), and some functionality may just not be supported for this package, but most functions are applicable to the packages listed.

## Examples

### Setup

In the following I suppress the package startup and other information that isn't necessary for demo.

```{r loadbayes, echo=FALSE}
brm_model <- mixedup:::brms_model
rstanarm_model <- mixedup:::rstanarm_model
```

```{r mods, results='hide', message=FALSE, warning=FALSE}
library(lme4)

lmer_model <- lmer(Reaction ~ Days + (1 + Days | Subject), data = sleepstudy)

library(glmmTMB)

tmb_model <- glmmTMB(Reaction ~ Days + (1 + Days | Subject), data = sleepstudy)

library(nlme)

nlme_model <-  nlme(
  height ~ SSasymp(age, Asym, R0, lrc),
  data = Loblolly,
  fixed = Asym + R0 + lrc ~ 1,
  random = Asym ~ 1,
  start = c(Asym = 103, R0 = -8.5, lrc = -3.3)
)

library(brms)

# brm_model = brm(
#   Reaction ~ Days + (1 + Days | Subject), 
#   data = sleepstudy, 
#   refresh = -1,
#   verbose = FALSE,
#   open_progress = FALSE,
#   cores = 4,
#   iter = 1000
# )

library(rstanarm)

# rstanarm_model = stan_glmer(
#   Reaction ~ Days + (1 + Days | Subject), 
#   data = sleepstudy, 
#   refresh = -1,
#   verbose = FALSE,
#   show_messages = FALSE,
#   open_progress = FALSE,
#   cores = 4,
#   iter = 1000
# )

library(mgcv)

gam_model = gam(
  Reaction ~  Days +
    s(Subject, bs = 're') +
    s(Days, Subject, bs = 're'),
  data = lme4::sleepstudy,
  method = 'REML'
)
```


### Extract Output from a Mixed Model

```{r extract-re, message=TRUE}
library(mixedup)

extract_random_effects(tmb_model)

extract_fixed_effects(nlme_model)

extract_random_coefs(lmer_model)

extract_vc(brm_model, ci_level = .8)

summarize_model(lmer_model, cor_re = TRUE, digits = 1)

find_typical(gam_model, probs = c(.25, .50, .75))
```

### Consistent output

```{r samestuff}
mods = list(
  tmb  = tmb_model,
  lmer = lmer_model, 
  brm  = brm_model,
  stan = rstanarm_model,
  gam  = gam_model
)

purrr::map_df(mods, extract_vc, .id = 'model') 
```



## Code of Conduct

Please note that the 'mixedup' project is released with a [Contributor Code of Conduct](.github/CODE_OF_CONDUCT.md).

By contributing to this project, you agree to abide by its terms.