Selecting a preconfigured atlas from an instance table

siibra provides a table of preconfigured atlas objects of different species. Atlas objects are very simple structures: They are mostly used to group a set of preconfigured parcellations and reference spaces by species. They do not provide much further functionality on their own.

We start by loading the library

import siibra

Preconfigured atlas objects are accessible via the instance table siibra.atlases, which is a shortcut to siibra.Atlas.registry(). Instance tables are simple container structures, populated with preconfigured objects when accessed for the first time. The first call will require an internet connection to retrieve the initial configuration information. After initial access, the configuration information will cached on the local disk and can be accessed offline.

print(type(siibra.atlases))

<class 'siibra.commons.InstanceTable'>

siibra uses instance tables not only for atlases, but also for parcellations (siibra.parcellations), reference spaces (siibra.spaces) or feature modalities (siibra.modalities), as will be shown in later code examples.

Objects stored in a siibra instance table can be accessed in different ways:

1. In “list-style”: by iterating over all objects or using the index operator “[]”

2. By fuzzy keyword matching via the get() function or index operator

3. By tab-completion of their “keys”

# We can print the keys of all predefined atlas objects in the registry:
siibra.atlases.keys

['MULTILEVEL_HUMAN_ATLAS', 'MONKEY_ATLAS', 'ALLEN_MOUSE_COMMON_COORDINATE_FRAMEWORK_V3', 'WAXHOLM_SPACE_ATLAS_OF_THE_SPRAGUE_DAWLEY_RAT_BRAIN']

The keys can be used to select atlas object by autocompletion when you hit <TAB>. This makes it convenient to find the right name in an interactive shell.

atlas = siibra.atlases.MULTILEVEL_HUMAN_ATLAS
atlas

<Atlas(identifier='juelich/iav/atlas/v1.0.0/1', name='Multilevel Human Atlas', species='Homo sapiens')>

We can also select an atlas by specifying the key as a string in the get() method:

siibra.atlases.get("MULTILEVEL HUMAN ATLAS")

<Atlas(identifier='juelich/iav/atlas/v1.0.0/1', name='Multilevel Human Atlas', species='Homo sapiens')>

More importantly, we can use an arbitrary set of words matching the name or key of atlas. This is usually the simplest way to select from a Registry. It will fail if no unique match is found.

siibra.atlases.get('human')

<Atlas(identifier='juelich/iav/atlas/v1.0.0/1', name='Multilevel Human Atlas', species='Homo sapiens')>

Of course, as in a list, we can also iterate over the objects in the instance table or use the index operator to fetch an objects by its position:

for atlas in siibra.atlases:
    print(atlas.name)
print(siibra.atlases[0])

Multilevel Human Atlas
Monkey Atlas
Allen Mouse Common Coordinate Framework v3
Waxholm Space atlas of the Sprague Dawley rat brain
Multilevel Human Atlas

Fuzy string matching also works in the index operator. For legibility however, we typically prefer the “get()” form in our code examples.

siibra.atlases['human']

<Atlas(identifier='juelich/iav/atlas/v1.0.0/1', name='Multilevel Human Atlas', species='Homo sapiens')>

An atlas has a range of properties and functions, for example is linked to a species:

atlas = siibra.atlases.WAXHOLM_SPACE_ATLAS_OF_THE_SPRAGUE_DAWLEY_RAT_BRAIN
atlas.species

Species: Rattus norvegicus

Furthermore, an atlas provides its own registries of supported spaces and parcellations. We will cover these in the next examples.

atlas.spaces.keys

['WAXHOLM_SPACE_OF_THE_SPRAGUE_DAWLEY_V1_01']