Title: Fast Functional Generalized Estimating Equations via a One-Step Estimator
Version: 0.1.0
Description: Fits functional generalized estimating equations for longitudinal functional outcomes and covariates using a one-step estimator that is fast even for large cluster sizes or large numbers of clusters. The package supports quasi-likelihoods derived from a range of families, common link functions, and several working correlation structures. Uncertainty quantification is based on sandwich variance estimators and bootstrap procedures that remain valid even when the working correlation is incorrectly specified. The package provides an implementation of the method described in Loewinger et al. (2025) https://pmc.ncbi.nlm.nih.gov/articles/PMC12306803/. For irregularly spaced AR(1) precision matrices, the package can optionally use the archived package 'irregulAR1'; if needed, it can be obtained from the CRAN Archive at https://cran.r-project.org/src/contrib/Archive/irregulAR1/.
License: GPL (≥ 3)
Encoding: UTF-8
RoxygenNote: 7.3.3
Depends: R (≥ 4.2)
Imports: data.table, ggplot2, gridExtra, MASS, Matrix, mgcv, refund, Rfast, SuperGauss
Suggests: irregulAR1, knitr, rmarkdown, sanic, Rcpp, RcppArmadillo
VignetteBuilder: knitr
URL: https://github.com/gloewing/fastFGEE
BugReports: https://github.com/gloewing/fastFGEE/issues
NeedsCompilation: no
Packaged: 2026-04-01 18:37:49 UTC; loewingergc
Author: Gabriel Loewinger ORCID iD [aut, cre]
Maintainer: Gabriel Loewinger <gloewinger@gmail.com>
Repository: CRAN
Date/Publication: 2026-04-08 19:10:22 UTC

fastFGEE: Fast Functional Generalized Estimating Equations

Description

Fits functional generalized estimating equations (fGEE) for longitudinal functional outcomes using a one-step estimator.

Details

The main user-facing functions are fgee and fgee.plot.

Optional packages

AI-assisted development

Portions of the package were developed with assistance from large language models. All code was reviewed, tested, and edited by the human author(s), who take responsibility for the package.

Author(s)

Maintainer: Gabriel Loewinger gloewinger@gmail.com (ORCID)

See Also

Useful links:

Internal: compute eta = X %*% beta with optional "accumulate" to avoid dense X

Description

Internal: compute eta = X %*% beta with optional "accumulate" to avoid dense X

Usage

.dt_linpred(
  dt,
  xcols,
  beta,
  out = "eta",
  method = c("accumulate", "matrix"),
  return = c("dt", "vector")
)

Simulated longitudinal functional example data

Description

A simulated dataset used in examples and testing for fastFGEE. The object d is a data frame containing a functional response stored in an AsIs matrix column together with a cluster identifier, two scalar covariates, and a longitudinal time variable.

Usage

data(d)

Format

A data frame with 5 variables:

Y

An AsIs matrix-valued column containing the functional response. In the included example, the matrix has 100 columns named Y_1 to Y_100.

ID

Cluster identifier.

X1

First scalar covariate.

X2

Second scalar covariate.

time

Longitudinal time variable.

Details

This dataset is intended for package examples, vignettes, and quick testing of fgee. It represents a simulated binary-response setting on a common functional grid.

Source

Simulated for the package examples.

Fits functional generalized estimating equations (fGEE) for longitudinal functional outcomes using a one-step estimator, with optional fully iterated final estimation.

Description

Fits functional generalized estimating equations (fGEE) for longitudinal functional outcomes using a one-step estimator, with optional fully iterated final estimation.

Usage

fgee(
  formula,
  data,
  cluster,
  family,
  corr_fn = "ar1",
  corr_long = "ar1",
  time = NULL,
  long.dir = TRUE,
  var.type = "sandwich",
  pffr.mod = NULL,
  knots = NULL,
  bs = "bs",
  cv = "fastkfold",
  cv.grid = NULL,
  exact = FALSE,
  rho.smooth = FALSE,
  joint.CI = "wild",
  gee.fit = TRUE,
  linpred_method = c("accumulate", "matrix"),
  clip_mu = 0,
  m.pffr = c(2, 1),
  check_alignment = TRUE,
  max.iter = 1,
  tune.method = c("one-step", "fully-iterated"),
  boot.samps = 3000,
  ...
)

Arguments

formula

A model formula. The left-hand side should be a functional response stored as a matrix-like column (typically wrapped in I()).

data

A data frame containing the variables in formula.

cluster

Name of the cluster identifier column.

family

A family object or family name understood by refund::pffr().

corr_fn

Working correlation in the functional direction. One of "independent", "exchangeable", "ar1", or "fpca".

corr_long

Working correlation in the longitudinal direction. One of "independent", "exchangeable", or "ar1".

time

Optional name of the longitudinal ordering variable.

long.dir

Logical; retained for backwards compatibility.

var.type

Variance estimator. One of "sandwich", "fastboot", or "boot". For bootstraping, we recommend "fastboot" over "boot" because it is more thoroughly tested.

pffr.mod

Optional fitted refund::pffr() object to use as the initial estimator.

knots

Number of spline knots for the initial pffr() fit.

bs

Basis type passed to refund::pffr().

cv

Cross-validation mode used for smoothing parameter selection.

cv.grid

Optional grid (or staged grids) of smoothing parameters.

exact

Logical; for Gaussian identity-link models, use the exact penalized weighted least-squares update.

rho.smooth

Logical; smooth pointwise correlation estimates over the relevant index when applicable.

joint.CI

Logical or character controlling joint confidence intervals.

gee.fit

Logical; if FALSE, return uncertainty quantification around the initial fit without the GEE update.

linpred_method

Method used to form linear predictors.

clip_mu

Lower bound used for numerical stabilization of fitted means.

m.pffr

Penalty order specification passed to refund::pffr().

check_alignment

Logical; check alignment between the wide data and the pffr() long representation.

max.iter

Maximum number of GEE iterations. 1 gives the one-step fit.

tune.method

Smoothing-parameter tuning method.

boot.samps

Number of bootstrap replicates used when applicable.

...

Additional arguments reserved for future use.

Value

A "fgee1step" object. pffr_initial.fit contains the initial fit refund::pffr object. vb contains the variance/covariance matrix for the coefficient estimates (sandwich or bootstrap-based). qn contains the joint CI quantiles. di and \ wi are lists of length N, with the updated cluster-specific estimating equation and hessian terms (without the penalty).

Author(s)

Gabriel Loewinger gloewinger@gmail.com

References

Gabriel Loewinger, Alex W. Levis, Erjia Cui, and Francisco Pereira. (2025). Fast Penalized Generalized Estimating Equations for Large Longitudinal Functional Datasets. arXiv:2506.20437.

Examples


library(fastFGEE)
data("d", package = "fastFGEE")
fit <- fgee(
 formula = Y ~ X1 + X2,
 data = d,
 cluster = "ID",
 family = binomial(link = "logit"),
 time = "time",
 corr_long = "exchangeable",
 corr_fn = "independent")

 fgee.plot(fit)

Plot coefficient estimates from a fitted fastFGEE model

Description

Produces coefficient plots with pointwise and joint confidence intervals when available.

Usage

fgee.plot(
  fit,
  num_row = NULL,
  xlab = "Functional Domain",
  title_names = NULL,
  ylim = NULL,
  align_x = NULL,
  x_rescale = 1,
  y_val_lim = 1.1,
  y_scal_orig = 0.05,
  return = FALSE,
  terms.plot = TRUE,
  all.terms = TRUE,
  int.uncertainty = FALSE
)

Arguments

fit

A fitted object returned by fgee.

num_row

Number of rows used when arranging plots.

xlab

X-axis label.

title_names

Optional replacement titles for coefficient plots.

ylim

Optional y-axis limits.

align_x

Optional value used to re-center the x-axis.

x_rescale

Optional x-axis rescaling factor.

y_val_lim

Expansion factor for the upper y-axis limit.

y_scal_orig

Expansion factor for the lower y-axis limit.

return

Logical; if TRUE, return the plotting data instead of only drawing the plots.

terms.plot

Logical; retained for backwards compatibility.

all.terms

Logical; retained for backwards compatibility.

int.uncertainty

Logical; retained for backwards compatibility.

Value

Invisibly returns a list of plotting data frames when return = TRUE; otherwise draws plots.

Internal: get variance / mu' / linkinv for a family

Description

Internal: get variance / mu' / linkinv for a family

Usage

gee_family_fns(
  family,
  link = NULL,
  dispersion = NULL,
  theta = NULL,
  precision = NULL,
  zi_prob = NULL,
  clamp_eps = 1e-08,
  varFn = NULL,
  muprimeFn = NULL,
  linkinvFn = NULL,
  ...
)