netneurotools.spatial.permute_ac_map

netneurotools.spatial.permute_ac_map(Y, weights, I_trg, epsilon=0.0001, temp=1, niter=100, frac=0.5, max_stage=100, rng=None, seed=None, verbose=False, standardized=True, use_numba=False)[source]

Permute a random map Y until its autocorrelation structure is equal to I_trg.

This function uses a simulated annealing procedure to permute pair of values in a random map Y until its autocorrelation structure with respect to the weight matrices in weights matches the autocorrelation structure specified in I_trg.

Parameters:

  • Y ((n,) ndarray) – Initial vector to optimize. This is typically a random permutation of some empirical data.

  • weights ((n, n) or (k, n, n) ndarray) – Weight matrix or collection of weight matrices used to compute Moran’s I. Each matrix captures a unique type of pairwise interaction 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,)) – Target Moran’s I values for the generative algorithm. If multiple weight matrices are supplied, one target value must be provided for each matrix.

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

  • temp (float, default: 1) – Initial temperature for the simulated annealing algorithm.

  • niter (int, default: 100) – Number of swap proposals per annealing stage.

  • frac (float, default: 0.5) – Multiplicative cooling factor applied to the temperature after each annealing stage.

  • max_stage (int, default: 100) – Maximum number of stages in the optimization schedule.

  • rng (numpy.random.Generator, optional) – Random number generator used to perform random swaps during the optimization. If None (default), a new generator is created from seed.

  • seed (int, optional) – Seed used to initialize the random number generator. Ignored if rng is provided.

  • verbose (bool or int, default: False) – Levels of verbose during the optimization procedure.

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

  • use_numba (bool, optional) – Whether to use numba for calculation. Default: False (if numba is installed).

Returns:

  • Y ((n,) ndarray or list of ndarray) – Simulated maps with a specified autocorrelation structure (for each tolerance value).

  • it (int or list of int) – Iteration number(s) at which the solution is recorded (for each tolerance value).

  • temp (float or list of float) – Annealing temperature(s) at which the solution is recorded (for each tolerance value).

  • error (float or list of float) – Final optimization error(s) (for each tolerance value).