MATLAB code for reading and writing CIFTI files, v2

This library is compatible with the CIFTI-2 format, withoutexternally installed dependencies (except that CIFTI-1 files requirewb_command for conversion), returning a structure that exposes theinformation contained in the CIFTI-2 XML with minimal translation, as wellas the data matrix with no added padding. The cifti_read function isthe intended starting point, ciftiopen and similar are compatibilitywrappers so that the library can be used in older code.

Additionally, the library provides numerous helper functions to make manycommon operations (such as extracting the data for one structure) into asingle line of intuitive code.

The previous code that was derived from FieldTrip is in the "ft_cifti"folder.

The cifti structure returned by this library uses 0-basedindices for vertex and voxel indices, 1-based for cifti indices, andthe helper functions return 1-based indices for everything.

Usage

All exposed functions have usage information available through the help command:

>> help cifti_read
 function outstruct = cifti_read(filename, ...)
    Read a cifti file.
...

The simplest practical usage is to load a cifti file with cifti_read, takeits data from the .cdata field, modify it, store it back into the .cdata field,and write it back out to a new file with cifti_write:

mycifti = cifti_read('something.dscalar.nii');
mycifti.cdata = sqrt(mycifti.cdata);
cifti_write(mycifti, 'sqrt.dscalar.nii');

The ciftiopen, ciftisave, and ciftisavereset functions provide backwardcompatibility with a previous cifti library (option II ofHCP FAQ 2),and you can also use this ciftisavereset function even if you use cifti_read.An alternative way to do the equivalent of ciftisavereset is to use thecifti_write_from_template helper function (which also has options to setthe names of the maps for dscalar, and similar for other cifti file types):

mycifti = cifti_read('something.dscalar.nii');
cifti_write_from_template(mycifti, mycifti.cdata(:, 1), 'firstmap.dscalar.nii', 'namelist', {'map #1'});

%ciftisavereset equivalent (keeping 'mycifti' unmodified):
mycifti = cifti_read('something.dscalar.nii');
newcifti = mycifti;
newcifti.cdata = mycifti.cdata(:, 1);
ciftisavereset(newcifti, 'firstmap.dscalar.nii');
clear newcifti;

The cifti_struct_create_from_template function can create a cifti struct without writingit to a file, with the same options as cifti_write_from_template to control the otherdiminfo. The cifti_write... or cifti_struct... functions should handle most cases ofworking with common cifti files, including extracting the data for one cortical surface,doing some computation on it, and replacing the surface data with the new values:

mycifti = cifti_read('something.dscalar.nii');
leftdata = cifti_struct_dense_extract_surface_data(mycifti, 'CORTEX_LEFT');
newleftdata = 1 - leftdata;
newcifti = cifti_struct_dense_replace_surface_data(mycifti, newleftdata, 'CORTEX_LEFT');
...

The dense part of some function names refers to only being applicable to "dense" filesor diminfo (in cifti xml terms, a "brain models" mapping), such as dtseries, dscalar,dlabel, or dconn. There are more dense helpers mainly because there is a more commonneed to make use of the information in a dense diminfo than most other diminfo types.

The cifti_diminfo_* helpers are lower-level and require more understanding of thedetails of the cifti format, and often require writing more code to use them, so youshould generally look at the cifti_write... and cifti_struct... functions first.

Function reference

Main functions

read/write and compatibility

outstruct = cifti_read(filename, ...)
cifti_write(cifti, filename, ...)

cifti = ciftiopen(filename, ...)     %note: these 3 do not use option pairs,
ciftisave(cifti, filename, ...)      %  the varargin here is to make passing 'wb_command' optional
ciftisavereset(cifti, filename, ...)

struct create helpers and write convenience functions

cifti = cifti_struct_create_from_template(ciftitemplate, data, type, ...)
cifti_write_from_template(ciftitemplate, data, filename, ...)

cifti = cifti_struct_create_sdseries(data, ...)
cifti_write_sdseries(data, filename, ...)

dense struct extract/replace helpers

[outdata, outroi] = cifti_struct_dense_extract_surface_data(cifti, structure[, dimension])
cifti = cifti_struct_dense_replace_surface_data(cifti, data, structure[, dimension])

[outdata, outsform1, outroi] = cifti_struct_dense_extract_volume_all_data(cifti[, cropped, dimension])
cifti = cifti_struct_dense_replace_volume_all_data(cifti, data[, cropped, dimension])

[outdata, outsform1, outroi] = cifti_struct_dense_extract_volume_structure_data(cifti, structure[, cropped, dimension])
cifti = cifti_struct_dense_replace_volume_structure_data(cifti, data, structure[, cropped, dimension])

misc

[surflist, vollist] = cifti_diminfo_dense_get_structures(diminfo)     %returns the names of structures that exist in this diminfo

outstring = cifti_metadata_get(metadata, key)           %returns empty string for nonexistent key
metadata = cifti_metadata_remove(metadata, key)         %returns unmodified metadata struct for nonexistent key
metadata = cifti_metadata_set(metadata, key, value)     %overwrites key if it exists

Special usage

advanced diminfo helpers

outinfo = cifti_diminfo_dense_get_surface_info(diminfo, structure)
outinfo = cifti_diminfo_dense_get_volume_all_info(diminfo[, cropped])
outinfo = cifti_diminfo_dense_get_volume_structure_info(diminfo, structure[, cropped])

outmap = cifti_diminfo_make_scalars(nummaps[, namelist, metadatalist])
outmap = cifti_diminfo_make_series(nummaps[, start, step, unit])

advanced misc

indices = cifti_vox2ind(dims, voxlist1)         %helper to act like sub2ind for voxel ijk lists