-
Notifications
You must be signed in to change notification settings - Fork 28
/
README.Rmd
148 lines (112 loc) · 5.98 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
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
options(tibble.print_min = 5, tibble.print_max = 5)
library("mgcv")
library("gratia")
```
# gratia
<!-- badges: start -->
[](https://github.com/gavinsimpson/gratia/actions)
[](https://app.codecov.io/gh/gavinsimpson/gratia)
[](https://cran.r-project.org/package=gratia)
[](https://cran.r-project.org/package=gratia)
<!-- badges: end -->
## 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.
## Features
```{r draw-gam-figure, dev = "png", fig.height = 6, fig.width = 9, dpi = 120, 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)
```
```{r draw-gam-figure-2d, dev = "png", fig.height = 6, fig.width = 9, dpi = 120, 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, dev = "png", fig.height = 6, fig.width = 9, dpi = 120, 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:
Or for a bivariate smooth:
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()`
## 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 "favor, charm,
thanks" ([according to Merriam Webster](https://www.merriam-webster.com/dictionary/grace)).
The chair that Grace Wabha 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.)