Code for predicting individual differences in behavioral variables (e.g., intelligence, personality) from resting-state fMRI functional connectivity, using data from the Young Adult Human Connectome Project. The code depends on the HCP data structure. HCP data (MRI, and behavior/demographics) is available from the HCP website (https://www.humanconnectome.org/study/hcp-young-adult)
A later version of this pipeline, extended to be used with other datasets processed with fmriprep, is available at https://github.com/adolphslab/rsDenoise
Authors: Julien Dubois (jcrdubois@gmail.com) and Paola Galdi (paola.galdi@gmail.com)
The code is provided as is, for documentation purposes.
The following files are included:
HCP_helpers.py : contains all helper functions and module imports for resting-state fMRI preprocessing, and prediction of behavior
personality.ipynb : reproduces analyses in
Dubois, J.*, Galdi, P.*, Han, Y., Paul, L.K. and Adolphs, R. Resting-state functional brain connectivity best predicts the personality dimension of openness to experience. Personality Neuroscience, in press. Preprint: https://www.biorxiv.org/content/early/2018/03/02/215129
intelligence.ipynb : reproduces analyses in
Dubois, J., Galdi, P., Paul, L.K. and Adolphs, R. A distributed brain network predicts general intelligence from resting-state human neuroimaging data. Philosophical Transactions of the Royal Society B, in revision. Preprint: https://www.biorxiv.org/content/early/2018/01/31/257865
recomputeNEOFFIfactors.ipynb : standalone notebook which can be used to correct NEOFAC_A [agreeableness factor] (see https://www.mail-archive.com/hcp-users@humanconnectome.org/msg05266.html: it appears that one of the test items was not properly reverse coded to compute the agreeableness factor). Data downloaded on 03/08/2018 was found to still be affected by the bug
If you use this code, please cite the most relevant of these two papers.
In order to run the provided code the following packages are needed:
Preprocessing is performed executing a sequence of steps or operations, each of which corresponds to a function in the HCP_helpers.py file. There are 7 available operations: Voxel Normalization, Detrending, Motion Regression, Scrubbing, Tissue Regression, Global Signal Regression and Temporal Filtering. The corresponding functions are built using the following template:
def OperationName(niiImg, flavor, masks, imgInfo):
[data,volData]
. If the file to be processes is a Nifti file, the variable data
contains Nifti data and the variable volData
is None
. If the input file is a Cifti file, the variable data
contains Cifti data and the variable volData
contains volumetric data. Image data can be loaded with function load_img()
.makeTissueMasks()
, a list of four elements corresponding to 1) whole brain mask, 2) white matter mask, 3) cerebrospinal fluid mask and 4) gray matter mask. load_img()
.A preprocessing pipeline can be fully described with the following data structure:
[
['Operation1', 1, [param1]],
['Operation2', 2, [param1, param2, param3]],
['Operation3', 3, [param1, param2]],
['Operation4', 4, [param1]],
['Operation5', 5, [param1, param2]],
['Operation6', 6, [param1, param2, param3]],
['Operation7', 7, [param]]
]
It is a list of structures. Each structure is a list of 3 elements:
Operations are executed following the operation order specified by the user. Note that in case of regression operations, a single regression step combining multiple regressors (e.g., tissue regressors and global signal regressor) can be requested by assigning the same order to all regression steps.
There are three pipelines already specified in the HCP_helpers.py file.
config.operationDict = {
'A': [ #Finn et al. 2015
['VoxelNormalization', 1, ['zscore']],
['Detrending', 2, ['legendre', 3, 'WMCSF']],
['TissueRegression', 3, ['WMCSF', 'GM']],
['MotionRegression', 4, ['R dR']],
['TemporalFiltering', 5, ['Gaussian', 1]],
['Detrending', 6, ['legendre', 3 ,'GM']],
['GlobalSignalRegression', 7, ['GS']]
],
'B': [ #Satterthwaite et al. 2013 (Ciric7)
['VoxelNormalization', 1, ['demean']],
['Detrending', 2, ['poly', 2, 'wholebrain']],
['TemporalFiltering', 3, ['Butter', 0.01, 0.08]],
['MotionRegression', 4, ['R dR R^2 dR^2']],
['TissueRegression', 4, ['WMCSF+dt+sq', 'wholebrain']],
['GlobalSignalRegression', 4, ['GS+dt+sq']],
['Scrubbing', 4, ['RMS', 0.25]]
],
'C': [ #Siegel et al. 2016 (SiegelB)
['VoxelNormalization', 1, ['demean']],
['Detrending', 2, ['poly', 1, 'wholebrain']],
['TissueRegression', 3, ['CompCor', 5, 'WMCSF', 'wholebrain']],
['TissueRegression', 3, ['GM', 'wholebrain']],
['GlobalSignalRegression', 3, ['GS']],
['MotionRegression', 3, ['censoring']],
['Scrubbing', 3, ['FD+DVARS', 0.25, 5]],
['TemporalFiltering', 4, ['Butter', 0.009, 0.08]]
],
}
Example: ['VoxelNormalization', 1, ['zscore']]
Example: ['Detrending', 2, ['poly', 3, 'GM']]
Note: R = [X Y Z pitch yaw roll]
Note: if temporal filtering has already been performed, the motion regressors are filtered too.
Note: if scrubbing has been requested, a regressor is added for each volume to be censored; the censoring option performs only scrubbing.
Example: ['MotionRegression', 3, ['R dR']]
Note: this step only flags the volumes to be censored, that are then regressed out in the MotionRegression step.
Note: uncensored segments of data lasting fewer than 5 contiguous volumes, are flagged for removal as well.
Example: ['Scrubbing', 4, ['FD+DVARS', 0.25, 5]]
Example: ['TissueRegression', 5, ['CompCor', 5, 'WMCSF', 'wholebrain']]
Example: ['GlobalSignalRegression', 6, ['GS+dt+sq']]
Note: if scrubbing has been requested, censored volumes are replaced by linear interpolation.
Example: ['TemporalFiltering', 7, ['Butter', 0.009, 0.08]]