Repository files navigation

Working with GAMs within the ‘tidyverse’ can be tedious and evendifficult without a good understanding of GAMs themselves and how themodel 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 forworking with generalized additive models (GAMs) fitted using the ‘mgcv’package, via a reimplementation of theplot() method for GAMs that‘mgcv’ provides, as well as ‘tidyverse’ compatible representations ofestimated smooths.

The main features ofgratia are currently

• Aggplot2-based replacement formgcv:::plot.gam():draw.gam().

  For example, the classic four term additive example from Gu & Wahba:

  Estimated smooths from a GAM

  Or for a bivariate smooth:

  Estimated smooths from a GAM

  Note that some specialist smoothers (bs %in% c("mrf","sw", "sf"))are not currently supported, but univariate,factor andcontinuousby-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 andtensor product smooths are supported,

• Estimation of derivatives of fitted smoothers:derivatives(),

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

• Model diagnostics viaappraise()

  Model diagnostics figure

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

install.packages("gratia")

howevergratia is under active development and you may wish to installthe development version from github. The easiest way to do this is viatheinstall_github() function from packageremotes. Make sure youhaveremotes installed, then run

remotes::install_github("gavinsimpson/gratia")

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

# Install gratia in Rinstall.packages("gratia", repos = c(  "https://gavinsimpson.r-universe.dev",  "https://cloud.r-project.org"))

gratia grew out of an earlier package,schoenberg, itself adevelopment of the earlier packagetsgam, which was originallyintended to be used with GAMs fitted to time series. As I was developingtsgam however it became clear that the package could be used moregenerally and that the name “tsgam” was no longer appropriate. To avoidbreaking blog posts I had written usingtsgam I decided to copy thegit repo and all the history to a new repo for the package under thenameschoenberg. At a later date someone released another packagecalledschoenberg to CRAN, so that scuppered that idea. Now I’mcalling the packagegratia. Hopefully I won’t have to change it again…

In naming hisgreta package,Nick Golding observed the recent phenomena of naming statisticalmodelling software, such as Stan or Edward, after individuals thatplayed a prominent role in the development of the field. This lead Nickto name his Tensor Flow-based packagegreta afterGreteHermann.

In the same spirit,gratia is named in recognition of thecontributions ofGraceWahba, who did pioneeringwork on the penalised spline models that are at the foundation of theway GAMs are estimated inmgcv. I wanted to name the packagegrace,to explicitly recognise Grace’s contributions, but unfortunately therewas already a package namedGrace on CRAN. So I looked elsewhere forinspiration.

The English word “grace” derives from the Latingratia, meaning“favor, charm, thanks” (according to MerriamWebster).

The chair that Grace Wabha currently holds is named afterIsaac JSchoenberg, aformer University Madison-Wisconsin Professor of Mathematics, who in a1946 paper provided the first mathematical reference to “splines”.(Hence the previous name for the package.)