Find brain regions in a parcellation

We can use Parcellation objects to find child brain regions.

We start by selecting an atlas and a parcellation.

import siibra
atlas = siibra.atlases.get('human')
julich_brain = atlas.parcellations.get('julich 2.9')

The most basic way is to search for all regions matching a particular string:

julich_brain.find('V1')

[<Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_AREA_HOC1_V1_17_CALCS', name='Area hOc1 (V1, 17, CalcS)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_AREA_HOC1_V1_17_CALCS_LEFT', name='Area hOc1 (V1, 17, CalcS) left', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_AREA_HOC1_V1_17_CALCS_RIGHT', name='Area hOc1 (V1, 17, CalcS) right', species='Homo sapiens')>]

You can filter the children and querying the root node by:

julich_brain.find('v1', filter_children=True)

[<Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_AREA_HOC1_V1_17_CALCS', name='Area hOc1 (V1, 17, CalcS)', species='Homo sapiens')>]

For more powerful searches, regular expressions can be used with ‘/<pattern>/<flags>’ or using re.compile(). Find hOc2 or hOc4 in the right hemisphere:

julich_brain.find('/hOc[24].*right/')

[<Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_AREA_HOC4LA_LOC_RIGHT', name='Area hOc4la (LOC) right', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_AREA_HOC4V_LINGG_RIGHT', name='Area hOc4v (LingG) right', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_AREA_HOC2_V2_18_RIGHT', name='Area hOc2 (V2, 18) right', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_AREA_HOC4D_CUNEUS_RIGHT', name='Area hOc4d (Cuneus) right', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_AREA_HOC4LP_LOC_RIGHT', name='Area hOc4lp (LOC) right', species='Homo sapiens')>]

Searching for more general brain regions, we see that areas often appear three times: Julich-Brain defines them separately for the left and right hemisphere, and additionally defines a common parent region.

for r in julich_brain.find('amygdala'):
    print(r.name)

amygdala
SF (Amygdala)
IF (Amygdala)
MF (Amygdala)
CM (Amygdala)
LB (Amygdala)
VTM (Amygdala)
LB (Amygdala) left
IF (Amygdala) left
CM (Amygdala) left
SF (Amygdala) left
MF (Amygdala) left
VTM (Amygdala) left
SF (Amygdala) right
IF (Amygdala) right
LB (Amygdala) right
MF (Amygdala) right
CM (Amygdala) right
VTM (Amygdala) right

Regions can also be search right away from the atlas object. However, it will return matching regions from all its known parcellations. search all regions known by the atlas

for r in atlas.find_regions('amygdala'):
    print(f"{r.name:30.30} {r.parcellation}")

amygdala                       [PRERELEASE] Julich-Brain Cytoarchitectonic Atlas (v3.1)
amygdala                       Julich-Brain Cytoarchitectonic Atlas (v3.0.3)
Component 21: Amygdala         DiFuMo Atlas (256 dimensions)
Component 120: Amygdala        DiFuMo Atlas (512 dimensions)
Component 105: Amygdala inferi DiFuMo Atlas (512 dimensions)
Component 425: Amygdala anteri DiFuMo Atlas (1024 dimensions)
Component 678: Amygdala poster DiFuMo Atlas (1024 dimensions)
Amygdala                       MarsAtlas cortical parcellation model

In fact, siibra provides a package-level function to search through regions of all parcellations.

siibra.find_regions('amygdala')

[<Region(identifier='minds/core/parcellationatlas/v1.0.0/12fca5c5-b02c-46ce-ab9f-f12babf4c7e1_COMPONENT_425_AMYGDALA_ANTERIOR', name='Component 425: Amygdala anterior', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/12fca5c5-b02c-46ce-ab9f-f12babf4c7e1_COMPONENT_678_AMYGDALA_POSTERIOR', name='Component 678: Amygdala posterior', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/141d510f-0342-4f94-ace7-c97d5f160235_COMPONENT_21_AMYGDALA', name='Component 21: Amygdala', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/63b5794f-79a4-4464-8dc1-b32e170f3d16_COMPONENT_120_AMYGDALA', name='Component 120: Amygdala', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/63b5794f-79a4-4464-8dc1-b32e170f3d16_COMPONENT_105_AMYGDALA_INFERIOR', name='Component 105: Amygdala inferior', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579_AMYGDALA', name='amygdala', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579_SF_AMYGDALA', name='SF (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579_LB_AMYGDALA', name='LB (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579_CM_AMYGDALA', name='CM (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579_IF_AMYGDALA', name='IF (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579_MF_AMYGDALA', name='MF (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579_VTM_AMYGDALA', name='VTM (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_AMYGDALA', name='amygdala', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_SF_AMYGDALA', name='SF (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_IF_AMYGDALA', name='IF (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_MF_AMYGDALA', name='MF (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_CM_AMYGDALA', name='CM (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_LB_AMYGDALA', name='LB (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_VTM_AMYGDALA', name='VTM (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_AMYGDALA', name='amygdala', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_SF_AMYGDALA', name='SF (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_IF_AMYGDALA', name='IF (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_CM_AMYGDALA', name='CM (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_MF_AMYGDALA', name='MF (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_LB_AMYGDALA', name='LB (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_VTM_AMYGDALA', name='VTM (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_AMYGDALA', name='amygdala', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_LB_AMYGDALA', name='LB (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_SF_AMYGDALA', name='SF (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_IF_AMYGDALA', name='IF (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_CM_AMYGDALA', name='CM (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_MF_AMYGDALA', name='MF (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_VTM_AMYGDALA', name='VTM (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_ASTR_AMYGDALA', name='Astr (Amygdala)', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/887da8eb4c36d944ef626ed5293db3ef_AMYGDALA', name='Amygdala', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/e3235c039c6f54c3ba151568c829f117_AMYGDALA', name='amygdala', species='Macaca mulatta')>]

Often however, we want to access one particular region, given a unique specification, and not obtain a list of many possible matches. This can be done using the get_region method. It assumes that the provided region specification is unique, and returns the single exact match. Note that if the specification is not unique, this method will raise an exception!

julich_brain.get_region('v1 left')

<Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_AREA_HOC1_V1_17_CALCS_LEFT', name='Area hOc1 (V1, 17, CalcS) left', species='Homo sapiens')>

siibra provides a package-level shortcut function for this as well:

siibra.get_region('julich 2.9', 'v1 left')

<Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_AREA_HOC1_V1_17_CALCS_LEFT', name='Area hOc1 (V1, 17, CalcS) left', species='Homo sapiens')>

In case that the given specification matches multiple regions, which however represent the children of the same parent, get_region will return the parent object. In that case, the returned region can be a full subtree:

julich_brain.get_region('amygdala')

<Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290_AMYGDALA', name='amygdala', species='Homo sapiens')>

Atlas objects provide direct access to the get_region() method of their parcellations. This way the above can also be done without explicitly accessing the parcellation object:

atlas.get_region('amygdala', parcellation='julich')

<Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_AMYGDALA', name='amygdala', species='Homo sapiens')>