The neuroshape toolbox is designed to run both functional gradients and geometric eigenmodes using the Connectopic Laplacian approach for resting-state functional gradients Haak et al. (2018), our lab's approach (Borne et al. (2023)) to producing and analyzing task-driven gradients using psychophysiological interactions, and the Laplace-Beltrami Operator on a finite vertex mesh as built in ShapeDNA (see also Reuter et al. (2006) and Wachinger et al. (2015)).

Installation requirements

neuroshape works with Python 3.8+ and utilizes the following dependencies:

• nibabel (>=3.0)
• nilearn (>=0.7)
• numpy (>=1.14)
• scikit-learn (>=0.17)
• scipy
• lapy (>=0.7)
• scikit-sparse (>=0.4.8)
• neuromaps

VERY IMPORTANT:

In order to use much of the functionality of this code, you must:

1. Install FreeSurfer and source it on your OS path.
2. Install Connectome Workbench and source it on your OS path.
3. Install Gmsh and source it on your OS path.
4. Install MRtrix3 and source the <MRtrix3 installation directory>/bin folder on your OS path.
5. Run export MRTRIX=<MRtrix3 installation directory>.
6. Source MATLAB on your OS path.
7. Install scikit-sparse's libraries. Follow the installation process over there first.

See instructions here on how to source binaries to path.

The python script volume_eigenmodes.py was sourced from the BrainEigenmodes repository. Please cite their Nature paper (Pang et al. 2023) if you use that.

The MATLAB scripts in neuroshape/functions/wishart were sourced from the HCPpipelines repository and related Neuroimage paper (Glasser et al. 2013). Please be sure to cite them if you use the --filter functionality in connectopic_laplacian.py.

Installation

After installing the above dependencies, install the neuroshape toolbox with:

$ pip install neuroshape

You can also compile from source (and install the dependencies automatically):

$ git clone https://github.com/breakspear/neuroshape
$ cd neuroshape
$ conda env create -f environment.yml
$ python setup.py build
$ python setup.py install

NOTE: The above must be performed in that order, otherwise the setup won't run properly. If you don't wish to initialize a whole new environment (or you don't use conda), install the dependencies separately and forgo the conda env create step. Either way, the above will install the module in your environment's (or /usr/local/python/) site-packages directory under the package neuroshape. You can then import the extensions into your own code, e.g.:

from neuroshape import Shape
s = Shape('surfacedata.gii')

We are working on implementing full documentation for all extensions and tools in this package. As the project is in a rapid development stage, we appreciate your patience. You visit the Read the Docs page here for all current documentation.

Citation

If you use the subroutines involved, such as lapy or volume_eigenmodes.py, please be sure to cite the original authors.

License

This work is licensed under a BSD 3-Clause "New" or "Revised" License.

Copyright (C) 2023 Systems Neuroscience Group Newcastle. Please read the full license here before use.