Package {gamutil}

Title:	Utilities to Facilitate Modeling Routines with Generalized Additive Models
Version:	0.8.1
Description:	After fitting a Generalized Additive (Mixed) Model, the next step is often to obtain predicted values for certain combinations of predictors for visualization of estimated effects in the model. It involves constructing a new data frame, add predicted values, and finally makes a (contour) plot. This package is intended to facilitate these steps to visualize estimated effects in a generalized additive model. The underlying modeling methodology is described in Wood (2017, ISBN:9781498728331).
Imports:	ggplot2, lifecycle, metR, mgcv, RColorBrewer
License:	MIT + file LICENSE
URL:	https://github.com/msaito8623/gamutil
BugReports:	https://github.com/msaito8623/gamutil/issues
Encoding:	UTF-8
Language:	en-US
RoxygenNote:	7.3.3
Suggests:	testthat (≥ 3.0.0), knitr, rmarkdown, RhpcBLASctl
Config/testthat/edition:	3
Depends:	R (≥ 3.5)
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-05-06 08:18:14 UTC; motoki
Author:	Motoki Saito [aut, cre]
Maintainer:	Motoki Saito <motokisaito.8623@gmail.com>
Repository:	CRAN
Date/Publication:	2026-05-11 19:10:19 UTC

gamutil: Utilities to Facilitate Modeling Routines with Generalized Additive Models

Description

After fitting a Generalized Additive (Mixed) Model, the next step is often to obtain predicted values for certain combinations of predictors for visualization of estimated effects in the model. It involves constructing a new data frame, add predicted values, and finally makes a (contour) plot. This package is intended to facilitate these steps to visualize estimated effects in a generalized additive model. The underlying modeling methodology is described in Wood (2017, ISBN:9781498728331).

Author(s)

Maintainer: Motoki Saito motokisaito.8623@gmail.com (ORCID)

See Also

Useful links:

• https://github.com/msaito8623/gamutil

• Report bugs at https://github.com/msaito8623/gamutil/issues

Add predicted values with standard errors to a data.frame

Description

In order to obtain predictions from a regression model, you need to first create a data.frame with combinations of values of the variables in the model, feed it to some function for prediction (e.g., predict.gam), and add upper and lower boundaries for confidence intervals yourself. This function takes such a data.frame (i.e., "ndat") and add predicted values and standard errors based on the model provided through "mdl". "ndat" can be created by gamutil::to_ndat.

Usage

add_fit(
  ndat,
  mdl,
  terms = NULL,
  cond = list(),
  terms.size = "min",
  ci.mult = qnorm(0.975),
  verbose = FALSE,
  include.parametric = TRUE,
  joint.se = FALSE
)

Arguments

Value

The data.frame provided through "ndat" with additional columns for predicted values (i.e., fit) and upper and lower confidence interval boundaries (i.e., upr and lwr).

Author(s)

Motoki Saito, motoki.saito@uni-oldenburg.de

Examples

library(mgcv)
set.seed(534)
dat <- gamSim(eg=6, verbose=FALSE)
model <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3)
               + ti(x0,x1) + ti(x0,x2) + ti(x0,x3)
               + ti(x1,x2) + ti(x1,x3) + ti(x2,x3), data=dat)
target_to_vary <- c('x0','x1')
ndat <- mdl_to_ndat(mdl=model, target=target_to_vary, len=4, method=median)
terms_to_predict <- target_to_vary
# Prediction of the summed effect by all the terms:
ndat1 <- add_fit(ndat, model, verbose=TRUE)
# Partial effect of ti(x0, x1):
ndat2 <- add_fit(ndat, model, terms=terms_to_predict, terms.size="min",
                 verbose=TRUE)
# Sum of subordinate partial effects (i.e., s(x0), s(x1), ti(x0,x1)):
ndat3 <- add_fit(ndat, model, terms=terms_to_predict, terms.size="medium",
                 verbose=TRUE)
# Sum of all the pertinent partial effects (i.e., s(x0), s(x1), ti(x0,x1),
# ti(x0,x2), ti(x0,x3), ti(x1,x2), ti(x1,x3)):
ndat4 <- add_fit(ndat, model, terms=terms_to_predict, terms.size="max",
                 verbose=TRUE)

Keep a variable constant

Description

For prediction of a regression model, you need to create a data.frame for the combinations of predictor values you would like to get the model's predictions for. Sometimes you would like to keep some of the predictors constant, e.g., their median values. It can be done with this function. This function returns a single value from the vector provided through "vec" with the function provided through "func" (median as default), if the provided vector is numeric. If the vector is character or factor, then the value in the vector with the most occurrences is taken as a representative value and returned.

Usage

constant(vec, func = median)

Arguments

Value

A new format-like string, from which the terms you specified have been removed.

Author(s)

Motoki Saito, motoki.saito@uni-oldenburg.de

Examples

# The most frequent occurrence is returned for character/factor.
vec <- c(rep('A',2), rep('B',3), rep('C',1))
print(constant(vec))
# The representative value by "func" is returned for numeric.
# (default=median)
set.seed(716)
vec <- rnorm(10)
print(constant(vec))
# Another function can be used, too (e.g., max).
print(constant(vec, max))

Create a data.frame from a GAM object for prediction

Description

In order to obtain predicted values from a GAM object, you need to provide a data.frame with combinations of values for the predictors in the model to mgcv::predict.gam. This function does this job only by giving it a GAM object (i.e., mdl) and telling it which variables you would like to vary (i.e, target).

Usage

mdl_to_ndat(mdl, target = c(), cond = list(), len = 100, method = median)

Arguments

Value

A data.frame with the variables specified by "target" being varied and the other variables being kept constant. The returned data.frame should be ready to be used for, e.g., predict.gam.

Author(s)

Motoki Saito, motoki.saito@uni-oldenburg.de

Examples

library(mgcv)
set.seed(534)
dat <- gamSim(verbose=FALSE)
model <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data=dat)
target_to_vary <- c('x0','x1')
condlist <- list('x2'=quantile(dat$x2, probs=c(0.25,0.75)))
ndat <- mdl_to_ndat(mdl=model, target=target_to_vary,
                    cond=condlist, len=4, method=median)
print(length(unique(ndat$x0))==4) # x0 is varied with length=4.
print(length(unique(ndat$x1))==4) # x1 is varied with length=4.
print(length(unique(ndat$x2))==2) # x2 is 25% or 75% quantiles.
print(length(unique(ndat$x3))==1) # x3 is fixed the median.

Contour plot from a data.frame with combinations of predictor values.

Description

This function takes a new data.frame which contains combinations of predictor values of interest (i.e., newdata or ndat) and returns a contour plot from the data.frame. "ndat" necessary for this function can be generated with gamutil::mdl_to_ndat and gamutil::add_fit.

Usage

ndat_to_contour(
  ndat,
  x,
  y,
  z,
  z.lwr = "lwr",
  z.upr = "upr",
  facet.col = NULL,
  facet.labeller = NULL,
  se = TRUE,
  break.interval = NULL,
  line.breaks = NULL,
  color.breaks = NULL,
  zlim = NULL,
  contour.labels = TRUE,
  contour.line.size = 0.5
)

Arguments

Value

A ggplot object of a contour plot with predicted values being colors (z-axis).

Author(s)

Motoki Saito, motoki.saito@uni-oldenburg.de

Examples

library(mgcv)
set.seed(534)
dat <- gamSim(eg=6,verbose=FALSE)
model <- gam(y ~ s(x0,by=fac) + s(x1,by=fac) + s(x2) + ti(x0,x1,by=fac),
             data=dat)
view <- c('x0','x1')
cnd  <- list(fac=c('1','4'))
ndat <- mdl_to_ndat(mdl=model, target=view, cond=cnd, len=10, method=median)
ndat <- add_fit(ndat, model, terms=view, cond=cnd, terms.size="min",
                ci.mult=1)
plt <- ndat_to_contour(ndat, x='x0', y='x1', z='fit', z.lwr='lwr',
                       z.upr='upr', facet.col='fac', se=TRUE)
print(plt)

Contour plot from a GAM model object.

Description

This function takes a gam/bam object and names of predictors of interest and draw a contour plot. Its usage is similar to itsadug::fvisgam and itsadug::pvisgam. The current version of this function produces "partially summed" effects of pertinent terms specified by the "view" argument (see examples).

Usage

plot_contour(
  mdl,
  view,
  cond = list(),
  summed = TRUE,
  axis.len = 50,
  terms.size = "min",
  se = TRUE,
  break.interval = NULL,
  contour.line.breaks = NULL,
  contour.color.breaks = NULL,
  zlim = NULL,
  facet.labeller = NULL,
  verbose = FALSE,
  contour.labels = TRUE,
  contour.line.size = 0.5,
  include.parametric = TRUE,
  joint.se = FALSE,
  too.far = NULL
)

Arguments

Value

A ggplot object, which is a contour line plot with predicted values as colors (z-axis).

Author(s)

Motoki Saito, motoki.saito@uni-oldenburg.de

Examples

library(mgcv)
set.seed(534)
dat <- gamSim(eg=6, verbose=FALSE)

# Without "by"
mdl1 <- gam(y ~ s(x0) + s(x1) + s(x2) + ti(x0,x1), data=dat)

# With "by"
mdl2 <- gam(y ~ s(x0,by=fac) + s(x1,by=fac) + s(x2) + ti(x0,x1,by=fac),
            data=dat)

# Summed effects (i.e., s(x0) + s(x1) + s(x2) + ti(x0,x1)
plt <- plot_contour(mdl1, view=c('x0','x1'), summed=TRUE)

# Partial effect (i.e., ti(x0,x1))
plt <- plot_contour(mdl1, view=c('x0','x1'), summed=FALSE, terms.size='min')

# The sum of pertinent partial effects (i.e., s((x0) + s(x1) + ti(x0,x1))
# with confidence interval contour lines.
plt <- plot_contour(mdl1, view=c('x0','x1'), summed=FALSE,
                    terms.size='medium')

# The sum of pertinent partial effects (i.e., s((x0) + s(x1) + ti(x0,x1))
# without confidence interval contour lines.
plt <- plot_contour(mdl1, view=c('x0','x1'), summed=FALSE,
                    terms.size='medium', se=FALSE)

# Summed effects for fac='1'
plt <- plot_contour(mdl2, view=c('x0','x1'), cond=list(fac='1'),
                    summed=TRUE)

# Partial effect (i.e., ti(x0,x1)) for fac='1'
plt <- plot_contour(mdl2, view=c('x0','x1'), cond=list(fac='1'),
                    summed=FALSE, terms.size='min')

# Summed effects for fac='1' and '2' in separate panels
plt <- plot_contour(mdl2, view=c('x0','x1'), cond=list(fac=c('1','2')),
                    summed=TRUE)

# Partial effects (i.e., ti(x0,x1)) for fac='1' and '2' in separate panels
plt <- plot_contour(mdl2, view=c('x0','x1'), cond=list(fac=c('1','2')),
                    summed=FALSE, terms.size='min')

Curve plot of a partial effect from a GAM model.

Description

Smooth/line counterpart to plot_contour. Builds a ggplot showing a fitted curve (with optional standard-error ribbon) for the partial effect of one continuous predictor, optionally split by a factor. Mirrors the argument conventions of plot_contour (summed, cond, terms.size, joint.se, ...) for symmetry.

Usage

plot_curve(
  mdl,
  view,
  cond = list(),
  summed = TRUE,
  axis.len = 100,
  terms.size = "min",
  se = TRUE,
  verbose = FALSE,
  include.parametric = TRUE,
  joint.se = FALSE
)

Arguments

Details

Two view configurations are supported in this version:

• one continuous predictor view = c("x") – a single line with an SE ribbon;

• one continuous + one categorical view = c("x", "f") (in either order) – one line per level of f, coloured by level.

When view contains a factor, the factor is automatically added to cond (with all levels) if it is not already present, so that add_fit's by-variable expansion has the levels it needs.

Value

A ggplot object.

Author(s)

Motoki Saito, motoki.saito@uni-oldenburg.de

Examples

library(mgcv)
set.seed(1)
n <- 400
d <- data.frame(x = rnorm(n),
                f = factor(sample(c("A","B","C"), n, TRUE)))
d$y <- d$x + ifelse(d$f == "A", 0.5*d$x, 0) + rnorm(n, 0, 0.5)
m <- bam(y ~ f + s(x, by = f, k = 3), data = d, method = "ML")
plot_curve(m, view = c("x", "f"), summed = FALSE,
           terms.size = "medium", joint.se = TRUE)

Plot a partial effect, dispatching by view-variable types.

Description

Convenience wrapper that picks between plot_contour and plot_curve based on the types of the variables named in view:

• two numeric -> plot_contour (2D contour plot);

• one numeric, or one numeric + one factor -> plot_curve (line plot, optionally split by factor).

Additional arguments are forwarded to whichever underlying function is selected. Arguments that the dispatched target does not accept (e.g. contour-specific arguments like too.far or zlim when dispatching to plot_curve) are silently dropped, so the same call site can be reused across model shapes.

Usage

plot_partial(mdl, view, ...)

Arguments

Value

A ggplot object.

Author(s)

Motoki Saito, motoki.saito@uni-oldenburg.de

Examples

library(mgcv)
set.seed(1)

# Two numeric view variables -> contour plot.
dat2 <- gamSim(eg=2, verbose=FALSE)$data
mdl_2num <- gam(y ~ s(x, z), data=dat2)
plot_partial(mdl_2num, view = c("x", "z"), summed = FALSE,
             terms.size = "medium", joint.se = TRUE, too.far = 0.10)

# One numeric + one factor -> curve plot, one line per factor level.
n <- 400
d  <- data.frame(x = rnorm(n),
                 f = factor(sample(c("A","B","C"), n, TRUE)))
d$y <- d$x + ifelse(d$f == "A", 0.5*d$x, 0) + rnorm(n, 0, 0.5)
mdl_num_fac <- bam(y ~ f + s(x, by = f, k = 3), data = d, method = "ML")
plot_partial(mdl_num_fac, view = c("x", "f"), summed = FALSE,
             terms.size = "medium", joint.se = TRUE)

Varying values for prediction

Description

For prediction with a regression model, you need to create a new data.frame to specify which combinations of predictors you would like to use for prediction. This function constitutes a part of the process and produces a sequence of values based on the vector provided through the argument "vec". If the vector is numeric, a vector of numeric values in the range between min(vec) and max(vec) with the length of "len" is returned. If the vector is character or factor, the sorted unique values of the elements in the vector are returned.

Usage

vary(vec, len = 100)

Arguments

Value

A vector of numeric or character (depending on the class of "vec" provided).

Author(s)

Motoki Saito, motoki.saito@uni-oldenburg.de

Examples

# The sorted unique values are returned for character/factor.
vec <- c(rep('A',2), rep('B',3), rep('C',1))
print(constant(vec)) # 'A', 'B', 'C'
# A equally-spaced numeric sequence for the length of "len" is
# returned for numeric, with the min and max being the min and
# max of the input vector (i.e., "vec")
set.seed(716)
vec <- rnorm(10)
print(vary(vec))
print(vary(vec, 4))