neuromaps.nulls.hungarian

neuromaps.nulls.hungarian(data, atlas='fsaverage', density='10k', parcellation=None, n_perm=1000, seed=None, spins=None, surfaces=None)[source]

Generate null maps for parcellated data using the Hungarian method ([SN3]).

Method projects parcels to a spherical surface and uses arbitrary rotations with reassignments based on optimization via the Hungarian method to generate null distribution. All nulls are “perfect” permutations of the input data (at the slight expense of spatial topology)

Parameters:

  • data ((N,) array_like) – Input data from which to generate null maps. The data must be parcellated and array-like. If None is provided then the resampling array will be returned instead.

  • atlas ({'fsLR', 'fsaverage', 'civet'}, optional) – Name of surface atlas on which data are defined. Default: ‘fsaverage’

  • density (str, optional) – Density of surface mesh on which data are defined. Must be compatible with specified atlas. Default: ‘10k’

  • parcellation (tuple-of-str or os.PathLike, optional) – Filepaths to parcellation images ([left, right] hemisphere) mapping data to atlas specified by atlas and density. Should only be supplied if data represents a parcellated null map. Default: None

  • n_perm (int, optional) – Number of null maps or permutations to generate. Default: 1000

  • seed ({int, np.random.RandomState instance, None}, optional) – Seed for random number generation. Default: None

  • spins (array_like or str or os.PathLike) – Filepath to or pre-loaded resampling array. If not specified spins are generated. Default: None

  • surfaces (tuple-of-str or os.PathLike, optional) – Instead of specifying atlas and density this specifies the surface files on which data are defined. Providing this will override arguments supplied to atlas and density. Default: None

Returns:

nulls – Generated null distribution, where each column represents a unique null map

Return type:

np.ndarray

References

[SN3]

Kuhn, H. W. (1955). The Hungarian method for the assignment problem. Naval Research Logistics Quarterly, 2(1‐2), 83-97.