rmldj/hcp-utils

Utilities to use HCP and HCP-like data with nilearn and other Python tools

hcp-utils

This package contains utilities to use Human Connectome Project (HCP) data and HCP-like data (e.g. obtained from legacy data using ciftify) as well as corresponding parcellations with nilearn and other Python tools.

The HCP data differs from conventional volumetric fMRI data which records the BOLD signal from each voxel in a 3D volume in that the signal from the cortical surface is treated as a folded two dimensional surface, and hence the data is associated with vertices of a predefined surface mesh, while the subcortical structures are described volumetrically using voxels.

The CIFTI (more precisely CIFTI-2) file format encompasses both the cortical 2D surface data as well as the subcortical volume data. However, only the voxels associated with relevant subcortical structures are kept. Thus these data are quite richly structured. Although the standard Python tools for dealing with fMRI data like nibabel can read both the CIFTI-2 files containing the fMRI signals and the GIFTI files containing the surface mesh definitions, there is not much that one could do further out-of-the-box, in particular visualization using nilearn or processing parcellated data using e.g. machine learning tools which work exclusively with numpy arrays. The goal of this package is to ease the interoperability of HCP data and these standard Python tools.

The utilities mainly deal with plotting surface data, accessing the predefined subcortical structures as well as using various parcellations and identifying connected components on the cortical surface. Various helper functions aid e.g. in mapping the HCP fMRI cortical data to surface vertices for visualization etc. The functions work directly with numpy arrays of shape Tx91282 or 91282 for fMRI data, with T being the number of time frames, while 91282 is the standard HCP dimensionality for the 3T cortical surface and subcortical data.

Documentation

Find the documentation at rmldj.github.io/hcp-utils

Installation

Make sure that you have the following packages installed (e.g. using miniconda)

nibabel, nilearn, numpy, scikit-learn, matplotlib, pandas, scipy

Then install with

pip install hcp_utils

upgrade with

pip install --upgrade hcp_utils

External data

Surface meshes

The default surface meshes for 3D visualization come from the group average of the Human Connectome Project (HCP) 1200 Subjects (S1200) data release (March 2017) processed using HCP pipelines. They can be obtained on BALSA: https://balsa.wustl.edu/reference/show/pkXDZ

These group average files are redistributed under the HCP Open Access Data Use Terms with the acknowledgment:

"Data were provided [in part] by the Human Connectome Project, WU-Minn Consortium (Principal Investigators: David Van Essen and Kamil Ugurbil; 1U54MH091657) funded by the 16 NIH Institutes and Centers that support the NIH Blueprint for Neuroscience Research; and by the McDonnell Center for Systems Neuroscience at Washington University."

Parcellations

When using the included parcellations, please cite the relevant papers, which include full details.

The Glasser MMP1.0 Parcellation: Glasser, Matthew F., Timothy S. Coalson, Emma C. Robinson, Carl D. Hacker, John Harwell, Essa Yacoub, Kamil Ugurbil, et al. 2016. “A Multi-Modal Parcellation of Human Cerebral Cortex.” Nature 536 (7615): 171–78. http://doi.org/10.1038/nature18933 (see in particular the details in Supplementary Neuroanatomical Results).

Yeo 7 or (17) Network Parcellation: Yeo, B. T. Thomas, Fenna M. Krienen, Jorge Sepulcre, Mert R. Sabuncu, Danial Lashkari, Marisa Hollinshead, Joshua L. Roffman, et al. 2011. “The Organization of the Human Cerebral Cortex Estimated by Intrinsic Functional Connectivity.” Journal of Neurophysiology 106 (3): 1125–65. https://doi.org/10.1152/jn.00338.2011.

The Cole-Anticevic Brain-wide Network Partition: Ji JL, Spronk M, Kulkarni K, Repovs G, Anticevic A, Cole MW (2019). "Mapping the human brain's cortical-subcortical functional network organization". NeuroImage. 185:35–57. https://doi.org/10.1016/j.neuroimage.2018.10.006 (also available as an open access bioRxiv preprint: http://doi.org/10.1101/206292) and https://github.com/ColeLab/ColeAnticevicNetPartition/

---

This package was initiated as a tool within the project "Bio-inspired artificial neural networks" funded by the Foundation for Polish Science (FNP).

hcp-utils's Issues

What is the MMP code of MMP parcellation?

When I want to classify the hcp task-based dataset, I need some specific region, like below:
Gambling Punish--region:Striatum; MMP code:361, 362; Prediction:--
Could you please explain me what's the meaning of those params?
Thank you.

Support for HCP 7T data?

Hello!
I was trying to use hcp-utils on some of the 7T data from HCP, which has a shape of (921, 170494). So the number of grayordinates is 170494 instead of 91282. However I noticed that in hcp-utils, struct and mesh both have hard coded indexes based on 3T HCP data (91282 grayordinates). Does this package support 7T data? If not, do you happen to know where I can find out how 7T data were subdivided?

Thank you very much!

Reassigning RGB values to parcellation

I am trying to convert the ROI label colors from hcp.mmp to those that correspond to a figure I have. I generated a colormap.csv file that contains the new RGB values and a reference map called roimap that lists the Glasser parcellation ROIs with the same ROI label and network ID as before. See code below:

import nibabel as nib
import nilearn.plotting as plotting
import numpy as np
import matplotlib
import matplotlib.pyplot as plt
import pandas
import csv as csv
import os
import copy
%matplotlib inline
import hcp_utils as hcp

colormap = "colormap.csv"
roimap = "ROI_Mapping_Python_csv.csv"
cmap = pandas.read_csv(colormap, header=None)
rmap = pandas.read_csv(roimap)

myparc = copy.deepcopy(hcp.mmp)

for l in range(1,361):
    # get network id
    networkID = (rmap['Network #'].loc[rmap['Region Label']==hcp.mmp.labels[l]]).values
    # get rgb
    newR, newG, newB = cmap[0][networkID].values[0], cmap[1][networkID].values[0], cmap[2][networkID].values[0]
    rgbval = [float(newR)/255.0, float(newG)/255.0, float(newB)/255.0]
    # saturate
    hsv = matplotlib.colors.rgb_to_hsv(rgbval) 
    hsv[1] = hsv[1] + 0.1
    newrgbval = matplotlib.colors.hsv_to_rgb(hsv)

    # set new rgb map
    myparc.rgba[l][0:3] = newrgbval

Although I have 379 ROIs as in hcp.mmp, I can't access the final 361-379. Moreover, the new RGB values in myparc.rgba are not being converted correctly. Could you provide some help with this?

colormap.xlsx
ROI_Mapping_Python.xlsx

issue with function parcel late in 1D

I may have uncovered an issue:

in hcp_utils.py, line 334

        Xp = np.zeros(np, dtype=X.dtype)

should be:

        Xp = np.zeros(n, dtype=X.dtype)

Don't you agree?

Adding 22 functional networks in preloaded parcellations

Of the preloaded parcellations that come with hcp_utils, hcp.mmp includes 360 regions (180 per hemisphere) plus 19 FreeSurfer subcortical regions, for a total of 379 regions. Along with this parcellation, could the 22 (or 23 if subcortical is included) functional networks described in Glasser et. al. 2016 and shown in the scene file, Glasser_et_al_2016_HCP_MMP1.0_4_SupplementaryNeuroanatomicalResults.scene, from https://balsa.wustl.edu/sceneFile/show/n889 be added as a new preloaded parcellation?

This would be extremely helpful in depicting both the ROIs and corresponding functional networks in 3D surface plot figures for research presentations and papers. It would also be useful for network-level analyses using Glasser parcellation.

citing use of package

Do you have a preferred citation we should use in publications if we display results of brain figures using hcp-utils?

Generating brain figure of subset of parcellation

Is there a way to specify what functional networks to color/highlight in a brain figure using hcp.view_parcellation(mesh_sub.inflated, hcp.ca_network)? For example, if analyses identify specific networks within the Cole-Anticevic Network partition that we want to illustrate (say the first 5 out of the 12 networks), is there currently a way to do this using hcp-utils?

Similarly, is there a way to specify parcels from a given parcellation that we want to highlight in generating brain figures?

Visualizing one hemisphere at a time

Hello! When using view_parcellation, is there a way to only visualize one hemisphere at a time like in nilearn?