nispace.nulls.generate_spins

nispace.nulls.generate_spins(parc, parc_space, n_perm=1000, method='original', seed=None, parc_hemi=None)[source]

Generate spin resampling indices for a surface parcellation.

Supports bilateral (tuple of two GiftiImages) and single-hemisphere (single GiftiImage) parcellations.

Parameters:

  • parc (tuple of two GiftiImage, or a single GiftiImage) – Bilateral (lh_img, rh_img) or single-hemisphere surface parcellation.

  • parc_space (str) – Surface space of parc (e.g. "fsaverage", "fsLR").

  • n_perm (int, default=1000) – Number of spin permutations to generate.

  • method (str, default="original") – Rotation-generation method forwarded to neuromaps’ gen_spinsamples. One of "original" (Alexander-Bloch method), "vasa", "hungarian", or "cornblath" ([14], [15], [16], [12]).

  • seed (int, optional) – Random seed for reproducibility.

  • parc_hemi (list of str, optional) – Which hemisphere a single (unilateral) parc belongs to (["L"] or ["R"]); defaults to "L" with a warning if not given. Not needed for a bilateral parc.

Returns:

spins_lh, spins_rh – Spin indices. For bilateral parcellations both have shape (n_parcels_hemi, n_perm). For a single-hemisphere parcellation the unused hemisphere gets shape (0, n_perm). RH indices are local to [0, n_rh).

Return type:

ndarray of int32

Notes

Typically invoked through generate_null_maps() for spin-based null methods, but also called directly (e.g. by NiSpace/Parcellation) when precomputing or caching a spin matrix ahead of repeated use.