Skip to contents

Vertex-wise analysis with random field theory cluster correction

RFT_vertex_analysis.Rd

Fits a linear or linear mixed model with the cortical or hippocampal surface data as the predicted outcome, and returns cluster-thresholded (Random field theory) t-stat map selected contrast.

Usage

RFT_vertex_analysis(
  model,
  contrast,
  random,
  formula,
  formula_dataset,
  surf_data,
  p = 0.05,
  atlas = 1,
  smooth_FWHM,
  VWR_check = TRUE
)

Arguments

model

An N X P data.frame object containing N rows for each subject and P columns for each predictor included in the model. This data.frame should not include the random effects variable.

contrast

A N x 1 numeric vector or object containing the values of the predictor of interest. Its length should equal the number of subjects in model (and can be a single column from model). The cluster-thresholded t-stat maps will be estimated only for this predictor.

random

A N x 1 numeric vector or object containing the values of the random variable (optional). Its length should be equal to the number of subjects in model (it should NOT be inside the model data.frame).

formula

An optional string or formula object describing the predictors to be fitted against the surface data, replacing the model, contrast, or random arguments. If this argument is used, the formula_dataset argument must also be provided.

  • The dependent variable is not needed, as it will always be the surface data values.

  • The first independent variable in the formula will always be interpreted as the contrast of interest for which to estimate cluster-thresholded t-stat maps.

  • Only one random regressor can be given and must be indicated as '(1|variable_name)'.

formula_dataset

An optional data.frame object containing the independent variables to be used with the formula (the IV names in the formula must match their column names in the dataset).

surf_data

A N x V matrix object containing the surface data (N row for each subject, V for each vertex), in fsaverage5 (20484 vertices), fsaverage6 (81924 vertices), fslr32k (64984 vertices) or hippocampal (14524 vertices) space. See also Hipvextract(), SURFvextract() or FSLRvextract output formats.

p

A numeric object specifying the p-value to threshold the results (Default is 0.05)

atlas

A numeric integer object corresponding to the atlas of interest. 1=Desikan, 2=Schaefer-100, 3=Schaefer-200, 4=Glasser-360, 5=Destrieux-148.

smooth_FWHM

A numeric vector object specifying the desired smoothing width in mm

VWR_check

A boolean object specifying whether to check and validate system requirements. Default is TRUE.

Value

A list object containing the cluster level results, thresholded t-stat map, positive, negative and bidirectional cluster maps, and a FDR-corrected p-value map.

Details

The function imports and adapts the 'BrainStat' Python library.

By default, false discovery rate correction is used together with the Random field theory (RFT) cluster correction. To turn off any form of cluster correction and obtain unthresholded t-statistics, users can simply run the non-TFCE analysis functions and set ‘p=1’.

Output definitions:

  • nverts: number of vertices in the cluster

  • P: p-value of the cluster

  • X, Y and Z: MNI coordinates of the vertex with the highest t-statistic in the cluster.

  • tstat: t statistic of the vertex with the highest t-statistic in the cluster

  • region: the region this highest -statistic vertex is located in, as determined/labelled by the selected atlas

See also

TFCE_vertex_analysis, TFCE_vertex_analysis_mixed

Examples

demodata = readRDS(system.file('demo_data/SPRENG_behdata_site1.rds', 
package = 'VertexWiseR'))[1:100,]
CTv = readRDS(file = url(paste0("https://github.com",
"/CogBrainHealthLab/VertexWiseR/blob/main/inst/demo_data/",
"SPRENG_CTv_site1.rds?raw=TRUE")))[1:100,] 

vertexwise_model=RFT_vertex_analysis(model=demodata[,c("sex","age")], 
contrast=demodata[,"age"], surf_data = CTv, atlas=1,p = 0.05, 
VWR_check=FALSE)
#> The binary variable 'sex' will be recoded with F=0 and M=1 for the analysis
#> smooth_FWHM argument was not given. surf_data will not be smoothed here.

#Description of the output:
#vertexwise_model$cluster_level_results

#Formula alternative:
#formula= as.formula("~ age + sex")
#vertexwise_model=RFT_vertex_analysis(formula=formula, 
#formula_dataset=demodata, surf_data = CTv, atlas=1, p = 0.05, 
#VWR_check=FALSE)