FRindex {Qindex}R Documentation

Functional Regression Indices & Weights

Description

Functions explained in this documentation are,

FRindex()

to compute the functional regression indices and weights based on the functional predictors.

predict.FRindex()

to compute the predicted values based on functional regression indices and weights model.

FR_gam()

a helper function to fit a functional regression model using generalized additive models with integrated smoothness estimation (gam).

Usage

FRindex(formula, data, sign_prob = 0.5, ...)

FR_gam(
  formula,
  data,
  xarg = as.double(colnames(X)),
  family,
  knot_pct = 0.4,
  knot.value = ceiling(length(xarg) * knot_pct),
  ...
)

## S3 method for class 'FRindex'
predict(
  object,
  newdata = object@data,
  newX = newdata[[object@formula[[3L]]]],
  new_xarg = as.double(colnames(newX)),
  ...
)

Arguments

formula

a two-sided formula.

Left-hand-side

is the name of the response y. Supported types of responses are double, logical and Surv.

Right-hand-side

is the name of the tabulated double matrix X of functional predictor values. Each row of X represents the tabulated values for a subject. All rows/subjects are tabulated on a common grid xarg. Each column of X represents the tabulated values at a point on the common grid for each subject.

data

data.frame, with the response y and the tabulated functional predictor values X specified in formula. If the functional predictor is the quantile function, then data is preferably the returned object of clusterQp().

sign_prob

double scalar between 0 and 1, probability corresponding to the selected nearest-even quantile in xarg, which is used to define the sign of the functional regression weights. Default is .5, i.e., the nearest-even median of xarg

...

for function predict.FRindex() and helper function FR_gam(), these are currently not in use. For function FRindex(), see a detailed explanation in section Using ... in FRindex()

xarg

strictly increasing double vector, the common grid on which the functional predictor values X are tabulated

family

family object, the distribution and link function to be used in gam. Default family for Surv response is mgcv::cox.ph(), for logical response is binomial(link = 'logit'), for double response is gaussian(link = 'identity').

knot_pct

positive double scalar, percentage of the number of columns of X, to be used as knot.value. Default is 40\%. If knot.value is provided by the end-user, then knot_pct is ignored.

knot.value

positive integer scalar, number of knots (i.e., parameter k in the spline smooth function s) used in gam. Default is the ceiling of knot_pct of the column dimension of X

object

an FRindex object for the predict method, the returned object from function FRindex()

newdata

data.frame, with at least the tabulated functional predictor values X^{new} based on object@formula

newX

double matrix, functional predictor values X^{new} for a set of new subjects. Each row of X^{new} represents the tabulated values for a new subject. All rows/subjects are tabulated on a common grid new_xarg. Each column of X^{new} represents the tabulated values at a point on the common grid for each new subject.

new_xarg

strictly increasing double vector, the common grid on which the functional predictor values X^{new} are tabulated. The length of new_xarg does not need to be the same as the length of object@xarg, but they must share the same range.

Details

Functional regression indices & weights model

Function FRindex() defines and calculates the functional regression indices and weights in the following steps.

  1. Fit a functional regression model to the response y using the functional predictor X, with tabulated tabulated on a same grid xarg for all subjects, using helper function FR_gam()

  2. Select one point in the tabulating grid xarg. For one-dimensional domain, we select the nearest-even quantile of the tabulating grid xarg, corresponding to the user-specified probability sign_prob. Default sign_prob = .5 indicates the median of xarg.

  3. Obtain the fitted coefficient function \hat\beta(x), tabulated on the grid xarg, using internal helper function gam2beta()

  4. Calculate the integral of the product of the fitted coefficient function \hat\beta(x) (from Step 3) and the functional predictor values X, using the trapzoid rule

  5. Obtain the sign of the correlation between

    • the subject-specific functional predictor values, at the selected quantile of xarg (from Step 2), and

    • the subject-specific integrals from Step 4

Functional regression weights (slot ⁠@weight⁠) are the tabulated weight function on the grid xarg. These weights are defined as the product of sign (from Step 5) and \hat\beta(x) (from Step 3).

Functional regression indices (slot ⁠@index⁠) are defined as the product of sign (from Step 5) and intg (from Step 4). Multiplication by sign is required to ensure that the resulting functional regression indices are positively associated with the functional predictor values at the selected quantile of xarg (from Step 2).

Predict method for functional regression indices & weights

Function predict.FRindex() computes functional regression indices and weights based on the tabulated functional predictors X^{new} in a new sets of subjects. It's important that the new tabulation grid new_xarg must have the same range as the model tabulation grid object@xarg. Then,

  1. Obtain the fitted coefficient function \hat\beta(x^{new}) of the existing generalized additive model object@gam, but tabulated on the new grid new_xarg, using internal helper function gam2beta()

  2. Calculate the integral of the product of the fitted coefficient function \hat\beta(x^{new}) (from Step 1) and the new functional predictor values X^{new}, using the trapzoid rule

Predicted functional regression weights are the tabulated weight function on the new grid new_xarg. These weights are defined as the product of object@sign and \hat\beta(x^{new}) (from Step 1).

Predicted functional regression indices are defined as the product of object@sign and intg (from Step 2). Multiplication by object@sign is required to ensure that the resulting functional regression indices are positively associated with the functional predictor values at the selected quantile of object@xarg.

Value

Functional regression indices & weights model

Function FRindex() returns an S4 FRindex object. The slots of S4 class FRindex are described in section Slots.

Predict method for functional regression indices & weights

Function predict.FRindex() returns a double vector, which is the predicted functional regression indices. The returned object contains an attributes

attr(,'weight')

double vector, the predicted functional regression weights

Slots

formula,data,xarg

see explanations in section Arguments

gam

gam object, the returned object of helper function FR_gam()

sign

double scalar of either 1 or -1, see Step 5 in section Details on function FRindex()

index,weight

double vectors, functional regression indices and functional regression weights, respectively. See section Details on function FRindex()

Using ... in FRindex()

Function FRindex() passes the parameters xarg, family, knot_pct and knot.value into helper function FR_gam() through three dots ....

The most important parameter among them is xarg. The default argument of the parameter xarg comes from the column names of the matrix of tabulated functional predictor values X. This is particularly convenient when the functional predictor is the quantile function, and data is the returned object of function clusterQp().

Both FRindex() and helper function FR_gam() accept user-provided xarg. In such case, the provided values will be checked such that

  1. xarg is a numeric vector without missingness

  2. length of xarg is the same as the number of columns of matrix X

  3. xarg must be strictly sorted (see is.unsorted)

Otherwise, an error message will be returned.

Details of Helper Function

Helper function FR_gam() uses gam to estimate the functional coefficient by fitting functional regression model.

Returns of Helper Functions

Helper function FR_gam() returns a gam object, with additional attributes

attr(,'X')

double matrix of tabulated functional predictor values X

attr(,'xarg')

double vector, see explanation of parameter xarg

References

Cui, E., Crainiceanu, C. M., & Leroux, A. (2021). Additive Functional Cox Model. Journal of Computational and Graphical Statistics. doi:10.1080/10618600.2020.1853550

Gellar, J. E., Colantuoni, E., Needham, D. M., & Crainiceanu, C. M. (2015). Cox regression models with functional covariates for survival data. Statistical Modelling. doi:10.1177/1471082X14565526

Examples

library(survival)

pt = unique(Ki67$PATIENT_ID)
length(pt) # 622
# set.seed if necessary
train_pt = sample(pt, size = 500L)
Ki67q = clusterQp(Marker ~ ., data = Ki67, exclude = c('tissueID','inner_x','inner_y'))
train_q = subset(Ki67q, PATIENT_ID %in% train_pt)
test_q = subset(Ki67q, !(PATIENT_ID %in% train_pt))
train_q$Marker = log1p(train_q$Marker)
test_q$Marker = log1p(test_q$Marker)

FRi = FRindex(Surv(RECFREESURV_MO, RECURRENCE) ~ Marker, data = train_q)
FRi@index # functional regression index
FRi@weight # functional regression weights
head(show(FRi)) # append `FRi` to the data

(FRi_test = predict(FRi, newdata = test_q))

FRi_train = predict(FRi)
# stopifnot(identical(FRi@index, c(FRi_train)), 
#  identical(FRi@weight, attr(FRi_train, 'weight')))

# set.seed if necessary
Ki67bbc_v2 = BBC_dichotom(Surv(RECFREESURV_MO, RECURRENCE) ~ NodeSt + Tstage, 
  data = data.frame(train_q, FRi_std = std_IQR(FRi_train)), 
  dichotom = ~ FRi_std)
summary(Ki67bbc_v2)

Ki67q = clusterQp(Marker ~ ., data = Ki67, exclude = c('tissueID','inner_x','inner_y'))
Ki67q$Marker = log1p(Ki67q$Marker)

library(survival)
FR_gam(Surv(RECFREESURV_MO, RECURRENCE) ~ Marker, data = Ki67q)
[Package Qindex version 0.1.5 Index]