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 [3] 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

References

[3].

fit()

Load and validate the parcellation, preparing it for data extraction.

Loads self.parcellation into memory (as a Nifti1Image or tuple of GiftiImage, depending on space) and populates self.parcellation_idc with the sorted, non-zero parcel IDs found in it. Must be called before .transform(); .fit_transform() calls it automatically.

Returns:

self – The fitted instance, to allow chaining (e.g. self.fit().transform(…)).

Return type:

Parcellater

fit_transform(data, space, background_value='auto', hemi=None, fill_dropped=True, report_background_parcels=False, min_num_valid_datapoints=None, min_fraction_valid_datapoints=None, ignore_background_data=None)

Call .fit() followed by .transform(data, space, …) in one step.

Convenience wrapper; see .fit() and .transform() for details on what each step does. All parameters are forwarded to .transform().

Parameters:

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

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

• background_value (float, list, set, array, 'auto', or False) – See .transform(). Default: 'auto'

• hemi ({'L', 'R'}, optional) – See .transform(). Default: None

• fill_dropped (bool) – See .transform(). Default: True

• report_background_parcels (bool) – See .transform(). Default: False

• min_num_valid_datapoints (int, optional) – See .transform(). Default: None

• min_fraction_valid_datapoints (float, optional) – See .transform(). Default: None

• ignore_background_data (bool, optional) – Deprecated. See .transform(). Default: None (not set)

Returns:

parcellated – Parcellated data. See .transform().

Return type:

np.ndarray

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, background_value='auto', hemi=None, fill_dropped=True, report_background_parcels=False, min_num_valid_datapoints=None, min_fraction_valid_datapoints=None, ignore_background_data=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

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

  Value(s) to treat as background, or False to disable background exclusion entirely. When disabled, background/zero is treated as real data – never masked, never triggers the empty-mean-to-NaN path (NaN itself is still always excluded, regardless of this parameter). Accepts:

  • 'auto' (default): auto-detect from border voxels (volumetric) or medial wall median (surface), combined with exact 0.0 – equivalent to ['auto', 0.0].

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

  • list/set/array: any combination of floats and the 'auto'/None sentinel.

  • False: disable background exclusion entirely.

• 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

• fill_dropped (bool) – Whether to expand the returned array to the full original parcel set (self.parcellation_idc, from .fit()), NaN-filling any parcel that vanished entirely during resampling to data’s grid (self._parc_idc_dropped). If False, the returned array only covers parcels present in the resampled parcellation, which may be shorter than self.parcellation_idc. Default: True

• report_background_parcels (bool) – Whether to explicitly record parcels whose raw (pre-exclusion) data was entirely background – every non-NaN raw voxel/vertex in the parcel matches background_value. Such parcels are already NaN via empty-mean aggregation regardless of this flag, so enabling it does not change the returned values – it only additionally records the affected parcels (self._parc_idc_bg, surfaced in parcellate_data()’s logging), separately from parcels dropped during resampling or excluded via the min_*_valid_datapoints options. Always a no-op when background_value=False: with background exclusion disabled, background_value may label real, meaningful data (e.g. binary/cluster-coverage maps, where an all-zero parcel is a genuine 0%-overlap result, not missing background) and must never be flagged here. Default: False

• min_num_valid_datapoints (int, optional) – Minimum number of valid (non-background, non-NaN) datapoints required per parcel; parcels below this are set to NaN and recorded in self._parc_idc_excl. Default: None

• min_fraction_valid_datapoints (float, optional) – Minimum fraction of valid (non-background, non-NaN) datapoints, relative to the parcel’s total voxel/vertex count in the resampled parcellation, required per parcel; parcels below this are set to NaN and recorded in self._parc_idc_excl. Default: None

• ignore_background_data (bool, optional) – Deprecated. Use background_value instead – pass background_value=False for what used to be ignore_background_data=False. If explicitly passed, takes precedence over background_value and replicates the old two-independent-parameter behavior for the deprecation transition period. Default: None (not set)

Returns:

parcellated – Parcellated data

Return type:

np.ndarray