Build a GAM formula.

Function used to build a generic GAM formula string from the given arguments. The function automatically includes a tract node smoothing term (with or without a grouping term) and a participant random effects (random intercept). Any regressor terms are included as additive effects.

Usage

build_formula(
  target,
  regressors = NULL,
  node_col = "nodeID",
  node_k = NULL,
  node_group = NULL,
  participant_col = "subjectID"
)

Arguments

target

The column name that encodes the metric to model.

regressors

Column name or list of column names to use as regressors, not including node smoothing terms and the participant effects. 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. If node_group, the basis value is applied to the group as well. Default: NULL

node_group

The column name to group the tract node smooth by. Default: NULL.

participant_col

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

Value

A GAM formula.

Details

The formula is build under the logic:

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

with <variables> indicating optional components.

Examples

formula <- build_formula(target = "dti_fa", node_k = 40)

formula <- build_formula(
  target     = "dki_md",
  regressors = c("group", "sex"), 
  node_k     = 32, 
  node_group = "group"
)