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

siibra/core/{relation_qualification.py → assignment.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");
@@ -12,11 +12,13 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Qualification between two arbitary concepts"""
+"""Qualification between two BrainStructures"""
 
 from enum import Enum
-from typing import Dict, TypeVar, Generic
 from dataclasses import dataclass
+from typing import Dict, Generic, TypeVar, TYPE_CHECKING
+if TYPE_CHECKING:
+    from .structure import BrainStructure
 
 T = TypeVar("T")
 
@@ -43,14 +45,14 @@ class Qualification(Enum):
             Qualification.CONTAINS: 'contains',
             Qualification.APPROXIMATE: 'approximates to',
             Qualification.HOMOLOGOUS: 'is homologous to',
-            Qualification.OTHER_VERSION: 'is another version of',
+            Qualification.OTHER_VERSION: 'is another version of'
         }
-        assert self in transl, f"{str(self)} verb cannot be found!"
+        assert self in transl, f"{str(self)} verb cannot be found."
         return transl[self]
 
     def invert(self):
         """
-        Return a MatchPrecision object with the inverse meaning
+        Return qualification with the inverse meaning
         """
         inverses = {
             Qualification.EXACT: Qualification.EXACT,
@@ -61,7 +63,7 @@ class Qualification(Enum):
             Qualification.HOMOLOGOUS: Qualification.HOMOLOGOUS,
             Qualification.OTHER_VERSION: Qualification.OTHER_VERSION,
         }
-        assert self in inverses, f"{str(self)} inverses cannot be found"
+        assert self in inverses, f"{str(self)} inverses cannot be found."
         return inverses[self]
 
     def __str__(self):
@@ -79,9 +81,10 @@ class Qualification(Enum):
 
 
 @dataclass
-class RelationAssignment(Generic[T]):
-    query_structure: T
-    assigned_structure: T
+class AnatomicalAssignment(Generic[T]):
+    """Represents a qualified assignment between anatomical structures."""
+    query_structure: "BrainStructure"
+    assigned_structure: "BrainStructure"
     qualification: Qualification
     explanation: str = ""
 
@@ -94,14 +97,14 @@ class RelationAssignment(Generic[T]):
         return msg if self.explanation == "" else f"{msg} - {self.explanation}"
 
     def invert(self):
-        return RelationAssignment(
+        return AnatomicalAssignment(
             self.assigned_structure,
             self.query_structure,
             self.qualification.invert(),
             self.explanation
         )
 
-    def __lt__(self, other: 'RelationAssignment'):
-        if not isinstance(other, RelationAssignment):
-            raise ValueError(f"Cannot compare RelationAssignment with instances of '{type(other)}'")
+    def __lt__(self, other: 'AnatomicalAssignment'):
+        if not isinstance(other, AnatomicalAssignment):
+            raise ValueError(f"Cannot compare AnatomicalAssignment with instances of '{type(other)}'")
         return self.qualification.value < other.qualification.value

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] = []
@@ -64,9 +65,20 @@ class Atlas(concept.AtlasConcept, configuration_folder="atlases"):
             matchfunc=_parcellation.Parcellation.match,
         )
 
-    def get_parcellation(self, parcellation=None):
-        """Returns a valid parcellation object defined by the atlas.
-        If no specification is provided, the default is returned."""
+    def get_parcellation(self, parcellation=None) -> "_parcellation.Parcellation":
+        """
+        Returns a valid parcellation object defined by the atlas. If no
+        specification is provided, the default is returned.
+
+        Parameters
+        ----------
+        parcellation: str, Parcellation
+            specification of a parcellation or a parcellation object
+
+        Returns
+        -------
+            Parcellation
+        """
 
         if parcellation is None:
             parcellation_obj = self.parcellations[self._parcellation_ids[0]]
@@ -80,12 +92,19 @@ class Atlas(concept.AtlasConcept, configuration_folder="atlases"):
 
         return self.parcellations[parcellation]
 
-    def get_space(self, space=None):
-        """Returns a valid reference space object defined by the atlas.
-        If no specification is provided, the default is returned.
+    def get_space(self, space=None) -> "_space.Space":
+        """
+        Returns a valid reference space object defined by the atlas. If no
+        specification is provided, the default is returned.
+
+        Parameters
+        ----------
+        space: str, Space
+            specification of a space or a space object
 
-        Parameters:
-            space: Space, or string specification of a space
+        Returns
+        -------
+            Space
         """
         if space is None:
             space_obj = self.spaces[self._space_ids[0]]
@@ -105,12 +124,13 @@ class Atlas(concept.AtlasConcept, configuration_folder="atlases"):
         parcellation: _parcellation.Parcellation = None,
         maptype: MapType = MapType.LABELLED,
     ):
-        """Returns a parcellation map in the given space.
+        """
+        Returns a parcellation map in the given space.
 
         Parameters
         ----------
 
-        space : Space
+        space: Space
             The requested reference space. If None, the default is used.
         parcellation: Parcellation
             The requested parcellation. If None, the default is used.
@@ -160,39 +180,46 @@ class Atlas(concept.AtlasConcept, configuration_folder="atlases"):
     def get_voi(self, space: _space.Space, point1: tuple, point2: tuple):
         """Get a volume of interest spanned by two points in the given reference space.
 
-        Args:
-            space (Space or str): The target reference space, or a string specification of the space
-            point1 (Tuple): A 3D coordinate given in this reference space
-            point2 (Tuple): Another 3D coordinate given in this reference space
+        Parameters
+        ----------
+        space: Space, str
+            The target reference space, or a string specification of the space
+        point1: Tuple
+            A 3D coordinate given in this reference space
+        point2: Tuple
+            Another 3D coordinate given in this reference space
 
-        Returns:
-            Bounding Box
+        Returns
+        -------
+            BoundingBox
         """
-        return self.get_space(space).get_bounding_box(point1, point2)
+        return self.get_template(space).get_boundingbox(point1, point2)
 
     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)
+            - 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
         -------
@@ -200,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");
@@ -21,11 +21,18 @@ from ..commons import (
     Species,
     TypePublication
 )
+from ..retrieval import cache
 
 import re
-from typing import TypeVar, Type, Union, List, TYPE_CHECKING
+from typing import TypeVar, Type, Union, List, TYPE_CHECKING, Dict
 
 T = TypeVar("T", bound="AtlasConcept")
+_REGISTRIES: Dict[Type[T], InstanceTable[T]] = {}
+
+
+@cache.Warmup.register_warmup_fn(is_factory=True)
+def _atlas_concept_warmup():
+    return [cls.registry for cls in _REGISTRIES]
 
 
 if TYPE_CHECKING:
@@ -33,6 +40,15 @@ if TYPE_CHECKING:
     TypeDataset = EbrainsDataset
 
 
+def get_registry(subclass_name: str):
+    subclasses = {c.__name__: c for c in _REGISTRIES}
+    if subclass_name in subclasses:
+        return subclasses[subclass_name].registry()
+    else:
+        logger.warn(f"No registry for atlas concepts named {subclass_name}")
+        return None
+
+
 class AtlasConcept:
     """
     Parent class encapsulating commonalities of the basic siibra concept like atlas, parcellation, space, region.
@@ -51,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.
@@ -78,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
@@ -87,6 +104,8 @@ class AtlasConcept:
         self._publications = publications
         self.datasets = datasets
         self._spec = spec
+        self._CACHED_MATCHES = {}  # we cache match() function results
+        self._prerelease = prerelease
 
     @property
     def description(self):
@@ -99,15 +118,29 @@ class AtlasConcept:
 
     @property
     def LICENSE(self) -> str:
-        return '\n'.join([ds.LICENSE for ds in self.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
-    def doi_or_url(self) -> str:
-        return '\n'.join([
+    def urls(self) -> List[str]:
+        """The list of URLs (including DOIs) associated with this atlas concept."""
+        return [
             url.get("url")
             for ds in self.datasets
             for url in ds.urls
-        ])
+        ]
 
     @property
     def authors(self):
@@ -139,7 +172,7 @@ class AtlasConcept:
     def registry(cls: Type[T]) -> InstanceTable[T]:
         if cls._configuration_folder is None:
             return None
-        if cls._registry_cached is None:
+        if _REGISTRIES[cls] is None:
             from ..configuration import Configuration
             conf = Configuration()
             # visit the configuration to provide a cleanup function
@@ -159,17 +192,20 @@ class AtlasConcept:
             r = siibra.volumes.Map.registry()
             """
             if len({o.__class__ for o in objects}) > 1:
-                logger.warning(f"{cls.__name__} registry contains multiple classes: {', '.join(list({o.__class__.__name__ for o in objects}))}")
+                logger.warning(
+                    f"{cls.__name__} registry contains multiple classes: "
+                    f"{', '.join(list({o.__class__.__name__ for o in objects}))}"
+                )
             assert hasattr(objects[0].__class__, "match") and callable(objects[0].__class__.match)
-            cls._registry_cached = InstanceTable(
+            _REGISTRIES[cls] = InstanceTable(
                 elements={o.key: o for o in objects},
                 matchfunc=objects[0].__class__.match
             )
-        return cls._registry_cached
+        return _REGISTRIES[cls]
 
     @classmethod
     def clear_registry(cls):
-        cls._registry_cached = None
+        _REGISTRIES[cls] = None
 
     @classmethod
     def get_instance(cls, spec: str):
@@ -204,45 +240,51 @@ class AtlasConcept:
         This method is called whenever AtlasConcept gets subclassed
         (see https://docs.python.org/3/reference/datamodel.html)
         """
-        cls._registry_cached = None
         cls._configuration_folder = configuration_folder
+        _REGISTRIES[cls] = None
         return super().__init_subclass__()
 
     def __str__(self):
-        return f"{self.__class__.__name__}: {self.name}"
+        return self.name
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__}(identifier='{self.id}', name='{self.name}', species='{self.species}')>"
 
-    def matches(self, spec):
+    def matches(self, spec) -> bool:
         """
         Parameters
         ----------
-            spec: str
-                Specification checked within the concept name, key or id
+        spec: str
+            Specification checked within the concept name, key or id
+
         Returns
         -------
-            bool
-                Whether the given specification matches the name, key or id of the concept.
+        bool
+            Whether the given specification matches the name, key or id of the concept.
         """
-        if isinstance(spec, self.__class__) and (spec == self):
-            return True
-        elif isinstance(spec, str):
-            if spec == self.key:
-                return True
-            elif spec == self.id:
-                return True
-            else:
-                # match the name
-                words = [w for w in re.split("[ -]", spec)]
-                squeezedname = clear_name(self.name.lower()).replace(" ", "")
-                return any(
-                    [
-                        all(w.lower() in squeezedname for w in words),
-                        spec.replace(" ", "") in squeezedname,
-                    ]
-                )
-        return False
+        if spec not in self._CACHED_MATCHES:
+            self._CACHED_MATCHES[spec] = False
+            if isinstance(spec, self.__class__) and (spec == self):
+                self._CACHED_MATCHES[spec] = True
+            elif isinstance(spec, str):
+                if spec == self.key:
+                    self._CACHED_MATCHES[spec] = True
+                elif spec == self.id:
+                    self._CACHED_MATCHES[spec] = True
+                else:
+                    # match the name
+                    words = [w for w in re.split("[ -]", spec)]
+                    squeezedname = clear_name(self.name.lower()).replace(" ", "")
+                    self._CACHED_MATCHES[spec] = any(
+                        [
+                            all(w.lower() in squeezedname for w in words),
+                            spec.replace(" ", "") in squeezedname,
+                        ]
+                    )
+        return self._CACHED_MATCHES[spec]
 
     @classmethod
-    def match(cls, obj, spec):
+    def match(cls, obj, spec) -> bool:
         """Match a given object specification. """
         assert isinstance(obj, cls)
         return obj.matches(spec)