---
title: "Visualize partially-summed effects in GAM"
author: "Motoki Saito"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Visualize partially-summed effects in GAM}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(gamutil)
mdl <- gamutil:::mdl
RhpcBLASctl::blas_set_num_threads(1)
RhpcBLASctl::omp_set_num_threads(1)
```

```{r setup}
library(gamutil)
```
This package facilitates daily modeling routines with GA(M)Ms by the mgcv
package (Wood, 2017). Suppose you already fitted a GAM below, using mgcv::gam
or mgcv::bam:

```{r}
print(mdl)
```

## Summed effects
Summed-effects can be visualized by mgcv::vis.gam, or itsadug::fvisgam (van
Rij, 2020). The same plot can also be plotted by mgcv::plot_contour as below:

```{r, fig.dim=c(5,5)}
library(mgcv)
vis.gam(mdl, view=c('x1','x2'), plot.type='contour')
```

```{r, fig.dim=c(6,5)}
plot_contour(mdl, view=c('x1','x2'))
```

There is no correct way in choosing the number of contour lines and their
values. In gamutil::plot_contour, you can use user-defined contour lines by
the optional arguments "contour.line.breaks" and "contour.color.breaks" for
contour lines and contour colors respectively:

```{r, fig.dim=c(6,5)}
lbr <- seq(-10, 10, by=1.0)
cbr <- seq(-10, 10, by=0.1)
plot_contour(mdl, view=c('x1','x2'),
	     contour.line.breaks=lbr, contour.color.breaks=cbr)
```


## Partial effects
Partial effects can be visualized by mgcv::plot.gam or itsadug::pvisgam. The
same plot can be obtained with gamutil::plot_contour as below:

```{r, fig.dim=c(6,5)}
plot.gam(mdl, select=6)
```

```{r, fig.dim=c(6,5)}
lbr <- seq(-5, 5, by=0.50)
cbr <- seq(-5, 5, by=0.05)
plot_contour(mdl, view=c('x1','x2'), summed=FALSE, terms.size='min',
	     verbose=TRUE, contour.line.breaks=lbr, contour.color.breaks=cbr)
```

The optional argument "terms.size='min'" ensures that you include only the term
that contains the variables specified in "view", namely "x1" and "x2" in this
example.


## Partially-summed effects

The argument "terms.size" can take three values. They are "min", "medium", and
"max". "min" is intended to plot only one term, i.e., partial effects. "medium"
includes all the terms that contain the variables specified in "view" but no
other variables. In the current example, it would include "s(x1)", "s(x2)", and
"ti(x1,x2)". Note that "ti(x0, x1)", "ti(x0,x2)", and ti(x0, x1, x2) are
excluded, although they contain one of the variables in "view". They are
excluded because they also contain the variables that are not specified in
"view".

```{r, fig.dim=c(6,5)}
plot_contour(mdl, view=c('x1','x2'), summed=FALSE, terms.size='medium',
	     verbose=TRUE)
```

In contrast, "terms.size='max'" plots all the terms that include at least one
of the variables specified in the "view" argument. In the current example, it
would include "s(x1)", "s(x2)", "ti(x0,x1)", "ti(x0,x2)", "ti(x1,x2)", and
"ti(x0,x1,x2)".

```{r, fig.dim=c(6,5)}
plot_contour(mdl, view=c('x1','x2'), summed=FALSE, terms.size='max',
	     verbose=TRUE)
```


## Notes

The return value of gamutil::plot_contour is a ggplot object. Therefore, you
can modify the plot afterwards.

```{r, fig.dim=c(6,5)}
library(ggplot2)
plt <- plot_contour(mdl, view=c('x1','x2'), summed=FALSE, terms.size='medium',
		    verbose=TRUE)
plt <- plt + theme(text=element_text(size=25))
plt
```