neuromaps.nulls.burt2020

neuromaps.nulls.burt2020(data, atlas='fsaverage', density='10k', parcellation=None, n_perm=1000, seed=None, distmat=None, n_proc=1, tempdir=None, **kwargs)[source]

Generate null maps for data using method from [SN7] and [SN8].

Method uses variograms to estimate spatial autocorrelation of data and generates surrogate maps with similar variogram properties

Parameters:

  • data (array_like or path_like or niimg_like or giimg_like or tuple) – Input data from which to generate null maps. When a parcellation is provided, the data must be parcellated and array-like. Otherwise, the data can either be a volumetric image (niimg_like, e.g. nib.Nifti1Image) or a surface-based image (giimg_like, e.g. nib.GiftiImage). Alternatively, it can be a path-like object (str or os.PathLike) pointing to an image file.

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

  • density (str, optional) – Density of atlas 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

  • n_proc (int, optional) – Number of processors to use for parallelizing computations. If negative will use max available processors plus 1 minus the specified number. Default: 1 (no parallelization)

  • distmat (tuple-of-str or os.PathLike, optional) – Filepaths to pre-computed (left, right) surface distance matrices. Providing this will cause atlas, density, and parcellation to be ignored. Default: None

  • tempdir (os.PathLike, optional) – Directory specifying where the temporary distance matrix computed when generating volumetric nulls without parcellations should be stored. If None, a default directory is used. Default: None

  • kwargs (key-value pairs) – Other keyword arguments passed directly to the underlying null method generator

Returns:

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

Return type:

np.ndarray

References

[SN7]

Burt, J. B., Helmer, M., Shinn, M., Anticevic, A., & Murray, J. D. (2020). Generative modeling of brain maps with spatial autocorrelation. NeuroImage, 220, 117038.