modelarrayio.utils.cifti.extract_cifti_scalar_data

modelarrayio.utils.cifti.extract_cifti_scalar_data(cifti_file, reference_brain_names=None)[source]

Load a scalar cifti file and get its data and mapping.

Supports dscalar (.dscalar.nii), parcellated scalar (.pscalar.nii), and parcellated connectivity (.pconn.nii) files. For pconn files the 2-D connectivity matrix is flattened to a 1-D array (row-major order) and brain_structures contains the row parcel name repeated once per column, so callers receive a consistent 1-D array of element names.

Parameters:

  • cifti_file (str or pathlib.Path or nibabel.Cifti2Image) – CIFTI2 file on disk or already loaded CIFTI image.

  • reference_brain_names (numpy.ndarray) – Array of vertex/parcel names used for cross-file consistency checks. For pconn files this must be the brain_structures value returned by a previous call to this function.

Returns:

  • cifti_scalar_data (numpy.ndarray) – The scalar data from the cifti file, always 1-D. For pconn files this is the row-major flattened connectivity matrix.

  • brain_structures (numpy.ndarray) – Per-element spatial labels as strings. For dscalar files these are the per-greyordinate brain structure names. For pscalar files these are the parcel names. For pconn files these are the row-parcel names repeated n_col_parcels times (one entry per flattened element).