gratia

gratia: An R package for exploring generalized additive models - Published in JOSS (2024)

https://github.com/gavinsimpson/gratia

Keywords

Scientific Fields

Repository

ggplot-based graphics and useful functions for GAMs fitted using the mgcv package

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  dev = "ragg_png",
  dpi = 96
)
options(tibble.print_min = 5, tibble.print_max = 5)
library("mgcv")
library("gratia")
```

# gratia


[![R build status](https://github.com/gavinsimpson/gratia/workflows/R-CMD-check/badge.svg)](https://github.com/gavinsimpson/gratia/actions)
[![codecov](https://codecov.io/gh/gavinsimpson/gratia/branch/main/graph/badge.svg?token=GG5NQfgRFu)](https://app.codecov.io/gh/gavinsimpson/gratia)
[![CRAN\_Status\_Badge](https://www.r-pkg.org/badges/version/gratia)](https://cran.r-project.org/package=gratia)
[![CRAN Downloads](https://cranlogs.r-pkg.org/badges/grand-total/gratia)](https://cran.r-project.org/package=gratia)
[![DOI](https://joss.theoj.org/papers/10.21105/joss.06962/status.svg)](https://doi.org/10.21105/joss.06962)
[![r-universe version](https://gavinsimpson.r-universe.dev/gratia/badges/version)](https://gavinsimpson.r-universe.dev/gratia)
[![r-universe status](https://gavinsimpson.r-universe.dev/gratia/badges/checks)](https://gavinsimpson.r-universe.dev/gratia)


## Overview

Working with GAMs within the 'tidyverse' can be tedious and even difficult
without a good understanding of GAMs themselves and how the model is returned
by 'mgcv' and what the model objects contain. 'gratia' is designed to help with
this.

'gratia' provides 'ggplot'-based graphics and utility functions for working with
generalized additive models (GAMs) fitted using the 'mgcv' package, via a
reimplementation of the `plot()` method for GAMs that 'mgcv' provides, as well
as 'tidyverse' compatible representations of estimated smooths.

## Citation

If you use *gratia* in your work, please cite the package using:

Simpson, G. L., (2024). gratia: An R package for exploring generalized additive
models. *Journal of Open Source Software*, **9**(104), 6962,


## Features

```{r draw-gam-figure, fig.height = 6, fig.width = 9, echo = FALSE, fig.show = "hide", message = FALSE}
df1 <- data_sim("eg1", n = 400, seed = 42)
m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df1, method = "REML")
draw(m1, residuals = TRUE, rug = FALSE)
```

```{r draw-gam-figure-2d, fig.height = 6, fig.width = 9, echo = FALSE, fig.show = "hide", message = FALSE}
df2 <- data_sim("eg2", n = 1000, seed = 42)
m2 <- gam(y ~ s(x, z), data = df2, method = "REML")
draw(m2)
```

```{r appraise-figure, fig.height = 6, fig.width = 9, echo = FALSE, fig.show = "hide"}
appraise(m1)
```

The main features of *gratia* are currently

* A *ggplot2*-based replacement for `mgcv:::plot.gam()`: `draw.gam()`.

  For example, the classic four term additive example from Gu & Wahba:
	
  ![Estimated smooths from a GAM](man/figures/README-draw-gam-figure-1.png)

  Or for a bivariate smooth:
    
  ![Estimated smooths from a GAM](man/figures/README-draw-gam-figure-2d-1.png)

  Note that some specialist smoothers (`bs %in% c("mrf","sw", "sf")`) are not
  currently supported, but univariate, *factor* and *continuous* `by`-variable
  smooths, simple random effect smooths (`bs = 're'`), factor-smooth
  interaction smooths (`bs = "fs"`), constrained factor smooths (`bs = "sz"`),
  full soap film smooths (`bs = "so"`), and bivariate, trivariate, and
  quadvariate TPRS and tensor product smooths are supported,

* Estimation of derivatives of fitted smoothers: `derivatives()`,

* Estimation of point-wise across-the-function confidence intervals and
  simultaneous intervals for smooths: `confint.gam()`.

* Model diagnostics via `appraise()`

  ![Model diagnostics figure](man/figures/README-appraise-figure-1.png)

## Installing *gratia*

*gratia* is now available on CRAN, and can be installed with

```{r install, eval = FALSE}
install.packages("gratia")
```

however *gratia* is under active development and you may wish to install the
development version from github. The easiest way to do this is via the
`install_github()` function from package *remotes*. Make sure you have
*remotes* installed, then run

```{r install-github, eval = FALSE}
remotes::install_github("gavinsimpson/gratia")
```

to install the package. Alternatively, binary packages of the development
version are available from rOpenSci's R Universe service:

```{r install-r-universe, eval = FALSE}
# Install gratia in R
install.packages("gratia", repos = c(
  "https://gavinsimpson.r-universe.dev",
  "https://cloud.r-project.org"
))
```

## History

*gratia* grew out of an earlier package, *schoenberg*, itself a development of
the earlier package *tsgam*, which was originally intended to be used with GAMs
fitted to time series. As I was developing *tsgam* however it became clear that
the package could be used more generally and that the name "tsgam" was no longer
appropriate. To avoid breaking blog posts I had written using *tsgam* I decided
to copy the git repo and all the history to a new repo for the package under the
name *schoenberg*. At a later date someone released another package called
*schoenberg* to CRAN, so that scuppered that idea. Now I'm calling the package
*gratia*. Hopefully I won't have to change it again…

## Why *gratia*?

In naming his [*greta*](https://github.com/greta-dev/greta) package, Nick
Golding observed the recent phenomena of naming statistical modelling software,
such as Stan or Edward, after individuals that played a prominent role in the
development of the field. This lead Nick to name his Tensor Flow-based package
*greta* after [*Grete Hermann*](https://greta-stats.org/articles/webpages/why_greta.html).

In the same spirit, *gratia* is named in recognition of the contributions of
[Grace Wahba](https://en.wikipedia.org/wiki/Grace_Wahba), who did pioneering
work on the penalised spline models that are at the foundation of the way GAMs
are estimated in *mgcv*. I wanted to name the package *grace*, to explicitly
recognise Grace's contributions, but unfortunately there was already a package
named *Grace* on CRAN. So I looked elsewhere for inspiration.

The English word "grace" derives from the Latin *gratia*, meaning "favour, charm,
thanks" ([according to Merriam Webster](https://www.merriam-webster.com/dictionary/grace)).

The chair that Grace Wahba currently holds is named after 
[Isaac J Schoenberg](https://en.wikipedia.org/wiki/Isaac_Jacob_Schoenberg), a
former University Madison-Wisconsin Professor of Mathematics, who in a 1946
paper provided the first mathematical reference to "splines". (Hence the
previous name for the package.)

Owner

JOSS Publication

gratia: An R package for exploring generalized additive models

Published

December 21, 2024

DOI

10.21105/joss.06962

Volume 9, Issue 104, Page 6962

Authors

Gavin L. Simpson
Department of Animal and Veterinary Sciences, Aarhus University, Denmark

Editor

Oskar Laverny

Tags

splines generalized additive models posterior simulation

View PDF Review Thread Software Archive

Citation (CITATION.cff)

cff-version: 1.2.0
message: 'To cite package "gratia" in publications use:'
type: software
license: MIT
title: 'gratia: Graceful ggplot-Based Graphics and Other Functions for GAMs
  Fitted Using mgcv'
version: 0.10.0
doi: 10.32614/CRAN.package.gratia
abstract: 'Graceful ggplot-based graphics and utility functions for working with
  generalized additive models (GAMs) fitted using the mgcv package. Provides a
  reimplementation of the plot() method for GAMs that mgcv provides, as well
  as tidyverse- compatible representations of estimated smooths.'
authors:
- family-names: Simpson
  given-names: Gavin L.
  email: ucfagls@gmail.com
  orcid: https://orcid.org/0000-0002-9084-8413
preferred-citation:
  type: manual
  title: 'gratia: Graceful ggplot-Based Graphics and Other Functions for GAMs
    Fitted Using mgcv'
  authors:
  - family-names: Simpson
    given-names: Gavin L.
    email: ucfagls@gmail.com
    orcid: https://orcid.org/0000-0002-9084-8413
  version: 0.10.0
  doi: 10.32614/CRAN.package.gratia
  abstract: 'Graceful ggplot-based graphics and utility functions for working
    with generalized additive models (GAMs) fitted using the mgcv package.
    Provides a reimplementation of the plot() method for GAMs that mgcv
    provides, as well as tidyverse-compatible representations of estimated
    smooths.'
  repository: https://CRAN.R-project.org/package=gratia
  repository-code: https://github.com/gavinsimpson/gratia
  url: https://gavinsimpson.github.io/gratia/
  date-released: '2024-12-20'
  contact:
  - family-names: Simpson
    given-names: Gavin L.
    email: ucfagls@gmail.com
    orcid: https://orcid.org/0000-0002-9084-8413
  keywords:
  - gam
  - generalized-additive-models
  - ggplot2
  - glm
  - lm
  - mgcv
  - r-package
  - random-effects
  - smoothing
  license: MIT
  year: '2024'
repository: https://CRAN.R-project.org/package=gratia
repository-code: https://github.com/gavinsimpson/gratia
url: https://gavinsimpson.github.io/gratia/
date-released: '2024-12-20'
contact:
- family-names: Simpson
  given-names: Gavin L.
  email: ucfagls@gmail.com
  orcid: https://orcid.org/0000-0002-9084-8413
keywords:
- gam
- generalized-additive-models
- ggplot2
- glm
- lm
- mgcv
- r-package
- random-effects
- smoothing

Papers & Mentions

GitHub Events

Committers

Last synced: 5 months ago

Issues and Pull Requests

Last synced: 4 months ago

Packages