netneurotools.spatial.generate_ac_maps

netneurotools.spatial.generate_ac_maps(X, weights, I_trg=None, n_maps=10, epsilon=0.0001, standardized=True, seed=None, **kwargs)[source]

Generate surrogate maps preserving the autocorrelation structure of X.

This function calculates the Moran’s I of X with respect to each weight matrix provided in weights. Then, starting from Y, a random permutation of X, random pairs of values are swapped until the Moran’s I of Y matches the Moran’s I values of X within the specified tolerance. Alternative target values of Moran’s I can also be specified using the I_trg parameter.

See reference [1] for more info.

Parameters:

  • X (array-like of shape (n,)) – Vector of empirical values to be randomized.

  • weights (array-like of shape (n, n) or (k, n, n)) – Weight matrix or collection of weight matrices used to compute Moran’s I. Each matrix captures a unique type of pairwise interactions between brain regions. When multiple weight matrices are provided, the optimization matches the target Moran’s I values for all of them simultaneously.

  • I_trg (float or array-like of shape (k,), optional) – Target Moran’s I value(s). If not provided, the Moran’s I of X is computed for each weight matrix and used as the target.

  • n_maps (int, default: 10) – Number of surrogate maps to generate.

  • epsilon (float or array-like of shape (m,), default: 0.0001) – Error tolerance for the optimization. If an array is provided, the algorithm records the first solution that reaches each tolerance level.

  • standardized (bool, default: True) – Whether Moran’s I values are standardized or not.

  • seed (int, optional) – Seed used to initialize the random number generator.

  • **kwargs – Additional keyword arguments passed to generate_ac_map().

Returns:

Y_all – Surrogate maps whose autocorrelation structure matches the autocorrelation structure of X up to the tolerance value(s) specified in epsilon.

Return type:

(n,) or (n_maps, n) or (n_maps, n_eps, n) ndarray

References