| Title: | Read and Write CIFTI-2 Neuroimaging Files |
|---|---|
| Description: | Pure R implementation of CIFTI-2 format I/O for grayordinate neuroimaging data. Reads and writes dense timeseries (.dtseries.nii), dense scalars (.dscalar.nii), and dense labels (.dlabel.nii) files without requiring external tools such as Connectome Workbench. Provides S4 classes mirroring the CIFTI-2 XML schema, user-friendly axis abstractions, and optional integration with 'neuroim2' and 'neurosurf' for spatially-aware brain imaging objects. |
| Authors: | Bradley R Buchsbaum [aut, cre, cph] |
| Maintainer: | Bradley R Buchsbaum <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-05-29 11:36:16 UTC |
| Source: | https://github.com/bbuchsbaum/ciftier |
Extracts left and right cortex data and combines them into a
neurosurf::BilatNeuroSurfaceVector.
as_bilat_surface_vector(x, left_geometry, right_geometry)as_bilat_surface_vector(x, left_geometry, right_geometry)
x |
A |
left_geometry |
A |
right_geometry |
A |
A BilatNeuroSurfaceVector.
Extracts data for a cortical surface structure from a
CiftiImage and returns it as a neurosurf object.
as_neuro_surface(x, structure, geometry)as_neuro_surface(x, structure, geometry)
x |
A |
structure |
Character string naming the surface structure (e.g., "cortex_left", "cortex_right"). |
geometry |
A |
For a single-map image, returns a neurosurf::NeuroSurface.
For multi-map or time series data, returns a
neurosurf::NeuroSurfaceVector.
A NeuroSurface (single map) or NeuroSurfaceVector
(multiple maps / time series).
Combines all volume-based brain structures into a single
SparseNeuroVol or SparseNeuroVec.
as_neuro_vec(x)as_neuro_vec(x)
x |
A |
A SparseNeuroVol (single map) or SparseNeuroVec
(multiple maps / time series).
Extracts data for a subcortical (volume-based) brain structure from a
CiftiImage and returns it as a neuroim2 sparse volume.
as_neuro_vol(x, structure)as_neuro_vol(x, structure)
x |
A |
structure |
Character string naming the subcortical structure (e.g., "thalamus_left", "CIFTI_STRUCTURE_PUTAMEN_RIGHT"). |
For a single-map image (e.g., one scalar map), returns a
neuroim2::SparseNeuroVol. For multi-map or time series data,
returns a neuroim2::SparseNeuroVec.
A SparseNeuroVol (single map) or SparseNeuroVec
(multiple maps / time series).
Convert Axis Objects Back to CiftiHeader
axes_to_header(row_axis, col_axis, version = "2")axes_to_header(row_axis, col_axis, version = "2")
row_axis |
A |
col_axis |
A |
version |
Character version string (default "2"). |
A CiftiHeader object.
Create a BrainModelAxis from a Mask
brain_model_from_mask(mask, name, affine = NULL)brain_model_from_mask(mask, name, affine = NULL)
mask |
For surfaces: a logical vector (length = nvertex). For volumes: a 3D logical array. |
name |
Canonical CIFTI structure string. |
affine |
4x4 affine matrix (required for volume masks). |
A BrainModelAxis object.
Create a BrainModelAxis from Surface Vertex Indices
brain_model_from_surface(vertices, nvertex, name)brain_model_from_surface(vertices, nvertex, name)
vertices |
Integer vector of 0-based vertex indices. |
nvertex |
Total number of vertices on the surface. |
name |
Canonical CIFTI structure string. |
A BrainModelAxis object.
Get Brain Models from an Object
brain_models(x, ...)brain_models(x, ...)
x |
A CIFTI object. |
... |
Additional arguments. |
A list of CiftiBrainModel objects.
Describes a BRAIN_MODELS dimension — each row/col maps to a surface vertex or volume voxel.
## S4 method for signature 'BrainModelAxis' show(object) ## S4 method for signature 'BrainModelAxis' length(x) ## S4 method for signature 'BrainModelAxis,numeric,missing' x[i, j, ..., drop = TRUE] ## S4 method for signature 'BrainModelAxis,logical,missing' x[i, j, ..., drop = TRUE] ## S4 method for signature 'BrainModelAxis' c(x, ...) ## S4 method for signature 'BrainModelAxis,BrainModelAxis' e1 == e2 ## S4 method for signature 'BrainModelAxis' iter_structures(x, ...)## S4 method for signature 'BrainModelAxis' show(object) ## S4 method for signature 'BrainModelAxis' length(x) ## S4 method for signature 'BrainModelAxis,numeric,missing' x[i, j, ..., drop = TRUE] ## S4 method for signature 'BrainModelAxis,logical,missing' x[i, j, ..., drop = TRUE] ## S4 method for signature 'BrainModelAxis' c(x, ...) ## S4 method for signature 'BrainModelAxis,BrainModelAxis' e1 == e2 ## S4 method for signature 'BrainModelAxis' iter_structures(x, ...)
object |
A |
x |
A |
i |
Numeric or logical index vector. |
j |
Not used. |
... |
Additional arguments (ignored). |
drop |
Logical (ignored). |
e1 |
First |
e2 |
Second |
nameCharacter vector of structure names (one per grayordinate).
vertexInteger vector of 0-based vertex indices (NA for voxel entries).
voxelInteger matrix (N x 3) of 0-based IJK indices (NA rows for surface entries).
surface_maskLogical vector: TRUE for surface entries, FALSE for volume.
nverticesNamed list mapping structure names to total vertex counts.
affine4x4 numeric matrix (volume affine) or NULL.
volume_shapeInteger vector of length 3 or NULL.
Converts a CiftiHeader to an XML character string.
build_cifti_xml(header)build_cifti_xml(header)
header |
A |
A character string containing the CIFTI-2 XML.
Get the Data Matrix
cifti_data(x, ...)cifti_data(x, ...)
x |
A CIFTI object. |
... |
Additional arguments. |
A numeric matrix.
Constructs a CiftiImage from neuroim2 volume objects and/or neurosurf surface objects.
cifti_from_data( surfaces = list(), volumes = list(), row_axis = NULL, intent = 3002L )cifti_from_data( surfaces = list(), volumes = list(), row_axis = NULL, intent = 3002L )
surfaces |
A named list of neurosurf objects, where names are CIFTI
structure identifiers (e.g., "cortex_left", "cortex_right"). Each element
should be a |
volumes |
A named list of neuroim2 volume objects, where names are CIFTI
structure identifiers (e.g., "thalamus_left"). Each element should be a
|
row_axis |
A |
intent |
Integer NIfTI intent code (default: 3002 for dtseries). |
A CiftiImage.
Get the CIFTI Header
cifti_header(x, ...)cifti_header(x, ...)
x |
A CIFTI object. |
... |
Additional arguments. |
A CiftiHeader object.
Identifies what kind of data a dimension contains.
CIFTI_INDEX_TYPESCIFTI_INDEX_TYPES
An object of class character of length 5.
Get the NIfTI Intent Code
cifti_intent(x, ...)cifti_intent(x, ...)
x |
A CIFTI object. |
... |
Additional arguments. |
An integer intent code.
NIfTI intent codes used by CIFTI-2 files.
CIFTI_INTENTSCIFTI_INTENTS
An object of class integer of length 11.
CIFTI-2 Brain Model Types
CIFTI_MODEL_TYPESCIFTI_MODEL_TYPES
An object of class character of length 2.
CIFTI-2 Series Unit Types
CIFTI_SERIES_UNITSCIFTI_SERIES_UNITS
An object of class character of length 4.
Named character vector of valid CIFTI-2 brain structure identifiers. Names are short aliases; values are the full CIFTI XML strings.
CIFTI_STRUCTURESCIFTI_STRUCTURES
An object of class character of length 33.
Describes one brain structure's mapping in a BrainModels index map. Indices stored here follow CIFTI conventions (0-based).
index_offsetInteger offset into the matrix dimension.
index_countInteger number of indices for this model.
model_typeCharacter: "CIFTI_MODEL_TYPE_SURFACE" or "CIFTI_MODEL_TYPE_VOXELS".
brain_structureCharacter: canonical CIFTI structure string.
surface_number_of_verticesInteger: total vertices on the surface (0 for voxel models).
vertex_indicesInteger vector of 0-based vertex indices (surface models).
voxel_indices_ijkInteger matrix (N x 3) of 0-based IJK voxel indices (voxel models).
Top-level parsed CIFTI-2 XML header.
versionCharacter string (e.g., "2").
matrixA CiftiMatrix object.
Create a CiftiImage
CiftiImage( data = NULL, header = NULL, row_axis = NULL, col_axis = NULL, intent = 0L, file_name = "" )CiftiImage( data = NULL, header = NULL, row_axis = NULL, col_axis = NULL, intent = 0L, file_name = "" )
data |
A numeric matrix (rows x cols), or NULL. |
header |
A |
row_axis |
A |
col_axis |
A |
intent |
Integer NIfTI intent code. |
file_name |
Character source file path. |
A CiftiImage object.
A complete CIFTI-2 image: data matrix + header + axis descriptors.
## S4 method for signature 'CiftiImage' show(object) ## S4 method for signature 'CiftiImage' row_axis(x, ...) ## S4 method for signature 'CiftiImage' col_axis(x, ...) ## S4 method for signature 'CiftiImage' cifti_header(x, ...) ## S4 method for signature 'CiftiImage' cifti_intent(x, ...) ## S4 method for signature 'CiftiImage' cifti_data(x, ...) ## S4 method for signature 'CiftiImage' dim(x) ## S4 method for signature 'CiftiImage' brain_models(x, ...) ## S4 method for signature 'CiftiImage' named_maps(x, ...) ## S4 method for signature 'CiftiImage' volume_info(x, ...) ## S4 method for signature 'CiftiImage,character' extract_structure(x, structure, ...) ## S4 method for signature 'CiftiImage,ANY,ANY' x[i, j, ..., drop = FALSE]## S4 method for signature 'CiftiImage' show(object) ## S4 method for signature 'CiftiImage' row_axis(x, ...) ## S4 method for signature 'CiftiImage' col_axis(x, ...) ## S4 method for signature 'CiftiImage' cifti_header(x, ...) ## S4 method for signature 'CiftiImage' cifti_intent(x, ...) ## S4 method for signature 'CiftiImage' cifti_data(x, ...) ## S4 method for signature 'CiftiImage' dim(x) ## S4 method for signature 'CiftiImage' brain_models(x, ...) ## S4 method for signature 'CiftiImage' named_maps(x, ...) ## S4 method for signature 'CiftiImage' volume_info(x, ...) ## S4 method for signature 'CiftiImage,character' extract_structure(x, structure, ...) ## S4 method for signature 'CiftiImage,ANY,ANY' x[i, j, ..., drop = FALSE]
object |
A |
x |
A |
... |
Additional arguments (ignored). |
structure |
Character string naming a brain structure (optional filter). |
i |
Row indices. |
j |
Column indices. |
drop |
Logical (ignored). |
dataA numeric matrix (or NULL for header-only reads).
headerA CiftiHeader object.
row_axisA CiftiAxis describing rows.
col_axisA CiftiAxis describing columns.
intentInteger NIfTI intent code.
file_nameCharacter source file path (may be empty).
A single label entry in a CIFTI label table.
keyInteger key value.
labelCharacter label string.
redNumeric red channel (0-1).
greenNumeric green channel (0-1).
blueNumeric blue channel (0-1).
alphaNumeric alpha channel (0-1).
A table of label entries for a named map.
labelsA list of CiftiLabel objects.
Complete matrix metadata — contains all dimension descriptors.
mapsA list of CiftiMatrixIndicesMap objects.
metadataA named list of metadata key-value pairs.
Describes one dimension of the CIFTI data matrix.
applies_to_dimensionInteger vector (0-based dimension indices this map applies to).
index_typeCharacter: one of the CIFTI_INDEX_TYPES values.
brain_modelsList of CiftiBrainModel objects.
named_mapsList of CiftiNamedMap objects.
parcelsList of CiftiParcel objects.
surfacesList of CiftiSurface objects.
volumeA CiftiVolume or NULL.
series_startNumeric start value for SERIES type.
series_stepNumeric step value for SERIES type.
series_unitCharacter unit for SERIES type.
number_of_series_pointsInteger count for SERIES type.
One named map entry (used in SCALARS and LABELS index types).
map_nameCharacter string naming the map.
label_tableA CiftiLabelTable or NULL.
metadataA named list of metadata key-value pairs.
One parcel in a PARCELS index map.
nameCharacter parcel name.
surface_verticesA named list mapping structure names to integer vectors of 0-based vertex indices.
voxel_indices_ijkInteger matrix (N x 3) of 0-based IJK voxel indices.
Surface metadata for a PARCELS index map.
brain_structureCharacter: canonical CIFTI structure string.
number_of_verticesInteger: total vertices on the surface.
Volume geometry reference (dimensions and affine transform).
dimensionsInteger vector of length 3 (I, J, K).
transformA 4x4 numeric matrix (voxel-to-world affine).
Get the Column Axis of a CIFTI Object
col_axis(x, ...)col_axis(x, ...)
x |
A CIFTI object. |
... |
Additional arguments. |
A CiftiAxis object.
Connectivity matrix between grayordinates (BrainModelAxis x BrainModelAxis).
dconn(data, row_brain_model, col_brain_model = row_brain_model)dconn(data, row_brain_model, col_brain_model = row_brain_model)
data |
Numeric matrix (grayordinates x grayordinates). |
row_brain_model |
A |
col_brain_model |
A |
A CiftiImage with intent 3001.
Create a Dense Label CIFTI Image
dlabel(data, brain_model, names = NULL, label_tables = NULL)dlabel(data, brain_model, names = NULL, label_tables = NULL)
data |
Integer matrix (maps x grayordinates) of label keys. |
brain_model |
A |
names |
Character vector of map names. |
label_tables |
List of |
A CiftiImage with intent 3007.
Connectivity from grayordinates (rows) to parcels (columns).
dpconn(data, brain_model, parcels)dpconn(data, brain_model, parcels)
data |
Numeric matrix (grayordinates x parcels). |
brain_model |
A |
parcels |
A |
A CiftiImage with intent 3010.
Create a Dense Scalar CIFTI Image
dscalar(data, brain_model, names = NULL)dscalar(data, brain_model, names = NULL)
data |
Numeric matrix (maps x grayordinates). |
brain_model |
A |
names |
Character vector of map names. |
A CiftiImage with intent 3006.
Create a Dense Timeseries CIFTI Image
dtseries(data, brain_model, start = 0, step = 1, unit = "SECOND")dtseries(data, brain_model, start = 0, step = 1, unit = "SECOND")
data |
Numeric matrix (time x grayordinates). |
brain_model |
A |
start |
Numeric start time (default 0). |
step |
Numeric TR / time step. |
unit |
Character unit (default "SECOND"). |
A CiftiImage with intent 3002.
Returns the sub-matrix corresponding to a specific brain structure from a CiftiImage.
extract_structure(x, structure, ...)extract_structure(x, structure, ...)
x |
A |
structure |
Character string naming the structure (e.g., "cortex_left"). |
... |
Additional arguments. |
A list with elements data (matrix), axis (subsetted axis),
and indices (column indices into the original data).
Convert CiftiHeader to Axis Objects
header_to_axes(header)header_to_axes(header)
header |
A |
A list with elements row_axis and col_axis.
Returns a list of (structure_name, slice) pairs for each brain structure in an axis.
iter_structures(x, ...)iter_structures(x, ...)
x |
An axis object. |
... |
Additional arguments. |
A named list of index ranges.
Describes a LABELS dimension — each entry is a named label map with an associated label table.
## S4 method for signature 'LabelAxis' show(object) ## S4 method for signature 'LabelAxis' length(x) ## S4 method for signature 'LabelAxis,numeric,missing' x[i, j, ..., drop = TRUE]## S4 method for signature 'LabelAxis' show(object) ## S4 method for signature 'LabelAxis' length(x) ## S4 method for signature 'LabelAxis,numeric,missing' x[i, j, ..., drop = TRUE]
object |
A |
x |
A |
i |
Numeric index vector. |
j |
Not used. |
... |
Additional arguments (ignored). |
drop |
Logical (ignored). |
nameCharacter vector of map names.
labelList of CiftiLabelTable objects (one per map).
metaList of named lists (metadata per map).
Get Named Maps from an Object
named_maps(x, ...)named_maps(x, ...)
x |
A CIFTI object. |
... |
Additional arguments. |
A list of CiftiNamedMap objects.
Create a ParcelsAxis from Brain Models
parcels_from_brain_models(named_brain_models)parcels_from_brain_models(named_brain_models)
named_brain_models |
A named list where each element is a
|
A ParcelsAxis object.
Describes a PARCELS dimension — each row/col maps to a named parcel.
## S4 method for signature 'ParcelsAxis' show(object) ## S4 method for signature 'ParcelsAxis' length(x) ## S4 method for signature 'ParcelsAxis,numeric,missing' x[i, j, ..., drop = TRUE] ## S4 method for signature 'ParcelsAxis' iter_structures(x, ...)## S4 method for signature 'ParcelsAxis' show(object) ## S4 method for signature 'ParcelsAxis' length(x) ## S4 method for signature 'ParcelsAxis,numeric,missing' x[i, j, ..., drop = TRUE] ## S4 method for signature 'ParcelsAxis' iter_structures(x, ...)
object |
A |
x |
A |
i |
Numeric index vector. |
j |
Not used. |
... |
Additional arguments (ignored). |
drop |
Logical (ignored). |
parcel_nameCharacter vector of parcel names.
voxelsList of integer matrices (N x 3) of 0-based IJK indices per parcel.
verticesList of named lists mapping structure names to integer vectors per parcel.
nverticesNamed list mapping structure names to total vertex counts.
affine4x4 numeric matrix or NULL.
volume_shapeInteger vector of length 3 or NULL.
Parses raw XML bytes (or a character string) from a CIFTI-2 NIfTI extension
into a CiftiHeader object.
parse_cifti_xml(xml_data)parse_cifti_xml(xml_data)
xml_data |
Raw vector, character string, or xml2 document. |
A CiftiHeader object.
Connectivity matrix between parcels (ParcelsAxis x ParcelsAxis).
pconn(data, row_parcels, col_parcels = row_parcels)pconn(data, row_parcels, col_parcels = row_parcels)
data |
Numeric matrix (parcels x parcels). |
row_parcels |
A |
col_parcels |
A |
A CiftiImage with intent 3003.
Parcel data with a series axis on rows (e.g., parcellated time series with parcels on both axes is ConnParcelSeries, intent 3009).
pcseries(data, parcels, start = 0, step = 1, unit = "SECOND")pcseries(data, parcels, start = 0, step = 1, unit = "SECOND")
data |
Numeric matrix (series x parcels). |
parcels |
A |
start |
Numeric start value (default 0). |
step |
Numeric step value. |
unit |
Character unit (default "SECOND"). |
A CiftiImage with intent 3009.
Connectivity from parcels (rows) to grayordinates (columns).
pdconn(data, parcels, brain_model)pdconn(data, parcels, brain_model)
data |
Numeric matrix (parcels x grayordinates). |
parcels |
A |
brain_model |
A |
A CiftiImage with intent 3011.
Create a Parcel Label CIFTI Image
plabel(data, parcels, names = NULL, label_tables = NULL)plabel(data, parcels, names = NULL, label_tables = NULL)
data |
Integer matrix (maps x parcels) of label keys. |
parcels |
A |
names |
Character vector of map names. |
label_tables |
List of |
A CiftiImage with intent 3012.
Create a Parcel Scalar CIFTI Image
pscalar(data, parcels, names = NULL)pscalar(data, parcels, names = NULL)
data |
Numeric matrix (maps x parcels). |
parcels |
A |
names |
Character vector of map names. |
A CiftiImage with intent 3008.
Create a Parcel Timeseries CIFTI Image
ptseries(data, parcels, start = 0, step = 1, unit = "SECOND")ptseries(data, parcels, start = 0, step = 1, unit = "SECOND")
data |
Numeric matrix (time x parcels). |
parcels |
A |
start |
Numeric start time (default 0). |
step |
Numeric TR / time step. |
unit |
Character unit (default "SECOND"). |
A CiftiImage with intent 3004.
Reads a CIFTI-2 file (.dtseries.nii, .dscalar.nii, .dlabel.nii, etc.)
and returns a CiftiImage.
read_cifti(file_name, drop_data = FALSE)read_cifti(file_name, drop_data = FALSE)
file_name |
Path to the CIFTI-2 file. |
drop_data |
If TRUE, only read the header/axes without loading the data matrix. Useful for inspecting large files. |
The function reads the NIfTI-2 header using RNifti, extracts the CIFTI-2 XML extension (ecode=32), parses it into axis objects, and optionally reads the binary data matrix.
A CiftiImage object.
Get the Row Axis of a CIFTI Object
row_axis(x, ...)row_axis(x, ...)
x |
A CIFTI object. |
... |
Additional arguments. |
A CiftiAxis object.
Describes a SCALARS dimension — each entry is a named scalar map.
## S4 method for signature 'ScalarAxis' show(object) ## S4 method for signature 'ScalarAxis' length(x) ## S4 method for signature 'ScalarAxis,numeric,missing' x[i, j, ..., drop = TRUE] ## S4 method for signature 'ScalarAxis' c(x, ...) ## S4 method for signature 'ScalarAxis,ScalarAxis' e1 == e2## S4 method for signature 'ScalarAxis' show(object) ## S4 method for signature 'ScalarAxis' length(x) ## S4 method for signature 'ScalarAxis,numeric,missing' x[i, j, ..., drop = TRUE] ## S4 method for signature 'ScalarAxis' c(x, ...) ## S4 method for signature 'ScalarAxis,ScalarAxis' e1 == e2
object |
A |
x |
A |
i |
Numeric index vector. |
j |
Not used. |
... |
Additional arguments (ignored). |
drop |
Logical (ignored). |
e1 |
First |
e2 |
Second |
nameCharacter vector of map names.
metaList of named lists (metadata per map).
Describes a SERIES dimension (e.g., time points).
## S4 method for signature 'SeriesAxis' show(object) ## S4 method for signature 'SeriesAxis' length(x) ## S4 method for signature 'SeriesAxis,numeric,missing' x[i, j, ..., drop = TRUE] ## S4 method for signature 'SeriesAxis' c(x, ...) ## S4 method for signature 'SeriesAxis,SeriesAxis' e1 == e2## S4 method for signature 'SeriesAxis' show(object) ## S4 method for signature 'SeriesAxis' length(x) ## S4 method for signature 'SeriesAxis,numeric,missing' x[i, j, ..., drop = TRUE] ## S4 method for signature 'SeriesAxis' c(x, ...) ## S4 method for signature 'SeriesAxis,SeriesAxis' e1 == e2
object |
A |
x |
A |
i |
Numeric index vector. |
j |
Not used. |
... |
Additional arguments (ignored). |
drop |
Logical (ignored). |
e1 |
First |
e2 |
Second |
startNumeric start value.
stepNumeric step size.
sizeInteger number of points.
unitCharacter unit string (one of CIFTI_SERIES_UNITS).
Convert 1-based R Index to 0-based CIFTI Index
to_cifti_index(x)to_cifti_index(x)
x |
An integer vector of 1-based indices. |
An integer vector of 0-based indices.
Converts short names, common aliases, and partial matches to the
canonical CIFTI_STRUCTURE_* string.
to_cifti_structure_name(name)to_cifti_structure_name(name)
name |
A character string (e.g., "cortex_left", "CORTEX_LEFT", "CortexLeft", "CIFTI_STRUCTURE_CORTEX_LEFT"). |
The canonical CIFTI structure string.
to_cifti_structure_name("cortex_left") to_cifti_structure_name("CORTEX_LEFT") to_cifti_structure_name("CortexLeft")to_cifti_structure_name("cortex_left") to_cifti_structure_name("CORTEX_LEFT") to_cifti_structure_name("CortexLeft")
Convert 0-based CIFTI Index to 1-based R Index
to_r_index(x)to_r_index(x)
x |
An integer vector of 0-based indices. |
An integer vector of 1-based indices.
Get Volume Information
volume_info(x, ...)volume_info(x, ...)
x |
A CIFTI object. |
... |
Additional arguments. |
A CiftiVolume object or NULL.
Writes a CiftiImage to a CIFTI-2 NIfTI file.
write_cifti(x, file_name, data_type = "FLOAT32")write_cifti(x, file_name, data_type = "FLOAT32")
x |
A |
file_name |
Output file path. |
data_type |
Data type for the binary data. One of "FLOAT32" (default) or "FLOAT64". |
Invisibly returns the file path.