Authors
Daniel Bullock (dnbulloc@iu.edu)
Lab Director
Franco Pestilli (franpest@indiana.edu) - University of Austin at Texas / Indiana University
Collaborators
Aina Puce (ainapuce@gmail.com ) - Indiana University Bloomington
Nathalie George (nathalie.george@upmc.fr ) - Institut du Cerveau et de la Moelle épinière
Funding sources / Sponsors
This repo contains the matlab code necessary to perform the white matter endpoint overlap analysis contained within "Visual information routes in the posterior dorsal and ventral face network studied with intracranial neurophysiology, and white matter tract endpoints" by Babo-Rebelo, et al. 2021 (preprint). The primary code item in this repository is the pipeline wrapper for this analysis, named coordinateOverlapAnalysisWrapper.m. In the sections below the process for setting up and using this wrapper will be described.
There are three primary, path-related variables that the user will need to set up:
- csvDir
- projectDir
- outDir
Their purpose and expected content will be described below, followed by a description of the parameters used in this analysis:
This variable is the path to the directory containing all of your files specifying the locations of your EEG sites.
Each csv file within this directory is treated as a different "group" of sites. Within each of these files, coordinates are expected to be stored in N rows and 3 columns (separated by commas), such that the rows correspond to individual EEG sites, and the columns correspond to the X, Y and Z coordinates of those sites. NOTE: these coordinates are expected to be in the same reference schema (i.e. mni) as the endpoint maps contained within the projectDir directory. The names of these files will serve as the row labels in the output figure/table generated at the end of this script.
This is the path to the brainlife project directory that contains the relevant endpoint maps. Code used by this script (specifically, bsc_amalgamateROISacrossDirectories) will iterate across subjects within this project and, across subjects, merge (via element-wise addition) rois with the same name.
The directory is expected to be in the format standardly output by brainlife. There are a couple important caveats to this though. The first is that this amalgamation code will force an error if there are multiple roi directories under a subject. As such, it is expected that users only download one set of ROIs per subject, or otherwise ensure that there is only one directory of ROIs per subject. The second caveat is that all of the ROIs with the same name are expected to be in the same reference space, so as to facilitate their merging. Given our use case here, with the use of the input EEG coordinates, this will likely already be the case. To ensure that endpoint maps (as generated by https://brainlife.io/app/5cc9ea944b5e4502275edb99, for example) are in the same reference space, a warp to the same reference space is required (as performed by https://brainlife.io/app/5c7319a5badd19003102e8d8, for example)
This is the path to the output directory, both for the amalgam endpoint ROIS and for the analysis output table and plot.
No specific format is expected for this directory, but it is recommended that it be a clear directory, simply for ease of use and interaction.
As it is currently set up, the parameters have been set up to be consistent with the analysis performed in the paper. However should you wish to modify these, you may do so.
This variable imposes a minimum thresholding prior to the amalgamation of an roi. Thus, before adding an roi to the amalgam, all values lower than this variable input in the nifti.data field will be dropped to 0.
Can be a numerical value between 0 and the maximum value in the data structure (note, this function will not error if a value exceeding the max is passed in, it will simply set all data values to 0)
This variable imposes a minimum thresholding prior to check for overlap with the input EEG coordinates. All values in input amalgam endpoint rois below this input value are set to 0.
Can be a numerical value between 0 and the total number of subjects, which is presumably the max value that could be achieved (note, this function will not error if a value exceeding the max is passed in, it will simply set all data values to 0)
It is advisable to run each subfunction (i.e. bsc_getBrainlifeDataDirPaths, bsc_amalgamateROISacrossDirectories, wma_multiCoordinateOverlapAnalysis) one at the time, given that each of these can take a non-trivial amount of time. As the number of endpoint maps, subjects, and EEG sites increases, so too does the run time for this script. In particular bsc_amalgamateROISacrossDirectories can take particularly long to run due to the frequent need to read from the disk. Assuming that the time taken by this function to process each endpoint nifti file is ~1 seconds, with 120 endpoint maps (from 60 tracts) and ~ 1000 subjects (i.e. HCP, https://brainlife.io/project/5941a225f876b000210c11e5/detail) this step could take 1000*120*1= 120,000 seconds = ~ 33 hours.