nispace.io.parcellate_data

nispace.io.parcellate_data(data, data_labels=None, data_space=None, parcellation=None, parc_labels=None, parc_space=None, parc_hemi=None, resampling_target='data', background_value='auto', report_background_parcels=False, min_num_valid_datapoints=None, min_fraction_valid_datapoints=None, return_parc=False, dtype=None, n_proc=1, verbose=True, ignore_zero_division_warning=True, ignore_background_data=None, drop_background_parcels=None)[source]

Parcellates given imaging data using a specified parcellation.

Parameters:

  • data (list, dict, pd.DataFrame, pd.Series, or np.ndarray) – The imaging data to be parcellated. Lists/dicts are treated as paths or loaded nifti/gifti images (dict values become the data, dict keys become data_labels); DataFrames/Series/ndarrays are treated as already-parcellated data of shape (n_files, n_parcels).

  • data_labels (list, optional) – Labels for the input data. If not given, derived from file basenames (list input) or from the DataFrame/Series index/name (already-parcellated input).

  • data_space (str) – The space in which the input data is defined.

  • parcellation (str, os.PathLike, nib.Nifti1Image, nib.GiftiImage, tuple, or Parcellation) – The parcellation image or surfaces, where each region is identified by a unique integer ID. A Parcellation object is also accepted; parc_labels/parc_hemi/parc_space are then taken from its active space unless explicitly overridden. Required (non-None) when data is a list/dict.

  • parc_labels (list) – Labels for the parcellation regions.

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

  • parc_hemi (list of str) – Hemispheres to consider for parcellation, e.g., [“L”, “R”].

  • resampling_target ({'data', 'parcellation'}) – Specifies which image gives the final shape/size.

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

    Value(s) to treat as background, or False to disable background exclusion entirely (background/zero is then treated as real data – never masked, never triggers the empty-mean-to-NaN path; NaN 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.

  • report_background_parcels (bool) – Whether to explicitly flag (and log) parcels whose raw 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 it only affects whether they’re recorded/logged, not the returned values. Always a no-op when background_value=False, since in that mode background_value may label real, meaningful data (e.g. binary Y cluster-coverage maps, where an all-zero parcel is a genuine 0%-overlap result, not missing background) that must never be flagged here. Default: False

  • min_num_valid_datapoints (int, optional) – Minimum number of valid datapoints required per parcel.

  • min_fraction_valid_datapoints (float, optional) – Minimum fraction of valid datapoints required per parcel.

  • return_parc (bool, default False) – If True, also return the loaded parcellation image (nifti/gifti/tuple).

  • dtype (data-type, optional) – Desired data type of the output.

  • n_proc (int, default 1) – Number of processors to use for parallel processing (list/dict input only).

  • verbose (bool, default True) – Whether to print progress/info messages.

  • ignore_zero_division_warning (bool, default True) – Whether to suppress numpy’s “invalid value encountered in divide” warning raised when a parcel’s mean is computed from zero valid datapoints.

  • ignore_background_data (bool, optional) – Deprecated. Use background_value instead – pass background_value=False for what used to be ignore_background_data=False. Default: None (not set)

  • drop_background_parcels (bool, optional) – Deprecated. Use report_background_parcels instead (same meaning). Default: None (not set)

Returns:

  • pd.DataFrame – Parcellated data of shape (n_files, n_parcels).

  • pd.DataFrame, nib.Nifti1Image or nib.GiftiImage or tuple – If return_parc=True, also returns the loaded parcellation image.

Raises:

  • TypeError – If the input data type is not recognized.

  • ValueError – If the resampling target is invalid.

Notes

This function handles different types of input data, including lists, DataFrames, Series, and ndarrays. It also manages different parcellation formats and resampling targets.