siibra 1.0a14__py3-none-any.whl → 1.0.1a0__py3-none-any.whl

siibra/core/atlas.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");
@@ -30,14 +30,15 @@ class Atlas(concept.AtlasConcept, configuration_folder="atlases"):
     spaces, as well as common functionalities of those.
     """
 
-    def __init__(self, identifier: str, name: str, species: Species):
+    def __init__(self, identifier: str, name: str, species: Species, **kwargs):
         """Construct an empty atlas object with a name and identifier."""
 
         concept.AtlasConcept.__init__(
             self,
             identifier=identifier,
             name=name,
-            species=species
+            species=species,
+            **kwargs
         )
         self._parcellation_ids: List[str] = []
         self._space_ids: List[str] = []
@@ -196,27 +197,29 @@ class Atlas(concept.AtlasConcept, configuration_folder="atlases"):
 
     def find_regions(
         self,
-        regionspec,
-        all_versions=False,
-        filter_children=True,
-        **kwargs
+        regionspec: str,
+        all_versions: bool = False,
+        filter_children: bool = True,
+        find_topmost: bool = False
     ):
         """
-        Find regions with the given specification in all
-        parcellations offered by the atlas. Additional kwargs
-        are passed on to Parcellation.find().
+        Find regions with the given specification in all parcellations offered
+        by the atlas.
 
         Parameters
         ----------
-        regionspec: str, regex, int, Region, MapIndex
+        regionspec: str, regex
             - 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 at https://docs.python.org/3/library/re.html#flags)
             - a regex applied to region names
-            - a Region object
         all_versions : Bool, default: False
             If True, matched regions for all versions of a parcellation are returned.
         filter_children : bool, default: True
             If False, children of matched parents will 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
         -------
@@ -224,9 +227,13 @@ class Atlas(concept.AtlasConcept, configuration_folder="atlases"):
             list of regions matching to the regionspec
         """
         result = []
-        for p in self._parcellation_ids:
-            parcobj = _parcellation.Parcellation.get_instance(p)
-            if parcobj.is_newest_version or all_versions:
-                match = parcobj.find(regionspec, filter_children=filter_children, **kwargs)
-                result.extend(match)
+        for p in self.parcellations:
+            if p.is_newest_version or all_versions:
+                result.extend(
+                    p.find(
+                        regionspec=regionspec,
+                        filter_children=filter_children,
+                        find_topmost=find_topmost
+                    )
+                )
         return result

siibra/core/concept.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");
@@ -67,7 +67,8 @@ class AtlasConcept:
         modality: str = "",
         publications: List[TypePublication] = [],
         datasets: List['TypeDataset'] = [],
-        spec=None
+        spec=None,
+        prerelease: bool = False,
     ):
         """
         Construct a new atlas concept base object.
@@ -94,7 +95,7 @@ class AtlasConcept:
             The preconfigured specification.
         """
         self._id = identifier
-        self.name = name
+        self.name = name if not prerelease else f"[PRERELEASE] {name}"
         self._species_cached = None if species is None \
             else Species.decode(species)  # overwritable property implementation below
         self.shortname = shortname
@@ -104,6 +105,7 @@ class AtlasConcept:
         self.datasets = datasets
         self._spec = spec
         self._CACHED_MATCHES = {}  # we cache match() function results
+        self._prerelease = prerelease
 
     @property
     def description(self):
@@ -116,12 +118,19 @@ class AtlasConcept:
 
     @property
     def LICENSE(self) -> str:
-        licenses = {ds.LICENSE for ds in self.datasets if ds.LICENSE}
-        if not licenses:
-            return "No license information is found."
-        if len(licenses) == 1:
-            return next(iter(licenses))
-        logger.info("Found multiple licenses corresponding to datasets.")
+        licenses = []
+        for ds in self.datasets:
+            if ds.LICENSE is None or ds.LICENSE == "No license information is found.":
+                continue
+            if isinstance(ds.LICENSE, str):
+                licenses.append(ds.LICENSE)
+            if isinstance(ds.LICENSE, list):
+                licenses.extend(ds.LICENSE)
+        if len(licenses) == 0:
+            logger.warning("No license information is found.")
+            return ""
+        if len(licenses) > 1:
+            logger.info("Found multiple licenses corresponding to datasets.")
         return '\n'.join(licenses)
 
     @property

siibra/core/parcellation.py

@@ -1,4 +1,4 @@
-# Copyright 2018-2023
+# 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
@@ -138,7 +148,12 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
                     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.
 
@@ -151,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.
@@ -167,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"
@@ -195,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)
@@ -261,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
     ):
         """
@@ -279,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
@@ -309,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:
@@ -364,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