Note
Go to the end to download the full example code.
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_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_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_HOC4LP_LOC_RIGHT', name='Area hOc4lp (LOC) 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_HOC2_V2_18_RIGHT', name='Area hOc2 (V2, 18) 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
IF (Amygdala)
SF (Amygdala)
MF (Amygdala)
LB (Amygdala)
CM (Amygdala)
VTM (Amygdala)
LB (Amygdala) left
MF (Amygdala) left
IF (Amygdala) left
SF (Amygdala) left
CM (Amygdala) left
SF (Amygdala) right
VTM (Amygdala) left
IF (Amygdala) right
MF (Amygdala) right
LB (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}")
Component 425: Amygdala anteri DiFuMo Atlas (1024 dimensions)
Component 678: Amygdala poster DiFuMo Atlas (1024 dimensions)
Component 21: Amygdala DiFuMo Atlas (256 dimensions)
Component 120: Amygdala DiFuMo Atlas (512 dimensions)
Component 105: Amygdala inferi DiFuMo Atlas (512 dimensions)
amygdala Julich-Brain Cytoarchitectonic Atlas (v3.1)
SF (Amygdala) Julich-Brain Cytoarchitectonic Atlas (v3.1)
IF (Amygdala) Julich-Brain Cytoarchitectonic Atlas (v3.1)
MF (Amygdala) Julich-Brain Cytoarchitectonic Atlas (v3.1)
CM (Amygdala) Julich-Brain Cytoarchitectonic Atlas (v3.1)
LB (Amygdala) Julich-Brain Cytoarchitectonic Atlas (v3.1)
VTM (Amygdala) Julich-Brain Cytoarchitectonic Atlas (v3.1)
Astr (Amygdala) Julich-Brain Cytoarchitectonic Atlas (v3.1)
MF (Amygdala) left Julich-Brain Cytoarchitectonic Atlas (v3.1)
LB (Amygdala) left Julich-Brain Cytoarchitectonic Atlas (v3.1)
SF (Amygdala) left Julich-Brain Cytoarchitectonic Atlas (v3.1)
CM (Amygdala) left Julich-Brain Cytoarchitectonic Atlas (v3.1)
IF (Amygdala) left Julich-Brain Cytoarchitectonic Atlas (v3.1)
CM (Amygdala) right Julich-Brain Cytoarchitectonic Atlas (v3.1)
IF (Amygdala) right Julich-Brain Cytoarchitectonic Atlas (v3.1)
MF (Amygdala) right Julich-Brain Cytoarchitectonic Atlas (v3.1)
SF (Amygdala) right Julich-Brain Cytoarchitectonic Atlas (v3.1)
LB (Amygdala) right Julich-Brain Cytoarchitectonic Atlas (v3.1)
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_LB_AMYGDALA', name='LB (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_MF_AMYGDALA', name='MF (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_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_LB_AMYGDALA', name='LB (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_CM_AMYGDALA', name='CM (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_IF_AMYGDALA', name='IF (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_IF_AMYGDALA', name='IF (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_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-300_LB_AMYGDALA_LEFT', name='LB (Amygdala) left', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_CM_AMYGDALA_LEFT', name='CM (Amygdala) left', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_MF_AMYGDALA_LEFT', name='MF (Amygdala) left', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_IF_AMYGDALA_LEFT', name='IF (Amygdala) left', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_SF_AMYGDALA_LEFT', name='SF (Amygdala) left', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_LB_AMYGDALA_RIGHT', name='LB (Amygdala) right', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_CM_AMYGDALA_RIGHT', name='CM (Amygdala) right', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_SF_AMYGDALA_RIGHT', name='SF (Amygdala) right', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_MF_AMYGDALA_RIGHT', name='MF (Amygdala) right', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-300_IF_AMYGDALA_RIGHT', name='IF (Amygdala) right', 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_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_MF_AMYGDALA', name='MF (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_LB_AMYGDALA', name='LB (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/94c1125b-b87e-45e4-901c-00daee7f2579-310_MF_AMYGDALA_LEFT', name='MF (Amygdala) left', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_LB_AMYGDALA_LEFT', name='LB (Amygdala) left', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_SF_AMYGDALA_LEFT', name='SF (Amygdala) left', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_CM_AMYGDALA_LEFT', name='CM (Amygdala) left', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_IF_AMYGDALA_LEFT', name='IF (Amygdala) left', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_CM_AMYGDALA_RIGHT', name='CM (Amygdala) right', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_IF_AMYGDALA_RIGHT', name='IF (Amygdala) right', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_MF_AMYGDALA_RIGHT', name='MF (Amygdala) right', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_SF_AMYGDALA_RIGHT', name='SF (Amygdala) right', species='Homo sapiens')>, <Region(identifier='minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-310_LB_AMYGDALA_RIGHT', name='LB (Amygdala) right', 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-310_AMYGDALA', name='amygdala', species='Homo sapiens')>
Total running time of the script: (0 minutes 1.838 seconds)
Estimated memory usage: 104 MB