nispace.utils.utils.merge_parcellations

nispace.utils.utils.merge_parcellations(parcellations, labels=None, quick=False)[source]

Combine two or more NIfTI parcellation images into one labeled volume.

Plain numpy/nibabel (no numba). Only implemented for nib.Nifti1Image input. Used in datasets.py and core/parcellation.py to merge a cortex and a subcortex parcellation into one combined image — always via the fast 2-image path (quick=True) in practice.

Parameters:

  • parcellations (list of nib.Nifti1Image) – Images to merge; all must be the same type and shape.

  • labels (list, optional) – Per-parcellation label sequences to assign (only used by the slow, quick=False path). Defaults to each parcellation’s own existing label values.

  • quick (bool, default=False) – If True, take the first parcellation’s labels as-is and offset the second parcellation’s nonzero labels by the first’s max label (only supports exactly 2 parcellations; returns just the merged image). If False, sequentially relabels every parcel across all parcellations starting at 1 (supports any number of parcellations; also returns a labels_merged Series mapping new label -> original label).

Returns:

Merged parcellation image (and, for the slow path, a Series mapping each new integer label to its original source label).

Return type:

nibabel.Nifti1Image, or (nibabel.Nifti1Image, pd.Series) if quick=False

Raises:

  • ValueError – If parcellations/labels aren’t lists, have mismatched lengths, or the parcellations aren’t uniformly typed/shaped.

  • NotImplementedError – If parcellations[0] is not a nib.Nifti1Image.