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

Access to EBRAINS

While the core features in siibra can be accessed without any authentication, siibra can perform dynamic queries to regional datasets stored in the EBRAINS Knowledge Graph. To use this functionality, you need to obtain an EBRAINS authentication token with a valid EBRAINS user account. Registering to EBRAINS is easy and free of charge, so we strongly recommend to sign up. To use your EBRAINS access token in siibra:

  1. If you do not yet have an EBRAINS account, register here.

  2. When using siibra, fetch an authentication token by using siibra.fetch_ebrains_token(). You will be asked to visit an ebrains login website. Login, and accept the requested detail.

Since tokens are temporary, step 2. needs to be repeated regularly. If you prefer, you can also create your token by visiting the EBRAINS authorization endpoint. Copy the token, and either store it in the environment variable $HBP_AUTH_TOKEN or pass it explicitly to siibra using siibra.set_ebrains_token(). The token is a string sequence with more than 1000 characters, usually starting with with “ey”.

Note that as of now, you need to to step 2 approximately every day to perform EBRAINS data queries. However, siibra maintains a local cache on disk, so once retrieved, data features become usable and accessible without refreshing the token.

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.