-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathREADME.Rmd
129 lines (88 loc) · 4.8 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
---
output: rmarkdown::github_document
always_allow_html: yes
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```
# redres <img align="right" width="150" height="175" src="README_files/static-figures/sticker.png">
`redres` is an R package developed to help with diagnosing linear mixed models fit using the function `lmer` from the `lme4` package. It is meant to supplement the `lme4` package.
<!-- badges: start -->
[](https://travis-ci.org/goodekat/redres)
[](https://codecov.io/gh/goodekat/redres?branch=master)
<!-- badges: end -->
Note that the code coverage is less than 90% due to our function `launch_app` that runs the Shiny app. The other functions in the package all have 100% code coverage. See the image below of the coverage report (taken on May 6, 2019).
<img align="center" width="600" src="README_files/static-figures/test-coverage.png">
## Installation
`redres` can be installed from the GitHub repository using the devtools package.
```{r eval = FALSE}
# Installs redres
devtools::install_github("goodekat/redres")
```
Once installed, the package can be loaded as usual.
```{r}
# Loads the library
library(redres)
```
## Functions
The package contains the following functions.
#### compute_redres
`compute_redres` computes residuals given an `lmer` model and a specified residual type. The available residual types are listed below.
- `"pearson_cond"`: Pearson conditional residuals
- `"pearson_mar"`: Pearson marginal residuals
- `"raw_cond"`: raw conditional residuals (default)
- `"raw_mar"`: raw marginal residuals
- `"std_cond"`: studentized conditional residuals
- `"std_mar"`: studentized marginal residuals
```{r message = FALSE}
# fits an lmer model
library(lme4)
m <- lmer(Reaction ~ Days + (Days | Subject), data = sleepstudy)
# computes the default residuals (raw conditional)
rc_resids <- compute_redres(m)
# computes the Pearson marginal residuals
pm_resids <- compute_redres(m, type = "pearson_mar")
# computes the studentized conditional residuals
sc_resids <- compute_redres(m, type = "std_cond")
# puts the residuals in a data frame with observed response and prints the first six rows
resids <- data.frame(sleepstudy$Reaction, rc_resids, pm_resids, sc_resids)
head(resids)
```
#### plot_redres
`plot_redres` creates a plot (using `ggplot2`) of the residuals versus the fitted values given a model and a specified residual type. All residual types listed for `redres` work with `plot_redres`.
```{r}
# creates a plot of the conditional studentized residuals versus the fitted values
plot_redres(m, type = "std_cond")
```
#### plot_resqq
`plot_resqq` creates a normal quantile plot (using `ggplot2` and `qqplotr`) of the raw conditional residuals, `raw_cond`. By the assumptions of a model fit using `lmer` these residuals are expected to be normally distributed. Obvious departures indicate an invalid assumption. See [vignette](https://goodekat.github.io/redres/articles/redres-vignette.html) for more details about interpreting quantile plots.
```{r}
# creates a residual quantile plot for the error term
plot_resqq(m)
```
#### plot_ranef
`plot_ranef` creates normal quantile plots for all random effects in the model. Under the assumptions of a `lmer` model, each random effect term is normally distributed. This function will return a grid of plots fit using `ggplot2` and `qqplotr`.
```{r}
# creates normal quantile plots for each random effect
plot_ranef(m)
```
#### launch_redres
`launch_redres` opens a Shiny app that includes interactive panels to view the diagnostic plots from a model. The function can be used by inputting one or two models into the app in the form of a vector. If two models are input, the residual plots for each model will be shown side by side in the app. Screen shots of the app are shown below.
```{r eval = FALSE}
# opens the app
launch_redres(m)
```
<img align="center" width="600" src="README_files/static-figures/app1.png">
<img align="center" width="600" src="README_files/static-figures/app2.png">
<img align="center" width="600" src="README_files/static-figures/app3.png">
## Learn More
To learn more about `redres`, read through the [vignette](https://goodekat.github.io/redres/articles/redres-vignette.html) for `redres` which contains:
- details on how the residuals are computed
- explanations of how to use the different residual types
- interpretations of the plots
- examples using `redres` to assess the assumptions of a linear mixed model
Additionally, more information is available at the package [website](https://goodekat.github.io/redres/).
```{r echo = FALSE, results = FALSE}
# copy static figures to docs folder
file.copy("./README_files", "./docs", overwrite = TRUE, recursive = TRUE)
```