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

siibra/features/feature.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,14 +17,16 @@
 from . import anchor as _anchor
 
 from ..commons import logger, InstanceTable, siibra_tqdm, __version__
-from ..core import concept
-from ..core import space, region, parcellation
+from ..core import concept, space, region, parcellation, structure
+from ..volumes import volume
 
 from typing import Union, TYPE_CHECKING, List, Dict, Type, Tuple, BinaryIO, Any, Iterator
 from hashlib import md5
 from collections import defaultdict
 from zipfile import ZipFile
-from abc import ABC
+from abc import ABC, abstractmethod
+from re import sub
+from textwrap import wrap
 
 if TYPE_CHECKING:
     from ..retrieval.datasets import EbrainsDataset
@@ -86,9 +88,8 @@ class Feature:
     Base class for anatomically anchored data features.
     """
 
-    SUBCLASSES: Dict[Type['Feature'], List[Type['Feature']]] = defaultdict(list)
-
-    CATEGORIZED: Dict[str, Type['InstanceTable']] = defaultdict(InstanceTable)
+    _SUBCLASSES: Dict[Type['Feature'], List[Type['Feature']]] = defaultdict(list)
+    _CATEGORIZED: Dict[str, Type['InstanceTable']] = defaultdict(InstanceTable)
 
     category: str = None
 
@@ -97,7 +98,9 @@ class Feature:
         modality: str,
         description: str,
         anchor: _anchor.AnatomicalAnchor,
-        datasets: List['TypeDataset'] = []
+        datasets: List['TypeDataset'] = [],
+        id: str = None,
+        prerelease: bool = False,
     ):
         """
         Parameters
@@ -114,6 +117,8 @@ class Feature:
         self._description = description
         self._anchor_cached = anchor
         self.datasets = datasets
+        self._id = id
+        self._prerelease = prerelease
 
     @property
     def modality(self):
@@ -141,19 +146,19 @@ class Feature:
                 # some base classes may not be sub class of feature, ignore these
                 if not issubclass(BaseCls, Feature):
                     continue
-                cls.SUBCLASSES[BaseCls].append(cls)
+                cls._SUBCLASSES[BaseCls].append(cls)
 
         cls._live_queries = []
         cls._preconfigured_instances = None
         cls._configuration_folder = configuration_folder
         cls.category = category
         if category is not None:
-            cls.CATEGORIZED[category].add(cls.__name__, cls)
+            cls._CATEGORIZED[category].add(cls.__name__, cls)
         return super().__init_subclass__(**kwargs)
 
     @classmethod
     def _get_subclasses(cls):
-        return {Cls.__name__: Cls for Cls in cls.SUBCLASSES}
+        return {Cls.__name__: Cls for Cls in cls._SUBCLASSES}
 
     @property
     def description(self):
@@ -167,15 +172,29 @@ class Feature:
 
     @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 feature."""
+        return [
             url.get("url")
             for ds in self.datasets
             for url in ds.urls
-        ])
+        ]
 
     @property
     def authors(self):
@@ -188,10 +207,12 @@ class Feature:
     @property
     def name(self):
         """Returns a short human-readable name of this feature."""
-        return f"{self.__class__.__name__} ({self.modality}) anchored at {self.anchor}"
+        readable_class_name = sub("([a-z])([A-Z])", r"\g<1> \g<2>", self.__class__.__name__)
+        name_ = sub("([b,B]ig [b,B]rain)", "BigBrain", readable_class_name)
+        return name_ if not self._prerelease else f"[PRERELEASE] {name_}"
 
     @classmethod
-    def get_instances(cls, **kwargs) -> List['Feature']:
+    def _get_instances(cls, **kwargs) -> List['Feature']:
         """
         Retrieve objects of a particular feature subclass.
         Objects can be preconfigured in the configuration,
@@ -209,7 +230,7 @@ class Feature:
 
         from ..configuration.configuration import Configuration
         conf = Configuration()
-        Configuration.register_cleanup(cls.clean_instances)
+        Configuration.register_cleanup(cls._clean_instances)
         assert cls._configuration_folder in conf.folders
         cls._preconfigured_instances = [
             o for o in conf.build_objects(cls._configuration_folder)
@@ -226,11 +247,19 @@ class Feature:
         raise NotImplementedError("Generic feature class does not have a standardized plot.")
 
     @classmethod
-    def clean_instances(cls):
+    def _clean_instances(cls):
         """ Removes all instantiated object instances"""
         cls._preconfigured_instances = None
 
-    def matches(self, concept: concept.AtlasConcept) -> bool:
+    def matches(
+        self,
+        concept: Union[structure.BrainStructure, space.Space],
+    ) -> bool:
+        """
+        Match the features anatomical anchor agains the given query concept.
+        Record the most recently matched concept for inspection by the caller.
+        """
+        # TODO: storing the last matched concept. It is not ideal, might cause problems in multithreading
         if self.anchor and self.anchor.matches(concept):
             self.anchor._last_matched_concept = concept
             return True
@@ -239,26 +268,36 @@ class Feature:
 
     @property
     def last_match_result(self):
-        return None if self.anchor is None \
-            else self.anchor.last_match_result
+        "The result of the last anchor comparison to a BrainStructure."
+        return None if self.anchor is None else self.anchor.last_match_result
 
     @property
     def last_match_description(self):
-        return "" if self.anchor is None \
-            else self.anchor.last_match_description
+        "The description of the last anchor comparison to a BrainStructure."
+        return "" if self.anchor is None else self.anchor.last_match_description
 
     @property
     def id(self):
+        if self._id:
+            return self._id
+
+        if self._prerelease:
+            name_ = self.name.replace("[PRERELEASE] ", "")
+        else:
+            name_ = self.name
+
         prefix = ''
         for ds in self.datasets:
             if hasattr(ds, "id"):
                 prefix = ds.id + '--'
                 break
-        return prefix + md5(self.name.encode("utf-8")).hexdigest()
+        return prefix + md5(
+            f"{name_} - {self.anchor}".encode("utf-8")
+        ).hexdigest()
 
-    def _export(self, fh: ZipFile):
+    def _to_zip(self, fh: ZipFile):
         """
-        Internal implementation. Subclasses can override but call super()._export(fh).
+        Internal implementation. Subclasses can override but call super()._to_zip(fh).
         This allows all classes in the __mro__ to have the opportunity to append files
         of interest.
         """
@@ -298,7 +337,7 @@ class Feature:
             )
         )
 
-    def export(self, filelike: Union[str, BinaryIO]):
+    def to_zip(self, filelike: Union[str, BinaryIO]):
         """
         Export as a zip archive.
 
@@ -309,11 +348,11 @@ class Feature:
             correct extension (.zip) is set.
         """
         fh = ZipFile(filelike, "w")
-        self._export(fh)
+        self._to_zip(fh)
         fh.close()
 
     @staticmethod
-    def serialize_query_context(feat: 'Feature', concept: concept.AtlasConcept) -> str:
+    def _serialize_query_context(feat: 'Feature', concept: concept.AtlasConcept) -> str:
         """
         Serialize feature from livequery and query context.
 
@@ -348,7 +387,7 @@ class Feature:
         return f"lq0::{feat.__class__.__name__}::{encoded_c}::{feat.id}"
 
     @classmethod
-    def deserialize_query_context(cls, feature_id: str) -> Tuple[Type['Feature'], concept.AtlasConcept, str]:
+    def _deserialize_query_context(cls, feature_id: str) -> Tuple[Type['Feature'], concept.AtlasConcept, str]:
         """
         Deserialize id into query context.
 
@@ -372,6 +411,7 @@ class Feature:
 
     @staticmethod
     def _encode_concept(concept: concept.AtlasConcept):
+        from ..locations import Location
         encoded_c = []
         if isinstance(concept, space.Space):
             encoded_c.append(f"s:{concept.id}")
@@ -380,6 +420,10 @@ class Feature:
         elif isinstance(concept, region.Region):
             encoded_c.append(f"p:{concept.parcellation.id}")
             encoded_c.append(f"r:{concept.name}")
+        elif isinstance(concept, volume.Volume):
+            encoded_c.append(f"v:{concept.name}")
+        elif isinstance(concept, Location):
+            encoded_c.append(f"loc:{Location}")
 
         if len(encoded_c) == 0:
             raise EncodeLiveQueryIdException("no concept is encoded")
@@ -419,7 +463,7 @@ class Feature:
     def _parse_featuretype(cls, feature_type: str) -> List[Type['Feature']]:
         ftypes = sorted({
             feattype
-            for FeatCls, feattypes in cls.SUBCLASSES.items()
+            for FeatCls, feattypes in cls._SUBCLASSES.items()
             if all(w.lower() in FeatCls.__name__.lower() for w in feature_type.split())
             for feattype in feattypes
         }, key=lambda t: t.__name__)
@@ -429,41 +473,52 @@ class Feature:
             return list(ftypes)
 
     @classmethod
-    def livequery(cls, concept: Union[region.Region, parcellation.Parcellation, space.Space], **kwargs) -> List['Feature']:
+    def _livequery(cls, concept: Union[region.Region, parcellation.Parcellation, space.Space], **kwargs) -> List['Feature']:
         if not hasattr(cls, "_live_queries"):
             return []
 
         live_instances = []
         for QueryType in cls._live_queries:
-            argstr = f" ({', '.join('='.join(map(str,_)) for _ in kwargs.items())})" \
+            argstr = f" ({', '.join('='.join(map(str, _)) for _ in kwargs.items())})" \
                 if len(kwargs) > 0 else ""
-            logger.info(
+            logger.debug(
                 f"Running live query for {QueryType.feature_type.__name__} "
                 f"objects linked to {str(concept)}{argstr}"
             )
             q = QueryType(**kwargs)
-            features = [
-                Feature.wrap_livequery_feature(feat, Feature.serialize_query_context(feat, concept))
-                for feat in q.query(concept)
-            ]
-            live_instances.extend(features)
+            if isinstance(concept, space.Space):
+                features = q.query(concept.get_template())
+            else:
+                features = q.query(concept)
+            live_instances.extend(
+                Feature._wrap_livequery_feature(f, Feature._serialize_query_context(f, concept))
+                for f in features
+            )
+
         return live_instances
 
     @classmethod
-    def match(
+    def _match(
         cls,
-        concept: Union[region.Region, parcellation.Parcellation, space.Space],
+        concept: Union[structure.BrainStructure, space.Space],
         feature_type: Union[str, Type['Feature'], list],
         **kwargs
     ) -> List['Feature']:
         """
-        Retrieve data features of the desired modality.
+        Retrieve data features of the requested feature type (i.e. modality).
+        This will
+        - call Feature.match(concept) for any registered preconfigured features
+        - run any registered live queries
+        The preconfigured and live query instances are merged and returend as a list.
+
+        If multiple feature types are given, recurse for each of them.
+
 
         Parameters
         ----------
         concept: AtlasConcept
             An anatomical concept, typically a brain region or parcellation.
-        modality: subclass of Feature
+        feature_type: subclass of Feature, str
             specififies the type of features ("modality")
         """
         if isinstance(feature_type, list):
@@ -474,7 +529,7 @@ class Feature:
             )
             return list(dict.fromkeys(
                 sum((
-                    cls.match(concept, t, **kwargs) for t in feature_type
+                    cls._match(concept, t, **kwargs) for t in feature_type
                 ), [])
             ))
 
@@ -485,39 +540,47 @@ class Feature:
             if len(ftype_candidates) == 0:
                 raise ValueError(
                     f"feature_type {str(feature_type)} did not match with any "
-                    f"features. Available features are: {', '.join(cls.SUBCLASSES.keys())}"
+                    f"features. Available features are: {', '.join(cls._SUBCLASSES.keys())}"
                 )
             logger.info(
                 f"'{feature_type}' decoded as feature type/s: "
                 f"{[c.__name__ for c in ftype_candidates]}."
             )
-            return cls.match(concept, ftype_candidates, **kwargs)
+            return cls._match(concept, ftype_candidates, **kwargs)
 
         assert issubclass(feature_type, Feature)
 
-        if not isinstance(concept, (region.Region, parcellation.Parcellation, space.Space)):
+        # At this stage, no recursion is needed.
+        # We expect a specific supported feature type is to be matched now.
+        if not isinstance(concept, (structure.BrainStructure, space.Space)):
             raise ValueError(
-                "Feature.match / siibra.features.get only accepts Region, "
-                "Space and Parcellation objects as concept."
+                f"{concept.__class__.__name__} cannot be used for feature queries as it is not a `BrainStructure` or a `Space` type."
             )
 
-        msg = f"Matching {feature_type.__name__} to {concept}"
+        # Collect any preconfigured instances of the requested feature type
+        # which match the query concept
         instances = [
             instance
-            for f_type in cls.SUBCLASSES[feature_type]
-            for instance in f_type.get_instances()
+            for f_type in cls._SUBCLASSES[feature_type]
+            for instance in f_type._get_instances()
         ]
 
         preconfigured_instances = [
             f for f in siibra_tqdm(
-                instances, desc=msg, total=len(instances), disable=(not instances)
-            ) if f.matches(concept)
+                instances,
+                desc=f"Matching {feature_type.__name__} to {concept}",
+                total=len(instances),
+                disable=(not instances)
+            )
+            if f.matches(concept)
         ]
 
-        live_instances = feature_type.livequery(concept, **kwargs)
+        # Then run any registered live queries for the requested feature type
+        # with the query concept.
+        live_instances = feature_type._livequery(concept, **kwargs)
 
         results = list(dict.fromkeys(preconfigured_instances + live_instances))
-        return CompoundFeature.compound(results, concept)
+        return CompoundFeature._compound(results, concept)
 
     @classmethod
     def _get_instance_by_id(cls, feature_id: str, **kwargs):
@@ -527,17 +590,17 @@ class Feature:
             pass
 
         try:
-            F, concept, fid = cls.deserialize_query_context(feature_id)
+            F, concept, fid = cls._deserialize_query_context(feature_id)
             return [
                 f
-                for f in F.livequery(concept, **kwargs)
+                for f in F._livequery(concept, **kwargs)
                 if f.id == fid or f.id == feature_id
             ][0]
         except ParseLiveQueryIdException:
             candidates = [
                 inst
-                for Cls in Feature.SUBCLASSES[Feature]
-                for inst in Cls.get_instances()
+                for Cls in Feature._SUBCLASSES[Feature]
+                for inst in Cls._get_instances()
                 if inst.id == feature_id
             ]
             if len(candidates) == 0:
@@ -552,31 +615,8 @@ class Feature:
         except IndexError:
             raise NotFoundException
 
-    @classmethod
-    def get_ascii_tree(cls):
-        # build an Ascii representation of class hierarchy
-        # under this feature class
-        from anytree.importer import DictImporter
-        from anytree import RenderTree
-
-        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)
-        return "\n".join(
-            "%s%s" % (pre, node.name)
-            for pre, _, node in RenderTree(tree)
-        )
-
     @staticmethod
-    def wrap_livequery_feature(feature: 'Feature', fid: str):
+    def _wrap_livequery_feature(feature: 'Feature', fid: str):
         """
         Wrap live query features, override only the id attribute.
 
@@ -596,6 +636,7 @@ class Feature:
             def __init__(self, inst: Feature, fid: str):
                 self.inst = inst
                 self.fid = fid
+                self.category = inst.category
 
             def __str__(self) -> str:
                 return self.inst.__str__()
@@ -625,6 +666,11 @@ class Compoundable(ABC):
         assert len(cls._filter_attrs) > 0, "All compoundable classes have to have `_filter_attrs` defined."
         assert len(cls._compound_attrs) > 0, "All compoundable classes have to have `_compound_attrs` defined."
         assert all(attr in cls._filter_attrs for attr in cls._compound_attrs), "`_compound_attrs` must be a subset of `_filter_attrs`."
+        cls._indexing_attrs = [
+            attr
+            for attr in cls._filter_attrs
+            if attr not in cls._compound_attrs
+        ]
         return super().__init_subclass__(**kwargs)
 
     def __init__(self):
@@ -649,15 +695,35 @@ class Compoundable(ABC):
     @property
     def _element_index(self) -> Any:
         """
-        Unique index of this compoundable feature as a subfeature of the
-        Compound. Should be hashable.
+        Unique index of this compoundable feature as an element of the Compound.
+        Must be hashable.
         """
-        index = [
-            self.filter_attributes[attr]
-            for attr in self._filter_attrs
-            if attr not in self._compound_attrs
-        ]
-        return index[0] if len(index) == 1 else tuple(index)
+        index_ = [self.filter_attributes[attr] for attr in self._indexing_attrs]
+        index = index_[0] if len(index_) == 1 else tuple(index_)
+        assert hash(index), "`_element_index` of a compoundable must be hashable."
+        return index
+
+    @classmethod
+    def _merge_anchors(cls, anchors: List[_anchor.AnatomicalAnchor]):
+        return sum(anchors)
+
+    @classmethod
+    @abstractmethod
+    def _merge_elements(
+        cls,
+        elements,
+        description: str,
+        modality: str,
+        anchor: _anchor.AnatomicalAnchor
+    ) -> Feature:
+        """
+        Compute the merge data and create a merged instance from a set of
+        elements of this class. This will be used by CompoundFeature to
+        create the aggegated data and plot it. For example, to compute an
+        average connectivity matrix from a set of subfeatures, we create a
+        RegionalConnectivty feature.
+        """
+        raise NotImplementedError
 
 
 class CompoundFeature(Feature):
@@ -671,7 +737,7 @@ class CompoundFeature(Feature):
     def __init__(
         self,
         elements: List['Feature'],
-        queryconcept: Union[region.Region, parcellation.Parcellation, space.Space]
+        queryconcept: Union[region.Region, parcellation.Parcellation, space.Space],
     ):
         """
         A compound of several features of the same type with an anchor created
@@ -703,21 +769,57 @@ class CompoundFeature(Feature):
             self,
             modality=modality,
             description="\n".join({f.description for f in elements}),
-            anchor=sum([f.anchor for f in elements]),
-            datasets=list(dict.fromkeys([ds for f in elements for ds in f.datasets]))
+            anchor=self._feature_type._merge_anchors([f.anchor for f in elements]),
+            datasets=list(dict.fromkeys([ds for f in elements for ds in f.datasets])),
+            prerelease=all(f._prerelease for f in elements),
         )
         self._queryconcept = queryconcept
+        self._merged_feature_cached = None
 
     def __getattr__(self, attr: str) -> Any:
         """Expose compounding attributes explicitly."""
         if attr in self._compounding_attributes:
             return self._compounding_attributes[attr]
-        else:
-            raise AttributeError(f"{self._feature_type.__name__} has no attribute {attr}.")
+        if hasattr(self._feature_type, attr):
+            raise AttributeError(
+                f"{self.__class__.__name__} does not have access to '{attr}' "
+                "since it does not have the same value for all its elements."
+            )
+        raise AttributeError(
+            f"{self.__class__.__name__} or {self._feature_type.__name__} have no attribute {attr}."
+        )
 
     def __dir__(self):
         return super().__dir__() + list(self._compounding_attributes.keys())
 
+    def plot(self, *args, **kwargs):
+        kwargs["title"] = "(Derived data: averaged)\n" + kwargs.get(
+            "title",
+            "\n".join(wrap(self.name, kwargs.pop("textwrap", 40)))
+        )
+        return self._get_merged_feature().plot(*args, **kwargs)
+
+    def _get_merged_feature(self) -> Feature:
+        if self._merged_feature_cached is None:
+            logger.info(f"{self.__class__.__name__}.data averages the data of each element.")
+            assert issubclass(self.feature_type, Compoundable)
+            self._merged_feature_cached = self.feature_type._merge_elements(
+                elements=self.elements,
+                modality=self.modality,
+                description=self.description,
+                anchor=self.anchor
+            )
+        return self._merged_feature_cached
+
+    @property
+    def data(self):
+        return self._get_merged_feature().data
+
+    @property
+    def indexing_attributes(self) -> Tuple[str]:
+        "The attributes determining the index of this CompoundFeature's elements."
+        return tuple(self.elements[0]._indexing_attrs)
+
     @property
     def elements(self):
         """Features that make up the compound feature."""
@@ -725,7 +827,7 @@ class CompoundFeature(Feature):
 
     @property
     def indices(self):
-        """Unique indices to features making up the compound feature."""
+        """Unique indices to features making up the CompoundFeature."""
         return list(self._elements.keys())
 
     @property
@@ -736,23 +838,30 @@ class CompoundFeature(Feature):
     @property
     def name(self) -> str:
         """Returns a short human-readable name of this feature."""
+        readable_feature_type = sub(
+            "([b,B]ig [b,B]rain)", "BigBrain",
+            sub("([a-z])([A-Z])", r"\g<1> \g<2>", self.feature_type.__name__)
+        )
         groupby = ', '.join([
-            f"{v} {k}" for k, v in self._compounding_attributes.items()
+            f"{k}: {v}"
+            for k, v in self._compounding_attributes.items()
+            if k != 'modality'
         ])
-        return (
-            f"{self.__class__.__name__} of {len(self)} "
-            f"{self.feature_type.__name__} features grouped by ({groupby})"
-            f" anchored at {self.anchor}"
-        )
+        cf_name = f"{len(self)} {readable_feature_type} features{f' {groupby}' if groupby else ''}"
+        return cf_name if not self._prerelease else f"[PRERELEASE] {cf_name}"
 
     @property
     def id(self) -> str:
+        if self._prerelease:
+            name_ = self.name.replace("[PRERELEASE] ", "")
+        else:
+            name_ = self.name
         return "::".join((
             "cf0",
             f"{self._feature_type.__name__}",
             self._encode_concept(self._queryconcept),
             self.datasets[0].id if self.datasets else "nodsid",
-            md5(self.name.encode("utf-8")).hexdigest()
+            md5(name_.encode("utf-8")).hexdigest()
         ))
 
     def __iter__(self) -> Iterator['Feature']:
@@ -775,7 +884,7 @@ class CompoundFeature(Feature):
             raise IndexError(f"No feature with index '{index}' in this compound.")
 
     @classmethod
-    def compound(
+    def _compound(
         cls,
         features: List['Feature'],
         queryconcept: Union[region.Region, parcellation.Parcellation, space.Space]
@@ -834,7 +943,7 @@ class CompoundFeature(Feature):
         assert cf_version == "cf0"
         candidates = [
             f
-            for f in Feature.match(
+            for f in Feature._match(
                 concept=cls._decode_concept(queryconcept),
                 feature_type=clsname
             )
@@ -849,8 +958,8 @@ class CompoundFeature(Feature):
         else:
             raise ParseCompoundFeatureIdException
 
-    def _export(self, fh: ZipFile):
-        super()._export(fh)
+    def _to_zip(self, fh: ZipFile):
+        super()._to_zip(fh)
         for idx, element in siibra_tqdm(self._elements.items(), desc="Exporting elements", unit="element"):
             if '/' in str(idx):
                 logger.warning(f"'/' will be replaced with ' ' of the file for element with index {idx}")

siibra/features/image/__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");