fsl.data.cifti

Provides a sparse representation of volumetric and/or surface data

The data can be either defined per voxel/vertex (DenseCifti) or per parcel (class:`ParcelCifti).

The data can be read from NIFTI, GIFTI, or CIFTI files. Non-sparse volumetric or surface representations can be extracte.

class fsl.data.cifti.Cifti(arr: ndarray, axes: Sequence[Axis | None])

Bases: object

Parent class for the two types of CIFTI files.

The type of the CIFTI file is determined by the last axis, which can be one of:

• BrainModelAxis

• ParcelsAxis

__init__(arr: ndarray, axes: Sequence[Axis | None])

Defines a new dataset in greyordinate space

Parameters:

• data – (…, N) array for N greyordinates or parcels; can contain Nones for undefined axes

• axes – sequence of CIFTI axes describing the data along each dimension

to_cifti(default_axis=None)

Create a CIFTI image from the data

Parameters:

default_axis –

What to use as an axis along any undefined dimensions

• By default an error is raised

• if set to “scalar” a ScalarAxis is used with names of “default {index}”

• if set to “series” a SeriesAxis is used

Returns:

nibabel CIFTI image

classmethod from_cifti(filename, writable=False)

Creates new greyordinate object from dense CIFTI file

Parameters:

• filename – CIFTI filename or nib.Cifti2Image object

• writable – if True, opens data array in writable mode

save(cifti_filename, default_axis=None)

Writes this sparse representation to/from a filename

Parameters:

• cifti_filename – output filename

• default_axis –

  What to use as an axis along any undefined dimensions

  • By default an error is raised

  • if set to “scalar” a ScalarAxis is used with names of “default {index}”

  • if set to “series” a SeriesAxis is used

Returns:

classmethod from_gifti(filename, mask_values=(0, nan))

Creates a new greyordinate object from a GIFTI file

Parameters:

• filename – GIFTI filename

• mask_values – values to mask out

Returns:

greyordinate object representing the unmasked vertices

classmethod from_image(input, mask_values=(nan, 0))

Creates a new greyordinate object from a NIFTI file

Parameters:

• input – FSL image.Image object

• mask_values – which values to mask out

Returns:

greyordinate object representing the unmasked voxels

__dict__ = mappingproxy({'__module__': 'fsl.data.cifti', '__doc__': '\n    Parent class for the two types of CIFTI files.\n\n    The type of the CIFTI file is determined by the last axis, which can be one of:\n\n    - :py:class:`BrainModelAxis <cifti2_axes.BrainModelAxis>`\n    - :py:class:`ParcelsAxis <cifti2_axes.ParcelsAxis>`\n    ', '__init__': <function Cifti.__init__>, 'to_cifti': <function Cifti.to_cifti>, 'from_cifti': <classmethod(<function Cifti.from_cifti>)>, 'save': <function Cifti.save>, 'from_gifti': <classmethod(<function Cifti.from_gifti>)>, 'from_image': <classmethod(<function Cifti.from_image>)>, '__dict__': <attribute '__dict__' of 'Cifti' objects>, '__weakref__': <attribute '__weakref__' of 'Cifti' objects>, '__annotations__': {}})

__module__ = 'fsl.data.cifti'

__weakref__

list of weak references to the object (if defined)

class fsl.data.cifti.DenseCifti(*args, **kwargs)

Bases: Cifti

Represents sparse data defined for a subset of voxels and vertices (i.e., greyordinates)

__init__(*args, **kwargs)

Defines a new dataset in greyordinate space

Parameters:

• data – (…, N) array for N greyordinates or parcels; can contain Nones for undefined axes

• axes – sequence of CIFTI axes describing the data along each dimension

property brain_model_axis: BrainModelAxis

property extension

to_image(fill=0) → Image

Get the volumetric data as an image.Image

surface(anatomy, fill=nan, partial=False)

Gets a specific surface

If partial is True a view of the data rather than a copy is returned.

Parameters:

• anatomy – BrainStructure or string like ‘CortexLeft’ or ‘CortexRight’

• fill – which value to fill the array with if not all vertices are defined

• partial – only return the part of the surface defined in the greyordinate file (ignores fill if set)

Returns:

• if not partial: (…, n_vertices) array

• if partial: tuple with (N, ) int array with indices on the surface included in (…, N) array

__annotations__ = {}

__module__ = 'fsl.data.cifti'

class fsl.data.cifti.ParcelCifti(*args, **kwargs)

Bases: Cifti

Represents sparse data defined at specific parcels

__init__(*args, **kwargs)

Defines a new dataset in greyordinate space

Parameters:

• data – (…, N) array for N greyordinates or parcels; can contain Nones for undefined axes

• axes – sequence of CIFTI axes describing the data along each dimension

property extension

property parcel_axis: ParcelsAxis

to_image(fill=0)

Get the volumetric data as an Image

surface(anatomy, fill=nan, partial=False)

Gets a specific surface

Parameters:

• anatomy – BrainStructure or string like ‘CortexLeft’ or ‘CortexRight’

• fill – which value to fill the array with if not all vertices are defined

• partial – only return the part of the surface defined in the greyordinate file (ignores fill if set)

Returns:

• if not partial: (…, n_vertices) array

• if partial: tuple with (N, ) int array with indices on the surface included in (…, N) array

__annotations__ = {}

__module__ = 'fsl.data.cifti'

class fsl.data.cifti.BrainStructure(primary, secondary=None, hemisphere='both', geometry=None)

Bases: object

Which brain structure does the parent object describe?

Supports how brain structures are stored in both GIFTI and CIFTI files

__init__(primary, secondary=None, hemisphere='both', geometry=None)

Creates a new brain structure

Parameters:

• primary – Name of the brain structure (e.g. cortex, thalamus)

• secondary – Further specification of which part of the brain structure is described (e.g. ‘white’ or ‘pial’ for the cortex)

• hemisphere – which hemisphere is the brain structure in (‘left’, ‘right’, or ‘both’)

• geometry – does the parent object describe the ‘volume’ or the ‘surface’

__eq__(other)

Two brain structures are equal if they could describe the same structure

property gifti

Returns the keywords needed to define the surface in the meta information of a GIFTI file

__str__()

Returns a short description of the brain structure

property cifti

Returns a description of the brain structure needed to define the surface in a CIFTI file

classmethod from_string(value, issurface=None)

Parses a string to find out which brain structure is being described

Parameters:

• value – string to be parsed

• issurface – defines whether the object describes the volume or surface of the brain structure (default: surface if the brain structure is the cortex volume otherwise)

classmethod from_gifti(gifti_obj)

Extracts the brain structure from a GIFTI object

__dict__ = mappingproxy({'__module__': 'fsl.data.cifti', '__doc__': 'Which brain structure does the parent object describe?\n\n    Supports how brain structures are stored in both GIFTI and CIFTI files\n    ', '__init__': <function BrainStructure.__init__>, '__eq__': <function BrainStructure.__eq__>, 'gifti': <property object>, '__str__': <function BrainStructure.__str__>, 'cifti': <property object>, 'from_string': <classmethod(<function BrainStructure.from_string>)>, 'from_gifti': <classmethod(<function BrainStructure.from_gifti>)>, '__dict__': <attribute '__dict__' of 'BrainStructure' objects>, '__weakref__': <attribute '__weakref__' of 'BrainStructure' objects>, '__hash__': None, '__annotations__': {}})

__hash__ = None

__module__ = 'fsl.data.cifti'

__weakref__

list of weak references to the object (if defined)

fsl.data.cifti.load(filename, mask_values=(0, nan), writable=False) → DenseCifti | ParcelCifti

Reads CIFTI data from the given file

File can be:

• NIFTI file

• GIFTI file

• CIFTI file

Parameters:

• filename – input filename

• mask_values – which values are outside of the mask for NIFTI or GIFTI input

• writable – allow to write to disk

Returns:

appropriate CIFTI sub-class (parcellated or dense)