netneurotools.networks.strength_preserving_rand_sa

netneurotools.networks.strength_preserving_rand_sa(A, rewiring_iter=10, nstage=100, niter=10000, temp=1000, frac=0.5, energy_type='sse', energy_func=None, R=None, connected=None, verbose=False, seed=None)[source]

Strength-preserving network randomization using simulated annealing.

Randomize an undirected weighted network, while preserving the degree and strength sequences using simulated annealing.

This function allows for a flexible choice of energy function.

Parameters:

  • A ((N, N) array-like) – Undirected weighted connectivity matrix

  • rewiring_iter (int, optional) – Rewiring parameter. Default = 10. Each edge is rewired approximately rewiring_iter times.

  • nstage (int, optional) – Number of annealing stages. Default = 100.

  • niter (int, optional) – Number of iterations per stage. Default = 10000.

  • temp (float, optional) – Initial temperature. Default = 1000.

  • frac (float, optional) – Fractional decrease in temperature per stage. Default = 0.5.

  • energy_type (str, optional) –

    Energy function to minimize. Can be either:
    ‘sse’: Sum of squared errors between strength sequence vectors

    of the original network and the randomized network

    ‘max’: Maximum absolute error ‘mae’: Mean absolute error ‘mse’: Mean squared error ‘rmse’: Root mean squared error

    Default = ‘sse’.

  • energy_func (callable, optional) – Callable with two positional arguments corresponding to two strength sequence numpy arrays that returns an energy value. Overwrites “energy_type”. See “energy_type” for specifying a predefined energy type instead.

  • R ((N, N) array-like, optional) – Pre-randomized connectivity matrix. If None, a rewired connectivity matrix is generated using the Maslov & Sneppen algorithm. Default = None.

  • connected (bool, optional) – Whether to ensure connectedness of the randomized network. By default, this is inferred from data.

  • verbose (bool, optional) – Whether to print status to screen at the end of every stage. Default = False.

  • seed (float, optional) – Random seed. Default = None.

Returns:

  • B ((N, N) array-like) – Randomized connectivity matrix

  • min_energy (float) – Minimum energy obtained by annealing

Notes

Uses Maslov & Sneppen rewiring model to produce a surrogate connectivity matrix, B, with the same size, density, and degree sequence as A. The weights are then permuted to optimize the match between the strength sequences of A and B using simulated annealing.

This function is adapted from a function written in MATLAB by Richard Betzel.

References

Misic, B. et al. (2015) Cooperative and Competitive Spreading Dynamics on the Human Connectome. Neuron. Milisav, F. et al. (2024) A simulated annealing algorithm for randomizing weighted networks.