Fit a GAM for tract node metrics (e.g. FA, MD)

This function has a series of steps:

If family == "auto", choose the distribution (either beta or gamma) that has the lowest AIC when fitting to the dMRI metric data
If k == "auto", build an initial GAM model with k = 16 and continue to double the k value until gam.check shows that k is large enough
Fit a GAM model such that:

target ~ covariates + s(nodeID, by=group, k = k_value) + s(subjectID, bs = "re")
Optionally save the output of gam.check and summary to files.

Usage

fit_gam(
  df_tract,
  target = NULL,
  covariates = NULL,
  smooth_terms = NULL,
  group_by = NULL,
  participant_id = NULL,
  formula = NULL,
  k = NULL,
  autocor = TRUE,
  family = "auto",
  method = "fREML",
  ...
)

Arguments

df_tract: AFQ Dataframe of node metric values for single tract
target: The diffusion metric to model (e.g. "FA", "MD"). If this is set, formula must NOT be set.
covariates: List of strings of GAM covariates, not including the smoothing terms over nodes and the random effect due to subjectID. If this is set, formula must NOT be set.
smooth_terms: Smoothing terms, not including the smoothing terms over nodes and the random effect due to subjectID. If this is set, formula must NOT be set.
group_by: The grouping variable used to group nodeID smoothing terms If this is set, formula must NOT be set.
participant_id: The name of the column that encodes participant ID If this is set, formula must NOT be set.
formula: Optional explicit formula to use for the GAM. If provided, this will override the dynamically generated formula build from the target and covariate inputs. Default = NULL. If this is set, all other inputs that determine the formula must be set to NULL.
k: Dimension of the basis used to represent the node smoothing term, If k = 'auto' (default), this function will attempt to find the best value.
autocor: Whether to account for autocorrelation in the tract profile. Default = TRUE.
family: Distribution to use for the gam. Must be either 'gamma', 'beta', or 'auto'. If 'auto', this function will select the best fit between beta and gamma distributions.
method: String, fitting method passed to mgcv::bam
...: Further keyword arguments passed to mgcv::bam

Value

Fitted GAM model

Examples

if (FALSE) { # \dontrun{
df_afq <- read.csv("/path/to/afq/output.csv")
tract <- "CST_L"
df_tract <- df_afq[which(df_afq$tractID == tract), ]
gam_fit <- fit_gam(df_tract,
                   target = "dti_fa",
                   covariates = list("group", "sex"),
                   family = "gamma",
                   k = "auto")
} # }