This page describes some example that use the HCP's Workbench Command (wb_command) to operate on HCP files. Full documentation of all wb_command usage is available at https://www.humanconnectome.org/software/workbench-command where you can browse the different functions/options. But if you are completely new, the examples and info below may help get you started. Note this page is not exhaustive - there are many more commands/things you can do with this tool than what is shown below.

File Format

HCP files come in the cifti format which has the ability to package vertex and voxel wise data together into the same file. The term brainordinates is used to refer to both vertices and voxels. There are a variety of file types. If you are coming from mnc/obj/nii land, one novel concept is the file name is intended to describe, in some way, the type of data. First is a distinction between 'dense' and 'parcellated' - dense files contain data for each brainordinate, while parcellated files contain data at specified parcels/regions. Cifti files may also be time series (containing tseries in the name) or connectivity matrices (containing conn in the name). This means you can distinguish between a dconn (dense connectivity - connectivity data between brainordinates), pconn (parcellated connectivity - connectivity between parcels/rois), dtseries (dense time series - time series data for each brainordinate), ptseries (parcellated time series - time series for each parcel) and more. A full listing of the types of cifti files and their mapping is

dconn: ROW is dense, COLUMN is dense
dscalar: ROW is scalars, COLUMN is dense
dtseries: ROW is series, COLUMN is dense
dlabel: ROW is labels, COLUMN is dense
pconn: ROW is parcels, COLUMN is parcels
pdconn: ROW is dense, COLUMN is parcels
dpconn: ROW is parcels, COLUMN is dense
pscalar: ROW is scalars, COLUMN is parcels
ptseries: ROW is series, COLUMN is parcels

The above is copied from https://www.humanconnectome.org/software/workbench-command/-cifti-help, where you can find more details on the cifti file type

Example Commands

The examples below are listed for only one of the potential COLUMN types, so if you have a different COLUMN mapping adjust accordingly - i.e. if a command takes a ptseries as input and outputs a pconn, the same command will likely work if you replace with dtseries and dconn respectively.

Parcellate a dense time series

wb_command -cifti-parcellate $input.dtseries.nii $atlas.dlabel.nii COLUMN $output.ptseries.nii -method MEAN

assigns each parcel the mean of the brainordinates located within the parcel, at each timepoint in the time series, and stores the parcellated timeseries in the output

Parcellate a dense t1t2 file

wb_command -cifti-parcellate $t1t2.dscalar.nii $atlas.dlabel.nii COLUMN $output.pscalar.nii

similarly computes the mean t1t2 of brainordinates in each parcel and stores in the output file. Note the different file type - dscalar compared to dtseries since this is not time series data.

Correlate time series to create connectivity matrix

wb_command -cifti-correlation -mem-limit N $input.ptseries.nii $outputconnectivity.pconn.nii -fisher-z

computes the time series correlation between each pair of parcels (or brainordinates if dtseries) and stores in the output. N is an integer specifying the available memory in GB. Specifying -fisher-z applies fisher small z transform (ie, artanh) to correlation. Both -mem-limit and -fisher-z are optional and can be omitted.

Correlate time series of two files to create connectivity matrix

If you instead have two separate time series files and want the correlation of time series between two files, instead of within a single file

wb_command -cifti-correlation -mem-limit N $tseries1.ptseries.nii $tseries2.ptseries.nii $tseries1_corr_tseries2.ptseries.nii

Convert text file to cifti file

If you have a text file that you want to convert to a cifti you can use

wb_command -cifti-convert -from-text $input.txt $template.pscalar.nii $outputcifti.pscalar.nii

The above would create outputcifti.pscalar.nii which has same dimensions as template.pscalar.nii but contains the values in input.txt. This can be adapted for other cifti file types, so long as the dimensions are appropriate (eg. using a pconn as the template file would required your input file to have matrix like dimensions)