Run vertex-wise linear mixed model in one hemisphere using lme4::lmer()

It runs the single_lmm function across vertices in a single hemisphere.

Usage

hemi_vw_lmm(
  hemi,
  data_list,
  formula,
  subj_dir,
  outp_dir = NULL,
  FS_HOME = "",
  folder_id = "folder_id",
  fwhm = 10,
  fs_template = "fsaverage",
  mcz_thr = 30,
  cwp_thr = 0.025,
  seed = 3108,
  apply_cortical_mask = TRUE,
  save_ss = TRUE,
  model = "lme4::lmer",
  use_model_template = TRUE,
  n_cores = 1,
  chunk_size = 1000,
  verbose = TRUE
)

Arguments

hemi

Character string specifying which hemisphere(s) to analyze. Options: "both" (default), "lh" (left only), "rh" (right only).

data_list

A list of data.frames containing phenotype information, typically generated by imp2list.

formula

A model formula object. This should specify a linear mixed model lme4 syntax. The outcome variable should be one of the supported brain surface metrics (see Details). Example: vw_thickness ~ age * sex + site + (1|participant_id).

subj_dir

Character string specifying the path to FreeSurfer data directory. Must follow the verywise directory structure (see package vignette for details).

outp_dir

Character string specifying the output directory for results. If NULL (default), creates a "verywise_results" subdirectory within subj_dir.

FS_HOME

Character string specifying the FreeSurfer home directory. Defaults to FREESURFER_HOME environment variable.

folder_id

Character string specifying the column name in pheno that contains subject directory names of the input neuroimaging data (e.g., "sub-001_ses-baseline" or "site1/sub-010_ses-F1"). These are expected to be nested inside subj_dir. Default: "folder_id".

fwhm

Numeric value specifying the full-width half-maximum for smoothing kernel. Default: 10.

fs_template

Character string specifying the FreeSurfer template for vertex registration. Options: * "fsaverage" (default) = 163842 vertices (highest resolution), * "fsaverage6" = 40962 vertices, * "fsaverage5" = 10242 vertices, * "fsaverage4" = 2562 vertices, * "fsaverage3" = 642 vertices Note that lower resolutions should be only used to downsample the brain map, for faster model tuning. The final analyses should also run using `fs_template = "fsaverage"` to avoid (small) imprecisions in vertex registration and smoothing.

mcz_thr

Numeric value for Monte Carlo simulation threshold. Any of the following are accepted (equivalent values separate by `/`): * 13 / 1.3 / 0.05, * 20 / 2.0 / 0.01, * 23 / 2.3 / 0.005, * 30 / 3.0 / 0.001, \* default * 33 / 3.3 / 0.0005, * 40 / 4.0 / 0.0001.

cwp_thr

Numeric value for cluster-wise p-value threshold (on top of all corrections). Set this to 0.025 when both hemispheres are analyzed, 0.05 for single hemisphere. Default: 0.025.

seed

Integer specifying the random seed for reproducibility. Default: 3108.

apply_cortical_mask

Logical indicating whether to exclude non-cortical vertices from analysis. Default: TRUE (recommended).

save_ss

Logical indicating whether to save the super-subject matrix as an .rds file for faster future processing. Default: TRUE (recommended).

model

Character string specifying the statistical model type. Default: "lme4::lmer".

use_model_template

Logical indicating whether to pre-compile the model template for faster estimation. Default: TRUE (recommended).

n_cores

Integer specifying the number of CPU cores for parallel processing. Default: 1.

chunk_size

Integer specifying the number of vertices processed per chunk in parallel operations. Larger values use more memory but may be faster. Default: 1000.

verbose

Logical indicating whether to display progress messages. Default: TRUE.

Value

A list of file-backed matrices (bigstatsr::FBM objects) containing pooled coefficients, SEs, t- and p- values and residuals. Results are also automatically saved to disk in .mgh format.

See also

run_vw_lmm for the main user interface, single_lmm for single-vertex modeling.

Author

Serena Defina, 2024.