Skip to contents

Fit a GAM model.

Source: R/fit-models.R
fit_gam.Rd

Function used to fit a GAM formula from an explicit formula or builds a formula from the given arguments.

Usage

# Default S3 method
fit_gam(
  target,
  df,
  regressors = NULL,
  node_col = "nodeID",
  node_k = "auto",
  node_group = NULL,
  participant_col = "subjectID",
  autocor = TRUE,
  family = "auto",
  method = "fREML",
  discrete = TRUE,
  ...
)

# S3 method for class 'formula'
fit_gam(
  formula,
  df,
  node_col = "nodeID",
  autocor = TRUE,
  family = "auto",
  method = "fREML",
  discrete = TRUE,
  ...
)

Arguments

target

The column name that encodes the metric to model.

formula

Explicit formula to use for the GAM model.

df

The data frame that contains the GAM metrics.

regressors

Column name or list of column names to use as regressors. This list can also include smoothing terms. Default: NULL.

node_col

The column name that encodes tract node positions. Default: "nodeID".

node_k

The basis dimensions used to represent the node smoother. See details to the group as well. Default: NULL

node_group

The column name to group the tract node smooth by (i.e., s(node_col, by = node_group, k = node_k)).

participant_col

The column name that encodes participant ID. Default: "subjectID".

autocor

Logical indicating if AR1 autocorrelation should be corrected for in the GAM model. Default: TRUE

family

Name or family function of the distribution to use for modeling the GAM dependent variable.

  • If name, the possible values: ("auto", "beta", "gamma", "gaussian").

  • If "auto", will automatically determine the distribution of best fit between mgcv::betar ("beta"), stats::Gamma ("gamma"), or stats::gaussian ("gaussian").

  • If function, see family or family.mgcv for more family or extended.family class functions.

method

GAM fitting method passed to bam. Default: "fREML"

discrete

With method is "fREML" it is possible to discretize covariates for storage and efficiency reasons. See bam for more information. Default: TRUE

...

Further keyword arguments to be passed to estimate_smooth_basis and bam

Value

Fit GAM model object.

Details

GAM model formula

If calling fit_gam with the default method, the GAM model formula will be built with build_formula.

The formula is built following the logic:

target ~ <regressors>
  + s(node_col, <by = node_group>, k = <node_k or estimated>)
  + s(participant_col, bs = "re")

with <variables> indicating optional components.

Automated model fitting procedure

This function has a series of (optional) automatic steps in the GAM model fitting procedure:

  1. If family == "auto", choose the distribution (either "beta", "gamma", or "gaussian") that has the lowest AIC when fitting to the GAM dependent variable data. Implemented with estimate_distribution.

  2. If node_k == "auto", estimates the best k for the node smoother. This is implemented with estimate_smooth_basis.

  3. If autocor == TRUE, estimates the best AR1 autocorrelation lag and applies the lag to the GAM model. Implemented with itsadug::start_value_rho.

Examples

if (FALSE) { # \dontrun{
df_tract <- read_afq_sarica(na_omit = TRUE) %>% 
  filter(tractID == "Right Corticospinal")

# default method specification
model_fit <- fit_gam(
  target     = "fa", 
  df         = df_tract,
  regressors = c("age", "group"), 
  node_group = "group", 
  node_k     = "auto",
  family     = "auto" 
)

# formula method specification
model_fit <- fit_gam(
  formula = fa ~ age + group 
    + s(nodeID, by = "group", bs = "fs") 
    + s(subjectID, bs = "re"), 
  df = df_tract
)} # }