multiFAMM {multifamm}

Multivariate Functional Additive Mixed Model Regression

Description

This is the main function of the package and fits the multivariate functional additive regression model with potentially nested or crossed functional random intercepts.

Usage

multiFAMM(data, fRI_B = FALSE, fRI_C = FALSE, nested = FALSE,
  bs = "ps", bf_mean = 8, bf_covariates = 8, m_mean = c(2, 3),
  covariate = FALSE, num_covariates = NULL, covariate_form = NULL,
  interaction = FALSE, which_interaction = matrix(NA), bf_covs, m_covs,
  var_level = 1, use_famm = FALSE, save_model_famm = FALSE,
  one_dim = NULL, mfpc_weight = FALSE, mfpc_cutoff = 0.95,
  number_mfpc = NULL, mfpc_cut_method = c("total_var", "unidim"),
  final_method = c("w_bam", "bam", "gaulss"), weight_refit = FALSE,
  verbose = TRUE, ...)

Arguments

data

Data.table that contains the information with some fixed variable names, see Details.

fRI_B

Boolean for including functional random intercept for individual (B in Cederbaum). Defaults to FALSE.

fRI_C

Boolean for including functional random intercept for word (C in Cederbaum). Defaults to FALSE.

nested

TRUE to specify a model with nested functional random intercepts for the first and second grouping variable and a smooth error curve. Defaults to FALSE.

bs

Spline basis function, only tested for "ps" (as in sparseFLMM).

bf_mean

Basis dimension for functional intercept (as in sparseFLMM).

bf_covariates

Basis dimension for all covariates (as in sparseFLMM).

m_mean

Order of penalty for basis function (as in sparseFLMM).

covariate

Covariate effects (as in sparseFLMM).

num_covariates

Number of covariates included in the model (as in sparseFLMM).

covariate_form

Vector of strings for type of covariate (as in sparseFLMM).

interaction

TRUE if there are interactions between covariates (as in sparseFLMM). Defaults to FALSE.

which_interaction

Symmetric matrix specifying the interaction terms (as in sparseFLMM).

bf_covs

Vector of marginal basis dimensions for fRI covariance estimation (as in sparseFLMM).

m_covs

List of marginal orders for the penalty in fRI covariance estimation (as in sparseFLMM).

var_level

Pre-specified level of explained variance on each dimension (as in sparseFLMM). Defaults to including all non-negative Eigenvalues.

use_famm

Re-estimate the mean in FAMM context (as in sparseFLMM) - overwritten by one_dim.

save_model_famm

Give out the FAMM model object (as in sparseFLMM) - overwritten by one_dim.

one_dim

Specify the name of the dimension if sparseFLMM is to be computed only on one dimension.

mfpc_weight

TRUE if the estimated univariate error variance is to be used as weights in the scalar product of the MFPCA.

mfpc_cutoff

Pre-specified level of explained variance of results of MFPCA. Defaults to 0.95.

number_mfpc

List containing the number of mfPCs needed for each variance component e.g. list("E" = x, "B" = y).

mfpc_cut_method

Method to determine the level of explained variance

• total_var: (weighted) sum of variation over the dimensions.

• unidim: separate on each dimension.

final_method

Function used for estimation of final model to allow for potential heteroscedasticity ("w_bam", "bam", "gaulss").

weight_refit

Get the weights for the weighted bam by first refitting the model under an independence assumption but with mfpc basis functions. Defaults to FALSE.

verbose

Print progress of the multifamm. Defaults to TRUE.

...

Additional arguments to be passed to (mainly) the underlying sparseFLMM function.

Details

Expand the method proposed by Fabian Scheipl to incorporate the variance decomposition developed by Cederbaum et al. (2016). To account for the correlation between the dimensions, the MFPCA approach by Happ and Greven (2016) is applied.

The data set has to be of the following format:

• y_vec (numeric): vector of response values

• t (numeric): observation point locations

• n_long (integer): curve identification

• subject_long (integer): subject identification (NEEDS TO BE SPECIFIED)

• word_long (integer): word identification

• combi_long (integer): repetition

• dim (factor): level of the dimension

• covariate.1 (numeric): potential covariate(s) named with trailing 1,2,3,...

It is possible to introduce weights for the final estimation of the multiFAMM. Currently, it is only implemented to use the inverse of the univariate measurement error estimates as weights. Note that negative values of variance estimates are set to zero in fast symmetric additive covariance smoothing. In order to still include weights, zero-values are substituted by values of the smallest positive variance estimate.

Value

A list with five elements

• the final multivariate FAMM

• the sparseFLMM output for each of the dimensions

• information on the untruncated MPFCA results

• the truncated MFPC output

• the data used to fit the model.

Examples

# subset of the phonetic data (very small subset, no meaningful results can
# be expected and no random effects other than the random smooth should be
# included in the model)

data(phonetic_subset)

m <- multiFAMM(data = phonetic_subset, covariate = TRUE, num_covariates = 2,
               covariate_form = c("by", "by"), interaction = TRUE,
               which_interaction = matrix(c(FALSE, TRUE, TRUE, FALSE),
               nrow = 2, ncol = 2), bf_covs = c(5), m_covs = list(c(2, 3)),
               mfpc_cut_method = "total_var", final_method = "w_bam")