Sovereign 8s.is mirror of standardgalactic/cifti-matlab
  • MATLAB 79.9%
  • C 19.2%
  • Shell 0.8%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-08-28 21:16:08 -05:00
@xmltreemod escape special characters in attribute values 2021-12-20 16:45:52 -06:00
ft_cifti clarify ft_cifti folder's legacy status 2024-07-30 18:01:25 -05:00
private support voxel and surface models of the same structure 2026-08-28 21:16:08 -05:00
cifti_diminfo_dense_get_structures.m rename many functions to be less abbreviated, improve some error checking 2020-08-12 22:03:04 -05:00
cifti_diminfo_dense_get_surface_info.m rename many functions to be less abbreviated, improve some error checking 2020-08-12 22:03:04 -05:00
cifti_diminfo_dense_get_volume_all_info.m include coordinates in volume info struct 2024-10-18 21:29:41 -05:00
cifti_diminfo_dense_get_volume_structure_info.m include coordinates in volume info struct 2024-10-18 21:29:41 -05:00
cifti_diminfo_make_scalars.m rename cifti_file to cifti_struct 2020-08-28 17:05:47 -05:00
cifti_diminfo_make_series.m rename cifti_file to cifti_struct 2020-08-28 17:05:47 -05:00
cifti_metadata_get.m alpha version of new cifti code 2020-02-21 13:41:12 -06:00
cifti_metadata_remove.m alpha version of new cifti code 2020-02-21 13:41:12 -06:00
cifti_metadata_set.m use 'newdata' and similar in help info 2020-08-21 21:47:38 -05:00
cifti_read.m support reading/writing additional nifti extensions, fix padding math 2024-10-18 21:32:12 -05:00
cifti_struct_create_from_template.m rename cifti_file to cifti_struct 2020-08-28 17:05:47 -05:00
cifti_struct_create_sdseries.m rename cifti_file to cifti_struct 2020-08-28 17:05:47 -05:00
cifti_struct_dense_extract_surface_data.m rename cifti_file to cifti_struct 2020-08-28 17:05:47 -05:00
cifti_struct_dense_extract_volume_all_data.m fix missing extract_volume missing volinfo 2024-09-12 19:03:50 -05:00
cifti_struct_dense_extract_volume_structure_data.m fix missing extract_volume missing volinfo 2024-09-12 19:03:50 -05:00
cifti_struct_dense_replace_surface_data.m rename cifti_file to cifti_struct 2020-08-28 17:05:47 -05:00
cifti_struct_dense_replace_volume_all_data.m rename cifti_file to cifti_struct 2020-08-28 17:05:47 -05:00
cifti_struct_dense_replace_volume_structure_data.m rename cifti_file to cifti_struct 2020-08-28 17:05:47 -05:00
cifti_vox2ind.m change vector convention to row, *_map to return a struct 2020-08-10 17:58:06 -05:00
cifti_write.m update version 2026-02-24 19:20:51 -06:00
cifti_write_from_template.m support reading/writing additional nifti extensions, fix padding math 2024-10-18 21:32:12 -05:00
cifti_write_sdseries.m support reading/writing additional nifti extensions, fix padding math 2024-10-18 21:32:12 -05:00
ciftiopen.m rename read/write_cifti to cifti_read/write 2020-08-18 21:18:36 -05:00
ciftisave.m add legacy series behavior emulation to ciftisave 2021-11-23 20:11:15 -06:00
ciftisavereset.m write_from_template, make stacklevel a number 2020-08-21 21:49:47 -05:00
LICENSE license readability, phrasing 2021-04-07 13:22:58 -05:00
README.md make compile_mex error to stderr as intended, edits for release version 2021-03-23 19:13:44 -05:00

MATLAB code for reading and writing CIFTI files, v2

This library is compatible with the CIFTI-2 format, without externally installed dependencies (except that CIFTI-1 files require wb_command for conversion), returning a structure that exposes the information contained in the CIFTI-2 XML with minimal translation, as well as the data matrix with no added padding. The cifti_read function is the intended starting point, ciftiopen and similar are compatibility wrappers so that the library can be used in older code.

Additionally, the library provides numerous helper functions to make many common operations (such as extracting the data for one structure) into a single 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-based indices for vertex and voxel indices, 1-based for cifti indices, and the 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, take its 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 backward compatibility with a previous cifti library (option II of HCP 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 the cifti_write_from_template helper function (which also has options to set the 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 writing it to a file, with the same options as cifti_write_from_template to control the other diminfo. The cifti_write... or cifti_struct... functions should handle most cases of working 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" files or 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 common need 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 the details of the cifti format, and often require writing more code to use them, so you should 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