Type: Package
Title: Generalized Additive Models with Hyper Column
Version: 0.2.3
Description: Generalized additive models with a numeric hyper column. 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.3
Encoding: UTF-8
License: GPL-2
Language: en-US
URL: https://github.com/tingtingzhan/hyper.gam, https://tingtingzhan.quarto.pub/groupedhyperframe/bioinformatics_btaf430.html, https://tingtingzhan-groupedhyperframe.netlify.app/bioinformatics_btaf430.html
Depends: R (≥ 4.5), groupedHyperframe (≥ 0.3.0)
Imports: caret, cli, mgcv, nlme, parallel, plotly
Suggests: spatstat.geom, survival, htmlwidgets
NeedsCompilation: no
Packaged: 2026-03-02 15:42:21 UTC; tingtingzhan
Author: Tingting Zhan ORCID iD [aut, cre], Erjia Cui ORCID iD [ctb]
Maintainer: Tingting Zhan <tingtingzhan@gmail.com>
Repository: CRAN
Date/Publication: 2026-03-02 16:20:02 UTC

hyper.gam: Generalized Additive Models with Hyper Column

Description

Generalized additive models with a numeric hyper column. 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.

Author(s)

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

Other contributors:

See Also

Useful links:

xy-Correlation

Description

xy-Correlation

Usage

cor_xy(object, ...)

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

Arguments

object

a hyper_gam object

...

additional parameters, currently not in use

probs

numeric scalar or vector \tilde{p}, taking values between 0 and 1, see function quantile.

Details

..

Value

The S3 method cor_xy.hyper_gam() returns a numeric scalar or vector of correlation(s).

S3 Generic getData on Class gam

Description

S3 Generic getData on Class gam

Usage

## S3 method for class 'gam'
getData(object)

Arguments

object

a gam object

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

formula

formula, e.g., y~X, in which

data

data.frame

family

family object, see function gam for details. Default values are

  • mgcv::cox.ph() for Surv response y;

  • stats::binomial(link = 'logit') for logical response y;

  • stats::gaussian(link = 'identity') for double response y

nonlinear

logical scalar, whether to use nonlinear or linear functional model. Default FALSE

...

additional parameters for functions s and ti, most importantly k

Details

The 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

The 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

x

hyper_gam object

n

integer scalar, fineness of visualization, default 501L. See parameter n.grid of function vis.gam.

xlab, ylab

character scalars

zlab

character scalar, for function persp.hyper_gam

...

additional parameters, currently not in use

image_col

argument col of image.default

Value

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

The S3 method 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(3L, nrow(newdata))),
  qlim = range(X[is.finite(X)], newX[is.finite(newX)]),
  beta_col = "purple",
  surface_col = c("white", "lightgreen")
)

Arguments

...

one or more hyper_gam models based on a same data set.

sign_adjusted

logical scalar

newdata

see function predict.hyper_gam().

proj_xy

logical scalar, whether to show the projection of \hat{S}\big(p, Q_i(p)\big) (see sections Details and Value) to the (p,q)-plain, default TRUE

proj_xz

logical scalar, whether to show the projection of \hat{S}\big(p, Q_i(p)\big) to the (p,s)-plain, default TRUE

proj_beta

logical scalar, whether to show \hat{\beta}(p) on the (p,s)-plain when applicable, default TRUE

n

integer scalar, fineness of visualization, default 501L. See parameter n.grid of function vis.gam.

newid

integer scalar or vector, row indices of newdata to be visualized. Default 1:2, i.e., the first two test subjects. Use newid = NULL to disable visualization of newdata.

qlim

length-2 double vector, range on q-axis. Default is the range of X and X^{\text{new}} combined.

beta_col

character scalar, color of \hat{\beta(p)}

surface_col

length-2 character vector, color of the integrand surface(s), for lowest and highest surface values

Value

The 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

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

object

a hyper_gam object

k

integer scalar

mc.cores

integer scalar, see function mclapply

...

additional parameters, currently not in use

Value

The (pseudo) S3 method 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

object

an hyper_gam model

newdata

test hyperframe, with at least the response y^{\text{new}} and the double-hypercolumn X^{\text{new}} tabulated on the same grid as the training hypercolumn X. If missing, the training data object$data will be used.

sign_adjusted

logical scalar, default TRUE

sgn

(internal use) numeric scalar, either -1 or 1, the sign of cor_xy() return, to be used in the sign adjustment

...

additional parameters, currently not in use.

Details

The S3 method 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

The S3 method 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

x

numeric vector

center

function

scale

function

Details

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

Value

The 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

object

..

...

parameters of function cor_xy.hyper_gam()

Value

The S3 method 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

object

a hyper_gam model

...

additional parameters, currently not in use

Value

The S3 method update.hyper_gam() returns a hyper_gam model