BrainSpace: Macroscale Gradient Mapping Toolbox

The BrainSpace MATLAB toolbox is organized into five functional groups to facilitate neuroimaging analysis and visualization:

1. Main Object: The core computational engine of the toolbox.
2. Surface Handling: Functions for reading, writing, parcellating, and manipulating brain surfaces.
3. Null Hypothesis Testing: Statistical tools including spin permutations, memory computation, and Moran randomization.
4. Visualization: Tools for plotting and visualizing data.
5. Data Loaders: Utilities to load sample datasets for tutorials and testing.

Note: The toolbox also includes Support Functions which are internal requisites for the main features and are not intended for direct user interaction.

The brainspace.gradient module provides tools for manifold learning, dimensionality reduction, and alignment. It is organized into several functional submodules:

• Gradients: Core gradient map implementations via brainspace.gradient.gradient.GradientMaps.
• Embedding: Dimensionality reduction techniques including Embedding, DiffusionMaps, LaplacianEigenmaps, and PCAMaps.
• Alignment: Methods to align different data representations, specifically using ProcrustesAlignment or the procrustes_alignment function.
• Kernels: Affinity computation via brainspace.gradient.kernels.compute_affinity.
• Utility functions: Mathematical helpers like dominant_set, is_symmetric, and make_symmetric.

To determine how many gradients to keep, inspect the eigenvalues (lambdas) of the components. In GradientMaps, these are stored in the lambdas_ attribute.

A scree plot can be used to identify a cut-off point: higher eigenvalues (or lower in Laplacian eigenmaps) indicate more important components.

import matplotlib.pyplot as plt

# Create a scree plot of the eigenvalues
fig, ax = plt.subplots(1, figsize=(5, 4))
ax.scatter(range(gm.lambdas_.size), gm.lambdas_)
ax.set_xlabel('Component Nb')
ax.set_ylabel('Eigenvalue')
plt.show()

The moran_randomization function provides two procedures for generating null models:

1. 'singleton': This procedure matches the input data's spatial autocorrelation more closely. However, it is limited by the number of possible randomizations (maximum of $2^n$, where $n$ is the number of datapoints). In most use cases, this provides sufficient randomizations.
2. 'pair': If the required number of perturbations (n_rep) is so high that it exceeds the maximum possible randomizations allowed by the 'singleton' method, you should use the 'pair' procedure instead.

To get familiar with BrainSpace, start with the tutorials which cover the core functionalities:

1. Creation and alignment of gradients (pymod.gradient)
2. Creation of null models (pymod.nullmodels)
3. Working with datasets (pymod.datasets)
4. Plotting and visualization (pymod.plotting)

For detailed technical specifications, refer to the API documentation.

BrainSpace provides utility functions to load common datasets for testing and tutorials:

• load_group_fc(name, scale, group): Loads group-level functional connectivity matrices. Example: load_group_fc('schaefer', scale=400).
• load_parcellation(name, scale, join): Loads parcellation labels. Example: load_parcellation('schaefer', scale=400, join=True).
• load_conte69(): Loads the Conte69 hemisphere surfaces for visualization.

from brainspace.datasets import load_group_fc, load_parcellation, load_conte69

conn_matrix = load_group_fc('schaefer', scale=400)
labeling = load_parcellation('schaefer', scale=400, join=True)
surf_lh, surf_rh = load_conte69()

The load_marker function is used to load specific cortical metric data for both the left and right hemispheres. It returns two matrices representing the data for each hemisphere.

Parameters:

• name: A string specifying the type of surface metric to load. Valid options are:
  • 'thickness': Cortical thickness.
  • 't1wt2w': T1w/T2w intensity.
  • 'curvature': Curvature.

Returns:

• metric_lh: Data matrix for the left hemisphere.
• metric_rh: Data matrix for the right hemisphere.

[metric_lh, metric_rh] = load_marker('thickness');

Gradients computed on parcellated data (e.g., 400 nodes) must be mapped back to the original surface resolution (e.g., 32492 points) before plotting. Use map_to_labels from brainspace.utils.parcellation to perform this mapping. Once mapped, use plot_hemispheres with the array_name parameter to visualize the gradient values on the surface.

import numpy as np
from brainspace.utils.parcellation import map_to_labels
from brainspace.plotting import plot_hemispheres

# Map the first gradient component back to the original surface resolution
# labeling is the parcellation object used during gradient computation
grad = map_to_labels(gm.gradients_[:, 0], labeling, mask=labeling != 0, fill=np.nan)

# Plot the mapped gradient on the cortical surface
plot_hemispheres(surf_lh, surf_rh, array_name=grad, size=(800, 200))