nikitas-k / eigenstrapping

A toolbox for generating spatial null maps using geometric eigenmodes

The eigenstrapping toolbox is designed to help researchers generate statistically-rigorous models for null hypothesis testing between brain maps using non-local spectral shape descriptors - or geometric eigenmodes. Documentation can be found here. Read our preprint here!

Features

• A growing library of eigenmodes of standard surfaces and surface densities (fsaverage, fsLR)
• Cortical and subcortical null models for assessing statistical correspondence between brain maps
• Generation of geometric eigenmodes on user-derived surfaces

Installation Guide

Eigenstrapping is available in Python 3.7+. MATLAB version coming soon!

Installation

eigenstrapping can be installed by downloading the package from the Github repository:

git clone https://github.com/SNG-newy/eigenstrapping.git
cd eigenstrapping
python3 -m pip install .

Dependencies

To run eigenstrapping, the following Python packages are required (these should be automatically installed with the above command(s), as listed in the requirements.txt file):

• numpy
• scipy
• scikit-learn
• lapy
• matplotlib
• nibabel
• nilearn
• pandas
• brainspace
• netneurotools

nibabel and nilearn are required for surfaces and volumes. matplotlib is only required for fitting plots in :mod:`eigenstrapping.fit` and some of the surface plotting functions. Future improvements will reduce the number of dependencies needed.

Important additional dependencies

In order to avail the user of the volumetric pipeline, the following packages must be installed and sourced correctly:

• Connectome Workbench
• FreeSurfer 6.0.0+
• gmsh

Optional dependencies

In order to speed up calculation of eigenmodes, you can utilize scikit-sparse libraries to use Cholesky decomposition rather than LU decomposition. If these libraries are already installed, the functions in eigenstrapping will automagically recognize this and use these libraries, without the user specifying (as default behavior, this can be turned off. Refer to :ref:`Deriving eigenmodes <usage_geometry_eigenmodes>`).

You can install these libraries by following the instructions here.

Citing

When using eigenstrapping, please cite the following manuscript:

• Generation of surrogate brain maps preserving spatial autocorrelation through random rotation of geometric eigenmodes. Koussis, N.C., Pang, J.C., Jeganathan, J., Paton, B., Fornito, A., Robinson, P.A., Misic, B., Breakspear, M. (2024). bioRxiv 2024.02.07.579070 [Preprint]. https://dx.doi.org/10.1101/2024.02.07.579070

The core functions expand on code from BrainEigenmodes, please cite their work if you use our code:

• Geometric constraints on human brain function. Pang, J. C., Aquino, K. M., Oldehinkel, M., Robinson, P. A., Fulcher, B. D., Breakspear, M., & Fornito, A. (2023). Nature, 1-9. https://doi.org/10.1038/s41586-023-06098-1

Please also cite the papers for the method that we use to calculate eigenmodes on the surface:

• Laplace-Beltrami spectra as 'Shape-DNA' of surfaces and solids. Reuter M, Wolter F-E, Peinecke N. Computer-Aided Design. 2006;38(4):342-366. http://dx.doi.org/10.1016/j.cad.2005.10.011
• BrainPrint: a discriminative characterization of brain morphology. Wachinger C, Golland P, Kremen W, Fischl B, Reuter M. Neuroimage. 2015;109:232-48. http://dx.doi.org/10.1016/j.neuroimage.2015.01.032 http://www.ncbi.nlm.nih.gov/pubmed/25613439

And if you use the Heat Kernel for Geodesics method in :func:`eigenstrapping.geometry.geodesic_distmat`:

• Crane, K., Weischedel, C., & Wardetzky, M. (2013). Geodesics in heat: A new approach to computing distance based on heat flow. ACM Transactions on Graphics (TOG), 32(5), 1-11. https://arxiv.org/pdf/1204.6216

License information

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License cc-by-nc-sa. The full license can be found in the LICENSE file in the eigenstrapping distribution.