brainconn.utils.visualization.align_matrices

align_matrices(m1, m2, dfun='sqrdiff', verbose=False, H=1000000.0, Texp=1, T0=0.001, Hbrk=10)[source]

This function aligns two matrices relative to one another by reordering the nodes in M2. The function uses a version of simulated annealing.

Parameters:
  • M1 (NxN numpy.ndarray) – first connection matrix
  • M2 (NxN numpy.ndarray) – second connection matrix
  • dfun (str) –
    distance metric to use for matching
    ’absdiff’ : absolute difference ‘sqrdiff’ : squared difference (default) ‘cosang’ : cosine of vector angle
  • verbose (bool) – print out cost at each iteration. Default False.
  • H (int) – annealing parameter, default value 1e6
  • Texp (int) – annealing parameter, default value 1. Coefficient of H s.t. Texp0=1-Texp/H
  • T0 (float) – annealing parameter, default value 1e-3
  • Hbrk (int) – annealing parameter, default value = 10. Coefficient of H s.t. Hbrk0 = H/Hkbr
Returns:

  • Mreordered (NxN numpy.ndarray) – reordered connection matrix M2
  • Mindices (Nx1 numpy.ndarray) – reordered indices
  • cost (float) – objective function distance between M1 and Mreordered

Notes

Connection matrices can be weighted or binary, directed or undirected. They must have the same number of nodes. M1 can be entered in any node ordering.

Note that in general, the outcome will depend on the initial condition (the setting of the random number seed). Also, there is no good way to determine optimal annealing parameters in advance - these parameters will need to be adjusted “by hand” (particularly H, Texp, T0, and Hbrk). For large and/or dense matrices, it is highly recommended to perform exploratory runs varying the settings of ‘H’ and ‘Texp’ and then select the best values.

Based on extensive testing, it appears that T0 and Hbrk can remain unchanged in most cases. Texp may be varied from 1-1/H to 1-10/H, for example. H is the most important parameter - set to larger values as the problem size increases. Good solutions can be obtained for matrices up to about 100 nodes. It is advisable to run this function multiple times and select the solution(s) with the lowest ‘cost’.

If the two matrices are related it may be very helpful to pre-align them by reordering along their largest eigenvectors:

[v,~] = eig(M1); v1 = abs(v(:,end)); [a1,b1] = sort(v1); [v,~] = eig(M2); v2 = abs(v(:,end)); [a2,b2] = sort(v2); [a,b,c] = overlapMAT2(M1(b1,b1),M2(b2,b2),’dfun’,1);

Setting ‘Texp’ to zero cancels annealing and uses a greedy algorithm instead.