Generic "G_estimate" dispatch

Description

Estimates covariance of random components. The related function for the random intercept flag ('G_estimate_randint') does not require a generic because the operations are the same for concurrent and non-concurrent models.

Usage

G_estimate(fmm, ...)

Arguments

Value

An estimation of the G matrix

Special case of estimating covariance of random components G(s1, s2)

Description

Estimates the covariance matrix G at Step 3. If the only random effect is an intercept, we can use a speedup.

Usage

G_estimate_randint(fmm, designmat, betaHat, silent = TRUE)

Arguments

Value

An estimation of the G matrix

Generic "G_generate" G matrix setup

Description

Creates the design matrix that allows for the estimation of the G matrix. Output related to "G_estimate" dispatch.

Usage

G_generate(fmm, ...)

Arguments

Value

A design matrix for G estimation.

Fast block diagonal generator, taken from Matrix package examples

Description

Copyright (C) 2016 Martin Maechler, ETH Zurich. Copied here for more convenient integration.

Usage

bdiag_m(lmat)

Arguments

Value

Block diagonal version of input

Estimate non-negative diagonal terms on G matrix

Description

Helper function for 'G_estimate'. Uses least squares under non-negativity constraints, mainly relying on 'nnls' capability from 'lsei'.

Usage

cov_nnls(mum, data, L, data_cov, betaHat, GTilde, non_neg = 0, silent = TRUE)

Arguments

Value

A new GTilde matrix with enforced non-negativity

Organize covariance matrices

Description

Read the data frame of variance-covariance interactiosn and organize the covariance matrices correctly. Finds indices to feed into 'cov_organize' function above

Usage

cov_organize_start(cov_vec)

Arguments

Value

List of relevant outputs

Machen et al. (2025) variable trial length data

Description

Data from an experiment where mice ran through a maze where they received either a strawberry milkshake (SMS) or water (H2O) reward. Mice entered the reward zone at variable times.

Usage

d2pvt

Format

A data frame with 1335 rows and 248 columns:

id

Unique mouse ID

session

Session

outcome

The outcome of the trial, either SMS or H2O

SMS

Redundant encoding for binary encoding of SMS reward

latency

Time, in seconds, for mouse tor each the reward

trial

Trial

photometry

Photometry recordings at time point

rewarded

Whether the mouse had been rewarded by time point

Source

Machen B, Miller SN, Xin A, Lampert C, Assaf L, Tucker J, Herrell S, Pereira F, Loewinger G, Beas S. The encoding of interoceptive-based predictions by the paraventricular nucleus of the thalamus D2+ neurons. bioRxiv (2025). doi:10.1101/2025.03.10.642469.

References

Machen B, Miller SN, Xin A, Lampert C, Assaf L, Tucker J, Herrell S, Pereira F, Loewinger G, Beas S. The encoding of interoceptive-based predictions by the paraventricular nucleus of the thalamus D2R+ neurons. bioRxiv [Preprint]. 2025 Aug 15:2025.03.10.642469. doi: 10.1101/2025.03.10.642469. PMID: 40161660; PMCID: PMC11952474.

Fast Univariate Inference for Longitudinal Functional Models

Description

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).

Usage

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,
  n_boots = 500,
  boot_type = NULL,
  seed = 1,
  subj_id = NULL,
  n_cores = NULL,
  caic = FALSE,
  randeffs = FALSE,
  non_neg = 0,
  MoM = 1,
  concurrent = FALSE,
  impute_outcome = FALSE,
  override_zero_var = FALSE,
  unsmooth = FALSE
)

Arguments

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).

Value

A list containing:

Author(s)

Erjia Cui ecui@umn.edu, Gabriel Loewinger gloewinger@gmail.com, Al W Xin axin@andrew.cmu.edu

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.

Examples

library(refund)

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

Jeong et al. (2022) licking behavior data

Description

Photometry recordings from head-fixed mice administered sucrose at random intervals. Observations are identified by subject ID, session, and trial number. Columns are downsampled for convenience.

Usage

lick

Format

A data frame with 2120 rows and 94 columns:

id

Unique mouse ID

session

Session

trial

Trial

lick_rate_050, lick_rate_100, lick_rate_150, lick_rate_200

The average licking rate 0.5, 1.0, 1.5, and 2.0 seconds after sucrose administration

iri

The inter-reward interval relative to the previous lick

photometry

Photometry recordings over the trial

lick

Whether a mouse was licking at a time point

Source

https://dandiarchive.org/dandiset/000351/draft Jeong H, Taylor A, Floeder JR, Lohmann M, Mihalas S, Wu B, Zhou M, Burke DA, Namboodiri VMK. Mesolimbic dopamine release conveys causal associations. Science. 2022 Dec 23;378(6626):eabq6740. doi: 10.1126/science.abq6740.

References

Jeong H, Taylor A, Floeder JR, Lohmann M, Mihalas S, Wu B, Zhou M, Burke DA, Namboodiri VMK. Mesolimbic dopamine release conveys causal associations. Science. 2022 Dec 23;378(6626):eabq6740. doi: 10.1126/science.abq6740. Epub 2022 Dec 23.

Generic "massmm" model fit

Description

Fits the model over the functional domain based on the object class.

Usage

massmm(fmm, ...)

Arguments

Value

Results depends on the dispatched method.

Create a new "fastFMM" object

Description

The class "fastFMM" (and its inheritors) contain parameters for fast univariate inference. The basic "fastFMM" object is equipped for non-concurrent model fitting.

Usage

new_fastFMM(
  formula,
  data,
  subj_id,
  argvals,
  family,
  residuals,
  caic,
  randeffs,
  var,
  analytic
)

Arguments

Details

Object creation populates fields relevant to later steps, such as the location of the functional domain in the data frame.

Value

A "fastFMM" object containing parameters for fitting a functional mixed model using the FUI scheme. The object contains each of the passed args ('formula, data, ..., analytic'), with the exception of 'var'. Additional entries returned are:

1. 'out_index': locations in 'data' where functional domain exists

2. 'argvals': either 'argvals' as passed (if bootstrap) or a vector '1:L' where 'L' is the size of the functional domain

Create a new "fastFMMconc" object

Description

Create an object that contains parameters for fast univariate inference for concurrent models.

Usage

new_fastFMMconc(
  formula,
  data,
  subj_id,
  argvals,
  family,
  residuals,
  caic,
  randeffs,
  var,
  analytic,
  fun_covariates
)

Arguments

Value

A "fastFMMconc" object containing parameters to fit a concurrent mixed model using the FUI scheme. This function is called within 'fui' if indicated by 'concurrent = TRUE'. Fields are shared with 'fastFMM' objects, with the addition of 'fun_covariates'.

Default FUI plotting

Description

Take a fitted fui object produced by fastFMM::fui() and plot the point estimates of fixed effects. When variance was calculated, the plot function also returns 95% pointwise and joint confidence intervals.

Usage

plot_fui(
  fuiobj,
  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
)

Arguments

Value

Plots of point estimates and CIs. If return = TRUE, also returns a list where each element is a data frame with the coefficient estimates and 95% confidence intervals (CIs).

Author(s)

Gabriel Loewinger gloewinger@gmail.com, Erjia Cui ecui@umn.edu, Al W Xin axin@andrew.cmu.edu

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.

Examples

library(refund)
set.seed(1)
DTI_use <- DTI[DTI$ID %in% sample(DTI$ID, 10),]
DTI_use <- cbind(DTI_use[, c("visit", "sex", "ID")], data.frame(DTI_use$cca))
fit_dti <- fui(
  cca ~ visit + sex + (1 | ID),
  data = DTI_use
)
plot_fui(fit_dti)

select_knots.R from refund package

Description

Copied from [select_knots](https://rdrr.io/cran/refund/src/R/select_knots.R) because the original is not exported for use.

Usage

select_knots(t, knots = 10, p = 3, option = "equally-spaced")

Arguments

Value

Vector of specified knots

Generic "unimm" model fitting

Description

Dispatches class-specific methods for fitting a single point during the univariate mixed model step.

Usage

unimm(fmm, ...)

Arguments

Value

Results depends on the dispatched method.

Analytic variance calculation

Description

Helper for 'fui'. Analytic calculation for Gaussian models.

Usage

var_analytic(
  fmm,
  mum,
  smoothed,
  MoM,
  non_neg,
  nknots_cov,
  seed,
  parallel,
  n_cores,
  silent
)

Arguments

Value

List of final outputs of 'fui'

Analytic variance calculation

Description

Helper for 'fui'. Bootstrapped variance calculation.

Usage

var_bootstrap(
  fmm,
  mum,
  nknots_min,
  nknots_min_cov,
  nknots_fpca,
  betaHat,
  data,
  L,
  n_boots,
  boot_type,
  seed,
  parallel,
  n_cores,
  smooth_method,
  splines,
  silent
)

Arguments

Value

List of final outputs of 'fui'

Parallel variance calculation

Description

A helper function for 'var_analytic' that calculations the variance elements of the covariance matrix.

Usage

var_parallel(fmm, ...)

Arguments

Value

Calculated variance at location s

Parallel variance calculation for non-concurrent models

Description

Calculate the variance of coefficients with index s.

Usage

## S3 method for class 'fastFMM'
var_parallel(fmm, mum, s, Z, RHat, HHat, id_list, obs_ind, res_template, ...)

Arguments

Value

List of entries at index 's' for XTV inverse, the variance of beta-tilde, and trimmed H-hat.