DOCSEARCHbyAlgolia
Submit Docs

neuromaps

repository·main·Indexed 43 days ago

https://github.com/netneurolab/neuromaps

A toolbox for projecting, resampling, and performing statistically-rigorous comparisons between brain maps and annotations. It provides a library of neuroimaging datasets, tools for transforming data between coordinate spaces (such as MNI-152 and fsaverage), and spatial null models for permutation testing and statistical validation.

Tokens
25.4K
Snippets
94
Records
125
Agent score
55%

What's inside neuromaps

  1. Overview of neuromaps features

    main

    The neuromaps toolbox is designed for making statistically-rigorous comparisons between brain maps (annotations).

    Key capabilities include:

    • Brain Map Library: Access to a growing collection of annotations in their original coordinate spaces (e.g., microstructure, function, electrophysiology, receptors).
    • Coordinate Space Transformations: Robust transforms between MNI-152, fsaverage, fsLR, and CIVET spaces.
    • Statistical Assessment: Integrated spatial null models to assess correspondences between different brain maps.

  2. Supported coordinate systems in neuromaps

    main

    The neuromaps toolbox supports four standard coordinate systems, each with specific resolutions or densities:

    Volumetric

    • MNI152: Uses the MNI ICBM 152 non-linear 6th generation symmetric template. Supported resolutions: 1mm, 2mm, 3mm (isotropic voxel sizes).

    Surface-based

    • fsLR: Developed by the Minn/Wash-U Human Connectome Project. Supported densities (vertices per hemisphere): 4k, 8k, 32k, 164k.
    • fsaverage: Used in FreeSurfer. Supported densities (vertices per hemisphere): 1k, 3k, 10k, 41k, 164k.
    • CIVET: Derived from the MNI152 volumetric template. Supported density (vertices per hemisphere): 41k.

  3. Locate Neuromaps data files

    main

    Neuromaps data is stored under the $NEUROMAPS_DATA environment variable.

    Directory Structure: Files are organized by source, description, and space. For example:

    • PET data: $NEUROMAPS_DATA/malen2022/raclopride/MNI152
    • Functional gradients: $NEUROMAPS_DATA/margulies2016/fcgradient01/fsLR/

    File Naming Conventions:

    • Volume data (NIfTI): source-desc_space-SPACE_res-RES_feature.nii.gz (e.g., source-malen2022_desc-raclopride_space-MNI152_res-2mm_feature.nii.gz)
    • Surface data (GIFTI): source-desc_space-SPACE_den-DEN_hemi-HEMI_feature.func.gii (e.g., source-margulies2016_desc-fcgradient01_space-fsLR_den-32k_hemi-L_feature.func.gii). Note: For surface data, replace L with R in the filename to access the opposite hemisphere.

  4. Locate neuromaps annotation files

    main

    Neuromaps data is stored under the $NEUROMAPS_DATA environment variable. The directory structure follows the pattern: $NEUROMAPS_DATA/{source}/{desc}/{space}/.

    File Naming Convention:

    • Volume data: source-{desc}_space-{space}_res-{res}_feature.nii.gz (or den-{den})
    • Surface data: source-{desc}_space-{space}_{den/res}-{den/res}_hemi-{L/R}_feature.func.gii

    Note: For surface data, you can switch hemispheres by replacing L with R (or vice versa) in the filename.

  5. Locate annotation data files

    main

    Annotation files are stored in a directory structure based on the $NEUROMAPS_DATA environment variable. The path follows the pattern: $NEUROMAPS_DATA/{source}/{desc}/{space}/.

    For surface data, the filename follows a specific naming convention: source-{source}_desc-{desc}_space-{space}_res-{res}_{feature}.nii.gz.

    Note: For surface data, you can access the opposite hemisphere by replacing L or R in the filename.

    # Example file location for dukart2018 flumazenil
$NEUROMAPS_DATA/dukart2018/flumazenil/MNI152/

# Example file name for surface data
source-dukart2018_desc-flumazenil_space-MNI152_res-3mm_feature.nii.gz

  6. Configure hemisphere and interpolation for surface transformations

    main

    Surface transformation functions in neuromaps.transforms accept two optional keyword parameters:

    1. hemi: Specifies the hemisphere(s) to process.

      • Use 'L' for left hemisphere only.
      • Use 'R' for right hemisphere only.
      • Use a tuple like ('R', 'L') to provide bilateral data in a non-standard (left, right) order.
      • If a single hemisphere is provided, the returned object is a tuple containing only one entry.

    2. method: Specifies the interpolation method.

      • 'linear' (default): Best for continuous data.
      • 'nearest': Best for integer-valued data like parcellations to avoid creating non-existent intermediate values.
    # Single hemisphere transformation
abagen_lh = abagen[0]
fslr_lh, = transforms.fsaverage_to_fslr(abagen_lh, '32k', hemi='L')

# Nearest-neighbors interpolation for parcellations
fslr_nearest = transforms.fsaverage_to_fslr(abagen, '32k', method='nearest')

# Custom hemisphere order
abagen_reverse = (abagen[1], abagen[0])
fslr_rh, fslr_lh = transforms.fsaverage_to_fslr(abagen_reverse, '32k', hemi=('R', 'L'))

  7. Locate annotation files on disk

    main

    Neuromaps data is stored under the $NEUROMAPS_DATA environment variable.

    Directory Structure: Files are organized by source, description, and space: $NEUROMAPS_DATA/{source}/{desc}/{space}/

    File Naming Convention:

    • Surface data (e.g., fsaverage): source-{desc}_space-{space}_den-{den}_hemi-{L/R}_{feature}.func.gii
    • Volumetric data (e.g., MNI152): source-{desc}_space-{space}_res-{res}_{feature}.nii.gz

    Tip: For surface data, you can switch hemispheres by replacing L with R (or vice versa) in the filename.

    # Example directory for beliveau2017 cumi101
$NEUROMAPS_DATA/beliveau2017/cumi101/fsaverage/

# Example filename for surface data
source-beliveau2017_desc-cumi101_space-fsaverage_den-164k_hemi-L_feature.func.gii

  8. Transform between surface-based coordinate systems

    main

    Transformations between different surface-based systems are bidirectional. Use the pattern neuromaps.transforms.XXX_to_YYY where XXX is the source system and YYY is the target system.

    Example: Transforming from fsaverage to fslr.

    from neuromaps.datasets import fetch_annotation
from neuromaps import transforms

abagen = fetch_annotation(source='abagen')
fslr = transforms.fsaverage_to_fslr(abagen, '32k')

fslr_lh, fslr_rh = fslr

  9. Cite neuromaps in your research

    main

    When using the neuromaps toolbox in your work, please cite the primary manuscript:

    Markello, RD, Hansen, JY, Liu, ZQ, Bazinet, V, Shafiei, G, Suarez, LE, Blostein, N, Seidlitz, J, Baillet, S, Satterthwaite, TD, Chakravarty, MM, Raznahan, A, Misic, B. (2022). neuromaps: structural and functional interpretation of brain maps. Nature Methods. doi:10.1038/s41592-022-01625-w

    To cite a specific version of the toolbox, use the Zenodo reference (e.g., 10.5281/zenodo.5842498).

  10. Cite specific neuromaps features and data

    main

    Depending on the specific functionality or data you use from neuromaps, additional citations may be required:

    • Volume-to-surface transformations (registration fusion): Cite Buckner et al 2011 (original proposition) and Wu et al 2018 (first implementation of MNI152 to fsaverage transformation).
    • Surface-to-surface transformations (multimodal surface matching): Cite Robinson et al 2014 and Robinson et al 2018.
    • Included brain map data: Cite the original papers that published the data. A reference table is available in the neuromaps wiki or via this Google Spreadsheet.
    • Spatial null models: Each type of null model has an associated citation. These can be found in the docstring of the relevant function or in the neuromaps API documentation.

  11. Install neuromaps

    main

    You can install neuromaps using several methods depending on your needs. It requires Python 3.8+.

    Install from PyPI

    For a stable version, use pip:

    pip install neuromaps

    Install from Source (Recommended)

    To get the latest features and bug fixes, install directly from the GitHub repository:

    pip install git+https://github.com/netneurolab/neuromaps.git

    Alternatively, clone the repository and install locally:

    git clone https://github.com/netneurolab/neuromaps
cd neuromaps
pip install .

    Critical Dependency: Connectome Workbench

    To use most transformation and resampling functionality, you must have Connectome Workbench installed and available in your system's PATH.

    pip install neuromaps