mface_cyc {gmfamm}

Multilevel functional principal components analysis with fast covariance estimation

Description

Decompose dense or sparse multilevel functional observations using multilevel functional principal component analysis with the fast covariance estimation approach.

Usage

mface_cyc(
  Y,
  id,
  visit = NULL,
  twoway = TRUE,
  weight = "obs",
  argvals = NULL,
  pve = 0.99,
  npc = NULL,
  p = 3,
  m = 2,
  knots = 35,
  silent = TRUE
)

Arguments

Y

A multilevel functional dataset on a regular grid stored in a matrix. Each row of the data is the functional observations at one visit for one subject. Missingness is allowed and need to be labeled as NA. The data must be specified.

id

A vector containing the id information to identify the subjects. The data must be specified.

visit

A vector containing information used to identify the visits. If not provided, assume the visit id are 1,2,... for each subject.

twoway

Logical, indicating whether to carry out twoway ANOVA and calculate visit-specific means. Defaults to TRUE.

weight

The way of calculating covariance. weight = "obs" indicates that the sample covariance is weighted by observations. weight = "subj" indicates that the sample covariance is weighted equally by subjects. Defaults to "obs".

argvals

A vector containing observed locations on the functional domain.

pve

Proportion of variance explained. This value is used to choose the number of principal components for both levels.

npc

Pre-specified value for the number of principal components. If given, this overrides pve.

p

The degree of B-splines functions to use. Defaults to 3.

m

The order of difference penalty to use. Defaults to 2.

knots

Number of knots to use or the vectors of knots. Defaults to 35.

silent

Logical, indicating whether to not display the name of each step. Defaults to TRUE.

Details

The fast MFPCA approach (Cui et al., 2023) uses FACE (Xiao et al., 2016) to estimate covariance functions and mixed model equations (MME) to predict scores for each level. As a result, it has lower computational complexity than MFPCA (Di et al., 2009) implemented in the mfpca.sc function, and can be applied to decompose data sets with over 10000 subjects and over 10000 dimensions.

This code is a direct copy of the function mfpca.face in the refund package (version 0.1-35) and slightly adapted to allow cyclical splines in the estimation of the eigenfunctions.

Value

A list containing:

Yhat

FPC approximation (projection onto leading components) of Y, estimated curves for all subjects and visits

Yhat.subject

Estimated subject specific curves for all subjects

Y.df

The observed data

mu

estimated mean function (or a vector of zeroes if center==FALSE).

eta

The estimated visit specific shifts from overall mean.

scores

A matrix of estimated FPC scores for level1 and level2.

efunctions

A matrix of estimated eigenfunctions of the functional covariance, i.e., the FPC basis functions for levels 1 and 2.

evalues

Estimated eigenvalues of the covariance operator, i.e., variances of FPC scores for levels 1 and 2.

pve

The percent variance explained by the returned number of PCs.

npc

Number of FPCs: either the supplied npc, or the minimum number of basis functions needed to explain proportion pve of the variance in the observed curves for levels 1 and 2.

sigma2

Estimated measurement error variance.

Author(s)

Ruonan Li [e-mail], Erjia Cui [e-mail], adapted by Alexander Volkmann

References

Cui, E., Li, R., Crainiceanu, C., and Xiao, L. (2023). Fast multilevel functional principal component analysis. Journal of Computational and Graphical Statistics, 32(3), 366-377.

Di, C., Crainiceanu, C., Caffo, B., and Punjabi, N. (2009). Multilevel functional principal component analysis. Annals of Applied Statistics, 3, 458-488.

Xiao, L., Ruppert, D., Zipunnikov, V., and Crainiceanu, C. (2016). Fast covariance estimation for high-dimensional functional data. Statistics and Computing, 26, 409-421.

Examples

require(refund)
data(DTI)
mfpca.DTI <- mfpca.face(Y = DTI$cca, id = DTI$ID, twoway = TRUE)