Abstract
Understanding how cognitive functions emerge from brain structure depends on quantifying how discrete regions are integrated within the broader cortical landscape. Recent work established that macroscale brain organization and function can be described in a compact manner with multivariate machine learning approaches that identify manifolds often described as cortical gradients. By quantifying topographic principles of macroscale organization, cortical gradients lend an analytical framework to study structural and functional brain organization across species, throughout development and aging, and its perturbations in disease. Here, we present BrainSpace, a Python/Matlab toolbox for (i) the identification of gradients, (ii) their alignment, and (iii) their visualization. Our toolbox furthermore allows for controlled association studies between gradients with other brainlevel features, adjusted with respect to null models that account for spatial autocorrelation. Validation experiments demonstrate the usage and consistency of our tools for the analysis of functional and microstructural gradients across different spatial scales.
Introduction
Over the last century, neuroanatomical studies in humans and nonhuman animals have highlighted two complementary features of neural organization. On the one hand, studies have demarcated structurally homogeneous areas with specific connectivity profiles, and ultimately distinct functional roles^{1,2,3,4,5}. In parallel, neuroanatomists have established spatial trends that span across cortical areas both in terms of their histological properties, and connectivity patterns^{6,7,8,9}. Such characterizations of cortical areas by their placement in the broader cortical hierarchy has provided a foundation for understanding functions that emerge through cortical interactions.
Although much of the more recent work linking measures of neural processing (for example from functional magnetic resonance imaging, MRI) to cognition has focused on identifying discrete regions and modules and their specific functional roles^{10}, recent conceptual and methodological developments have provided the data and methods that allow macroscale brain features mapped to low dimensional manifold representations, also described as gradients^{11}. Gradient analyses operating on connectivity data were applied to diffusion MRI tractography data in specific brain regions^{12,13} as well as neocortical, hippocampal, and cerebellar restingstate functional MRI connectivity maps^{11,14,15,16,17,18,19,20}. Similar techniques have also been used to describe myelinsensitive tissue measures and other morphological characteristics^{21,22,23}, as well as approaches based on combined network information aggregated from multiple features^{24}. Other studies have used a similar framework to describe task based neural patterns either using metaanalytical coactivation mapping^{20} or largescale functional MRI task data sets^{25}. Gradients have also been successfully derived from nonimaging data that were registered to stereotaxic space, including hippocampal post mortem gene expression information^{26} and 3D histology data^{22}, to explore cellular and molecular signatures of neuroimaging and connectome measures. Core to these techniques is the computation of an affinity matrix that captures interarea similarity of a given feature followed by the application of dimensionality reduction techniques to identify a gradual ordering of the input matrix in a lower dimensional manifold space (Fig. 1).
The ability to describe brain wide organizational principles in a single manifold offers the possibility to understand how the integrated nature of neural processing gives rise to function and dysfunction. Adopting a macroscale perspective on cortical organization has already provided insights into how cortexwide patterns relate to cortical dynamics^{27} and high level cognition^{25,28,29,30}. Furthermore, several studies have leveraged gradients as an analytical framework to describe atypical macroscale brain organization across clinical conditions, for example, by showing perturbations in functional connectome gradients in autism^{31} and schizophrenia^{32}. Finally, comparisons of gradients across different imaging modalities have highlighted the extent to which structure directly constrains functional measures^{22}, while consideration of gradients across species has highlighted how evolution has shaped more integrative features of the cortical landscape^{7,33,34,35,36,37}.
The growth in our capacity to map whole brain cortical gradients, coupled with the promise of a better understanding of how structure gives rise to function, highlights the need for a set of tools that support the analysis of neural manifolds in a compact and reproducible manner. The goal of this paper is to present an openaccess set of easytouse tools that allow the identification, visualization, and analysis of macroscale gradients of brain organization. We hope this will provide a method for calculating cortical manifolds that facilitates their use in future empirical work, allows comparison between studies, and allows for result replicability. To offer flexibility in implementation, we provide our toolbox in both Python and Matlab, two languages widely used in the neuroimaging and network neuroscience communities. Associated functions are freely available for download (http://github.com/MICAMNI/BrainSpace) and complemented with an expandable online documentation (http://brainspace.readthedocs.io). We anticipate that our toolbox will assist researchers interested in studying gradients of cortical organization, and propel further work that establishes the overarching principles through which structural and functional organization of human and nonhuman brains gives rise to key aspects of cognition.
Results
This section illustrates the usage of BrainSpace for gradient mapping and null model generation. Examples and evaluations are based on 217 subjects from the Human Connectome Project (HCP) dataset^{38}, as in prior work^{20}. Matlab code is presented in the main version of the paper. Corresponding Python codes are available in the Supplementary Information.
Generating gradients
To illustrate the basic functionality of the toolbox, we computed gradients derived from restingstate functional MRI functional connectivity (FC). In short, the input matrix was made sparse (to 10% sparsity) and a cosine similarity matrix was computed. Next, three different manifold algorithms (i.e., principal component analysis (PCA), Laplacian eigenmaps (LE), diffusion mapping (DM)) were applied, followed by plotting their first and second gradients on the cortical surface (Figure 2). Resulting gradients (Fig. 3) derived from all dimensionality reduction techniques resemble those published previously^{11}, although for PCA the somatomotor to visual gradient explains more variance than the default mode to sensory gradient.
Aligning gradients
Gradient alignment across modalities. Based on subjects present in both the FC dataset as well as those used in the validation group of ref. ^{22} (n = 70), we examined the correspondence between gradients computed from different modalities and evaluated increases in correspondence through gradient alignment. The modalities evaluated are FC and microstructural profile covariance (MPC). Here we compared gradients of these in unaligned form, and after Procrustes alignment and joint embedding (Fig. 4, Fig. 5). As expected, gradient correspondence increased slightly following Procrustes alignment compared to unaligned gradients, and even more markedly following joint embedding. Beyond maximizing correspondence, the choice of Procrustes versus joint embedding can depend on the specific applications. Procrustes alignment preserves the overall shape of the different gradients and can thus be preferable to compare different gradients. Joint embedding, on the other hand, identifies a joint solution that maximizes their similarity, resulting in a gradient that may be more of a ‘hybrid’ of the input manifolds. Joint embedding is, thus, a technique to identify correspondence and to map from one space to another, and conceptually related to widely used multivariate associative techniques such as canonical correlation analysis or partial least squares which seek to maximize the linear associations between two multidimensional datasets^{39}. Note that the computational cost of joint embedding is substantially higher, so Procrustes analysis may be the preferred option when computational resources are a limiting factor.
Gradient alignment across individuals. Researchers may also be interested in comparing gradient values between individuals^{31}, for example to assess perturbations in FC gradients as a measure of brain network hierarchy. One possible approach could be to first build a grouplevel gradient template, to which both diagnostic groups are aligned using Procrustes rotation. After that, the two groups can be compared statistically and at each vertex, for example using tools suitable for surfacebased linear modeling^{40}.
In the example below, we computed a template gradient from an outofsample dataset of 134 subjects from the HCP dataset (the validation cohort used by^{20}). Next, we used the Procrustes analysis to align individual’s gradients of each subject to the group level template (Fig. 6, Fig. 7).
Gradients across different spatial scales. The gradients presented so far were all derived at a vertexwise level, which requires considerable computational resources. To minimize time and space requirements and to make results comparable to parcellationbased studies, some users may be interested in deriving gradients from parcellated data. To illustrate the effect of using different parcellations, we repeated the gradient identification and analysis across different spatial scales for both a structural and a functional parcellation. Specifically, we subdivided the conte69 surface into 400, 300, 200, and 100 parcels based on both a clustering of a wellestablished anatomical atlas^{41}, as well as a recently published localglobal functional clustering^{42} and built FC gradients from these representations (Fig. 8). These parcellations and subsampling schemes are provided in the shared folder of the BrainSpace toolbox.
Overall, with increasing spatial resolution the FC gradients became more pronounced and gradients derived from functional and structural parcellations were more similar. At a scale of 200 nodes or lower, putative functional boundaries may not be as reliably captured when using anatomicallyinformed parcellations, resulting in more marked alterations in the overall shape of the gradients.
For further evaluation, we related the above gradients across multiple scales relative to Mesulam’s classic scheme of cortical laminar differentiation and hierarchy^{22,43}. It shows a clear correspondence between the first gradient and the Mesulam hierarchy for high resolution data of 300 nodes and more, regardless of the parcellation scheme. While high correspondence was still seen for functional parcellations at lower granularity, it was markedly reduced when using structural parcellations. For researchers interested in using Mesulam’s parcellation, it has been provided on Conte69 surfaces in the shared folder of the BrainSpace toolbox. We also provide the data required to reproduce the evaluated FC and MPC gradients across these different spatial scales. Such gradients can be used to stratify other imaging measures, including functional activation and connectivity patters^{28,31,44}, metaanalytical syntheses^{11,29}, cortical thickness measures or Amyloidbeta PET uptake data^{45}.
Null models
Here, we present an example to assess the significance of correlations between FC gradients and data from other modalities (cortical thickness and T1w/T2w image intensity in this example). We present code (see Fig. 9) to generate previously proposed spin tests^{46}, which preserve the autocorrelation of the permuted features by rotating the feature data on the sphere. In our example (Fig. 10), the correlations between FC gradients and T1w/T2w stay significant (twotailed, p < 0.001) even when comparing the correlation to 1000 null models whereas correlations between FC gradients and cortical thickness was nonsignificant (twotailed, p = 0.12).
Testretest stability
The HCP dataset has four rsfMRI scans, split over two days. As such, we can leverage this data to assess testretest stability of gradients. Here, we assessed the testretest stability of gradients at the group level. Specifically, we redid the analysis of Fig. 2, but split the dataset by day of scanning. Stability was very high for LE and DM (r > 0.99) and moderatetohigh for PCA (r ≈ 0.72) (Supplementary Fig. 1).
Discussion
While tools for unsupervised manifold identification and their alignment are extensively used in data science across multiple research domains^{47}, and while few prior connectome level studies made their workflow openly accessible (see refs. ^{11,15,48}), we currently lack a unified software package that incorporates the major steps of gradient construction and evaluation for neuroimaging and connectome datasets. We filled this gap with BrainSpace, a compact openaccess Matlab/Python toolbox for the identification and analysis of lowdimensional gradients for any given regional or connectomelevel feature. As such, BrainSpace provides an entry point for researchers interested in studying gradients as windows into brain organization and function. BrainSpace is a simple and modular package accessible to beginners, yet expandable for advanced programmers. At its core is a simple objectoriented model, allowing for flexible computation of different (i) affinity matrices, (ii) dimensionality reduction techniques, (iii) alignment functions, and (iv) null models. We also supplied precomputed gradients, a novel subparcellation of the DesikanKilliany atlas, and a literaturebased atlas of cortical laminar differentiation that we used in a recent study^{22,43}.
As our main purpose was to provide an accessible introduction of the toolbox’s basic functionality, we focused on tutorial examples and several selected assessments that demonstrate more general aspects of gradient analyses. First, relatively consistent FC gradients were produced by different dimensionality reduction techniques (i.e., PCA, LE, DM), at least when cosine similarity was chosen for affinity matrix computations. Interactions between input data, affinity matrix kernels, and dimensionality reduction techniques may nevertheless occur, a topic worthwhile to explore in future work. Second, we could show a relative consistency of FC gradients across spatial scales in the case of vertexwise analyses and when parcellations with 300 nodes or more were used. However, we also observed an interaction between the type of input data and parcellation at lower spatial scales. In fact, lower resolution structural parcellations might not capture finegrained functional boundaries, specifically in heteromodal and paralimbic association cortices which may be less constrained by underlying structuralmorphological features^{22}. It will be informative for future work to clarify how input modality (e.g., FC, MPC, or diffusion MRI), the choice of parcellation, and the spatial scale impact gradient analyses.
There are two broad ways through which the gradient method and the BrainSpace toolbox may improve our understanding of neural organization and its associated functions. One avenue is the identification of similarities and differences in gradients derived from different brain measures. To address associations between cortical microstructure and macroscale function, a previous study^{22} demonstrated that gradients derived from 3D histology and myelinsensitive MRI measures show both similarities and differences from those derived from resting statestate functional connectivity analysis^{11}. This raises the possibility that the gradient method may help quantify common and distinct influences on functional and structural brain organization and shed light on the neural basis of more flexible (i.e., less structurally constrained) aspects of human cognition^{22}. Another way that gradients can inform our understanding of how functions emerge from the cortex is through the analysis of how macroscale patterns of organization change in disease. One recent study^{31}, for example, demonstrated differences in the principal functional gradient, identified by^{11}, between individuals with autism spectrum disorder and typically developing controls. In this way, manifoldderived gradient analyses hold the possibility to characterize how macroscale functional organization may become dysfunctional in atypical neurodevelopment. To achieve both goals, alignment of different gradients should be considered, and this can be achieved by a number of methods we supplied, such as Procrustes alignment. This allows researchers to both compare gradients from different modalities and to homogenize measures across subjects, while minimizing the changes to individual manifolds. Our evaluations highlighted an increase in correspondence between individual subjects and the template manifold when Procrustes alignment was used compared to unaligned approaches, mainly driven by trivial changes in the sign of specific gradients in a subgroup of subjects. As an alternative to Procrustes alignment, it is also possible to align gradients via joint manifold alignments, often referred to as joint embedding^{37}. The gradients provided by this approach can augment both crosssubject^{49} as well as crossspecies analyses^{37}. Of note, joint embeddings generate a new manifold, which may result in new solutions that might slightly differ from the initial gradients computed individually.
When assessing the significance of correlations between gradients and other features of brain organization, there is an increasing awareness to ideally also evaluate correlations against null models with a similar spatial autocorrelation as the original features. BrainSpace provides two different approaches to build null models, including an adaptation of a previously released spin permutation test^{46} and Moran’s spectral randomization^{50}. Gradients can also serve as a coordinate system, and stratify cortical features that are not gradientbased per se. Examples include surfacebased geodesic distance measures from sensorymotor regions to other regions of cortex^{11}, taskbased functional activation patterns and metaanalytical data^{11,28,29}, as well as MRIbased cortical thickness and PETderived amyloid beta uptake measures^{45}. As such, using manifolds as a new coordinate system^{34} may complement widely used parcellation approaches^{2,42,51} and be can be useful for the compact representation of findings and aid in the interpretation and communication of results.
Although, we have only illustrated the use of our toolbox with neocortical surface data, the gradientbased functionality of BrainSpace is not restricted to these regions and can also be used with other datasets (e.g., hippocampal measures, subcortical measures, and volumetric data). However, as of version 0.1, visualization is only available for surface meshes. Extending the visualization functionality of BrainSpace to support other cerebral structures and volumetric data is a promising line of future work.
Methods
Input data description
Our toolbox requires a real input matrix. Let X ∈ ℝ^{n×p} be a matrix aggregating features of several seed regions. In other words, each seed is represented by a pdimensional vector, x_{i}, built based on the features of the ith seed region, where \(X\left( {i,j} \right) = x_i^j\) denotes the jth feature of the ith seed. In many neuroimaging applications, X may represent a connectivity metric (e.g., restingstate functional MRI connectivity or diffusion MRI tractography derived structural connectivity) between different seed and target brain regions. When seed and target regions are identical, the input matrix X is square. Furthermore, if the connectivity measure used to build the matrix is nondirectional, X is also symmetric. If seeds and targets are different, for example when assessing connectivity patterns of a given region with the rest of the brain^{15,20}, we may have that n ≠ p, resulting in a nonsquare matrix. The dimensions and symmetry properties of the input matrix X may interact with the dimensionality reduction procedures presented in section 4.5. A simple strategy to make matrices symmetric and square is to use kernel functions, which will be covered in the following section.
Affinities and kernel functions
Since we are interested in studying the relationships between the seed regions in terms of their features (e.g., connectivity with target regions), our toolbox provides several kernel functions to compute the relationship between every pair of seed regions and derive a nonnegative square symmetric affinity matrix A ∈ ^{n×n}, where A(i, j) = A(j, i) denotes the similarity or ‘affinity’ between seeds I and j. Moreover, a square symmetric matrix is a requirement for the next step in our framework (i.e., dimensionality reduction). Note that when the input matrix X is already square and symmetric (e.g., seed and target regions are the same), there may be no need to derive the affinity matrix and X can be used directly to perform dimensionality reduction. Accordingly, BrainSpace provides the option of skipping this step and using the input matrix as the affinity.
There are numerous kernels to compute affinity matrices. As of version 0.1, our toolbox implements the following: Gaussian, cosine similarity, normalized angle similarity, Pearson’s correlation coefficient, and Spearman rank order correlations. For simplicity, let x = x_{i} and y = x_{j}, these kernels can be expressed as follows:
1. Gaussian kernel:
where γ is the inverse kernel width and ■ denotes the l_{2}norm.
2. Cosine similarity:
where cossim (■,■) is the cosine similarity function and T stands for transpose.
3. Normalized angle similarity:
4. Pearson correlation:
where ρ is the Pearson correlation coefficient, and \({\bar{\boldsymbol{x}}}\) and \({\bar{\boldsymbol{y}}}\) denote the means of x and y, respectively.
5. Spearman rank order correlation:
where r_{x} and r_{y} denote the ranks of x and y, respectively.
Version 0.1 of BrainSpace thus includes commonly used kernels in the gradient literature and additional ones for experimentation. To our knowledge, no gradient paper has used Pearson or Spearman correlation. Note that if X is already rowwise demeaned, Pearson correlation amounts to cosine similarity. The Gaussian kernel is widely used in the machine learning community (for example in the context of Laplacian eigenmaps and support vector machines), which provides a simple approach to convert Euclidean distances between our seeds into similarities. Cosine similarity, (example application^{11}:), computes the angle between our feature vectors to describe their similarity. Notably, cosine similarity ranges from 1 to 1, with negative correlations to be transformed to nonnegative values. This motivated inclusion of the normalized angle kernel (example application:^{20}), which circumvents negative similarities by transforming similarities to [0,1], with 1 denoting identical angles, and 0 opposing angles. Cosine similarity and Pearson and Spearman correlation coefficients may produce negative values (i.e., [–1,1]) if feature vectors are negatively correlated. A simple mitigation is to set negative values to zero^{11}. Additionally, BrainSpace provides an option for rowwise thresholding of the input matrix^{11,20,22,31}. Each vector of the input matrix is thresholded at a given sparsity (e.g., by keeping the weights of the top 10\% entries for each region). This procedure ensures that only strong, potentially less noisy, connections contribute to the manifold solution.
In addition to the aforementioned kernels, BrainSpace provides the option to provide a custom kernel or of skipping this step and using the input matrix as an affinity matrix.
Dimensionality reduction
In the input matrix, each seed x_{i} is defined by a pdimensional feature vector, where p may denote hundreds of parcels or thousands of vertices/voxels. The aim of dimensionality reduction techniques is to find a meaningful underlying lowdimensional representation, \({\cal{G}} \in {\Bbb R}^{n \times m}\) with \(m \ll p\), hidden in the highdimensional ambient space. These methods can be grouped into linear and nonlinear techniques. The former use a linear transformation to unravel the latent representation, while techniques in the second category use nonlinear transformations. As of version 0.1, BrainSpace provides three of the most widely used dimensionality reduction techniques for macroscale gradient mapping: PCA for linear embedding, and LE and DM for nonlinear dimensionality reduction.
 1.
PCA is a linear approach that transforms the data to a lowdimensional space represented by a set of orthogonal components that explain maximal variance. Given a columnwise demeaned version of the input matrix X_{d}, the lowdimensional representation is computed as follows:
$${\cal{G}}_{PCA} = US^T,$$where U are the left singular vectors and S a diagonal matrix of singular values obtained after factorizing the input matrix using singular value decomposition, X_{d} = USV^{T}. Although here we present the singular value decomposition version below, PCA can also be performed via eigendecomposition of the covariance matrix of X.
 2.
LE is a nonlinear dimensionality reduction technique that uses the graph Laplacian of the affinity matrix A to perform the embedding:
$$L = D  A,$$where the degree matrix D is a diagonal matrix defined as \(D\left( {i,i} \right) = \mathop {\sum }\nolimits_j A\left( {i,j} \right)\) and L is the graph Laplacian matrix. Note that we can also work with its normalized version instead \(L_S = D^{1/2}LD^{1/2}\)^{52}. LE then proceeds to solve the generalized eigenvalue problem:
$$L{\boldsymbol{g}} = \lambda D{\boldsymbol{g}},$$where the eigenvectors g_{k} corresponding to the m smallest eigenvalues λ_{k} (excluding the first eigenvalue) are used to build the new lowdimensional representation:
$${\cal{G}}_{LE} = \left[ {{\boldsymbol{g}}_1,{\boldsymbol{g}}_2, \ldots ,{\boldsymbol{g}}_m} \right].$$  3.
DM also seeks a nonlinear mapping of the data based on the diffusion operator P_{α}, which is defined as follows:
$$P_\alpha = D_\alpha ^{  1}W_\alpha ,$$
where α ∈ [0,1] is the anisotropic diffusion parameter used by the diffusion operator, \(W_\alpha = D^{  1/\alpha }AD^{  1/\alpha }\) is built by normalizing the affinity matrix according to the diffusion parameter and D_{α} is the degree matrix derived from W_{α}. When α = 0, the diffusion amounts to normalized graph Laplacian on isotropic weights, for α = 1, it approximates the LaplaceBeltrami operator and for the case where α = 0.5 it approximates the FokkerPlanck diffusion^{53}. This parameter controls the influence of the density of sampling points on the manifold (α = 0, maximal influence; α = 1, no influence). In the gradient literature, the anisotropic diffusion hyperparameter is commonly set to α = 0,5^{11,16,20}, a choice that retains global relations between data points in the embedded space. Similar to LE, DM computes the eigenvalues and eigenvectors of the diffusion operator. However, in this case, the new representation is constructed with the scaled eigenvectors corresponding to the largest eigenvalues, after omitting the eigenvector with the largest eigenvalue:
where t is the time parameter that represent the scale.
All aforementioned dimensionality reduction approaches assume that our highdimensional data lies on some lowdimensional manifold embedded in ambient space, which is typically the case with neuroimaging datasets. These techniques, therefore, provide a convenient approach to handle the curse of dimensionality inherent to neuroimaging data. Moreover, they facilitate comparison by recovering representations with the same number of dimensions even when source data is noncomparable in ambient space (for example when subjects have different fMRI time series of different lengths). PCA, in particular, is able to discover the lowdimensional structure when the data lies in an approximately linear manifold, but performs poorly when there are nonlinear relationships within the data. In such scenarios, LE and DM are more appropriate to discover the intrinsic geometric structure. From a technical point of view, the advantage of PCA over the nonlinear approaches included in BrainSpace is that it provides a mapping from the high to the lowdimensional space rather than simply producing the new lowdimensional representations. Hence, the choice between linear and nonlinear dimensionality reduction is problemdependent and may also be influenced by the nature of the data under study.
Alignment of gradients
Gradients computed separately for two or more datasets (e.g., patients vs controls, left vs right hippocampi) may not be directly comparable due to different eigenvector orderings in case of eigenvalue multiplicity (i.e., eigenvalues with the same value) and sign ambiguity of the eigenvectors^{54}. Aligning gradients improves comparability and correspondence. However, we recommend visually inspecting the alignment results; if the manifold spaces are substantially different, then alignments may not provide sensible output. In version 0.1 of the BrainSpace toolbox, gradients can be aligned using Procrustes analysis^{55} or implicitly by joint embedding.
Procrustes analysis
Given a source \({\cal{G}}_s\) and a target \({\cal{G}}_t\) representation, Procrustes analysis seeks an orthogonal linear transformation ψ to align the source to the target, such that \(\psi ({\cal{G}}_s)\) and \({\cal{G}}_t\) are superimposed. Translation and scaling can also be performed by initially centering and normalizing the data prior to estimation of the transformation. For multiple datasets, a generalized Procrustes analysis can be employed. Let \({\cal{G}}_k,k = 1,2, \ldots ,N\) be the lowdimensional representations of N different datasets (i.e., input matrices X_{K}). The procedure proceeds iteratively by aligning all representations \({\cal{G}}_k\) to a reference and updating the reference \({\cal{G}}_R = \frac{1}{N}\mathop {\sum }\nolimits_k \psi ({\cal{G}}_k)\) by averaging the aligned representations. In the first iteration, the reference can be chosen from the available representations, or an outofsample template can be provided (e.g., from a holdout group).
Joint embedding
Joint embedding is a dimensionality reduction technique that finds a common underlying representation of multiple datasets via simultaneous embedding^{37}. The main challenge of this technique is to find a meaningful approach to establish correspondences between original datasets (i.e., X). In version 0.1 of BrainSpace, joint alignment is implemented based on spectral embedding and available for LE and DM. The only difference with these methods is that the embedding, rather than using the affinity matrices individually, is based on the joint affinity matrix \({\cal{J}}\), built as:
where A_{k} is the intradataset affinity of the input matrix X_{k} and A_{ij} is the interdataset affinity between X_{i} and X_{j}. As of version 0.1, both sets of affinities are built using the same kernel. It is important to note, therefore, that joint embedding can only be used if the input matrices have the same features (e.g., identical target regions). After the embedding, the resulting shared representation \({\cal{G}}_J = [ {{\cal{G}}_{1,}{\cal{G}}_2, \ldots ,{\cal{G}}_N} ]^T\) will be composed of N individual lowdimensional representations, such that for the kth input matrix X_{k} ∈ ℝ\(^{n_k}\)^{×m}, the corresponding representation is \({\cal{G}}_k \in {\Bbb R}^{n_k \times m}\), where n_{k} is the number of seeds (i.e., rows) of X_{k}.
Null models
Many researchers have compared gradients to other continuous brain markers such as cortical thickness measures or estimates of cortical myelination. Given the spatial autocorrelation present in many modalities, applying linear regression or similar methods may provide biased test statistics. To circumvent this issue, we recommend comparing the observed test statistic to those of a set of distributions with similar spatial autocorrelation. To this end, we provide two methods: spin permutations^{46} and Moran spectral randomization (MSR)^{56,57}. In cases where the input data lies on a surface and most of the sphere is used or if data can be mapped to a sphere, we recommend spin permutation. Otherwise, we recommend MSR. When performing a statistical test with multiple gradients as either predictor or response variable, we recommend randomizing the nongradient variable as these randomizations need not maintain statistical independence across different eigenvectors.
Spin permutations
Spin permutation analysis leverages spherical representations of the cerebral cortex, such as those derived from FreeSurfer^{58} or CIVET^{59}, to address the problem of spatial autocorrelation in statistical inference. Spin permutations estimate the null distribution by randomly rotating the spherical projections of the cortical surface while preserving the spatial relationships within the data^{46}. Let V_{r} ∈ ℝ^{1×3} be the matrix of vertex coordinates in the sphere, where l is the number of vertices, and R ∈ ℝ^{3×3} a matrix representing a rotation along the three axes uniformly sampled from all possible rotations^{60}. The rotated sphere V_{r} is computed as follows:
Samples of the null distribution are then created by assigning each vertex on V_{r} the data of its nearest neighbor on V.
Moran spectral randomization
Borrowed from the ecology literature, MSR can also be used to generate random variables with identical or similar spatial autocorrelation (in terms of Moran’s I correlation coefficient^{50}). This approach requires building a spatial weight matrix defining the relationships between the different locations. For our particular case, given a surface mesh with I vertices (i.e., locations), its topological information is used to build the spatial weight matrix L ∈ \({\mathbb{R}}\)^{l×l}, such that L(i, j) > 0 if vertices i and j are neighbors, and L(i, j) = 0 otherwise. In BrainSpace, L is built using the inverse distance between each vertex and the vertices in its immediate neighborhood, although other neighborhoods and weighting schemes (e.g., binary or Gaussian weights) can also be incorporated. The computed L is doubly centered and eigendecomposed into its whole spectrum, with the resulting eigenvectors M ∈ \({\mathbb{R}}\)^{l×l–1} being the socalled Moran eigenvector maps. Note that eigenvectors with 0 eigenvalue are dropped. One advantage of MSR is that we can work with the original cortical surfaces, and thus skip potential distortions introduced by spherical mesh parameterization.
To generate null distributions, let u ∈ \({\mathbb{R}}\)^{l} be an input feature vector defined on each vertex of our surface (e.g., cortical thickness), and r ∈ \({\mathbb{R}}\)^{l–1} the correlation coefficients of u with each spatial eigenvector in M. MSR aims to find a randomized feature vector z that respects the autocorrelation observed in u as follows:
where \({\bar{\boldsymbol{u}}}\) and σ_{u} stand for mean and standard deviation of u respectively, and a ∈ ℝ^{l–1} is a vector of random coefficients. Three different methods exist for generating vector a: singleton, pair, and triplet. As of version 0.1, only the singleton and pair procedures are supported in BrainSpace. Let v = Mr^{T}, in the singleton procedure, a is computed by randomizing the sign of each element in v (i.e., \(a_i = \pm {\boldsymbol{v}}_i\)). In the pair procedure, the elements of v are randomly changed in pairs. Let (v_{i,} v_{j}) be a pair of elements randomly chosen, then a is updated such that \({\boldsymbol{a}}_i = q_{ij}\cos (\phi )\) and \({\boldsymbol{a}}_j = q_{ij}\sin (\phi )\), with \(q_{ij} = \sqrt {{\boldsymbol{v}}_i^2 + {\boldsymbol{v}}_j^2}\) and \(\phi \sim {\cal{U}}(0,2\pi )\) randomly drawn from a uniform distribution. If the number of elements of v is odd, the singleton procedure is used for the remaining element.
As opposed to the singleton procedure, the null data generated by the pair procedure does not fully preserve the observed spatial autocorrelation. We therefore recommend the singleton procedure, unless the number of required randomizations exceeds 2^{l–1}, which is the maximum number of unique randomizations that can be produced using the singleton procedure.
Participants
All data were derived from the Human Connectome Project dataset^{38}. For all figures showing results based only on FC, we included subjects processed for a prior study (n = 217 (122 women), mean ± SD age = 28.5 ± 3.7 y]^{20}. In short, these were subjects for whom all restingstate fMRI and anatomical scans were fully completed, and no familial relationships existed between subjects in this group. Data shown for comparisons between FC and MPC were derived from the subjects available both in the prior dataset as well as the data used by ref. ^{22} [n = 70 (41 women), mean ± SD age = 28.7 ± 3.9 y]. As part of the Human Connectome Project acquisitions, informed consent was obtained from all subjects and all procedures were approved by the Washington University institutional review board.
Reporting summary
Further information on research design is available in the Nature Research Reporting Summary linked to this article.
Data availability
All data are freely provided by the Human Connectome Project^{38} and available from connectomeDB^{61} (https://db.humanconnectome.org/).
Code availability
Our toolbox is freely available at: http://github.com/MICAMNI/BrainSpace. The toolbox contains a parallel Python and Matlab implementation with closelymatched functionality (The Python implementation of BrainSpace incorporates a wrapper for VTK, which helps simplify object creation and pipelining). Along with the code, the toolbox contains several surface models, parcellations across multiple scales, and example data to reproduce the evaluations presented in this tutorial. Additional documentation of the proposed toolbox is available for both Python and Matlab implementations via http://brainspace.readthedocs.io.
References
 1.
Flechsig, P. E. Anatomie des menschlichen Gehirns und Rückenmarks auf myelogenetischer Grundlage vol. 1 (G. Thieme, 1920).
 2.
Glasser, M. F. et al. A multimodal parcellation of human cerebral cortex. Nature 536, 171 (2016).
 3.
Brodmann, K. Vergleichende Lokalisationslehre der Grosshirnrinde in ihren Prinzipien dargestellt auf Grund des Zellenbaues. (Barth, 1909).
 4.
PalomeroGallagher, N., & Zilles, K. Cortical layers: Cyto, myelo, receptorand synaptic architecture in human cortical areas. Neuroimage 197, 716741 (2019).
 5.
von Economo, C. F. & Koskinas, G. N. Die Cytoarchitektonik der Hirnrinde des erwachsenen Menschen. (J. Springer, 1925).
 6.
Dart, R. A. The dual structure of the neopallium: Its history and significance. J. Anat. 69, 3 (1934).
 7.
Goulas, A., Majka, P., Rosa, M. & Higetag, C. A blueprint of mammalian cortical connectomes. PLoS Biol. 17, e2005346 (2019).
 8.
Pandya, D., Petrides, M., & Cipolloni, P. B. Cerebral Cortex—Architecture, connections and the dual origin concept. (Oxford University Press, 2015).
 9.
Sanides, F. Comparative architectonics of the neocortex of mammals and their evolutionary interpretation. Ann. N. Y. Acad. Sci. 167, 404–423 (1969).
 10.
Eickhoff, S. B., Yeo, B. T. & Genon, S. Imagingbased parcellations of the human brain. Nat. Rev. Neurosci. 19, 672–686 (2018).
 11.
Margulies, D. S. et al. Situating the defaultmode network along a principal gradient of macroscale cortical organization. Proc. Natl Acad. Sci. USA 113, 12574–12579 (2016).
 12.
Bajada, C. J. et al. A graded tractographic parcellation of the temporal lobe. NeuroImage 155, 503–512 (2017).
 13.
Cerliani, L. et al. Probabilistic tractography recovers a rostrocaudal trajectory of connectivity variability in the human insular cortex. Hum. Brain Mapp. 33, 2005–2034 (2012).
 14.
Guell, Xavier, Schmahmann, J. D., Gabrieli, J. D. D. E., & Ghosh, S. S. Functional gradients of the cerebellum. ELife https://doi.org/10.7554/eLife.36652 (2018).
 15.
Haak, V. K., Marquand, A. F. & Beckmann, C. F. Connectopic mapping with restingstate fMRI. NeuroImage 170, 83–94 (2018).
 16.
Larivière, S.et al. Multiscale structure–function gradients in the neonatal connectome. Cereb. Cortex https://doi.org/10.1093/cercor/bhz069 (2019).
 17.
Marquand, A. F., Haak, K. V. & Beckmann, C. F. Functional corticostriatal connection topographies predict goal directed behaviour in humans. Nat. Hum. Behav. 1, 0146 (2017).
 18.
Przeździk, I., Faber, M., Fernandez, G., Beckmann, C. F. & Haak, K. V. The functional organisation of the hippocampus along its long axis is gradual and predicts recollection. Cortex 119, 324–335 (2019).
 19.
Tian, Y. & Zalesky, A. Characterizing the functional connectivity diversity of the insula cortex: Subregions, diversity curves and behavior. Neuroimage 183, 716–733 (2018).
 20.
Vos de Wael, R. et al. Anatomical and microstructural determinants of hippocampal subfield functional connectome embedding. Proc. Natl Acad. Sci. USA 115, 10154–10159 (2018).
 21.
Huntenburg, J. M. et al. A systematic relationship between functional connectivity and intracortical myelin in the human cerebral cortex. Cereb. Cortex 27, 981–997 (2017).
 22.
Paquola, C. et al. Microstructural and functional gradients are increasingly dissociated in transmodal cortices. PLoS Biol. 17, e3000284 (2019).
 23.
Wagstyl, K., Ronan, L., Goodyer, I. M. & Fletcher, P. C. Cortical thickness gradients in structural hierarchies. Neuroimage 111, 241–250 (2015).
 24.
Paquola, C. et al. The cortical wiring scheme of hierarchical information processing. BioRxiv, Preprint at https://www.biorxiv.org/content/10.1101/2020.01.08.899583v1 (2020).
 25.
Shine, J. et al. Human cognition involves the dynamic integration of neural activity and neuromodulatory systems. Nat. Neurosci. 22, 289–296 (2019).
 26.
Vogel, J. W. et al. A molecular gradient along the longitudinal axis of the human hippocampus informs largescale behavioral systems. Nat. Commun. (In Press).
 27.
Wang, P. et al. Inversion of a largescale circuit model reveals a cortical hierarchy in the dynamic resting human brain. Sci. Adv. https://doi.org/10.1126/sciadv.aat7854 (2019).
 28.
Murphy, C. et al. Distant from input: Evidence of regions within the default mode network supporting perceptuallydecoupled and conceptuallyguided cognition. NeuroImage 171, 393–401 (2018).
 29.
Murphy, C. et al. Modes of operation: a topographic neural gradient supporting stimulus dependent and independent cognition. NeuroImage 186, 487–496 (2019).
 30.
Sormaz, M. et al. Default mode network can support the level of detail in experience during active task states. Proc. Natl Acad. Sci. USA 115, 9318–9323 (2018).
 31.
Hong, S. J. et al. Atypical functional connectome hierarchy in autism. Nat. Commun. 10, 1022 (2019).
 32.
Tian, Y., Zalesky, A., Bousman, C., Everall, I. & Pantelis, C. Insula functional connectivity in schizophrenia: subregions, gradients, and symptoms. Biol. Psychiatry.: Cogn. Neurosci. Neuroimaging 4, 399–408 (2019).
 33.
Fulcher, B. D., Murray, J. D., Zerbi, V. & Wang, X.J. Multimodal gradients across mouse cortex. Proc. Natl Acad. Sci. USA 116, 4689–4695 (2019).
 34.
Huntenburg, J. M., Bazin, P.L. & Margulies, D. S. Largescale gradients in human cortical organization. Trends Cogn. Sci. 22, 21–31 (2018).
 35.
Buckner, R. L. & Krienen, F. M. The evolution of distributed association networks in the human brain. Trends Cogn. Sci. 17, 648–665 (2013).
 36.
Buckner, R. L. & Margulies, D. Macroscale cortical organization and a defaultlike apex transmodal network in the marmoset monkey. Nat. Commun. 10, 1976 (2019).
 37.
Xu, T. et al. Crossspecies functional alignment reveals evolutionary hierarchy within the connectome. BioRxiv, Preprint at https://www.biorxiv.org/content/10.1101/692616v1 (2019).
 38.
Van Essen, D. C. et al. The WUMinn Human Connectome Project: an overview. Neuroimage 80, 62–79 (2013).
 39.
Mcintosh, R. & Misic, B. Multivariate statistical analyses for neuroimaging data. Annu. Rev. Psychol. 64, 499–525 (2013).
 40.
Worsley, K. J. et al. SurfStat: A Matlab toolbox for the statistical analysis of univariate and multivariate surface and volumetric data using linear mixed effects models and random field theory. Neuroimage 47, S102 (2009).
 41.
Desikan, R. S. et al. An automated labeling system for subdividing the human cerebral cortex on MRI scans into gyral based regions of interest. Neuroimage 31, 968–980 (2006).
 42.
Schaefer, A. et al. Localglobal parcellation of the human cerebral cortex from intrinsic functional connectivity MRI. Cereb. Cortex 28, 3095–3114 (2017).
 43.
Mesulam, M. M. From sensation to cognition. Brain 121, 1013–1052 (1998).
 44.
Larivière, S. et al. Functional connectome contractions in temporal lobe epilepsy. BioRxiv, Preprint at https://www.biorxiv.org/content/10.1101/756494v1 (2019).
 45.
Lowe, A. J. et al. Targeting agerelated differences in brain and cognition with multimodal imaging and connectome topography profiling. Hum. Brain Mapp. 40, 5213–5230 (2019).
 46.
AlexanderBloch, A. F. et al. On testing for spatial correspondence between maps of human brain structure and function. NeuroImage. https://doi.org/10.1016/j.neuroimage.2018.05.070 (2018).
 47.
Pedregosa, F. et al. Scikitlearn: machine learning in Python. J. Mach. Learn. Res. 12, 2825–2830 (2011).
 48.
Guell, Xavier. et al. LittleBrain: a gradientbased tool for the topographical interpretation of cerebellar neuroimaging findings. PLoS One 17, e2005346 (2019).
 49.
Nenning, K.H. et al. Diffeomorphic functional brain surface alignment: functional demons. NeuroImage 156, 456–465 (2017).
 50.
Cliff, A. D. & Ord, J. K. Spatial autocorrelation. (Pion, London, 1973).
 51.
Yeo, B. T. T. et al. The organization of the human cerebral cortex estimated by intrinsic functional connectivity. J. Neurophysiol. 106, 1125–1165 (2011).
 52.
Ng, A. Y., Jordan, M. I., & Weiss, Y. On spectral clustering: analysis and an algorithm. Adv. Neural. Inf. Process Syst. 849–856 (2001).
 53.
Coifman, R. R. & Lafon, S. Diffusion maps. Appl. Computational Harmonic Anal. 21, 5–30 (2006).
 54.
Lombaert, H., Grady, L., Polimeni, J. R. & Cheriet, F. FOCUSR: feature oriented correspondence using spectral regularization—a method for precise surface matching. IEEE Trans. Pattern Anal. Mach. Intell. 35, 2143–2160 (2013).
 55.
Langs, G., Golland, P., & Ghosh, S. S. Predicting activation across individuals with restingstate functional connectivity based multiatlas label fusion. International Conference on Medical Image Computing and ComputerAssisted Intervention, 313–320 (2015).
 56.
Dray, S. A new perspective about Moran’s coefficient: spatial autocorrelation as a linear regression problem. Geographical Anal. 43, 127–141 (2011).
 57.
Wagner, H. H. & Dray, S. Generating spatially constrained null models for irregularly spaced data using Moran spectral randomization methods. Methods Ecol. Evolution 6, 1169–1178, https://doi.org/10.1111/2041210X.12407 (2015).
 58.
Fischl, B. FreeSurfer. Neuroimage 62, 774–781 (2012).
 59.
Kim, J. et al. Automated 3D extraction and evaluation of the inner and outer cortical surfaces using a Laplacian map and partial volume effect classification. Neuroimage 27, 210–21 (2005).
 60.
Blaser, R. & Fryzlewicz, P. Random rotation ensembles. J. Mach. Learn. Res. 17, 126–151 (2016).
 61.
Hodge, M. R. et al. ConnectomeDB—sharing human brain connectivity data. Neuroimage 124, 1102–1107 (2016).
Acknowledgements
Mr. Vos de Wael was funded by the Savoy Foundation for Epilepsy Research. Dr. Oualid Benkarim was funded by a Healthy Brains for Healthy Lives (HBHL) postdoctoral fellowship. Dr. Jessica Royer was supported by a Canadian Open Neuroscience Platform (CONP) fellowship. Dr Smallwood was supported by the European Research Council (WANDERINGMINDS—ERC646927). Dr. Paquola was funded through a postdoctoral fellowship of the Transforming Autism Care Consortium (TACC) and the Fonds de la recherche du Québec—Santé (FRQS). Dr. Boris Bernhardt acknowledges research support from the National Science and Engineering Research Council of Canada (NSERC, Discovery1304413), the Canadian Institutes of Health Research (CIHR, FDN154298), the Azrieli Center for Autism Research of the Montreal Neurological Institute (ACAR), SickKids Foundation (NI17039), and the Canada Research Chairs (CRC) Program. Data were provided, in part, by the Human Connectome Project, WUMinn Consortium (Principal Investigators: David Van Essen and Kamil Ugurbil; 1U54MH091657) funded by the 16 NIH Institutes and Centers that support the NIH Blueprint for Neuroscience Research; and by the McDonnell Center for Systems Neuroscience at Washington University.
Author information
Affiliations
Contributions
R.V., O.B., J.S. and B.B. developed the toolbox, designed the validations, and wrote the paper. S.L., D.M., J.R., S.T., S.V, C.P. and S.H., tested the toolbox and revised the paper. M.M., G.L., T.X. and B.M. revised and approved the paper.
Corresponding author
Ethics declarations
Competing interests
The authors declare no competing interests.
Additional information
Publisher’s note Springer Nature remains neutral with regard to jurisdictional claims in published maps and institutional affiliations.
Supplementary information
Rights and permissions
Open Access This article is licensed under a Creative Commons Attribution 4.0 International License, which permits use, sharing, adaptation, distribution and reproduction in any medium or format, as long as you give appropriate credit to the original author(s) and the source, provide a link to the Creative Commons license, and indicate if changes were made. The images or other third party material in this article are included in the article’s Creative Commons license, unless indicated otherwise in a credit line to the material. If material is not included in the article’s Creative Commons license and your intended use is not permitted by statutory regulation or exceeds the permitted use, you will need to obtain permission directly from the copyright holder. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/.
About this article
Cite this article
Vos de Wael, R., Benkarim, O., Paquola, C. et al. BrainSpace: a toolbox for the analysis of macroscale gradients in neuroimaging and connectomics datasets. Commun Biol 3, 103 (2020). https://doi.org/10.1038/s4200302007947
Received:
Accepted:
Published:
Further reading

Macroscale and microcircuit dissociation of focal and generalized human epilepsies
Communications Biology (2020)

Myeloarchitecture gradients in the human insula: Histological underpinnings and association to intrinsic functional connectivity
NeuroImage (2020)

Generative modeling of brain maps with spatial autocorrelation
NeuroImage (2020)

A gradient from longterm memory to novel cognition: Transitions through default mode and executive cortex
NeuroImage (2020)

Dispersion of functional gradients across the adult lifespan
NeuroImage (2020)
Comments
By submitting a comment you agree to abide by our Terms and Community Guidelines. If you find something abusive or that does not comply with our terms or guidelines please flag it as inappropriate.