fui function

Fast Univariate Inference for Longitudinal Functional Models

Fit a function-on-scalar regression model for longitudinal functional outcomes and scalar predictors using the Fast Univariate Inference (FUI) approach (Cui et al. 2022; Loewinger et al. 2024).

fui(
  formula,
  data,
  family = "gaussian",
  var = TRUE,
  analytic = TRUE,
  parallel = FALSE,
  silent = FALSE,
  argvals = NULL,
  nknots_min = NULL,
  nknots_min_cov = 35,
  smooth_method = "GCV.Cp",
  splines = "tp",
  design_mat = FALSE,
  residuals = FALSE,
  num_boots = 500,
  boot_type = NULL,
  seed = 1,
  subj_ID = NULL,
  num_cores = 1,
  caic = FALSE,
  REs = FALSE,
  non_neg = 0,
  MoM = 1,
  impute_outcome = FALSE
)

Arguments

• formula: Two-sided formula object in lme4 formula syntax. The difference is that the response need to be specified as a matrix instead of a vector. Each column of the matrix represents one location of the longitudinal functional observations on the domain.
• data: A data frame containing all variables in formula
• family: GLM family of the response. Defaults to gaussian.
• var: Logical, indicating whether to calculate and return variance of the coefficient estimates. Defaults to TRUE.
• analytic: Logical, indicating whether to use the analytic inferenc approach or bootstrap. Defaults to TRUE.
• parallel: Logical, indicating whether to do parallel computing. Defaults to FALSE.
• silent: Logical, indicating whether to show descriptions of each step. Defaults to FALSE.
• argvals: A vector containing locations of observations on the functional domain. If not specified, a regular grid across the range of the domain is assumed. Currently only supported for bootstrap (analytic=FALSE).
• nknots_min: Minimal number of knots in the penalized smoothing for the regression coefficients. Defaults to NULL, which then uses L/2 where L is the dimension of the functional domain.
• nknots_min_cov: Minimal number of knots in the penalized smoothing for the covariance matrices. Defaults to 35.
• smooth_method: How to select smoothing parameter in step 2. Defaults to "GCV.Cp"
• splines: Spline type used for penalized splines smoothing. We use the same syntax as the mgcv package. Defaults to "tp".
• design_mat: Logical, indicating whether to return the design matrix. Defaults to FALSE
• residuals: Logical, indicating whether to save residuals from unsmoothed LME. Defaults to FALSE.
• num_boots: Number of samples when using bootstrap inference. Defaults to 500.
• boot_type: Bootstrap type (character): "cluster", "case", "wild", "reb", "residual", "parametric", "semiparametric". NULL defaults to "cluster" for non-gaussian responses and "wild" for gaussian responses. For small cluster (n<=10) gaussian responses, defaults to "reb".
• seed: Numeric value used to make sure bootstrap replicate (draws) are correlated across functional domains for certain bootstrap approach
• subj_ID: Name of the variable that contains subject ID.
• num_cores: Number of cores for parallelization. Defaults to 1.
• caic: Logical, indicating whether to calculate cAIC. Defaults to FALSE.
• REs: Logical, indicating whether to return random effect estimates. Defaults to FALSE.
• non_neg: 0 - no non-negativity constrains, 1 - non-negativity constraints on every coefficient for variance, 2 - non-negativity on average of coefficents for 1 variance term. Defaults to 0.
• MoM: Method of moments estimator. Defaults to 1.
• impute_outcome: Logical, indicating whether to impute missing outcome values with FPCA. This has not been tested thoroughly so use with caution. Defaults to FALSE.

Returns

A list containing: - betaHat: Estimated functional fixed effects

• argvals: Location of the observations

• betaHat.var: Variance estimates of the functional fixed effects (if specified)

• qn: critical values used to construct joint CI

• ...: ...

Details

The FUI approach comprises of three steps:

1. Fit a univariate mixed model at each location of the functional domain, and obtain raw estimates from massive models;
2. Smooth the raw estimates along the functional domain;
3. Obtain the pointwise and joint confidence bands using an analytic approach for Gaussian data or Bootstrap for general distributions.

For more information on each step, please refer to the FUI paper by Cui et al. (2022). For more information on the method of moments estimator applied in step 3, see Loewinger et al. (2024).

Examples

library(refund)

## random intercept only
set.seed(1)
DTI_use <- DTI[DTI$ID %in% sample(DTI$ID, 10),]
fit_dti <- fui(
  cca ~ case + visit + sex + (1 | ID),
  data = DTI_use
)

References

Cui, E., Leroux, A., Smirnova, E., Crainiceanu, C. (2022). Fast Univariate Inference for Longitudinal Functional Models. Journal of Computational and Graphical Statistics, 31(1), 219-230.

Loewinger, G., Cui, E., Lovinger, D., Pereira, F. (2024). A Statistical Framework for Analysis of Trial-Level Temporal Dynamics in Fiber Photometry Experiments. eLife, 95802.

Author(s)

Erjia Cui ecui@umn.edu , Gabriel Loewinger gloewinger@gmail.com