Sunday, May 28, 2017

extracting values from CIFTI files: an easier way!

Several years ago I wrote a post on how to extract timecourses from HCP CIFTI files. That works, but newer versions of wb_command (I'm using version 1.2.3) have added functions that provide a simpler method.

Here's the situation: I want to extract the vertex-wise values corresponding to a specific Gordon parcel from a CIFTI COPE generated by the HCP, saving the values into a text file. Note that I don't want to do averaging or any other calculations on the vertex values - just extract the values.

Short version: convert both CIFTI dtseries files to text using wb_command -cifti-convert -to-text, then use the indices of the rows with the desired Gordon parcel number to get the correct vertices from the COPE file.


Gordon et. al released several versions of their parcellation, including Parcels_LR.dtseries.nii, which is aligned to the Conte69 (MNI) surface atlas, same as the preprocessed HCP CIFTIs. Parcels_LR.dtseries.nii is shown below (on the Conte69 anatomy) in Workbench (this tutorial and this one explain how to get to this point, if you're not familiar with Workbench).

The values I want are the COPEs the HCP generated from fitting the GLM; images like /SUBID/MNINonLinear/Results/tfMRI_WM/tfMRI_WM_hp200_s2_level2.feat/GrayordinatesStats/cope2.feat/pe1.dtseries.nii. Since these are parameter estimate images, they're not timeseries, but a single full-brain image. I want a vector of numbers (same length as the number of vertices in the parcel) for each COPE.

the command

Then we just run wb_command with -cifti-convert -to-text on the two images:
wb_command -cifti-convert -to-text Parcels_LR.dtseries.nii d:\temp\Gordon_Parcels_LR.dtseries.txt
wb_command -cifti-convert -to-text cope1_pe1.dtseries.nii d:\temp\cope1.txt

(On my windows box I open a command window in the directory containing wb_command.exe, and include the full path to the input and output files to avoid path issues.)

confirming correspondence

The commands should have generated two files, each a column of numbers. cope1.txt has 91,282 rows (cortex and subcortical structures), Gordon_Parcels_LR.dtseries.txt has 59,412 rows (cortex only). From what I can determine, the cortex is the first 59,412 rows of the 91,282 row CIFTI, and the vertex order is the same between the two.

This image shows a way to confirm the correspondence of values in the files. I have both Parcels_LR.dtseries.nii and cope1_pe1.dtseries.nii loaded in Workbench, with the parcels displayed. The two output text files are in the WinEdt window at the upper right of the screenshot; the cope on the left and parcels on the right.

I clicked on a spot in the right hemisphere, SMmouth parcel (little white marker), making the Workbench Information window appear (lower right of the screenshot). The green lines mark that the spot I clicked is row index 33186 in the CIFTI data. This is 0-based, so its values should fall in row 33187 in the 1-based WinEdt window; the blue pointers show this row in each file. The values match: the purple lines mark that this row in cope1.txt is -9.37034, same as the DATA SERIES cope1_pe1.dtseries.nii line of the Workbench Information window. Similarly, the row in Gordon_Parcels_LR.dtseries.txt is 197, same as the DATA SERIES Parcels_LR_dtseries.nii line in the Information window (red lines).

So, that's it: to get my vertex values, all I need to do is subset all the rows from cope1.txt that have the parcel number I want (e.g., 197) in Gordon_Parcels_LR.dtseries.txt.


  1. Instead of relying on surfaces being first in cifti files, you can also create a new cifti file containing the parcellation, but which is index-matched to your other files. This is fairly easy to do with wb_command -cifti-create-dense-from-template.

    You should also consider using the dlabel.nii version instead, especially for viewing in wb_view (because it contains independent colors per-label) and things like "wb_command -cifti-parcellate" that require a label file, rather than just an integer-valued file. While the gordon parcel names are just number-based, the HCP MMP parcels have names based on functional area literature, which makes them easier to keep straight (which is important when there are 180 of them per hemisphere...).

    1. Is -cifti-create-dense-from-template fixed? I tried it but ran into core dumps, and saw a few messages that it was broken.

    2. Right, I forgot about that. It would work on the dlabel file. The crashes were from either having only dtseries as input, or if input cifti files had volume structures.

      These crashes have been fixed in the source repository, but we haven't made a new release in a while. There is a development version available that we update manually, but we don't really advertise it, because scene files saved with a development version may break with a subsequent released version.

  2. Hello Jo!

    Thank you for your blog.

    I am writing you from Spain. I am a Master student and I would like to use some HCP data in my final dissertation. However, I can get these results, I mean:

    I would like to extract the timeseries of each voxel in the GM and the cartesian coordinate in MNI atlas for each one. Could you help me? I've been some days trying it without success.

    I tried with these cases:
    a) wb_command -cifti-convert -to-text /path/tfMRI_MOTOR_LR_Atlas.dtseries.nii /path/timeseries.txt

    Result: when the process is finished (without error messages) I go to the /path/ and no timeseries.txt is in it.

    b) wb_command -cifti-convert -to-nifti /path/tfMRI_MOTOR_LR_Atlas.dtseries.nii /path/file.nii.gz

    But I have as result a nifti file that I don't know how to interpret it:
    data_type FLOAT32
    dim1 32767
    dim2 3
    dim3 1
    dim4 284
    datatype 16
    pixdim1 1.000000
    pixdim2 1.000000
    pixdim3 1.000000
    pixdim4 1.000000

    Can I extract these information directly from the tfMRI_MOTOR_LR.nii.gz with FSL (for example) like any other dataset? What is the difference with the wb_commands? For example (to extract all timeseries):
    fslmeants -i tfMRI_MOTOR_LR.nii.gz -o timeseries.txt -m gm_mask.nii.gz --showall

    Thank you so much in advance for your help.