1 Preparation

You will need the following things:

    1. All software: Freesurfer, R, QDECR, etc. (see Vignette 1).
    1. Freesurfer data: Your Freesurfer output files in a single directory (usually SUBJECTS_DIR).
    1. Phenotype data: Your dataset with covariates, determinants, etc., loaded into R.

2 Running QDECR

WARNING!!! QDECR lets you run vertex-wise analyses however you want. Keep in mind that with great power comes great responsibility. We provide the tools, and it is up to you to use them sensibly. For example, it can be tempting to add interactions, splines, polynomials, etc., and using liberal correction thresholds without an a priori reason. Please use QDECR responsibly.

For now, lets focus on the application of multiple linear regression to each vertex.

We will study the association of age (variable: age) with cortical thickness, and adjust for sex (variable: sex). This yields the following formula: qdecr_thickness ~ age + sex. Below is an example of qdecr_fastlm, which lets us do linear regression:

out <- qdecr_fastlm(qdecr_thickness ~ age + sex, 
  data = data,
  id = "id", 
  hemi = "lh",
  project = "test_project",
  dir_tmp = "/dev/shm")

Here are the arguments we specified:

  • formula: The formula object is the first argument; we directly input qdecr_thickness ~ age + sex.
  • data: The data argument requires a data frame, a list of data frames or an imputed object from a package like mice.
  • id: Here you should put (as a character) the column name in your dataset that contains the identifiers for SUBJECTS_DIR.
  • hemi: The hemisphere you want to analyze (lh for left, rh for right).
  • project: The name that you want for your output. By default, both hemi and the vertex measure get added to it (so lh.test_project.qdecr_thickness).
  • dir_tmp: To make QDECR run fast, you need to use disk with fast I/O, like shared memory (/dev/shm)!

There are a bunch of other arguments that you can specify:

  • dir_out: The directory where you want to store the project files.
  • n_cores: The number of cores/threads you want to run on.
  • target: The target template (default: “fsaverage”).
  • mcz_thr: The Monte-Carlo simulation threshold (10, 13, 20, 23, default is 30).
  • mgh: still needs to be fixed
  • mask: still needs to be fixed
  • dir_subj: Character path to SUBJECTS_DIR if it’s not in your global environment.
  • dir_fshome: Character path to FREESURFER_HOME if it’s not in your global environment.
  • dir_out_tree: If TRUE, project will become a new directory within dir_out. If FALSE, all files will just be put into dir_out.
  • clean_up_bm: Default is TRUE; if FALSE, all the vertex-wise data and all residuals for each vertex are NOT deleted from dir_tmp. Keep in mind that these can be huge files.
  • clean_up: Default is TRUE; if FALSE, all temporary files (except the ones described above) won’t get deleted.
  • clobber: Default is FALSE; if TRUE, overwrites the output directory.
  • verbose: Default is TRUE; returns a lot of messages to keep you up to date what is happening.
  • save: If TRUE, the project is saved into an .fst object that you can later load back in.
  • save_data: If TRUE (and if SAVE is also TRUE) then you will also save the datasets into the .fst object.
  • debug: still needs to be fixed

Check ?qdecr_fastlm for all the arguments.

Running qdecr_fastlm takes several minutes, anywhere from minutes for small datasets to hours for large and imputed datasets.

3 Checking the output

We saved the output in the variable out. Here are some commands that you can use to check out what it did:

## Get a global overview
print(out) #same output

## Histogram of the mean vertex data
hist(out) # per vertex
hist(out, qtype = "subject") # per subject

## Overview of all significant clusters
summary(out, annot = TRUE) # also provides info on which regions the clusters fall into

## view the stack/contrast names

## Obtain a Freeview plot for a specific stack/contrast (note: this function requires the `magick` package)
qdecr_snap(out, 2)
qdecr_snap(out, 'age') #same output

[Next vignette: 3. Using QDECR]