nispace.nulls.get_distance_matrix

nispace.nulls.get_distance_matrix(parc, parc_space, parc_hemi=['L', 'R'], parc_resample=2, centroids=False, surf_euclidean=False, n_proc=1, verbose=True, dtype=<class 'numpy.float32'>)[source]

Compute a parcel-by-parcel distance matrix for a volumetric or surface parcellation.

Dispatches on parc_space: MNI/volumetric parcellations get a euclidean distance matrix (voxel-to-voxel mean, or centroid-to-centroid if centroids=True, via find_vol_parc_centroids()); fsaverage/fsLR surface parcellations get a geodesic (mesh-surface) distance matrix by default, or a euclidean centroid-to-centroid one if surf_euclidean=True (via find_surf_parc_centroids()). parc_resample triggers a parcel-loss-guarded resampling pass first (skipped with a warning if it would drop any parcel). Used by api.py and core/parcellation.py’s Parcellation.get_dist_mat path (see [[project_distance_matrices]]) whenever no precomputed distance matrix is available.

Parameters:

  • parc (image-like or tuple) – Volumetric parcellation image, or (lh_img, rh_img) tuple of surface GiftiImages.

  • parc_space (str) – Reference space; must contain "mni" for the volumetric path, or be one of "fsaverage"/"fsLR"/"fsa"/"fslr" for the surface path.

  • parc_hemi (list of str, default=["L", "R"]) – Hemispheres present (surface path only).

  • parc_resample (int, str, or bool, default=2) – Volumetric: target voxel size in mm (True -> 3mm). Surface: target density string (e.g. "32k"). Falsy disables resampling.

  • centroids (bool, default=False) – Volumetric path: use centroid-to-centroid distances instead of mean voxel-to-voxel distances.

  • surf_euclidean (bool, default=False) – Surface path: use euclidean centroid-to-centroid distances instead of the default geodesic mesh distance.

  • n_proc (int, default=1) – Number of parallel jobs for the (per-parcel or per-hemisphere) loop.

  • verbose (bool, default=True) – Show progress bars / info logging.

  • dtype (default=np.float32) – Output distance matrix dtype.

Returns:

A single 2D distance matrix for a volumetric parcellation; a tuple of one 2D matrix per hemisphere for a surface parcellation.

Return type:

np.ndarray or tuple of np.ndarray