Calculating Subject Distances

This section explains how to use the connectir_subdist.R command. This tool attempts to characterize individual differences in whole-brain functional connectivity patterns for each brain unit (voxel or parcellation). We will first explain the gist of what the command does and then go into how to run it.

What Does It Do?

This command encompasses two levels of calculations. First, for each participant, we compute all the possible connections in the brain as correlations between pairs of voxels or parcellations (i.e., a connectome). Instead of examining the whole connectome at once, we will parse through a relevant set of features, namely each voxels (or parcellations) connectivity with the rest of the brain. We refer to these set of connections as a whole-brain connectivity map or connectivity pattern. Then, at each voxel, we calculate the distance (e.g., one minus correlation) between pairs of participant whole-brain connectivity maps, resulting in a distance matrix. Note that to save memory, we compute connectivity maps and distance matrices in blocks of voxels. The distance matrices are all saved in one big file onto the disk.

How Do I Run It?

UPDATE: You can also use the --automask1 option with --brainmask1 standard_grey_matter_mask.nii.gz instead of generating your own group mask

You will need a few input files to run connectir_subdist.R. In addition, you will likely need lots of RAM.

• File with paths of 4D functional files in standard space (can be nifti or text files)
• Brain mask file where each voxel is present in all the participants (only required if functionals are nifti files)
• Background image (this should be in the same space if input is nifti; otherwise if input are ROIs or text files, this should be the nifti image that you want to project your ROIs into after everything is done)

When you have those ready, you then run the command as follows. I will annotate this example further down.

connectir_subdist.R -i LIST_OF_INPUT_FILES \
  --brainmask1 MASK_FILE \
  --bg BACKGROUND_IMAGE \
  --memlimit MEMORY_LIMIT \
  --ztransform \
  OUTPUT_DIRECTORY

As you can see the command is fairly straightforward. The arguments are:

• -i LIST_OF_INPUT_FILES: This is a text file with a list of your functional files (one row per subject/scan). Note this list of files should be the same order as the model file to be used in the mdmr step. The files can either be analyze/nifti format or text files containing time-series for your various regions-of-interest (rows=time, col=regions). Format of these text files are related to the file extensions (so if you want to read in a csv file, then the file extension must be *.csv):
  • *.txt: space delimited
  • *.1D: space delimited
  • *.tab: tab delimited
  • *.csv: comma separated
• --brainmask1 MASK_FILE: A group mask (analyze/nifti file) where any non-zero values indicate voxels that have a value in all of your subjects. You might also want to further constrain what voxels should be considered. For instance, we typically also combine our subject masks with a grey matter mask (via FSL's tissue prior). The grey matter mask helps to speed up computation and also limits analysis to regions we are most concerned with.
• --bg BACKGROUND_IMAGE: As mentioned above, this is for visualization purposes and is the background image to display results. This might, for instance, be the MNI standard brain.
• --memlimit MEMORY_LIMIT: Since we are looking at all possible connections within subjects, this can be very memory demanding especially if we want to do things fast. This option sets an upper bound on your memory usage and this will likely depend on the size of your input dataset (e.g., # of voxels and # of subjectS). You can try a number and then see the program output some information on the memory usage that could help guide your selection. Note that maxing out your memory may not necessarily improve performance.
• --ztransform: This will apply a Fischer Z-Transform to your correlations for each individual subject before computing distances between subject connectivity maps.

Parallelization

If your setup of R is enabled for parallel computing, then you can also use the following two options:

• -c or --forks: It will split your job into pieces and run each in parallel (need to have foreach/parallel setup)
• -t or --threads: This sets the number of processors to use in parallel for any matrix algebra operations (needs some matrix algebra library installed and linked to R such as Intel MKL or OpenBLAS...not openblas is what is installed with Rinstall)

Advanced Options

When connectir computes distances between each pair of subject connectivity maps, it uses a Pearson correlation. Correlations scale the data and so ignore differences between subjects in terms of the mean and variance. Although this can be warranted theoretically or practically, one may also want to have a distance measure without any scaling. For this purpose, you can use the Euclidean distance with the --method option via --method euclidean. There are other methods that you can see with the help or in our paper. One important note is that using another distance measure can considerably slow down your computation. In that case, we might recommend using parcellations instead of voxelwise for your analyses.

Any Other Advice?

Just a repeat word of advice...if you have lots of participants (N > 100), then I might recommend using parcellation units instead of voxelwise. If you do stick with voxelwise data, I would suggest 4mm data. In our previous work, we found similar results to voxelwise data (4mm) with as few as 50 parcellations and the most similar results with 800 parcellations. Thus, if you are looking for exploratory analyses, then brain parcellations might be your avenue to success.