Type:	Package
Title:	Generalized Additive Models with Hyper Column
Version:	0.1.2
Description:	Generalized additive models with a numeric hyper column tabulated on a common grid. Sign-adjustment based on the correlation of model prediction and a selected slice of the hyper column. Visualization of the integrand surface over the hyper column.
RoxygenNote:	7.3.2
Encoding:	UTF-8
License:	GPL-2
Depends:	R (≥ 4.5)
Language:	en-US
Imports:	caret, cli, mgcv, nlme, parallel, plotly, groupedHyperframe
Suggests:	knitr, quarto, rmarkdown, spatstat.geom, survival, matrixStats, htmlwidgets
VignetteBuilder:	quarto, knitr
NeedsCompilation:	no
Packaged:	2025-06-27 16:44:13 UTC; tingtingzhan
Author:	Tingting Zhan [aut, cre], Inna Chervoneva [aut], Erjia Cui [ctb]
Maintainer:	Tingting Zhan <tingtingzhan@gmail.com>
Repository:	CRAN
Date/Publication:	2025-06-27 17:00:08 UTC

hyper.gam: Generalized Additive Models with Hyper Column

Description

Generalized additive models with a numeric hyper column tabulated on a common grid. Sign-adjustment based on the correlation of model prediction and a selected slice of the hyper column. Visualization of the integrand surface over the hyper column.

Note

Help files of individual functions are intentionally suppressed in the pdf manual. Users are encouraged to get started with the vignettes.

Author(s)

Maintainer: Tingting Zhan tingtingzhan@gmail.com (ORCID)

Authors:

• Inna Chervoneva Inna.Chervoneva@jefferson.edu (ORCID)

Other contributors:

• Erjia Cui ecui@umn.edu (ORCID) [contributor]

xy-Correlation

Description

xy-Correlation

Usage

cor_xy(object, ...)

## S3 method for class 'gam'
cor_xy(object, probs = 0.5, ...)

Arguments

Details

..

Value

Function cor_xy.gam() returns a numeric scalar or vector of correlation(s).

gam with matrix predictor

Description

A generalized additive model gam with one-and-only-one matrix predictor.

Usage

hyper_gam(formula, data, family, nonlinear = FALSE, ...)

Arguments

Details

Function hyper_gam() fits a gam model of response y with matrix predictor X. This method was originally defined in the context of quantile. In the following text, the matrix predictor X is denoted as Q(p), where p is as.numeric(colnames(X)).

Linear quantile index, with a linear functional coefficient \beta(p),

\text{QI}=\displaystyle\int_0^1\beta(p)\cdot Q(p)\,dp

can be estimated by fitting a functional generalized linear model (FGLM, James, 2002) to exponential-family outcomes, or by fitting a linear functional Cox model (LFCM, Gellar et al., 2015) to survival outcomes.

Non-linear quantile index, with a bivariate twice differentiable function F(\cdot,\cdot),

\text{nlQI}=\displaystyle\int_0^1 F\big(p, Q(p)\big)\,dp

can be estimated by fitting a functional generalized additive model (FGAM, McLean et al., 2014) to exponential-family outcomes, or by fitting an additive functional Cox model (AFCM, Cui et al., 2021) to survival outcomes.

Value

Function hyper_gam() returns a hyper_gam object, which inherits from class gam.

Author(s)

Tingting Zhan, Erjia Cui

References

James, G. M. (2002). Generalized Linear Models with Functional Predictors, doi:10.1111/1467-9868.00342

Gellar, J. E., et al. (2015). Cox regression models with functional covariates for survival data, doi:10.1177/1471082X14565526

Mathew W. M., et al. (2014) Functional Generalized Additive Models, doi:10.1080/10618600.2012.729985

Cui, E., et al. (2021). Additive Functional Cox Model, doi:10.1080/10618600.2020.1853550

Visualize hyper_gam object using R package graphics

Description

Create perspective and contour plots of FR-index integrand using R package graphics.

End users are encouraged to use function integrandSurface() with plotly work horse.

Usage

## S3 method for class 'hyper_gam'
persp(
  x,
  n = 31L,
  xlab = "Percentages",
  ylab = "Quantiles",
  zlab = "Integrand of FR-index",
  ...
)

## S3 method for class 'hyper_gam'
contour(
  x,
  n = 501L,
  image_col = topo.colors(20L),
  xlab = "Percentages",
  ylab = "Quantiles",
  ...
)

Arguments

Value

Function persp.hyper_gam(), a method dispatch of S3 generic persp, does not have a return value.

Function contour.hyper_gam(), a method dispatch of S3 generic contour, does not have a return value

Integrand Surface(s) of Sign-Adjusted Quantile Indices hyper_gam

Description

An interactive htmlwidgets of the perspective plot for hyper_gam model(s) using package plotly.

Usage

integrandSurface(
  ...,
  sign_adjusted = TRUE,
  newdata = data,
  proj_xy = TRUE,
  proj_xz = TRUE,
  proj_beta = FALSE,
  n = 501L,
  newid = seq_len(min(5L, .row_names_info(newdata, type = 2L))),
  qlim = range(X, newX),
  axis_col = c("dodgerblue", "deeppink", "darkolivegreen"),
  beta_col = "purple",
  surface_col = c("white", "lightgreen")
)

Arguments

Value

Function integrandSurface() returns a pretty htmlwidgets created by R package plotly to showcase the perspective plot of the estimated sign-adjusted integrand surface \hat{S}(p,q).

If a set of training/test subjects is selected (via parameter newid), then

• the estimated sign-adjusted line integrand curve \hat{S}\big(p, Q_i(p)\big) of subject i is displayed on the surface \hat{S}(p,q);

• the quantile curve Q_i(p) is projected on the (p,q)-plain of the 3-dimensional (p,q,s) cube, if proj_xy=TRUE (default);

• the user-specified \tilde{p} is marked on the (p,q)-plain of the 3D cube, if proj_xy=TRUE (default);

• \hat{S}\big(p, Q_i(p)\big) is projected on the (p,s)-plain of the 3-dimensional (p,q,s) cube, if one and only one hyper_gam model is provided in in put argument ... and proj_xz=TRUE (default);

• the estimated linear functional coefficient \hat{\beta}(p) is shown on the (p,s)-plain of the 3D cube, if one and only one linear hyper_gam model is provided in input argument ... and proj_beta=TRUE (default).

Integrand Surface

The estimated integrand surface of quantile indices and non-linear quantile indices, defined on p\in[0,1] and q\in\text{range}\big(Q_i(p)\big) for all training subjects i=1,\cdots,n, is

\hat{S}_0(p,q) = \begin{cases} \hat{\beta}(p)\cdot q & \text{for QI}\\ \hat{F}(p,q) & \text{for nlQI} \end{cases}

Sign-Adjustment

Ideally, we would wish that, in the training set, the estimated linear and/or non-linear quantile indices

\widehat{\text{QI}}_i = \displaystyle\int_0^1 \hat{S}_0\big(p, Q_i(p)\big)dp

be positively correlated with a more intuitive quantity, e.g., quantiles Q_i(\tilde{p}) at a user-specified \tilde{p}, for the interpretation of downstream analysis, Therefore, we define the sign-adjustment term

\hat{c} = \text{sign}\left(\text{corr}\left(Q_i(\tilde{p}), \widehat{\text{QI}}_i\right)\right),\quad i =1,\cdots,n

as the sign of the correlation between the estimated quantile index \widehat{\text{QI}}_i and the quantile Q_i(\tilde{p}), for training subjects i=1,\cdots,n.

The estimated sign-adjusted integrand surface is \hat{S}(p,q) = \hat{c} \cdot \hat{S}_0(p,q).

The estimated sign-adjusted quantile indices \int_0^1 \hat{S}\big(p, Q_i(p)\big)dp are positively correlated with subject-specific sample medians (default \tilde{p} = .5) in the training set.

Note

The maintainer is not aware of any functionality of projection of arbitrary curves in package plotly. Currently, the projection to (p,q)-plain is hard coded on (p,q,s=\text{min}(s))-plain.

k-Fold Prediction of hyper_gam Model

Description

k-fold prediction of hyper_gam model.

Usage

kfoldPredict.hyper_gam(object, k, mc.cores = getOption("mc.cores"), ...)

Arguments

Value

Function kfoldPredict.hyper_gam() returns a numeric vector, with attributes for savvy developers

attr(.,'fold')

integer vector, indices of the i-th fold

attr(.,'sgn')

numeric vector of length-k, sign-adjustment for each fold

attr(.,'no_sadj')

numeric vector, predictions without sign adjustment

attr(.,'global_sadj')

numeric vector, predictions based on sign-adjustment by the complete data (instead of each fold)

Prediction of hyper_gam Model

Description

Prediction of hyper_gam model.

Usage

## S3 method for class 'hyper_gam'
predict(
  object,
  newdata = object$data,
  sign_adjusted = TRUE,
  sgn = if (sign_adjusted) sign(cor_xy(object, probs = 0.5)) else 1,
  ...
)

Arguments

Details

Function predict.hyper_gam() computes the sign-adjusted gam model prediction. The sign-adjustment ensures that the return is positively associated with the training hypercolumn X at the selected tabulating grid.

Value

Function predict.hyper_gam() returns a double vector.

Alternative scale Methods

Description

Alternative scale using median, IQR and mad.

Usage

scale_do(x, center, scale)

Arguments

Details

Function scale_do() performs scaling according to user-specified definition of center and scale.

Value

Function scale_do() returns a numeric vector of the same length as x.

Examples

set.seed(1315); x = rnorm(20)
x |> scale_do(center = median, scale = mad) 
x |> scale_do(center = median, scale = IQR) 

Sign Adjustment

Description

Sign Adjustment

Usage

sign_adjust(object, ...)

## S3 method for class 'hyper_gam'
sign_adjust(object, ...)

Arguments

Value

Function sign_adjust.hyper_gam() returns a numeric vector.

update a hyper_gam model

Description

update a hyper_gam model

Usage

## S3 method for class 'hyper_gam'
update(object, ...)

Arguments

Value

Function update.hyper_gam() returns a hyper_gam model