nispace.nulls.find_vol_parc_centroids

nispace.nulls.find_vol_parc_centroids(parc, affine=None, parcel_idc=None, return_data_space=False, snap=True)[source]

Compute per-parcel mean voxel coordinates in world (MNI) space.

Plain numpy/nibabel (no numba). Used internally by get_distance_matrix() (centroids=True path).

Parameters:

  • parc (np.ndarray or image-like) – Parcellation label array, or an image to load one from.

  • affine (np.ndarray, optional) – 4x4 affine mapping voxel to world coordinates. Required if parc is a plain array; otherwise taken from parc itself.

  • parcel_idc (array-like, optional) – Parcel label values to compute centroids for. Defaults to all nonzero labels present in parc.

  • return_data_space (bool, default=False) – Also return centroid coordinates in voxel (data) space.

  • snap (bool, default=True) – Snap the mean coordinate to the nearest voxel actually inside the parcel (guards against the raw mean landing outside a non-convex parcel). If False, the raw (possibly off-parcel) mean is returned.

Returns:

Centroid coordinates in world space, shape (n_parcels, 3) (and, if requested, the same in voxel space).

Return type:

np.ndarray, or (np.ndarray, np.ndarray) if return_data_space=True

Raises:

TypeError – If affine is not given and parc is not a Nifti1Image.