siibra 0.5a2__py3-none-any.whl → 1.0.0a1__py3-none-any.whl

siibra/core/parcellation.py

@@ -1,4 +1,4 @@
-# Copyright 2018-2021
+# Copyright 2018-2024
 # Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
 
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -17,11 +17,21 @@ from . import region
 
 from ..commons import logger, MapType, Species
 from ..volumes import parcellationmap
+from ..exceptions import NoMapMatchingValues
 
-from typing import Union, List, Dict
+from functools import lru_cache
 import re
+from typing import Union, List, TYPE_CHECKING
+try:
+    from typing import Literal
+except ImportError:
+    # support python 3.7
+    from typing_extensions import Literal
 
 
+if TYPE_CHECKING:
+    from .space import Space
+
 # NOTE : such code could be used to automatically resolve
 # multiple matching parcellations for a short spec to the newset version:
 #               try:
@@ -68,8 +78,6 @@ class ParcellationVersion:
 
 class Parcellation(region.Region, configuration_folder="parcellations"):
 
-    _CACHED_REGION_SEARCHES: Dict[str, List[region.Region]] = {}
-
     def __init__(
         self,
         identifier: str,
@@ -82,6 +90,7 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
         modality: str = None,
         publications: list = [],
         datasets: list = [],
+        prerelease: bool = False,
     ):
         """
         Constructs a new parcellation object.
@@ -118,7 +127,8 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
             description=description,
             publications=publications,
             datasets=datasets,
-            modality=modality
+            modality=modality,
+            prerelease=prerelease,
         )
         self._species_cached = Species.decode(species)
         self._id = identifier
@@ -129,15 +139,21 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
         return self._id
 
     def matches(self, spec):
-        if isinstance(spec, str):
-            if all(
-                w in self.shortname.lower()
-                for w in re.split(r'\s+', spec.lower())
-            ):
-                return True
+        if spec not in self._CACHED_MATCHES:
+            if isinstance(spec, str):
+                if all(
+                    w in self.shortname.lower()
+                    for w in re.split(r'\s+', spec.lower())
+                ):
+                    self._CACHED_MATCHES[spec] = True
         return super().matches(spec)
 
-    def get_map(self, space=None, maptype: Union[str, MapType] = MapType.LABELLED, spec: str = ""):
+    def get_map(
+        self,
+        space: Union[str, "Space"],
+        maptype: Union[Literal['labelled', 'statistical'], MapType] = MapType.LABELLED,
+        spec: str = ""
+    ):
         """
         Get the maps for the parcellation in the requested template space.
 
@@ -150,8 +166,8 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
         Parameters
         ----------
         space: Space or str
-            template space specification
-        maptype: MapType
+            reference space specification such as name, id, or a `Space` instance.
+        maptype: MapType or str
             Type of map requested (e.g., statistical or labelled).
             Use MapType.STATISTICAL to request probability maps.
             Defaults to MapType.LABELLED.
@@ -166,26 +182,24 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
             A ParcellationMap representing the volumetric map or
             a SparseMap representing the list of statistical maps.
         """
-        if not isinstance(maptype, MapType):
+        if isinstance(maptype, str):
             maptype = MapType[maptype.upper()]
+        assert isinstance(maptype, MapType), "Possible values of `maptype` are `MapType`s, 'labelled', 'statistical'."
 
         candidates = [
             m for m in parcellationmap.Map.registry()
             if m.space.matches(space)
             and m.maptype == maptype
-            and m.parcellation
             and m.parcellation.matches(self)
         ]
         if len(candidates) == 0:
-            logger.error(f"No {maptype} map in {space} available for {str(self)}")
-            return None
+            raise NoMapMatchingValues(f"No '{maptype}' map in '{space}' available for {str(self)}")
         if len(candidates) > 1:
             spec_candidates = [
-                c for c in candidates if all(w.lower() in c.name.lower() for w in spec.split())
+                c for c in candidates if all(w.lower() in c.id.lower() for w in spec.split())
             ]
             if len(spec_candidates) == 0:
-                logger.warning(f"'{spec}' does not match any options from {[c.name for c in candidates]}.")
-                return None
+                raise NoMapMatchingValues(f"'{spec}' does not match any options from {[c.name for c in candidates]}.")
             if len(spec_candidates) > 1:
                 logger.warning(
                     f"Multiple maps are available in this specification of space, parcellation, and map type.\n"
@@ -194,43 +208,6 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
             return spec_candidates[0]
         return candidates[0]
 
-    @staticmethod
-    def find_regions(region_spec: str, parents_only=True):
-        """
-        Find regions that match the given region specification in the subtree
-        headed by each parcellation in the registry.
-        Note
-        ----
-        Use Region.find() to search for a region in an instance of a
-        parcellation.
-
-        Parameters
-        ----------
-        regionspec: str
-            a string with a possibly inexact name, which is matched both
-            against the name and the identifier key,
-        parents_only: bool
-            If true, children of matched parents will not be returned
-        Returns
-        -------
-        List[Region]
-            list of matching regions
-        """
-        MEM = Parcellation._CACHED_REGION_SEARCHES
-        if region_spec not in MEM:
-            MEM[region_spec] = [
-                r
-                for p in Parcellation.registry()
-                for r in p.find(regionspec=region_spec)
-            ]
-        if parents_only:
-            return [
-                r for r in MEM[region_spec]
-                if (r.parent is None) or (r.parent not in MEM[region_spec])
-            ]
-        else:
-            return MEM[region_spec]
-
     @property
     def is_newest_version(self):
         return (self.version is None) or (self.version.next_id is None)
@@ -260,7 +237,7 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
     def get_region(
         self,
         regionspec: Union[str, region.Region],
-        find_topmost: bool = True,
+        find_topmost: bool = False,
         allow_tuple: bool = False
     ):
         """
@@ -278,7 +255,7 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
         regionspec: str, Region
             - a string with a possibly inexact name (matched both against the name and the identifier key)
             - a Region object
-        find_topmost: bool, default: True
+        find_topmost: bool, default: False
             If True, will automatically return the parent of a decoded region
             the decoded region is its only child.
         allow_tuple: bool, default: False
@@ -308,7 +285,11 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
 
         # if there exist an exact match of region spec to region name, return
         if isinstance(regionspec, str):
-            exact_match = [region for region in self if hasattr(region, "name") and region.name == regionspec]
+            exact_match = [
+                region
+                for region in self
+                if region.name == regionspec or region.key == regionspec
+            ]
             if len(exact_match) == 1:
                 return exact_match[0]
             if len(exact_match) > 1:
@@ -346,12 +327,6 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
                 f"Spec {regionspec!r} resulted in multiple matches: {', '.join(r.name for r in candidates)}."
             )
 
-    def __str__(self):
-        return self.name
-
-    def __repr__(self):
-        return self.name
-
     def __getitem__(self, regionspec: Union[str, int]):
         """
         Retrieve a region object from the parcellation by labelindex or partial name.
@@ -369,3 +344,44 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
             )
             return self.name < other.name
         return self.version.__lt__(other.version)
+
+
+@lru_cache(maxsize=128)
+def find_regions(
+    regionspec: str,
+    filter_children=True,
+    find_topmost=False
+):
+    """
+    Find regions matching the given region specification across all parcellation
+    instances in the registery.
+
+    Parameters
+    ----------
+    regionspec: str, regex, Region
+        - a string with a possibly inexact name (matched both against the name and the identifier key)
+        - a string in '/pattern/flags' format to use regex search (acceptable flags: aiLmsux) (see https://docs.python.org/3/library/re.html#flags)
+        - a regex applied to region names
+        - a Region object
+    filter_children : bool, default: True
+        If True, children of matched parents will not be returned
+    find_topmost : bool, default: False
+        If True (requires `filter_children=True`), will return parent
+        structures if all children are matched, even though the parent
+        itself might not match the specification.
+
+    Returns
+    -------
+    list[Region]
+        list of regions matching to the regionspec
+    """
+    result = []
+    for p in Parcellation.registry():
+        result.extend(
+            p.find(
+                regionspec=regionspec,
+                filter_children=filter_children,
+                find_topmost=find_topmost
+            )
+        )
+    return result