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

siibra/features/__init__.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");
@@ -14,6 +14,9 @@
 # limitations under the License.
 """Multimodal data features types and query mechanisms."""
 
+from typing import Union
+from functools import partial
+
 from . import (
     connectivity,
     tabular,
@@ -21,21 +24,24 @@ from . import (
     dataset,
 )
 
+from ..commons import logger
 
 from .feature import Feature
-get = Feature.match
+from ..retrieval import cache
+from ..commons import siibra_tqdm
 
+get = Feature._match
 
-TYPES = Feature._get_subclasses()
+TYPES = Feature._get_subclasses()  # Feature types that can be used to query for features
 
 
 def __dir__():
-    return list(Feature.CATEGORIZED.keys())
+    return list(Feature._CATEGORIZED.keys()) + ["get", "TYPES", "render_ascii_tree"]
 
 
 def __getattr__(attr: str):
-    if attr in Feature.CATEGORIZED:
-        return Feature.CATEGORIZED[attr]
+    if attr in Feature._CATEGORIZED:
+        return Feature._CATEGORIZED[attr]
     else:
         hint = ""
         if isinstance(attr, str):
@@ -46,7 +52,66 @@ def __getattr__(attr: str):
         raise AttributeError(f"No such attribute: {__name__}.{attr} " + hint)
 
 
-def warm_cache():
+@cache.Warmup.register_warmup_fn()
+def _warm_feature_cache_instances():
     """Preload preconfigured multimodal data features."""
     for ftype in TYPES.values():
-        _ = ftype.get_instances()
+        _ = ftype._get_instances()
+
+
+@cache.Warmup.register_warmup_fn(cache.WarmupLevel.DATA, is_factory=True)
+def _warm_feature_cache_data():
+    return_callables = []
+    for ftype in TYPES.values():
+        instances = ftype._get_instances()
+
+        # the instances *must* be cleared, or it will impede the garbage collection, and results in memleak
+        ftype._clean_instances()
+        tally = siibra_tqdm(desc=f"Warming data {ftype.__name__}", total=len(instances))
+        for f in instances:
+            def get_data(arg):
+                tally = arg.pop("tally")
+                feature = arg.pop("feature")
+                # TODO
+                # the try catch is as a result of https://github.com/FZJ-INM1-BDA/siibra-python/issues/509
+                # sometimes f.data can fail
+                try:
+                    _ = feature.data
+                except Exception as e:
+                    logger.warn(f"Feature {feature.name} warmup failed: {str(e)}")
+                finally:
+                    tally.update(1)
+            # append dictionary, so that popping the dictionary will mark the feature to be garbage collected
+            return_callables.append(partial(get_data, {"feature": f, "tally": tally}))
+    return return_callables
+
+
+def render_ascii_tree(class_or_classname: Union[type, str]):
+    """
+    Print the ascii hierarchy representation of a feature type.
+
+    Parameters
+    ----------
+    class_or_classname: type, str
+        Any Feature class or string of the feature type name
+    """
+    from anytree.importer import DictImporter
+    from anytree import RenderTree
+    Cls = TYPES[class_or_classname] if isinstance(class_or_classname, str) else class_or_classname
+    assert issubclass(Cls, Feature)
+
+    def create_treenode(feature_type):
+        return {
+            'name': feature_type.__name__,
+            'children': [
+                create_treenode(c)
+                for c in feature_type.__subclasses__()
+            ]
+        }
+    D = create_treenode(Cls)
+    importer = DictImporter()
+    tree = importer.import_(D)
+    print("\n".join(
+        "%s%s" % (pre, node.name)
+        for pre, _, node in RenderTree(tree)
+    ))

siibra/features/anchor.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");
@@ -12,40 +12,41 @@
 # 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.
-"""Handles the relation between study targets and AtlasConcepts."""
+"""Handles the relation between study targets and BrainStructures."""
 
-from ..commons import logger, Species
+from ..commons import Species, logger
 
-from ..core.concept import AtlasConcept
+from ..core.structure import BrainStructure
+from ..core.assignment import AnatomicalAssignment, Qualification
 from ..locations.location import Location
-from ..locations.boundingbox import BoundingBox
-from ..core.parcellation import Parcellation
+from ..core.parcellation import Parcellation, find_regions
 from ..core.region import Region
 from ..core.space import Space
-from ..core.relation_qualification import Qualification as AssignmentQualification, RelationAssignment
+from ..exceptions import SpaceWarpingFailedError
 
 from ..vocabularies import REGION_ALIASES
 
-from typing import Union, List, Dict
-
-AnatomicalAssignment = RelationAssignment[Union[Region, Location]]
+from typing import Union, List, Dict, Iterable
 
 
 class AnatomicalAnchor:
     """
-    Anatomical anchor to an atlas region,
-    a geometric primitive in an atlas reference space,
-    or both.
+    Anatomical anchor to an atlas region, a geometric primitive in an atlas
+    reference space, or both.
     """
 
-    _MATCH_MEMO: Dict[str, Dict[Region, AssignmentQualification]] = {}
-    _MASK_MEMO = {}
+    _MATCH_MEMO: Dict[str, Dict[Region, Qualification]] = {}
 
-    def __init__(self, species: Union[List[Species], Species, str], location: Location = None, region: Union[str, Region] = None):
+    def __init__(
+        self,
+        species: Union[List[Species], Species, str],
+        location: Location = None,
+        region: Union[str, Region] = None
+    ):
 
         if isinstance(species, (str, Species)):
             self.species = {Species.decode(species)}
-        elif isinstance(species, list):
+        elif isinstance(species, Iterable):
             assert all(isinstance(_, Species) for _ in species)
             self.species = set(species)
         else:
@@ -55,7 +56,7 @@ class AnatomicalAnchor:
             else:
                 self.species = {sp}
         self._location_cached = location
-        self._assignments: Dict[Union[AtlasConcept, Location], List[AnatomicalAssignment]] = {}
+        self._assignments: Dict[BrainStructure, List[AnatomicalAssignment]] = {}
         self._last_matched_concept = None
         if isinstance(region, dict):
             self._regions_cached = region
@@ -64,8 +65,9 @@ class AnatomicalAnchor:
             self._regions_cached = None
             self._regionspec = None
             if isinstance(region, Region):
-                self._regions_cached = {region: AssignmentQualification.EXACT}
+                self._regions_cached = {region: Qualification.EXACT}
             elif isinstance(region, str):
+                # we will decode regions only when needed, see self.regions property
                 self._regionspec = region
             else:
                 if region is not None:
@@ -73,24 +75,25 @@ class AnatomicalAnchor:
         self._aliases_cached = None
 
     @property
-    def location(self):
+    def location(self) -> Location:
         # allow to overwrite in derived classes
         return self._location_cached
 
     @property
     def parcellations(self) -> List[Parcellation]:
+        """
+        Return any parcellation objects that regions of this anchor belong to.
+        """
         return list({region.root for region in self.regions})
 
     @property
     def space(self) -> Space:
         # may be overriden by derived classes, e.g. in features.VolumeOfInterest
-        if self.location is None:
-            return None
-        else:
-            return self.location.space
+        return None if self.location is None else self.location.space
 
     @property
     def region_aliases(self):
+        # return any predefined aliases for the region specified in this anchor.
         if self._aliases_cached is None:
             self._aliases_cached: Dict[str, Dict[str, str]] = {
                 Species.decode(species_str): region_alias_mapping
@@ -100,43 +103,52 @@ class AnatomicalAnchor:
         return self._aliases_cached
 
     @property
-    def has_region_aliases(self):
+    def has_region_aliases(self) -> bool:
         return len(self.region_aliases) > 0
 
     @property
-    def regions(self) -> Dict[Region, AssignmentQualification]:
+    def regions(self) -> Dict[Region, Qualification]:
+        """
+        Return the list of regions associated with this anchor.
+        Decode the self._regionspec string into region objects now,
+        if applicable and called for the first time.
+        """
         # decoding region strings is quite compute intensive, so we cache this at the class level
         if self._regions_cached is not None:
             return self._regions_cached
 
         if self._regionspec is None:
-            self._regions_cached = {}
+            self._regions_cached = dict()
             return self._regions_cached
 
-        if self._regionspec not in self.__class__._MATCH_MEMO:
-            self._regions_cached = {}
-            # decode the region specification into a set of region objects
+        match_key = self._regionspec + '-' + str(self.species)
+        if match_key not in self.__class__._MATCH_MEMO:
+            # decode the region specification into a dict of region objects and assignment qualifications
             regions = {
-                r: AssignmentQualification.EXACT
-                for species in self.species
-                for r in Parcellation.find_regions(self._regionspec)
-                if r.species == species
+                region: Qualification.EXACT
+                for region in find_regions(self._regionspec, filter_children=True, find_topmost=False)
+                if region.species in self.species
             }
             # add more regions from possible aliases of the region spec
             for alt_species, aliases in self.region_aliases.items():
-                for regionspec, qualificationspec in aliases.items():
-                    for r in Parcellation.find_regions(regionspec):
+                for alias_regionspec, qualificationspec in aliases.items():
+                    for r in find_regions(alias_regionspec, filter_children=True, find_topmost=False):
                         if r.species != alt_species:
                             continue
-                        if r not in self._regions_cached:
-                            regions[r] = AssignmentQualification[qualificationspec.upper()]
-            self.__class__._MATCH_MEMO[self._regionspec] = regions
-        self._regions_cached = self.__class__._MATCH_MEMO[self._regionspec]
+                        if r not in regions:
+                            regions[r] = Qualification[qualificationspec.upper()]
+
+            self.__class__._MATCH_MEMO[match_key] = regions
+        self._regions_cached = self.__class__._MATCH_MEMO[match_key]
 
         return self._regions_cached
 
     def __str__(self):
-        region = "" if self._regionspec is None else str(self._regionspec)
+        parcs = {p.id: p.name for p in self.represented_parcellations()}
+        if len(parcs) == 1 and self._regionspec in [pid for pid in parcs]:
+            region = parcs[self._regionspec]  # if parcellation was anchored with the id instead of the name
+        else:
+            region = "" if self._regionspec is None else str(self._regionspec)
         location = "" if self.location is None else str(self.location)
         separator = " " if min(len(region), len(location)) > 0 else ""
         if region and location:
@@ -144,174 +156,41 @@ class AnatomicalAnchor:
         else:
             return region + separator + location
 
-    def __repr__(self):
-        return self.__str__()
-
-    def assign(self, concept: AtlasConcept):
+    def assign(self, concept: Union[BrainStructure, Space]) -> AnatomicalAssignment:
         """
-        Match this anchoring to an atlas concept.
+        Match this anchor to a query concept. Assignments are cached at runtime,
+        so repeated assignment with the same concept will be cheap.
         """
+        if isinstance(concept, Space):
+            if self.location is not None and self.location.space.matches(concept):
+                return [AnatomicalAssignment(concept, self.location, Qualification.CONTAINED)]
+            else:
+                return []
+
         if concept not in self._assignments:
-            matches: List[AnatomicalAssignment] = []
-            if isinstance(concept, Space):
-                if self.space == concept:
-                    matches.append(
-                        AnatomicalAssignment(self.space, concept, AssignmentQualification.EXACT)
-                    )
-            elif isinstance(concept, Region):
-                if concept.species in self.species:
-                    if any(_.matches(self._regionspec) for _ in concept) \
-                            or self.has_region_aliases:  # dramatic speedup, since decoding _regionspec is expensive
-                        for r in self.regions:
-                            matches.append(AnatomicalAnchor.match_regions(r, concept))
-                    if len(concept.root.find(self._regionspec)) == 0:
-                        # We perform the (quite expensive) location-to-region test
-                        # only if this anchor's regionspec is not known to the
-                        # parcellation of the query region. Otherwise we can rely
-                        # on the region-to-region test.
-                        if self.location is not None:
-                            matches.append(AnatomicalAnchor.match_location_to_region(self.location, concept))
-            elif isinstance(concept, Location):
-                if self.location is not None:
-                    matches.append(AnatomicalAnchor.match_locations(self.location, concept))
-                for region in self.regions:
-                    match = AnatomicalAnchor.match_location_to_region(concept, region)
-                    matches.append(None if match is None else match.invert())
-            self._assignments[concept] = sorted(m for m in matches if m is not None)
+            assignments: List[AnatomicalAssignment] = []
+            if self.location is not None:
+                try:
+                    assignments.append(self.location.assign(concept))
+                except SpaceWarpingFailedError as e:
+                    logger.debug(e)
+            for region in self.regions:
+                assignments.append(region.assign(concept))
+            self._assignments[concept] = sorted(a for a in assignments if a is not None)
 
         self._last_matched_concept = concept \
             if len(self._assignments[concept]) > 0 \
             else None
-
         return self._assignments[concept]
 
-    def matches(self, concept: AtlasConcept):
+    def matches(self, concept: Union[BrainStructure, Space]) -> bool:
         return len(self.assign(concept)) > 0
 
-    @classmethod
-    def match_locations(cls, location1: Location, location2: Location):
-        assert all(isinstance(loc, Location) for loc in [location1, location2])
-        if (location1, location2) not in cls._MATCH_MEMO:
-            if location1 == location2:
-                res = AnatomicalAssignment(location1, location2, AssignmentQualification.EXACT)
-            elif location1.contained_in(location2):
-                res = AnatomicalAssignment(location1, location2, AssignmentQualification.CONTAINED)
-            elif location1.contains(location2):
-                res = AnatomicalAssignment(location1, location2, AssignmentQualification.CONTAINS)
-            elif location1.intersects(location2):
-                res = AnatomicalAssignment(location1, location2, AssignmentQualification.OVERLAPS)
-            else:
-                res = None
-            cls._MATCH_MEMO[location1, location2] = res
-        return cls._MATCH_MEMO[location1, location2]
-
-    @classmethod
-    def match_regions(cls, region1: Region, region2: Region):
-        assert all(isinstance(r, Region) for r in [region1, region2])
-        if (region1, region2) not in cls._MATCH_MEMO:
-            if region1 == region2:
-                res = AnatomicalAssignment(region1, region2, AssignmentQualification.EXACT)
-            elif region1 in region2:
-                res = AnatomicalAssignment(region1, region2, AssignmentQualification.CONTAINED)
-            elif region2 in region1:
-                res = AnatomicalAssignment(region1, region2, AssignmentQualification.CONTAINS)
-            else:
-                res = None
-            cls._MATCH_MEMO[region1, region2] = res
-        return cls._MATCH_MEMO[region1, region2]
-
-    @classmethod
-    def match_location_to_region(cls, location: Location, region: Region):
-        assert isinstance(location, Location)
-        assert isinstance(region, Region)
-
-        for subregion in region.children:
-            res = cls.match_location_to_region(location, subregion)
-            if res is not None:
-                return res
-
-        if (location, region) not in cls._MATCH_MEMO:
-            # compute mask of the region
-            mask = None
-            if region.mapped_in_space(location.space, recurse=False):
-                if (region, location.space) not in cls._MASK_MEMO:
-                    cls._MASK_MEMO[region, location.space] = \
-                        region.fetch_regional_map(space=location.space, maptype='labelled')
-                mask = cls._MASK_MEMO[region, location.space]
-                mask_space = location.space
-                expl = (
-                    f"{location} was compared with the mask of query region "
-                    f"'{region.name}' in {location.space.name}."
-                )
-            else:
-                for space in region.supported_spaces:
-                    if not region.mapped_in_space(space, recurse=False):
-                        continue
-                    if not space.provides_image:  # siibra does not yet match locations to surface spaces
-                        continue
-                    if (region, space) not in cls._MASK_MEMO:
-                        cls._MASK_MEMO[region, space] = region.fetch_regional_map(space=space, maptype='labelled')
-                    mask = cls._MASK_MEMO[region, space]
-                    mask_space = space
-                    if location.space == mask_space:
-                        expl = (
-                            f"{location} was compared with the mask of query region '{region.name}' "
-                            f"in {mask_space}."
-                        )
-                    else:
-                        expl = (
-                            f"{location} was warped from {location.space.name} and then compared "
-                            f"in this space with the mask of query region '{region.name}'."
-                        )
-                    if mask is not None:
-                        break
-
-            if mask is None:
-                logger.debug(
-                    f"'{region.name}' provides no mask in a space "
-                    f"to which {location} can be warped."
-                )
-                res = None
-            else:
-                # compare mask to location
-                loc_warped = location.warp(mask_space)
-                if loc_warped is None:
-                    # seems we cannot warp our location to the mask space
-                    # this typically happens when the location extends outside
-                    # the brain. We might still be able the warp the
-                    # bounding box of the mask to the location and check.
-                    # TODO in fact we should estimate an affine matrix from the warped bounding box,
-                    # and resample the mask for the inverse test to be more precise.
-                    bbox_mask = BoundingBox.from_image(mask, mask_space).warp(location.space)
-                    return cls.match_locations(location, bbox_mask)
-                elif loc_warped.contained_in(mask):
-                    res = AnatomicalAssignment(location, region, AssignmentQualification.CONTAINED, expl)
-                elif loc_warped.contains(mask):
-                    res = AnatomicalAssignment(location, region, AssignmentQualification.CONTAINS, expl)
-                elif loc_warped.intersects(mask):
-                    res = AnatomicalAssignment(location, region, AssignmentQualification.OVERLAPS, expl)
-                else:
-                    logger.debug(
-                        f"{location} does not match mask of '{region.name}' in {mask_space.name}."
-                    )
-                    res = None
-            cls._MATCH_MEMO[location, region] = res
-
-        # keep mask cache small
-        if len(cls._MASK_MEMO) > 3:
-            # from Python 3.6, this remove the *oldest* entry
-            cls._MASK_MEMO.pop(next(iter(cls._MASK_MEMO)))
-
-        return cls._MATCH_MEMO[location, region]
-
-    def represented_parcellations(self):
+    def represented_parcellations(self) -> List[Parcellation]:
         """
         Return any parcellation objects that this anchor explicitly points to.
         """
-        return [
-            r for r in self.regions
-            if isinstance(r, Parcellation)
-        ]
+        return [r for r in self.regions if isinstance(r, Parcellation)]
 
     @property
     def last_match_result(self) -> List[AnatomicalAssignment]:
@@ -340,6 +219,6 @@ class AnatomicalAnchor:
 
         return AnatomicalAnchor(species, location, regions)
 
-    def __radd__(self, other):
+    def __radd__(self, other) -> 'AnatomicalAnchor':
         # required to enable `sum`
         return self if other == 0 else self.__add__(other)

siibra/features/connectivity/__init__.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");

siibra/features/connectivity/functional_connectivity.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");
@@ -41,7 +41,7 @@ class FunctionalConnectivity(
 
     @property
     def name(self):
-        return f"{super().name}, {self.paradigm} paradigm"
+        return super().name + f", paradigm: {self.paradigm}"
 
 
 class AnatomoFunctionalConnectivity(