This collab hosts a jupyter notebook that demonstrates a first prototype coupling of the EBRAINS human brain atlas with the The VirtualBrain simulator in a purely programmatic fashion. The notebook is accessible as a Jupyter notebook from this collaboratory.

The demo showcases how data services and computing can interact in a well-structured and meaningful way in the collaboratory. It is the first use case for purely programmatic access to EBRAINS atlases using a new Python client, brainscapes.

Prototype Python client for accessing the human atlas

The atlas client gives direct programmatic access to typical patterns of interaction with EBRAINS human brain atlas. It supports the multilevel character of this atlas, which defines cytoarchitectonic maps in multiple reference template spaces at different spatial resolutions (namely the MNI Colin, ICBM152 asymmetric as well as the BigBrain microscopic space), and links them with complementary maps related to brain function, connectivity and fibre architecture. The functionality of the Python client matches common patterns known from browsing the interactive atlas viewer: Selecting a parcellation, browsing and searching brain region hierarchies, downloading maps, selecting regions, and requesting manifold information and features associated with brain regions. While not all datasets and functionalities are yet accessible through the client, it makes data formats, region specifications and access patterns explicit, thereby fertilizing co-design and boosting the collaboration between EBRAINS data services and brain simulation.

A key feature of the atlas client is a streamlined implementation of performing data queries for selected brain regions, which gives access to multimodal regional “data features”, which are mostly curated datasets from the EBRAINS Knowledge Graph (KG). The client implements a hierarchy of features, which currently models three different forms of atlas integration:

1. Spatial data features define a brain location by specifying a coordinate in one of the supported reference template spaces. They match to a query if their associated coordinate is located inside the brain region, as specified by its map in the corresponding reference space. An example of spatial data features are gene expressions collected from small tissue blocks, or contact points of physiological electrodes.
2. Regional data features define a brain location by linking to a specific region defined in a supported parcellation. They match to a query if their associated brain region is part of the region that is selected in the atlas. Examples of regional data features are cell densities, neurotransmitter distributions or functional activations that were measured in a prespecified region like e.g. CA1.
3. Global data features apply to the whole brain instead of a concrete region. They can match to a query in different ways, e.g. by providing a whole-brain image defined in one of the supported reference spaces, or providing relationships between the regions of the selected brain parcellation. Examples of global features are functional activations maps or connectivity matrices.

As a result, all forms of data features can be queried using a single function of the atlas - query_data() - which takes as an argument a specification of the desired data modality, and uses the current selections made in the atlas for retrieval and filtering. For the current prototype, available data features include neurotransmitter densities, regional connectivity profiles, connectivity matrices, gene expressions, and spatial properties of brain regions. The focus is on data features defined in the MNI reference spaces for the Julich-Brain cytoarchitectonic maps. Some feature types provide only partial coverage of the brain regions to date. The further integration of data features from partners in inside the Human Brain Project as well as external groups is a continuous process.

As most of the multimodal data features are retrieved from the EBRAINS Knowledge Graph (KG), each user of the Python client needs to provide an individual KG API token, which can be obtained on a dedicated page of the EBRAINS Knowledge Graph. Besides EBRAINS, the client also implements access to other repositories, currently in particular the Allen Brain Atlas for retrieving gene expression data. By unifying access to different back end services, the client hides much of the complexity that would be required to interact with the individual services. Furthermore, by encapsulating many aspects of interacting with different maps and reference templates spaces, it also minimizes common risks like misinterpretation of coordinates from different reference spaces, or utilization of inconsistent versions of parcellation maps. The aim is to provide a safe way of using maps defined across multiple spatial scales. The atlas client also provides easily usable data structures for several data types that are relevant for modelling. For example, cortical profiles of different neurotransmitter receptors are exposed as dictionaries of named data vectors. Other data such as connectivities are available directly on a parcellation basis. The client will later enable access to cohorts of data and functional time series data, and ultimately customized big data queries, e.g. for extracting cell densities in certain brain regions. When a query is performed, the client stores downloaded items in a local cache to speed up later queries.

The VirtualBrain

The modelling software used in the demonstrator is TheVirtualBrain (TVB) software, a Python library and mathematical framework for simulating whole-brain network dynamics and neuroimaging data.  Following CDP8 in SGA2 and various tasks in SGA3 (in particular, T1.8 and T5.4) this software is now available directly in the collaboratory Jupyter notebook interface, as a Python package. TVB  provides a Python API for constructing instances of classes, which represent the mathematical components of a large scale brain simulation, of which two essential components are the connectivity, representing the white matter fiber bundles linking regions of interest together, as well as sets of neural mass models representing the dynamics of the regions of interest. These together form the minimal virtual brain model, built from any dataset wherein the parcellation is consistent, i.e. the spatial definition of the regions of interest is identical for the nodes in the connectivity and neural masses, which dovetails with the structural data provided by the “brainscapes” atlas client detailed above, as it renders data features always in a format following the user-chosen parcellation.  Specifically, in the current demonstrator we have focused on two data features: receptor densities and connectivities. The latter data feature contains one or more matrices of white matter tract measurements between regions.  To ensure numerical stability of the simulation, a logarithmic transform is applied, and the result, along with the set of region names and positions, is used to construct a TVB connectome object.  Having the atlas-provided metadata passed on to the TVB objects enables further workflow steps such as computing forward solutions for EEG, MEG, or sEEG directly with TVB and allowing linking backwards from simulated activities to the region of interest in the atlas.  Secondly, we incorporate the region-specific receptor densities, mapping their per-region values to parameters of the per-region neural mass model: in the current iteration this mapping is fixed, in which the excitation-inhibition ratio of AMPA and GABA receptors is mapped to the threshold parameter of the neural mass model Generic2D in TVB. To ensure this ratio is evaluated on the same set of regions as the connectivity nodes, an iteration over connectivity nodes is performed, and the receptor density data feature is evaluated with the atlas client for each node. For the nodes, in which this data feature is available, the densities for AMPA and GABA are averaged over cortical depth, their ratio is retained and the mean over regions where the data is available is taken to fill in for the areas where data is not yet available. This results in a vector of values, one per region, which is then used to configure the TVB neural mass model. With the configured TVB connectivity and neural mass model, a TVB simulator is constructed, configured and run for a short amount of the time. The resulting simulation presents a typical transient from initial conditions to fixed point, ensuring a numerically stable simulation.

All the previous steps were accomplished entirely in the EBRAINS collaboratory in Jupyter notebooks. The computational resources available to such notebooks are modest, which restricts the simulations. For large parameter sweeps, ICEI compute resources need to be used.

History

2020-12-14 - We released the prototype brainscapes client to pypi. The notebook in the collab has been modified accordingly.

2020-12-15 - The latest version of brainscapes now supports the new cytoarchitectonic maps Julich-Brain V2, and selects the new  maps as default.

2020-12-16 - We realized that every user of brainscapes needs to apply for API access permission to the Knowledge graph in addition to creating a valid authorization token using this endpoint. This can be done quickly by email, as described right on top of the KG developer page.