Understanding links between data features and anatomical locations

All data features are requested with the same function, siibra.features.get(). The type of feature (spatial, regional, or parcellation feature), and thus the way it is linked to an anatomical concept depends on the requested modality. This example shows how some features are linked to anatomical regions in different ways.

import siibra

Available feature types are listed in the module siibra.features. Most of these represent specifically supported data modalities, and will be covered one by one in the next examples.

siibra.features.TYPES

{'CompoundFeature': <class 'siibra.features.feature.CompoundFeature'>, 'Feature': <class 'siibra.features.feature.Feature'>, 'Tabular': <class 'siibra.features.tabular.tabular.Tabular'>, 'CorticalProfile': <class 'siibra.features.tabular.cortical_profile.CorticalProfile'>, 'BigBrainIntensityProfile': <class 'siibra.features.tabular.bigbrain_intensity_profile.BigBrainIntensityProfile'>, 'CellDensityProfile': <class 'siibra.features.tabular.cell_density_profile.CellDensityProfile'>, 'GeneExpressions': <class 'siibra.features.tabular.gene_expression.GeneExpressions'>, 'LayerwiseBigBrainIntensities': <class 'siibra.features.tabular.layerwise_bigbrain_intensities.LayerwiseBigBrainIntensities'>, 'LayerwiseCellDensity': <class 'siibra.features.tabular.layerwise_cell_density.LayerwiseCellDensity'>, 'ReceptorDensityFingerprint': <class 'siibra.features.tabular.receptor_density_fingerprint.ReceptorDensityFingerprint'>, 'ReceptorDensityProfile': <class 'siibra.features.tabular.receptor_density_profile.ReceptorDensityProfile'>, 'RegionalTimeseriesActivity': <class 'siibra.features.tabular.regional_timeseries_activity.RegionalTimeseriesActivity'>, 'RegionalBOLD': <class 'siibra.features.tabular.regional_timeseries_activity.RegionalBOLD'>, 'RegionalConnectivity': <class 'siibra.features.connectivity.regional_connectivity.RegionalConnectivity'>, 'FunctionalConnectivity': <class 'siibra.features.connectivity.functional_connectivity.FunctionalConnectivity'>, 'AnatomoFunctionalConnectivity': <class 'siibra.features.connectivity.functional_connectivity.AnatomoFunctionalConnectivity'>, 'StreamlineCounts': <class 'siibra.features.connectivity.streamline_counts.StreamlineCounts'>, 'StreamlineLengths': <class 'siibra.features.connectivity.streamline_lengths.StreamlineLengths'>, 'TracingConnectivity': <class 'siibra.features.connectivity.tracing_connectivity.TracingConnectivity'>, 'Image': <class 'siibra.features.image.image.Image'>, 'CellBodyStainedVolumeOfInterest': <class 'siibra.features.image.volume_of_interest.CellBodyStainedVolumeOfInterest'>, 'BlockfaceVolumeOfInterest': <class 'siibra.features.image.volume_of_interest.BlockfaceVolumeOfInterest'>, 'DTIVolumeOfInterest': <class 'siibra.features.image.volume_of_interest.DTIVolumeOfInterest'>, 'PLIVolumeOfInterest': <class 'siibra.features.image.volume_of_interest.PLIVolumeOfInterest'>, 'MRIVolumeOfInterest': <class 'siibra.features.image.volume_of_interest.MRIVolumeOfInterest'>, 'XPCTVolumeOfInterest': <class 'siibra.features.image.volume_of_interest.XPCTVolumeOfInterest'>, 'LSFMVolumeOfInterest': <class 'siibra.features.image.volume_of_interest.LSFMVolumeOfInterest'>, 'MorphometryVolumeOfInterest': <class 'siibra.features.image.volume_of_interest.MorphometryVolumeOfInterest'>, 'CellbodyStainedSection': <class 'siibra.features.image.sections.CellbodyStainedSection'>, 'BigBrain1MicronPatch': <class 'siibra.features.image.sections.BigBrain1MicronPatch'>, 'EbrainsDataFeature': <class 'siibra.features.dataset.ebrains.EbrainsDataFeature'>}

Regional features

As a first example, we use brain region V2 to query for “EbrainsRegionalDataset” features. See EBRAINS regional datasets for more information about this modality.

v2 = siibra.get_region("julich 2.9", "hoc2")
features = siibra.features.get(v2, siibra.features.dataset.EbrainsDataFeature)
for feature in features:
    print(f" - {feature.name}")

- Ebrains Dataset: Ultrahigh resolution 3D cytoarchitectonic map of Area hOc2 (V2, 18) created by a Deep-Learning assisted workflow (v1)
- Ebrains Dataset: Layer-specific distributions of segmented cells in Area hOc2 (V2, 18) of BigBrain (v1)
- Ebrains Dataset: Filter Activations of Convolutional Neuronal Networks Used in Cytoarchitectonic Brain Mapping (v1)
- Ebrains Dataset: Structure-phenotype associations for Julich-Brain Cytoarchitectonic Atlas regions (v1)
- Ebrains Dataset: Reference delineations of Area hOc2 (V2, 18) in individual sections of the BigBrain (v1)
- Ebrains Dataset: Density measurements of different receptors for dorsal part of Area hOc2 (V2, 18) [human] (v1)
- Ebrains Dataset: Probabilistic cytoarchitectonic map of Area hOc2 (V2, 18) (v4.2)
- Ebrains Dataset: Density measurements of different receptors for ventral part of Area hOc2 (V2, 18) [human] (v1)
- Ebrains Dataset: Functional brain complexity changes in humans under the influence of psychedelic low doses of ketamine (v1)
- Ebrains Dataset: Phase-interaction matrices of the phase relationships of different pathological states of consciousness (v1)
- Ebrains Dataset: Intracranial electrophysiological recordings from the human brain during memory tasks with pupillometry (v1)
- Ebrains Dataset: Measures of states of consciousness during attentional and cognitive load (v1)
- Ebrains Dataset: Resolving nerve fiber crossings at micrometer resolution in rat, vervet monkey, and human brain samples (v1.0)
- Ebrains Dataset: Extracting seizure onset from surface EEG with independent component analysis: Insights from simultaneous scalp and intracerebral EEG (v1)
- Ebrains Dataset: CEREBRUM-7T: Fast and Fully-volumetric Brain Segmentation of 7 Tesla MR Volumes (v1)
- Ebrains Dataset: Spontaneous EEG during sleep with intermittent awakenings (v1)
- Ebrains Dataset: Sleep deprivation in human electroencephalography (EEG) (v1)
- Ebrains Dataset: Response profiles to uni- and bilateral stimulation in higher-order visual cortex (v1)
- Ebrains Dataset: 3D reconstructions of human cortical pyramidal cells (v1)
- Ebrains Dataset: Human ultra-high resolution functional imaging data (7 Tesla) on multi-element event memories (general raw data) (v1)
- Ebrains Dataset: 3D reconstruction and analysis of four human brain cortex samples with two-photon fluorescence microscopy (v1.0)

Mappings to brain regions can have different precision: A feature may be associated with the exact region requested, but it may also be linked to a child region, similar region, or parent region. To understand the link between the query region and each requested feature, siibra adds some information about the match each time a query is executed. In particular,

• Feature.match_qualification returns a rating of the matching that was applied, and could be any of “exact”, “approximate”, “contained”, “contains”

• Feature.match_description often contains a human-readable description about the matching

Furthermore, if applicable,

• Feature.matched_region returns the region object to which the feature was last matched,

• Feature.matched_parcellation returns the parcellation object to which the feature was last matched, and

• Feature.matched_location returns the spatial primitive to which the feature was matched.

Let’s look at a few examples. We start with a rather broad specification - the occipital lobe. Here we hardly encounter an exact match, but many contained and approximately corresponding features. We print only some of the returned datasets.

selected_ids = [
    "54996ef6-b821-447a-b34c-7f2512396c8c",
    "8cd8506e-3a6f-406e-92c8-b52dda1dea23",
    "01550c5c-291d-4bfb-a362-875fcaa21724",
    "7269d1a2-c7ad-4745-972c-10dbf5a022b7",
]
occ = siibra.get_region("julich 2.9", "occipital")
for f in siibra.features.get(occ, "ebrains"):
    if any(_ in f.id for _ in selected_ids):
        print(f.name)
        print(" -> ", f.last_match_description)
        print()

Ebrains Dataset: Synthetic simultaneous EEG-fMRI resting state dataset simulated with The Virtual Brain (v1)
 ->  'lateral occipital cortex' is contained in 'occipital lobe'

Ebrains Dataset: Response profiles to uni- and bilateral stimulation in higher-order visual cortex (v1)
 ->  'lateral occipital cortex' is contained in 'occipital lobe' and 'occipital cortex' is contained in 'occipital lobe' and 'ventral occipital cortex' is contained in 'occipital lobe' and 'dorsal occipital cortex' is contained in 'occipital lobe'

Ebrains Dataset: Human ultra-high resolution functional imaging data (7 Tesla) on multi-element event memories (general raw data) (v1)
 ->  'lateral occipital cortex' is contained in 'occipital lobe' and 'occipital cortex' is contained in 'occipital lobe' and 'ventral occipital cortex' is contained in 'occipital lobe' and 'dorsal occipital cortex' is contained in 'occipital lobe'

Ebrains Dataset: Layer-specific distributions of segmented cells in Area hOc4d (Cuneus) of BigBrain (v1)
 ->  'Area hOc4d (Cuneus)' is contained in 'occipital lobe'

If we query a rather specific region, we get more exact matches.

v1 = siibra.get_region("julich 2.9", "v1")
for f in siibra.features.get(v1, "ebrains"):
    if any(_ in f.id for _ in selected_ids):
        print(f.name)
        print(" -> ", f.last_match_description)
        print()

Ebrains Dataset: Response profiles to uni- and bilateral stimulation in higher-order visual cortex (v1)
 ->  'occipital cortex' contains 'Area hOc1 (V1, 17, CalcS)'

Ebrains Dataset: Human ultra-high resolution functional imaging data (7 Tesla) on multi-element event memories (general raw data) (v1)
 ->  'occipital cortex' contains 'Area hOc1 (V1, 17, CalcS)'

Qualifications differ across queries

Note that the same data feature might have different qualifications when returned from different queries. Let’s take the following dataset with fMRI data in the primary visual cortex:

dataset_id = "de7a6c44-8167-44a8-9cf4-435a3dab61ed"

When querying for datasets related to V1, the match is qualified as an exact coincidence.

for f in siibra.features.get(v1, "ebrains"):
    if f.id.endswith(dataset_id):
        print(f.name)
        print(" -> ", f.last_match_description)
        print()

Ebrains Dataset: 7T-fMRI data to study mental imagery and illusory perception in the layers of human primary visual cortex (v1)
 ->  'Area hOc1 (V1, 17, CalcS)' coincides with 'Area hOc1 (V1, 17, CalcS)'

When querying for datasets related to only the left hemisphere of v1, the match is qualified as “contains”:

v1l = siibra.get_region("julich 2.9", "v1 left")
for f in siibra.features.get(v1l, "ebrains"):
    if dataset_id in f.id:
        print(f.name)
        print(" -> ", f.last_match_description)
        print()

Ebrains Dataset: 7T-fMRI data to study mental imagery and illusory perception in the layers of human primary visual cortex (v1)
 ->  'Area hOc1 (V1, 17, CalcS)' contains 'Area hOc1 (V1, 17, CalcS) left'

Lastly, when querying for datasets related to the occipital cortex, the match is qualified as “contained”:

for f in siibra.features.get(occ, "ebrains"):
    if f.id.endswith(dataset_id):
        print(f.last_match_description)

'Area hOc1 (V1, 17, CalcS)' is contained in 'occipital lobe'

Spatial features

There are also data features which are linked to locations in a specific reference space. For example, volumes of interest are tested for overlap with bounding boxes of regions. The following dataset covering the hippocampus intersects with the mask of CA1. Note how siibra deals with the fact that the volume of interest is defined in BigBrain space, while the region is only mapped in the MNI spaces - it warps the bounding box of the region to the space of the feature for the test.

ca1 = siibra.get_region("julich 2.9", "ca1")
features = siibra.features.get(ca1, siibra.features.fibres.PLIVolumeOfInterest)
print(features[0].name)
print(features[0].last_match_description)

The Enriched Connectome - 3D polarized light imaging connectivity data of full sagittal human brain sections (HSV fibre orientation map)
'Bounding box from (-16.65,-81.86,-67.26)mm to (-16.60,86.56,64.07)mm in BigBrain microscopic template (histology) space' overlaps with 'Bounding box from (-35.75,-22.40,-26.00)mm to (47.89,13.73,7.58)mm in BigBrain microscopic template (histology) space'

Another example are gene expressions retrieved from the Allen atlas. These are linked by the coordinate of their tissue probes in MNI space. If a coordinate is inside the selected brain regions, it is an exact match. For example, the gene expressions retrieved from the Allen atlas are linked by the coordinate For example, the gene expressions retrieved from the Allen atlas are linked by the coordinate of their tissue probes in MNI space. If a coordinate is inside the selected brain regions, it is an exact match.

features = siibra.features.get(v1, siibra.features.molecular.GeneExpressions, gene="TAC1")
print(features[0].last_match_description)

    For retrieving microarray data, siibra connects to the web API of
    the Allen Brain Atlas (© 2015 Allen Institute for Brain Science),
    available from https://brain-map.org/api/index.html. Any use of the
    microarray data needs to be in accordance with their terms of use,
    as specified at https://alleninstitute.org/legal/terms-use/.

'Area hOc1 (V1, 17, CalcS)' is contained in 'Area hOc1 (V1, 17, CalcS)' - MNI coordinates of tissue samples were filtered using Area hOc1 (V1, 17, CalcS)

Estimated memory usage: 385 MB