eigenstrapping.SurfaceEigenstrapping

class eigenstrapping.SurfaceEigenstrapping(data, surface=None, evals=None, emodes=None, num_modes=200, save_surface=False, seed=None, decomp_method='matrix', medial=None, randomize=False, resample=False, n_jobs=1, use_cholmod=False, permute=False, add_res=False, truncate_modes=False, ret_fwhm=False, truncate_args=None, save_rotations=False, parcellation=None, normalize=True, use_nn=False, nn_method='original', eigen_perms=None)[source]

Compute the eigenmodes and eigenvalues of the surface in surface and resample the hypersphere bounded by the eigengroups contained within emodes, to reconstruct the data using coefficients conditioned on the original data Based on the degenerate solutions of solving the Laplace-Beltrami operator on the cortex. The power spectrum is perfectly retained (the square of the eigenvalues). If evals and emodes are given (i.e., precomputed) then eigenmodes are not computed. Performs amplitude adjustment by default (see resample)

@author: Nikitas C. Koussis, School of Psychological Sciences,

University of Newcastle & Systems Neuroscience Group Newcastle

Michael Breakspear, School of Psychological Sciences, University of Newcastle & Systems Neuroscience Group Newcastle

Process

  • the orthonormal eigenvectors n within eigengroup l give the surface

    of the hyperellipse of dimensions l-1 NOTE: for eigengroup 0 with the zeroth mode, we ignore it, and for eigengroup 1, this is resampling the surface of the 2-sphere

  • the axes of the hyperellipse are given by the sqrt of the eigenvalues

    corresponding to eigenvectors n

  • linear transform the eigenvectors N to the hypersphere by dividing

    by the ellipsoid axes

  • finds the set of points p on the hypersphere given by the basis

    modes (the eigenmodes) by normalizing them to unit length

  • rotate the set of points p by cos(angle) for

    even dimensions and sin(angle) for odd dims (resampling step)

  • find the unit vectors of the points p by dividing by the

    Euclidean norm (equivalent to the eigenmodes)

  • make the new unit vectors orthonormal using Gram-Schmidt process

  • return the new eigenmodes of that eigengroup until all eigengroups

    are computed

  • reconstruct the null data by multiplying the original coefficients

    by the new eigenmodes

  • resamples the null data by performing rank-ordering to replicate

    the reconstructed data term, then adds the noise term back into the null data to produce a surrogate that replicates the original variance of the empirical data. * Only performed if resample = True.

References

1. Robinson, P. A. et al., (2016), Eigenmodes of brain activity: Neural field theory predictions and comparison with experiment. NeuroImage 142, 79-98. <https://dx.doi.org/10.1016/j.neuroimage.2016.04.050>

2. Jorgensen, M., (2014), Volumes of n-dimensional spheres and ellipsoids. <https://www.whitman.edu/documents/Academics/Mathematics/2014/jorgenmd.pdf>

  1. <https://math.stackexchange.com/questions/3316373/ellipsoid-in-n-dimension>

4. Blumenson, L. E. (1960). A derivation of n-dimensional spherical coordinates. The American Mathematical Monthly, 67(1), 63-66. <https://www.jstor.org/stable/2308932>

5. Trefethen, Lloyd N., Bau, David III, (1997). Numerical linear algebra. Philadelphia, PA: Society for Industrial and Applied Mathematics. ISBN 978-0-898713-61-9.

  1. https://en.wikipedia.org/wiki/QR_decomposition

7. Chen, Y. C. et al., (2022). The individuality of shape asymmetries of the human cerebral cortex. Elife, 11, e75056. <https://doi.org/10.7554/eLife.75056>

param surface:

Filename of surface to resample of surface.darrays[0].data of shape (n_vertices, 3) and surface.darrays[1].data of shape (n_faces, 3). Must be a single hemisphere or bounded surface.

type surface:

str of path to file or array_like

param data:

Filename of empirical data to resample

type data:

str of path to file or np.ndarray of (n_vertices,)

param evals:

Eigenvalues corresponding to the number of eigenmodes n in emodes

type evals:

np.ndarray of shape (n,), optional

param emodes:

Eigenmodes that are the solution to the generalized eigenvalue problem or Helmholtz equation in the Laplace-Beltrami operator of the cortex

type emodes:

np.ndarray of shape (n_vertices, n), optional

param num_modes:

If evals and emodes are not given, then they are computed on the surface given in surface. This variable controls how many modes to compute. Cannot exceed the number of vertices in surface. Default is 200.

type num_modes:

int, optional

param medial:

Medial wall mask for the input surface surface. Suitable only if surface is cortical hemisphere. Will use the labels for the medial wall to mask out of the surrogates. If None, uses the naive implementation of finding the medial wall by finding 0.0 values in data - prone to errors if data has zero values outside of the medial wall. Can also pass False to not attempt masking of medial wall at all.

WARNING: If passing False to medial and True to resample, resulting surrogates may have strange distributions since the rank-ordering step may assign medial-wall values outside of the medial wall. USE AT YOUR OWN RISK.

type medial:

np.logical_array or str of path to file, default None

param save_surface:

As above, if evals and emodes are computed and medial wall mask is given, then cortical surface with cuts is saved. Default False.

type save_surface:

bool, optional

param seed:

Specify the seed for random angle generation (or random state instance) default None.

type seed:

None or int or np.random.RandomState instance

param decomp_method:

method of calculation of coefficients: ‘matrix’, ‘matrix_separate’, ‘regression’.

The default is ‘matrix’.

type decomp_method:

str, optional

param resample:

Set whether to resample surrogate map from original map to preserve values, default True

type resample:

bool, optional

param randomize:

Set whether to shuffle coefficients calculated from minimizing least-squares error to reconstruct surrogates. Results in better randomization of surrogates at the cost of poorer replication of empirical spatial autocorrelation.

type randomize:

bool, optional

param find_optimal:

Overrides evals and emodes if “True”. Computes a large amount of modes (20% of all possible modes of surface) and finds the optimal number of modes to make residual error between least-squares error estimation of coefficients and empirical data “white” (Gaussian), then generates new residuals with the same variance structure. Can increase computation time significantly but results in best balance of empirical variogram and randomization of values.

type find_optimal:

bool, optional

param n_jobs:

Number of workers to use for parallelization. Default 1.

type n_jobs:

int, optional

param use_cholmod:

Specify whether or not to use sksparse subroutines - requires scikit-sparse and libsuitesparse-dev to be installed. See https://github.com/scikit-sparse/scikit-sparse for more information.

type use_cholmod:

bool, optional

:raises ValueError : Inappropriate inputs:

eigen_decomposition(method='matrix')[source]

Decompose data using eigenmodes and calculate the coefficient of contribution of each vector.

Parameters:

methodstring

method of calculation of coefficients: ‘matrix’, ‘matrix_separate’, ‘regression’

Returns:

coeffsnumpy array of shape (N, 3)

coefficient values

eigen_spectrum(data, show=True)[source]

Plot the modal decomposition power spectrum reconstruction using original modes. See eigen_decomposition(). Returns fig and ax handles from matplotlib.pyplot for further use.

Parameters:

  • data (np.ndarray of shape (n_vertices,)) – Data to decompose and reconstruct for eigen spectrum.

  • show (bool, optional) – Flag whether to show plot, default True

Returns:

  • fig (matplotlib.pyplot class) – Figure handle

  • ax (matplotlib.pyplot class) – Axes handle

generate(output_modes=False)[source]

Generate eigensphere resampled surrogate.

Returns:

surrogate_data – Eigensphere resampled surrogate

Return type:

np.ndarray

plot_data(surface, data, hemi='left', view='lateral', cmap='gray', show=True)[source]

Plots a data map using nilearn.plotting, returns fig and ax handles from matplotlib.pyplot for further use. Can also plot values on the surface by input to data.

Parameters:

  • surface (nib.GiftiImage class or np.ndarray of shape (n_vertices, 3)) – A single surface to plot.

  • data (np.ndarray of shape (n_vertices,)) – Data to plot on the surface

  • hemi (str, optional) – Which hemisphere to plot. The default is ‘left’.

  • view (str, optional) – Which view to look at the surface. The default is ‘lateral’. Accepted strings are detailed in the docs for nilearn.plotting

  • cmap (str or matplotlib.cm class) – Which colormap to plot the surface with, default is ‘viridis’

  • show (bool, optional) – Flag whether to show the plot, default is True

Returns:

  • fig (figure handle)

  • ax (axes handle)

resample_eigenspace(emodes, distribution='normal')[source]

Resample across the eigenspace through linear weighted sums of real modes iteratively. Each iteration returns new orthogonal modes that are reweighted combinations of previous modes. NOTE: should only be applied to modes that have the same eigenvalue, i.e., on the eigensphere.

Parameters:

modes (np.ndarray of (n_vertices, mu)) – Orthogonal vectors of n_vertices and mu modes

Returns:

new_modes – Array containing resampled vectors for each pair.

Return type:

np.ndarray of (n_vertices, mu)

rotate_modes(emodes, gen=True)[source]

Rotate modes using random rotations.

Parameters:

vectors (np.ndarray of (n_vertices, mu)) – Orthogonal vectors of n_vertices and mu modes

Returns:

rotated_vectors – Array containing rotated vectors for each pair.

Return type:

np.ndarray of (n_vertices, mu)