Getting started

Installation

siibra is available on pypi. To install the latest released version, simply run pip install siibra. In order to work with the latest version from github, use pip install git+https://github.com/FZJ-INM1-BDA/siibra-python.git@main.

There is also an image based on jupyter:scipy-notebook, which already includes siibra.

docker run -dit \
      -p 10000:8888 \
      --rm \
      --name siibra \
      docker-registry.ebrains.eu/siibra/siibra-python:latest

Documentation & Help

siibra-python’s documentation is hosted on https://siibra-python.readthedocs.io. The documentation includes a catalogue of documented code examples that walk you through the different concepts and functionalities. As a new user, it is recommended to go through these examples - they are easy and will quickly provide you with the right code snippets that get you started. Furthermore, a set of jupyter notebooks demonstrating more extensive example use cases are maintained in the siibra-tutorials repository. We are working on a full API documentation of the library. You find the current status on readthedocs, but be aware that it is not yet complete and as up-to-date as the code examples.

If you run into issues, please open a ticket on EBRAINS support or file bugs and feature requests on github. Please keep in mind that siibra-python is still in development. While care is taken to make everything work reliably, the API of the library is not yet stable, and the software is not yet fully tested.

Elements of an atlas in siibra

A typical brain atlas consists of

  • a reference coordinate space with a brain reference template, typically a structural image of the brain,

  • a parcellation map, which labels coordinates in the reference space with an identifier of a brain region,

  • a taxonomy, which defines the names of brain regions used by the parcellation, and links them to the identifiers used in the parcellation map.

siibra extends this basic concept by linking multiple spaces and parcellation maps with complementary properties, and combining them with multimodal data features that capture characteristic aspects of brain organisation for locations in the brain.

Labelled maps vs probability maps

The above describes what siibra calls a “labelled map”, where each location in the brain is uniquely labelled to belong to exactly one brain region. However, siibra also supports “statistical maps”, where each location in the brain is mapped to multiple brain regions with different weights (or probabilities). Each coordinate is then not mapped to a single label, but to a vector of weights, one per brain region. The weights for a specific brain region across all coordinates in the brain then form the statistical (or probabilistic) map for this single region, and the statistical maps of multiple regions may overlap.#f Datasets linked to locations in the brain

Multiple reference spaces

siibra supports different parcellation maps for a given reference space, but also different reference coordinate spaces for a given species. The human brain atlas in EBRAINS provides parcellation maps in

  • the MNI 152 space [1], which is defined by a multi-subject average of structural MRI scans defined at a resolution of about 1mm,

  • the freesurfer fsaverage space [2], which is a pure surface space defined over the vertices of a surface mesh of an average brain,

  • the BigBrain histological space [3] which is the anatomical space of a single subject brain that was 3D reconstructed from more than 7000 histological sections at an isotropic resolution of 20 micrometers.

siibra-explorer is designed visualize any of these different types efficiently, by allowing to zoom into very high resolution images, and by offering both volumetric and surface-based viewing modes.

Relationships between spaces

Some parcellations maps, especially the Julich-Brain cytoarchitectonic maps [4], are available in all those spaces, this way providing a natural link across those spaces and different spatial scales. An additional link is available through spatial transformations [5], which map coordinates in one space to their most likely corresponding coordinate in another. These spatial transformations are used by siibra-explorer when you change the reference space, in order to preserve the currently viewed region of interest.

Datasets linked to locations in the brain

siibra provides access to data features anchored to locations in the brain. Locations can be defined in very different ways, such as by specification of a brain region (thus only providing a semantic definition), a coordinate in a reference space, or a bounding box in a reference space. Data features represent datasets hosted on a public repository, typically but not exclusively the EBRAINS Knowledge Graph. A growing share of linked datasets are directly interpreted by siibra-explorer, which means that siibra-explorer offers direct access to the underlying data: Further than just displaying information about the dataset, siibra can visualize the data itself and allows to download it. These directly interpreted features are categorized into molecular, cellular, functional, fibres, connectivity and macrostructural. Many additional datasets are linked to brain regions, which only provide a metadata description and link to the corresponding dataset page on their original repository.