
# ggResidpanel <a href="https://goodekat.github.io/ggResidpanel/"><img src="man/figures/logo.png" align="right" height="139" alt="ggResidpanel website" /></a>

<!-- badges: start -->

[![](https://www.r-pkg.org/badges/version/ggResidpanel?color=green)](https://cran.r-project.org/package=ggResidpanel)
[![Lifecycle:
stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
[![R-CMD-check](https://github.com/goodekat/ggResidpanel/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/goodekat/ggResidpanel/actions/workflows/R-CMD-check.yaml)
[![monthly-downloads](http://cranlogs.r-pkg.org/badges/grand-total/ggResidpanel?color=blue)](https://cran.r-project.org/package=ggResidpanel)
[![total-downloads](http://cranlogs.r-pkg.org/badges/last-month/ggResidpanel?color=blue)](https://cran.r-project.org/package=ggResidpanel)
[![Codecov test
coverage](https://codecov.io/gh/goodekat/ggResidpanel/graph/badge.svg)](https://app.codecov.io/gh/goodekat/ggResidpanel)
<!-- badges: end -->

ggResidpanel is an R package for creating panels of diagnostic plots for
a model using ggplot2 and interactive versions of the plots using
plotly.

## Installation

This is the current development version of ggResidpanel. Install the
development version from GitHub or an older version from CRAN.

``` r
# Installs the development version of ggResidpanel from GitHub
remotes::install_github("goodekat/ggResidpanel")

# Installs ggResidpanel from CRAN
install.packages("ggResidpanel")
```

Load the ggResidpanel package.

``` r
# Load the library
library(ggResidpanel)
```

## Learn More

Here are some resources for learning how to use ggResidpanel:

- [Introduction
  Vignette](https://goodekat.github.io/ggResidpanel/articles/introduction.html)
- [Tutorial and User
  Manual](https://goodekat.github.io/ggResidpanel-tutorial/tutorial.html)

## Overview and Examples

The package provides functions that allow the user to assess diagnostic
plots from a model. These functions are:

- `resid_panel`: Creates a panel of diagnostic plots of the residuals
  from a model
- `resid_interact`: Creates an interactive panel of diagnostic plots of
  the residuals form a model
- `resid_xpanel`: Creates a panel of diagnostic plots of the predictor
  variables
- `resid_compare`: Creates a panel of diagnostic plots from multiple
  models
- `resid_auxpanel`: Creates a panel of diagnostic plots for model types
  not included in the package
- **NEW** `resid_calibrate`: Creates a panel of diagnostic residual
  plots from a fitted model and simulated responses from the same model.

Currently, ggResidpanel allows the first four functions listed above to
work with models fit using the functions of `lm`, `glm`, `lme` (from
nlme), and `lmer` or `glmer` (from lme4 or fit using lmerTest). Each of
these functions is applied below to show the panel that is output from
the function. The functions have multiple input options such as the
formatting options of `scale`, `theme`, `axis.text.size`,
`title.text.size`, and `title.opt`.

The `penguins` data used in the examples below is included in
ggResidpanel.

``` r
str(penguins)
```

    ## 'data.frame':    125 obs. of  4 variables:
    ##  $ heartrate: num  88.8 103.4 97.4 85.3 60.6 ...
    ##  $ depth    : num  5 9 22 25.5 30.5 32.5 38 32 6 10.5 ...
    ##  $ duration : num  1.05 1.18 1.92 3.47 7.08 ...
    ##  $ bird     : Factor w/ 9 levels "1","2","3","4",..: 1 1 1 1 1 1 1 1 1 1 ...

#### `resid_panel`

This function creates a panel of residual diagnostic plots given a
model. It allows the user to select a panel of plots from the options in
the package or create their own panel by selecting from the plots
available for this function.

``` r
# Fit a model
penguin_model <- 
  lme4::lmer(
    heartrate ~ depth + duration + (1|bird), 
    data = penguins
  )

# Create the default panel of plots
resid_panel(penguin_model)
```

![](man/figures/README-unnamed-chunk-4-1.png)<!-- -->

``` r
# Create a pancel with residual, qq, and yvp plots, add 95% confidence interval 
# bands to the qq-plot, and change the theme to classic
resid_panel(
  penguin_model, 
  plots = c("resid", "qq", "yvp"), 
  qqbands = TRUE, 
  theme = "classic"
)
```

![](man/figures/README-unnamed-chunk-4-2.png)<!-- -->

``` r
# Create a panel with all plots available for a model fit using lmer
resid_panel(penguin_model, plots = "all")
```

![](man/figures/README-unnamed-chunk-4-3.png)<!-- -->

#### `resid_interact`

This function creates interactive versions of residual diagnostic plot
panels given a model. Similar to `resid_panel`, it allows the user to
select a panel of plots from the options in the package or to create
their own panel by selecting from the plots available for this function.

``` r
# Create an interactive panel of the default diagnostic plots
resid_interact(penguin_model)
```

![](inst/figures/interact.gif)

#### `resid_xpanel`

This function creates a panel of plots of the residuals or response
variable versus the predictor (x) variables in the model.

``` r
# Create a panel of plots of the residuals versus the predictor variables
resid_xpanel(penguin_model, jitter.width = 0.1)
```

![](man/figures/README-unnamed-chunk-6-1.png)<!-- -->

``` r
# Create a panel of plots of the response variable versus the predictor variables
resid_xpanel(penguin_model, yvar = "response", jitter.width = 0.1)
```

![](man/figures/README-unnamed-chunk-6-2.png)<!-- -->

#### `resid_compare`

This function creates a panel of residual diagnostic plots given a list
of models. This allows the user to compare the diagnostic plots from
multiple models.

``` r
# Fit the model with a log transformation of the response variable and a 
# quadratic term for duration
penguin_model_log2 <- 
  lme4::lmer(
    log(heartrate) ~ depth + duration + I(duration^2) + (1|bird), 
    data = penguins
  )

# Plot the residual and normal quantile plots for the two models
resid_compare(
  list(penguin_model, penguin_model_log2),
  plots = c("resid", "qq")
)
```

![](man/figures/README-unnamed-chunk-7-1.png)<!-- -->

#### `resid_auxpanel`

This function creates a panel of residual diagnostic plots given inputs
of residuals and fitted values to use for models not accepted by
`resid_panel`. Users can select from panel options in the package or
create their own panel from the plots available for this function.

``` r
# Fit a regression tree to the penguins data
penguin_tree = rpart::rpart(heartrate ~ depth + duration, data = penguins)

# Obtain the predictions from the model on the observed data
penguin_tree_pred = predict(penguin_tree)

# Obtain the residuals from the model
penguin_tree_resid = penguins$heartrate - penguin_tree_pred

# Create a panel with the residual and index plot
resid_auxpanel(
  residuals = penguin_tree_resid, 
  predicted = penguin_tree_pred, 
  plots = c("resid", "index")
)
```

![](man/figures/README-unnamed-chunk-8-1.png)<!-- -->

#### `resid_calibrate`

This function creates a panel of diagnostic residual plots from a fitted
model and simulated responses from the same model. This isu sed to
calibrate expectations for simulation variability when assumptions are
true (see ), to compare to the actual observed residuals in any of a
suite of diagnostic plots. This function is based on the function and
requires the fitted model and the data set. However, for now, it only
works with `lm` models.

``` r
penguin1_model <- 
  lm(
    heartrate ~ depth + duration,
    data = penguins |> dplyr::filter(bird == 1)
  )

resid_calibrate(
  model = penguin1_model, 
  plots = "qq", 
  nsim = 3, 
  shuffle = TRUE, 
  identify = TRUE
)
```

    ## [1] "Real residuals are in column 3"

![](man/figures/README-unnamed-chunk-9-1.png)<!-- -->

## New Feature: Customization of Figures

The manner in which the plot panels are created by `ggResidpanel` is
such that it is not possible to directly modify the figures using
`ggplot2` functions. However, the `return_plot_list = TRUE` option in
`ggResidpanel` allows for the output of a list of figures. This option
requires that specific plots are specified in the `plots` option, and it
only works with the `resid_panel`, `resid_xpanel`, `resid_auxpanel`, and
`resid_calibrate` functions. Here is an example…

This code does lead to the desired results:

``` r
resid_panel(penguin_model, plots = c("resid", "index")) +
  ggplot2::theme_dark(header_family = "Times")
```

![](man/figures/README-unnamed-chunk-10-1.png)<!-- -->

Instead, use the return_plot_list = TRUE option:

``` r
list_of_plots <-
  resid_panel(
    penguin_model, 
    plots = c("resid", "index"), 
    return_plot_list = TRUE
  )
```

Details of created object:

``` r
typeof(list_of_plots)
## [1] "list"
names(list_of_plots)
## [1] "resid" "index"
```

Customize output plots:

``` r
list_of_plots$resid + ggplot2::theme_dark(header_family = "Times")
```

![](man/figures/README-unnamed-chunk-13-1.png)<!-- -->

``` r
list_of_plots$index + ggplot2::theme_dark(header_family = "Times")
```

![](man/figures/README-unnamed-chunk-13-2.png)<!-- -->

Streamlined code for customizing all plots in the list using the `purrr`
package:

``` r
list_of_custom_plots <-
  purrr::map(
    .x = list_of_plots, 
    .f = function(x) x + ggplot2::theme_dark(header_family = "Times")
  )
list_of_custom_plots
```

    ## $resid

![](man/figures/README-unnamed-chunk-14-1.png)<!-- -->

    ## 
    ## $index

![](man/figures/README-unnamed-chunk-14-2.png)<!-- -->

This output list of customized plots can also be placed in a panel
again:

``` r
cowplot::plot_grid(plotlist = list_of_custom_plots)
```

![](man/figures/README-unnamed-chunk-15-1.png)<!-- -->
