nispace.parcellate.Parcellater

class nispace.parcellate.Parcellater(parcellation, space, resampling_target='data', hemi=None)

Bases: object

Class for parcellating arbitrary volumetric / surface data. Copied from neuromaps 0.0.4 and adapted for convenient use in NiSpace.

Parameters:

• parcellation (str or os.PathLike or Nifti1Image or GiftiImage or tuple) – Parcellation image or surfaces, where each region is identified by a unique integer ID. All regions with an ID of 0 are ignored.

• space (str) – The space in which parcellation is defined

• resampling_target ({'data', 'parcellation', None}, optional) – Gives which image gives the final shape/size. For example, if resampling_target is ‘data’, the parcellation is resampled to the space + resolution of the data, if needed. If it is ‘parcellation’ then any data provided to .fit() are transformed to the space + resolution of parcellation. Providing None means no resampling; if spaces + resolutions of the parcellation and data provided to .fit() do not match a ValueError is raised. Default: ‘data’

• hemi ({'L', 'R'}, optional) – If provided parcellation represents only one hemisphere of a surface atlas then this specifies which hemisphere. If not specified it is assumed that parcellation is (L, R) hemisphere. Ignored if space is ‘MNI152’. Default: None

• labels (list, optional) – List of labels corresponding to indices in parcellation file

fit()

Prepare parcellation for data extraction

fit_transform(data, space, ignore_background_data=True, background_value=['auto', 0.0], hemi=None, fill_dropped=True, background_parcels_to_nan=False, min_num_valid_datapoints=None, min_fraction_valid_datapoints=None)

Prepare and perform parcellation of data

inverse_transform(data)

Project data to space + density of parcellation

Parameters:

data (array_like) – Parcellated data to be projected to the space of parcellation

Returns:

data – Provided data in space + resolution of parcellation

Return type:

Nifti1Image or tuple-of-nib.GiftiImage

transform(data, space, ignore_background_data=True, background_value=['auto', 0.0], hemi=None, fill_dropped=True, background_parcels_to_nan=False, min_num_valid_datapoints=None, min_fraction_valid_datapoints=None)

Applies parcellation to data in space

Parameters:

• data (str or os.PathLike or Nifti1Image or GiftiImage or tuple) – Data to parcellate

• space (str) – The space in which data is defined

• hemi ({'L', 'R'}, optional) – If provided data represents only one hemisphere of a surface dataset then this specifies which hemisphere. If not specified it is assumed that data is (L, R) hemisphere. Ignored if space is ‘MNI152’. Default: None

• ignore_background_data (bool) – Whether to exclude background voxels/vertices from parcel-mean computation. When True, values specified by background_value are masked before averaging. Default: True

• background_value (float, list, set, array, or 'auto') –

  Value(s) to treat as background when ignore_background_data=True. Accepts a scalar, or any collection of scalars and/or the sentinel string 'auto'/None:

  • float (e.g. 0.0): exclude that specific value

  • 'auto' or None: auto-detect from border voxels (volumetric) or medial wall median (surface)

  • list/set/array: any combination of the above

  Default: ['auto', 0.0] (excludes detected background and zeros)

• background_parcels_to_nan (bool) – Whether to set parcels whose mean equals the single resolved background value to NaN after aggregation. Only meaningful when ignore_background_data=False and background_value resolves to exactly one scalar; otherwise redundant (all-background parcels already return NaN from empty-mean aggregation). Default: False

Returns:

parcellated – Parcellated data

Return type:

np.ndarray