fcr {fcr}

Fit Functional Concurrent Regression

Description

This function implements functional concurrent regression for sparse functional responses with both functional and scalar covariates. This function is a wrapper for mgcv's gam/bam.

Usage

fcr(formula, argvals, subj, argvals.new = NULL, data = NULL, niter = 1,
  sp = FALSE, nPhi = NULL, use_bam = FALSE, discrete = FALSE,
  face.args = list(knots = 12, lower = -3, pve = 0.95), ...)

Arguments

formula

formula will accept any input formula which is valid for gam. The formula should only include terms not associated with the random function intercept b_i(t_ij). See Examples.

argvals

a string indicating the functional domain variable name in data

subj

a string indicating the unique subject identifier name in data

argvals.new

new values of the functional domanin to predict using face.sparse, optional if one desires to predict at points of the functional domain not included in the data fitting procedure, they must be supplied in this argument.

data

dataframe including all variables of interest. Must not have any missing data for variables used in model fitting. data must also not contain any variables named: "g", "phi" followed by any numbers, or "sp" followed by any numbers. These names are reserved for the fitting procedure.

niter

number of times to iterate the covariance estimation

sp

logical arguement indicating whether smoothing parameters for random effects should be supplied to gam or bam using estimates from face.sparse (TRUE), or whether smoothing parameters for random effects should be estimated by mgcv (FALSE). Defaults to FALSE.

nPhi

number of random effects to include in final model (i.e. number of eigenfunctions of the covariance function). Default value (NULL) results in the use of all estimated random effects.

use_bam

logical argument indicating whether to use gam or bam. For moderate or large number of eigenfunctions it is recommended to use bam.

discrete

logical argument indicating whether whether to supple discrete = TRUE argument to bam. This argument may reduce computation time, but is currently listed as “experimental". Not available when use_bam = FALSE. Defaults to FALSE.

face.args

list of arguments to pass to face.sparse. Can not pass the arguments “data", “newdata", “center" or “argvals.new" as these are determined by the procedure.

...

arguments to be passed to mgcv::gam()/bam()

Details

The models fit are of the form

y = f_0(t_{ij}) + f_1(t_{ij})X_{ij} + ... + b_i(t_{ij}) + \epsilon_{ij}

Note that this function will accept any valid formula for gam/bam. However, only the identity link function is available at this time. See the package vignettes for additional descriptions of dynamic prediction and the class of models fit by this function.

Value

An object of class fcr containing five elements

fit

An object corresponding to the fitted model from the mgcv package

face.object

An object corresponding to the estimated covariance features

runtime

Model fitting time

argvals

Character scalar corresponding the name of the functional domain variable

runtime

logical scalar corresponding to sp argument used in model fitting

References

Jaganath D, Saito M Giman RH Queirox DM, Rocha GA, Cama V, Cabrera L, Kelleher D, Windle HJ, Crabtree JE, Jean E, Checkley W. First Detected Helicobacter pylori Infection in Infancy Modifies the Association Between Diarrheal Disease and Childhood Growth in Peru. Helicobacter (2014); 19:272-297.

Leroux A, Xiao L, Crainiceanu C, Checkley W (2017). Dynamic prediction in functional concurrent regression with an application to child growth.

Xiao L, Li C, Checkley W, Crainiceanu C. Fast covariance estimation for sparse functional data. Statistics and Computing, (2017).

Examples

data <- content
## smoothing parameters
k <- 12  # number of interior knots for fpca (results in k + 3 basis functions)
K <- 15 # dimenson of smooth for time varying coefficients

## functional domain where we need predictions
tnew <- sort(unique(data$argvals))

###########################################
## Step 1: Smooth time-varying covariate ##
###########################################
dat.waz <- data.frame("y" = data$waz, "subj" = data$subj, argvals = data$argvals)
fit.waz <- face.sparse(dat.waz, newdata = dat.waz, knots = k, argvals.new = tnew)
data$wazPred <- fit.waz$y.pred


#####################
## Step 2: Fit fcr ##
#####################
fit <- fcr(formula = Y ~ s(argvals, k=K, bs="ps") +
                         s(argvals, by=Male, k=K, bs="ps") +
                         s(argvals, by=wazPred, bs="ps"),
           argvals = "argvals", subj="subj", data=data, use_bam=TRUE, argvals.new=tnew,
           face.args = list(knots=k, pve=0.99))

## plot covariance features
plot(fit, plot.covariance=TRUE)

## plot coefficient functions and qq plots for random effects
plot(fit)

########################
## Step 3: Prediction ##
########################
## data frames for in-sample and dynamic predictions
data_dyn <- data_in <- data

## change subject IDs to values not used in model fitting
## for dynamic prediction
data_dyn$subj <- data_dyn$subj + 1000

## make all observations beyond 0.5 NA in both data frames
## and dynamically predict the concurrent covariate in
## dynamic prediction
inx_na <- which(data_dyn$argvals > 0.5)
data_dyn$Y[inx_na] <- data_dyn$waz[inx_na] <- NA
data_dyn$wazPred <- predict(fit.waz,
                            newdata= data.frame("subj" = data_dyn$subj,
                                                "argvals" = data_dyn$argvals,
                                                "y" = data_dyn$Y))$y.pred

data_in$Y[inx_na]  <- NA


## in sample and dynamic predictions on the same subjects
insample_preds  <- predict(fit, newdata = data)
dynamic_preds   <- predict(fit, newdata = data_dyn)