Package 'gam.hp'

Hierarchical Partitioning of Adjusted R2 and Explained Deviance for Generalized Additive Models (GAM and BAM)

Description

This function conducts hierarchical partitioning to calculate the individual contributions of each predictor towards total adjusted R2 and explained deviance for Generalized Additive Models fitted by either gam or bam in the mgcv package.

Usage

gam.hp(mod, iv = NULL, type = "dev", commonality = FALSE, data = NULL)

Arguments

mod	Fitted "gam" or "bam" model object from the mgcv package.
iv	Optional. A list specifying groups of predictor variables for assessing group-wise relative importance. Each element of the list should contain the names of variables belonging to a specific group, corresponding to the predictor names defined in the model (mod).
type	Character. The type of R-square for GAM/BAM models, either "dev" or "adjR2". "dev" represents the explained deviance, and "adjR2" represents the adjusted R-square. The default is "dev".
commonality	Logical; if TRUE, the function returns the results of commonality analysis (i.e., 2^N−1 fractions for N predictors). Default is FALSE.
data	Optional. The dataset used to fit the model. If not provided, the function will attempt to extract the data directly from the fitted mod object. This argument is mainly useful for bam models, where the model object may not always store the full dataset (especially when using large datasets or parallel fitting options).

Details

The function supports both gam and bam model objects. It decomposes the total explained deviance or adjusted R2 into unique and shared contributions of individual predictors or groups of predictors using hierarchical partitioning. The adjusted R2 and explained deviance values are extracted from summary.gam() or summary.bam().

Value

dev	The R2 (either explained deviance or adjusted R2) for the full model.
hierarchical.partitioning	A matrix containing the individual effects and the percentage contribution of each predictor to total explained deviance or adjusted R2.

Author(s)

Jiangshan Lai [email protected]

References

• Lai J., Tang J., Li T., Zhang A., Mao L. (2024). Evaluating the relative importance of predictors in Generalized Additive Models using the gam.hp R package. *Plant Diversity*, 46(4): 542–546. <DOI:10.1016/j.pld.2024.06.002>

• Lai J., Zhu W., Cui D., Mao L. (2023). Extension of the glmm.hp package to zero-inflated generalized linear mixed models and multiple regression. *Journal of Plant Ecology*, 16(6): rtad038. <DOI:10.1093/jpe/rtad038>

• Lai J., Zou Y., Zhang S., Zhang X., Mao L. (2022). glmm.hp: an R package for computing individual effect of predictors in generalized linear mixed models. *Journal of Plant Ecology*, 15(6): 1302–1307. <DOI:10.1093/jpe/rtac096>

• Lai J., Zou Y., Zhang J., Peres-Neto P. (2022). Generalizing hierarchical and variation partitioning in multiple regression and canonical analyses using the rdacca.hp R package. *Methods in Ecology and Evolution*, 13(4): 782–788. <DOI:10.1111/2041-210X.13800>

• Chevan, A. & Sutherland, M. (1991). Hierarchical partitioning. *The American Statistician*, 45, 90–96. <DOI:10.1080/00031305.1991.10475776>

• Nimon, K., Oswald, F. L. & Roberts, J. K. (2013). Yhat: Interpreting regression effects. R package version 2.0.0.

Examples

library(mgcv)

## --- Example 1: Using gam() ---
mod1 <- gam(Sepal.Length ~ s(Petal.Length) + s(Petal.Width) + Sepal.Width,
            data = iris)
summary(mod1)
gam.hp(mod1)
gam.hp(mod1, type = "adjR2")
gam.hp(mod1, commonality = TRUE)
iv <- list(env1 = c("s(Petal.Length)", "s(Petal.Width)"), env2 = "Sepal.Width")
gam.hp(mod1, iv, type = "adjR2")
gam.hp(mod1, iv, commonality = TRUE)

## --- Example 2: Using bam() ---
mod2 <- bam(Sepal.Length ~ s(Petal.Length) + s(Petal.Width) + Sepal.Width,
            data = iris)
summary(mod2)
gam.hp(mod2)
gam.hp(mod2, type = "adjR2")
gam.hp(mod2, commonality = TRUE)
## Explicitly specifying data (useful for bam)
gam.hp(mod2, data = iris)

---

Permutation Test of Hierarchical Partitioning for GAM Analysis

Description

Permutation Test of Hierarchical Partitioning for GAM Analysis

Usage

permu.gamhp(mod = NULL, iv = NULL, type = "dev", permutations = 10)

Arguments

mod	gam model generated by mgcv::gam()
iv	optional The relative importance of predictor groups will be assessed. The input for iv should be a list, where each element contains the names of variables belonging to a specific group. These variable names must correspond to the predictor variables defined in the model (mod).
type	The type of total explained variation, either "dev" or "adjR2", in which "dev" is deviance explained and "adjR2" is adjusted R-square, the default is "adjR2".
permutations	An integer; Number of permutations for computing p value of individual contribution for the randomized dataset.

Details

This function is a permutation test of hierarchical partitioning for gam analysis. It returns a matrix of I values (the individual contribution towards total explained variation) for all values from permutations randomizations. For each permutation, the values in each variable (i.e each column of iv) are randomized independently, and gam.hp is run on the randomized iv. As well as the randomized I matrix, the function returns a summary table listing the observed I values, the p value of I for the randomized dataset.

Value

a data.frame containing a summary table listing the observed individual contribution, the p value of individual contribution for the randomized dataset

Author(s)

Jiangshan Lai [email protected]

Examples

library(mgcv)
mod1 <- gam(Sepal.Length ~ s(Petal.Length) + s(Petal.Width) + Sepal.Width,data = iris)
permu.gamhp(mod=mod1,type="dev",permutations=10)
iv <- list(env1=c("s(Petal.Length)","s(Petal.Width)"),env2="Sepal.Width")
permu.gamhp(mod=mod1,iv,type="dev",permutations=10)

---

Plot for a gam.hp object

Description

Plot for a gam.hp object

Usage

## S3 method for class 'gamhp'
plot(x, plot.perc = FALSE, ...)

Arguments

x	A gam.hp object.
plot.perc	Logical;if TRUE, the bar plot (based on ggplot2 package) of the percentage to individual effects of variables towards total explained variation, the default is FALSE to show plot with original individual effects.
...	unused

Value

a ggplot object

Author(s)

Jiangshan Lai [email protected]

Examples

library(mgcv)
mod1 <- gam(Sepal.Length ~ s(Petal.Length) + s(Petal.Width) + Sepal.Width,data = iris)
plot(gam.hp(mod1))

---