NiSpace

Spatial (alteration) patterns observed in MRI images may often reflect function and dysfunction of underlying biological systems. This applies equally to function and structure, on the surface or in the volumetric space, and to typical as well as disordered brain-anatomical and functional patterns.

In recent years, several methods have been developed to compare spatial patterns between brain maps. In the simplest case, two brain maps are correlated with each other at the voxel- or parcel-level. The resulting correlation coefficient reflects the degree to which the two maps share a spatial pattern. We refer to this spatial correlation as “colocalization”.

The NiSpace (NeuroImaging Spatial Colocalization Environment) toolbox aims to provide the most comprehensive, yet easy-to-use and flexible framework to date for:

• neuroimaging data retrieval in standard imaging spaces,

• transformations between imaging spaces,

• estimation of spatial colocalizations using uni- and multivariate methods,

• multi-method non-parametric significance testing,

• and publication-ready visualization.

NiSpace is under development and its documentation currently is incomplete. We welcome anyone who would like to give it a try – your feedback is highly appreciated!

Installation

You can install the development version of NiSpace in a Python 3.9+ environment via command line using pip:

pip install git+https://github.com/LeonDLotter/NiSpace.git@dev

For reproducibility, consider installing a specific commit:

pip install git+https://github.com/LeonDLotter/NiSpace.git@{commit_hash}

NiSpace by default generates null maps using the Moran randomization method. All other null models are optional dependencies. Install optional dependencies directly with:

pip install "git+https://github.com/LeonDLotter/NiSpace.git@dev#egg=nispace[opt]"

Use & Attribution of third-party data

NiSpace relies on third-party data for its key functionalities. These third-party data include a growing number of brain parcellations and reference datasets.

Reference datasets may be individual brain maps accessible in their original state (then often downloaded directly from the source) and in processed format to optimize them for use in NiSpace. They may also be tabulated data with parcel-wise values for up to thousands of maps.

Processed maps and table data are hosted in a separate public GitHub repository, licensed under a CC BY-NC-SA 4.0 license. However, individual datasets may be subject to other licenses, which are listed in the metadata of each individual dataset or even map.

Important

When fetching a dataset via the API, NiSpace will print a detailed description of the dataset to the terminal, including the source DOIs and an explicit request to cite these sources. If the dataset is a collection of maps from different sources, e.g. the "pet" dataset, it will print the license and DOIs associated with each individual map in a table format.

Most licenses are attribution licenses. That means it is mandatory to cite the original source if the data are used in any publication or software. If you use 30 PET maps in your work and these PET maps have, in sum, 40 DOIs associated with them, you have to cite all of these.

Important

We are very keen on re-publishing data strictly within the use cases permitted through their licenses. Should you feel that we did not do so correctly in an individual case, please contact me and I will remove or adapt the dataset swiftly.

Support & Updates

For questions about the toolbox, analysis choices, or if you need help with its application, we recommend opening a new topic on NeuroStars using the tag “nispace”. If you encounter bugs, or would like to request a new feature, dataset, or parcellation, feel free to open a GitHub issue.

We will post regular updates on new features and releases on NeuroStars. To automatically get notified about new posts, you can create a NeuroStars account and enable notifications for “the nispace tag” (bell icon on the right side).

Other available tools

There are of course many other related tools available, of which a few are listed below:

Name	Target Problem	Significance Testing	Volume/Surface	Interface
JuSpace	Colocalization between nuclear imaging and case-control-difference maps	group permutation, null maps	volume	MATLAB-GUI
neuromaps	Providing various reference brain maps, as well as advanced imaging space transformation and null map estimation functions	null maps	surface, volume	Python-API
ENIGMA Toolbox	Relationships between effect-size maps and various reference datasets	null maps	surface	Python/MATLAB-API
BrainSpace	Focus on gradient mapping but includes null map generation functions	null maps	surface, volume	Python/MATLAB-API
Imaging Transcriptomics Toolbox	Gene-Set-Enrichment-Analysis on neuroimaging data using Allen Brain Atlas		surface (volume)	Python-API
GAMBA	Gene-Set-Enrichment-Analysis on neuroimaging data using Allen Brain Atlas	gene-set permutation, null maps	volume (surface)	Web-GUI/MATLAB-API
GCEA	Gene-Set-Enrichment-Analysis on neuroimaging data using Allen Brain Atlas	gene-set permutation, null maps	volume (surface)	MATLAB-API

NiSpace tries to incorporate most of the functionality of these tools in a unified framework. It took many ideas and implementations from the toolboxes listed above. Two prior tools developed by Leon Lotter – JuSpyce (basis for NiSpace, Python) and ABAnnotate (easy-to-use neuroimaging gene-set enrichment based on GCEA, MATLAB) – were discontinued in favor of NiSpace.

Name	Target Problem	Significance Testing	Volume/Surface	Interface
NiSpace	Colocalization between two or multiple brain maps in single-map, case-control, and set-enrichment settings. Generalizes set-enrichment approach to all kinds of reference maps. Incorporates advanced imaging space transformation through neuromaps. Includes a large range of reference datasets	null maps, group permutation, set permutation	volume, surface	Python-API (GUI planned)

Citation

There is currently no dedicated toolbox paper for NiSpace. Please cite the following when you use our tools in your work:

• NiSpace Zenodo DOI: Lotter & Dukart, Zenodo 2024

• JuSpace toolbox paper: Dukart et al., HBM 2021

• neuromaps toolbox paper: Markello, Hansen, et al., Nat. Methods 2022

• Application papers in the context of which NiSpace’s core methods were developed: Lotter et al., Neurosci. & Biobehav. Rev. 2023; Lotter et al., Nat. Commun. 2024; Lotter et al., bioRxiv 2026

See the documentation’s citation section for more information.

Contact

You can contact me via email. For usage questions, please consider opening a topic on NeuroStars (see Support & Updates), so that others can benefit from our exchange.

Getting Started

• Installation
• Data Management
• Citation

Integrated Datasets

• Brain Templates
• Parcellations
• Reference Datasets

Usage

• Introduction
  • Spatial colocalization — concept & motivation
  • Getting started: the NiSpace object
  • Data: datasets, parcellations & custom inputs
  • Working with imaging phenotypes (Y data)
  • Null models and permutation testing
  • Multiple comparisons correction
  • Visualizing colocalization results
  • Brain plotting with NiSpace
  • NiSpace workflows
  • X-Set Enrichment Analysis (XSEA; c.f. ABAnnotate)
  • Advanced topics
• Examples

Reference

• Reference API