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', ignore_background_data=True, background_value=['auto', 0.0], drop_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)[source]

Parcellates given imaging data using a specified parcellation.

Parameters:

  • parcellation (str, os.PathLike, nib.Nifti1Image, nib.GiftiImage, or tuple) – The parcellation image or surfaces, where each region is identified by a unique integer ID.

  • 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.

  • data (list, dict, pd.DataFrame, pd.Series, or np.ndarray) – The imaging data to be parcellated.

  • data_labels (list) – Labels for the input data.

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

  • ignore_background_data (bool) – Whether to exclude background voxels from parcel-mean computation. When True, values specified by background_value are masked before averaging, so they do not dilute parcel means. 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)

  • drop_background_parcels (bool) – Whether to set parcels whose mean equals background_value to NaN after aggregation. Only meaningful when ignore_background_data is False: if ignore_background_data=True, all-background parcels already return NaN from aggregation (no valid values → empty mean), making this flag redundant. 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.

  • n_proc (int) – Number of processors to use for parallel processing.

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

Returns:

Parcellated data in a DataFrame.

Return type:

pd.DataFrame

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.