README.Rmd

---
output: github_document
---

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

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

# varde

<!-- badges: start -->
<!-- badges: end -->

The goal of varde is to provide functions for decomposing the variance in multilevel models, e.g., for g studies in generalizability theory or intraclass correlation analyses in interrater reliability.

## Installation

You can install the development version of varde from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("jmgirard/varde")
```

## Example

In the `ppa` example dataset, 72 human "raters" judged the perceived physical attractiveness of 36 human "targets" in 6 different conditions (i.e., stimulus "types").

```{r}
library(varde)

# Extract only type 1 observations (to simplify the example)
ppa_type1 <- ppa[ppa$Type == 1, ]
```


### Simple Frequentist G Study

```{r}
fit_0 <- lme4::lmer(
  formula = Sepal.Length ~ 1 + (1 | Species),
  data = iris
)
varde(fit_0)
```


### Simple Generalizability Study

```{r res_1, message=FALSE}
# Fit a mixed effects model with target and rater effects
fit_1 <- brms::brm(
  formula = Score ~ 1 + (1 | Target) + (1 | Rater),
  data = ppa_type1,
  chains = 4,
  cores = 4,
  init = "random",
  warmup = 5000,
  iter = 10000,
  seed = 2022,
  file = "m1"
)
```

```{r}
# Extract variance component estimates
res_1 <- varde(fit_1)
res_1
```

```{r p1a, fig.width=9, fig.height=4, out.width="100%"}
# Create river plot of variance percentages
plot(res_1, type = "river")
```

```{r p1b, fig.width=9, fig.height=2.5, out.width="100%", warning=FALSE}
# Create density plot of variance posteriors
plot(res_1, type = "variances")
```

```{r p1c, fig.width=9, fig.height=2.5, out.width="100%"}
# Create jitter plot of random intercepts
plot(res_1, type = "intercepts")
```

### Simple Two-Way ICC for Inter-Rater Reliability

```{r res_2, message=FALSE}
# Calculate variance components and ICCs
res_2 <- calc_icc(
  .data = ppa_type1, 
  subject = "Target",
  rater = "Rater",
  scores = "Score",
  k = 12,
  file = "m2"
)
res_2
```

```{r p2a, fig.width=9, fig.height=5, out.width="100%", warning=FALSE}
# Create density plot of all posteriors
plot(res_2)
```

```{r p2b, fig.width=9, fig.height=2, out.width="100%", warning=FALSE}
# Create density plot of specific posteriors
plot(res_2, parameters = c("ICC(A,k)", "ICC(C,k)"))
```

### Multivariate MCMC for Many ICCs

In `posneg`, 110 images were rated by between 2 and 5 raters on how "Negative" and "Positive" they appeared.

```{r res_3, message=FALSE}
# Calculate variance components and ICCs
res_3 <- calc_icc(
  .data = posneg, 
  subject = "Image",
  rater = "Rater",
  scores = c("Negative", "Positive"),
  file = "m3",
  cores = 4,
  control = list(adapt_delta = 0.999)
)
res_3
```