Title: Generate UpSet Plots of VP and HP Based on the ASV Concept
Version: 0.0.3
Maintainer: Jiangshan Lai <lai@njfu.edu.cn>
Description: Using matrix layout to visualize the unique, common, or individual contribution of each predictor (or matrix of predictors) towards explained variation on different models. These contributions were derived from variation partitioning (VP) and hierarchical partitioning (HP), applying the algorithm of "Lai et al. (2022) Generalizing hierarchical and variation partitioning in multiple regression and canonical analyses using the rdacca.hp R package.Methods in Ecology and Evolution, 13: 782-788 <doi:10.1111/2041-210X.13800>".
URL: https://github.com/laijiangshan/upset.hp
Depends: R (≥ 3.6.0)
Imports: MuMIn, vegan, glmm.hp, ggplot2, patchwork, grDevices
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Encoding: UTF-8
RoxygenNote: 7.3.1
Date: 2025-07-17
NeedsCompilation: no
Packaged: 2025-07-17 07:53:07 UTC; lai
Author: Jiangshan Lai ORCID iD [aut, cre], Yao Liu [aut], Bangken Ying [aut]
Repository: CRAN
Date/Publication: 2025-07-17 08:10:02 UTC

Visualization of VP and HP Using UpSet Diagram

Description

Visualization of variation partitioning (VP) and hierarchical partitioning (HP) with unlimited number of predictor variables (or matrices of predictors) using UpSet matrix layout.

Usage

upset.hp(
  vp,
  hp,
  plot.hp = TRUE,
  order.part = "effect",
  decreasing.part = TRUE,
  order.var = TRUE,
  decreasing.var = TRUE,
  cutoff = -1,
  nVar = 30,
  col.width = 0.6,
  pch.size = 3,
  line.lwd = 0.5,
  show.effect = TRUE,
  effect.cex = 2.7,
  title.cex = 10,
  axis.cex = 8,
  height.ratio = c(2, 1),
  width.ratio = c(1, 3),
  col = "nature"
)

Arguments

vp

A matrix, which contains the output of variation partitioning (i.e. commonality analysis) from rdacca.hp,glmm.hp,gam.hp,and phylolm.hp.

hp

A matrix, which contains the output of hierarchical partitioning from rdacca.hp,glmm.hp,gam.hp,and phylolm.hp.

plot.hp

The default is TRUE, which plots the individual effect for each predictor on left column diagram. If FALSE, compute and plot the sum of unique effect and common effect for each predictor.

order.part

How the VP components in matrix layout should be ordered. Options include "effect" (order the intersections by their effects) or "degree" (sort by the number of predictors involved in the intersection), default is "effect".

decreasing.part

How the intersections in order.part should be ordered. Default is TRUE, "effect" is decreasing (from greatest to least) or "degree" is increasing (from least to greatest).

order.var

The predictors in the matrix layout should be ordered by. Default is TRUE, which orders the predictors by their effects. IF FALSE, sort by the order of predictors in input data.

decreasing.var

If order.var=TRUE, how the predictors should be ordered. Default is TRUE, from greatest to least.

cutoff

Effects below cutoff will not be displayed, default is -1. Note: Negative effects due to adjustment of R-squared mean negligible contributions, but they are included in the computation of the total contribution of each predictor category.

nVar

Number of components in VP to plot, default is 30.

col.width

Width of bars in column diagram, default is 0.6.

pch.size

Size of points in matrix diagram, default is 3.

line.lwd

Width of lines in matrix diagram, default is 0.5.

show.effect

Show the relative importance of predictors (unique, common, or individual effects) above bars, default is TRUE.

effect.cex

Font size of the effects, default is 2.7.

title.cex

Font size of axis titles, default is 10.

axis.cex

Font size of axis labels, default is 8.

height.ratio

Ratio between matrix and top column diagram, default is c(2, 1).

width.ratio

Ratio between matrix and left column diagram, default is c(1, 3).

col

Character. Color palette name: "nature" (default), "science", "cell", "bw" (black-white), or "cvd" (color-blind friendly).

Details

upset.hp diagram is an extension of UpSet technique to and is used to visualize the object of rdacca.hp,glmm.hp,gam.hp,and phylolm.hp (Lai et al. 2022a,2022b,2023,2024; Liu et al. 2023). The matrix layout enables the effective representation of relative importance of predictors, such as the unique effects and common effects in VP, as well as additional summary statistics or individual effects in HP. upset.hp diagram could, in principle, allow visualization of any number of predictor variables or groups of predictor variables. But considering the interpretability of data, we would like to recommend that the number of predictors (or groups of predictors) no more than 7.

Value

Returns a ggplot2.

References

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:782-788.

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.,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>

Liu Y., Yu X., Yu Y., et al. (2023) Application of "rdacca. hp" R package in ecological data analysis: case and progress. Chinese Journal of Plant Ecology, 27:134-144.

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>

Examples

library(glmm.hp)
#upset for glmm.hp() in lm()
m2<-lm(mpg~wt+carb+cyl,mtcars)
vp <- glmm.hp(m2,commonality=TRUE)$commonality.analysis
hp <- glmm.hp(m2)$hierarchical.partitioning
upset.hp(vp, hp, col = "cvd")