Graceful 'ggplot'-Based Graphics and Other Functions for GAMs Fitted Using 'mgcv'

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.


Build Status Build status codecov.io CRAN_Status_Badge

Overview

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.

Features

The main features of gratia are currently

  • A ggplot2-based replacement for mgcv:::plot.gam(): draw(gam_model).

    Estimated smooths from a GAM

    Note specialist smoothers (bs %in% c("sos","mrf","so")) are not currently supported, but univariate, factor and continuous by-variable smooths, simple random effect smooths (bs = 're'), factor-smooth interaction smooths (bs = "fs"), and bivariate tensor product smooths are supported,

  • Estimatation of derivatives of fitted smoothers: derivatives() (older functionality in fderiv(gam_model)),

  • Estimation of point-wise across-the-function confidence intervals and simultaneous intervals for smooths: confint(gam_model).

  • Model diagnostics via appraise()

    Model diagnostics figure

Installing gratia

gratia is under active development and has not yet had its first release to CRAN. The easiest way to install the package is via the install_github() function from package devtools. Make sure you have devtools installed, then run

devtools::install_github("gavinsimpson/gratia")

to install the package.

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 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.

In the same spirit, gratia is named in recognition of the contributions of 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 "favor, charm, thanks" (according to Merriam Webster).

The chair that Grace Wabha currently holds is named after Isaac J 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.)

News

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("gratia")

0.2-8 by Gavin L. Simpson, 2 months ago


https://gavinsimpson.github.io/gratia


Report a bug at https://github.com/gavinsimpson/gratia/issues


Browse source code at https://github.com/cran/gratia


Authors: Gavin L. Simpson [aut, cre]


Documentation:   PDF Manual  


MIT + file LICENSE license


Imports mgcv, ggplot2, tibble, dplyr, tidyr, cowplot, grid, mvtnorm, stats, tools, grDevices

Suggests testthat, vdiffr, MASS, scam, datasets


See at CRAN