integrandSurface: Integrand Surface(s) of Sign-Adjusted Quantile Indices Qindex

In Qindex: Continuous and Dichotomized Index Predictors Based on Distribution Quantiles

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

Description

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

Usage

integrandSurface(
  ...,
  newdata = data,
  proj_Q_p = TRUE,
  proj_S_p = TRUE,
  proj_beta = TRUE,
  n = 501L,
  newid = seq_len(min(50L, .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

...	one or more Qindex models based on a same training set.
newdata	data.frame, with at least the response y^{\text{new}} and the double matrix of functional predictor values X^{\text{new}} of the test set. The predictor X^{\text{new}} are tabulated on the same p-grid as the training functional predictor values X. If missing, the training set will be used.
proj_Q_p	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_S_p	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.
axis_col	length-3 character vector, colors of the (p,q,s) axes
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

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_Q_p=TRUE (default);

• the user-specified \tilde{p} is marked on the (p,q)-plain of the 3D cube, if proj_Q_p=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 Qindex model is provided in in put argument ... and proj_S_p=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 Qindex model is provided in input argument ... and proj_beta=TRUE (default).

Integrand Surface

The quantile index (QI),

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

with a linear functional coefficient \beta(p) 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. More flexible non-linear quantile index (nlQI)

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

with a bivariate twice differentiable function F(\cdot,\cdot) 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.

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.

References

James, G. M. (2002). Generalized Linear Models with Functional Predictors, \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1111/1467-9868.00342")}

Gellar, J. E., et al. (2015). Cox regression models with functional covariates for survival data, \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1177/1471082X14565526")}

Mathew W. M., et al. (2014) Functional Generalized Additive Models, \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1080/10618600.2012.729985")}

Cui, E., et al. (2021). Additive Functional Cox Model, \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1080/10618600.2020.1853550")}

Examples

# see ?`Qindex-package`

Qindex documentation built on April 4, 2025, 2:14 a.m.