siibra 0.4a33__py3-none-any.whl → 0.4a46__py3-none-any.whl

siibra/features/feature.py

@@ -0,0 +1,420 @@
+# Copyright 2018-2021
+# Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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.
+
+from . import anchor as _anchor
+
+from ..commons import logger, InstanceTable, siibra_tqdm
+from ..core import concept
+from ..core import space, region, parcellation
+
+from typing import Union, TYPE_CHECKING, List, Dict, Type, Tuple
+from hashlib import md5
+from collections import defaultdict
+
+if TYPE_CHECKING:
+    from ..retrieval.datasets import EbrainsDataset
+    TypeDataset = EbrainsDataset
+
+
+class ParseLiveQueryIdException(Exception):
+    pass
+
+
+class EncodeLiveQueryIdException(Exception):
+    pass
+
+
+class NotFoundException(Exception):
+    pass
+
+
+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)
+
+    category: str = None
+
+    def __init__(
+        self,
+        modality: str,
+        description: str,
+        anchor: _anchor.AnatomicalAnchor,
+        datasets: List['TypeDataset'] = []
+    ):
+        """
+        Parameters
+        ----------
+        modality: str
+            A textual description of the type of measured information
+        description: str
+            A textual description of the feature.
+        anchor: AnatomicalAnchor
+        datasets : list
+            list of datasets corresponding to this feature
+        """
+        self._modality_cached = modality
+        self._description = description
+        self._anchor_cached = anchor
+        self.datasets = datasets
+
+    @property
+    def modality(self):
+        # allows subclasses to implement lazy loading of the modality
+        return self._modality_cached
+
+    @property
+    def anchor(self):
+        # allows subclasses to implement lazy loading of an anchor
+        return self._anchor_cached
+
+    def __init_subclass__(cls, configuration_folder=None, category=None):
+        # extend the subclass lists
+
+        # Iterate over all mro, not just immediate base classes
+        for BaseCls in cls.__mro__:
+            # some base classes may not be sub class of feature, ignore these
+            if not issubclass(BaseCls, Feature):
+                continue
+            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)
+        return super().__init_subclass__()
+
+    @classmethod
+    def _get_subclasses(cls):
+        return {Cls.__name__: Cls for Cls in cls.SUBCLASSES}
+
+    @property
+    def description(self):
+        """ Allowssubclasses to overwrite the description with a function call. """
+        return self._description
+
+    @property
+    def name(self):
+        """Returns a short human-readable name of this feature."""
+        return f"{self.__class__.__name__} ({self.modality}) anchored at {self.anchor}"
+
+    @classmethod
+    def get_instances(cls, **kwargs) -> List['Feature']:
+        """
+        Retrieve objects of a particular feature subclass.
+        Objects can be preconfigured in the configuration,
+        or delivered by Live queries.
+        """
+        if not hasattr(cls, "_preconfigured_instances"):
+            return []
+
+        if cls._preconfigured_instances is not None:
+            return cls._preconfigured_instances
+
+        if cls._configuration_folder is None:
+            cls._preconfigured_instances = []
+            return cls._preconfigured_instances
+
+        from ..configuration.configuration import Configuration
+        conf = Configuration()
+        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)
+            if isinstance(o, cls)
+        ]
+        logger.debug(
+            f"Built {len(cls._preconfigured_instances)} preconfigured {cls.__name__} "
+            f"objects from {cls._configuration_folder}."
+        )
+        return cls._preconfigured_instances
+
+    @classmethod
+    def clean_instances(cls):
+        """ Removes all instantiated object instances"""
+        cls._preconfigured_instances = None
+
+    def matches(self, concept: concept.AtlasConcept) -> bool:
+        if self.anchor and self.anchor.matches(concept):
+            self.anchor._last_matched_concept = concept
+            return True
+        self.anchor._last_matched_concept = None
+        return False
+
+    @property
+    def last_match_result(self):
+        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
+
+    @property
+    def id(self):
+        prefix = ''
+        id_set = {ds.id for ds in self.datasets if hasattr(ds, 'id')}
+        if len(id_set) == 1:
+            prefix = list(id_set)[0] + '--'
+        return prefix + md5(self.name.encode("utf-8")).hexdigest()
+
+    @staticmethod
+    def serialize_query_context(feat: 'Feature', concept: concept.AtlasConcept) -> str:
+        """
+        Serialize feature from livequery and query context. 
+
+        It is currently impossible to retrieve a livequery with a generic UUID.
+        As such, the query context (e.g. region, space or parcellation) needs to
+        be encoded in the id.
+
+        Whilst it is possible to (de)serialize *any* queries, the method is setup to only serialize
+        livequery features.
+
+        The serialized livequery id follows the following pattern:
+
+        <livequeryid_version>::<feature_cls_name>::<query_context>::<unserialized_id>
+        
+        Where:
+
+        - livequeryid_version: version of the serialization. (e.g. lq0)
+        - feature_cls_name: class name to query. (e.g. BigBrainIntensityProfile)
+        - query_context: string to retrieve atlas concept in the query context. Can be one of the following:
+            - s:<space_id>
+            - p:<parcellation_id>
+            - p:<parcellation_id>::r:<region_id>
+        - unserialized_id: id prior to serialization
+
+        See test/features/test_feature.py for tests and usages.
+        """
+        if not hasattr(feat.__class__, '_live_queries'):
+            raise EncodeLiveQueryIdException(f"generate_livequery_featureid can only be used on live queries, but {feat.__class__.__name__} is not.")
+
+        encoded_c = []
+        if isinstance(concept, space.Space):
+            encoded_c.append(f"s:{concept.id}")
+        elif isinstance(concept, parcellation.Parcellation):
+            encoded_c.append(f"p:{concept.id}")
+        elif isinstance(concept, region.Region):
+            encoded_c.append(f"p:{concept.parcellation.id}")
+            encoded_c.append(f"r:{concept.name}")
+
+        if len(encoded_c) == 0:
+            raise EncodeLiveQueryIdException("no concept is encoded")
+
+        return f"lq0::{feat.__class__.__name__}::{'::'.join(encoded_c)}::{feat.id}"
+
+    @classmethod
+    def deserialize_query_context(Cls, feature_id: str) -> Tuple[Type['Feature'], concept.AtlasConcept, str]:
+        """
+        Deserialize id into query context. 
+
+        See docstring of serialize_query_context for context.
+        """
+        lq_version, *rest = feature_id.split("::")
+        if lq_version != "lq0":
+            raise ParseLiveQueryIdException("livequery id must start with lq0::")
+
+        clsname, *concepts, fid = rest
+
+        Features = Cls.parse_featuretype(clsname)
+
+        if len(Features) == 0:
+            raise ParseLiveQueryIdException(f"classname {clsname!r} could not be parsed correctly. {feature_id!r}")
+        F = Features[0]
+
+        concept = None
+        for c in concepts:
+            if c.startswith("s:"):
+                if concept is not None:
+                    raise ParseLiveQueryIdException("Conflicting spec.")
+                concept = space.Space.registry()[c.replace("s:", "")]
+            if c.startswith("p:"):
+                if concept is not None:
+                    raise ParseLiveQueryIdException("Conflicting spec.")
+                concept = parcellation.Parcellation.registry()[c.replace("p:", "")]
+            if c.startswith("r:"):
+                if concept is None:
+                    raise ParseLiveQueryIdException("region has been encoded, but parcellation has not been populated in the encoding, {feature_id!r}")
+                if not isinstance(concept, parcellation.Parcellation):
+                    raise ParseLiveQueryIdException("region has been encoded, but previous encoded concept is not parcellation")
+                concept = concept.get_region(c.replace("r:", ""))
+        if concept is None:
+            raise ParseLiveQueryIdException(f"concept was not populated: {feature_id!r}")
+
+        return (F, concept, fid)
+
+    @classmethod
+    def parse_featuretype(cls, feature_type: str) -> List[Type['Feature']]:
+        return [
+            feattype
+            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
+        ]
+
+    @classmethod
+    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())})" \
+                if len(kwargs) > 0 else ""
+            logger.info(
+                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)
+        return live_instances
+
+    @classmethod
+    def match(cls, concept: Union[region.Region, parcellation.Parcellation, space.Space], feature_type: Union[str, Type['Feature'], list], **kwargs) -> List['Feature']:
+        """
+        Retrieve data features of the desired modality.
+
+        Parameters
+        ----------
+        concept: AtlasConcept
+            An anatomical concept, typically a brain region or parcellation.
+        modality: subclass of Feature
+            specififies the type of features ("modality")
+        """
+        if isinstance(feature_type, list):
+            # a list of feature types is given, collect match results on those
+            assert all((isinstance(t, str) or issubclass(t, cls)) for t in feature_type)
+            return list(set(sum((cls.match(concept, t, **kwargs) for t in feature_type), [])))
+
+        if isinstance(feature_type, str):
+            # feature type given as a string. Decode the corresponding class.
+            # Some string inputs, such as connectivity, may hit multiple matches
+            # In this case
+            candidates = cls.parse_featuretype(feature_type)
+            if len(candidates) == 0:
+                raise ValueError(f"feature_type {str(feature_type)} did not match with any features. Available features are: {', '.join(cls.SUBCLASSES.keys())}")
+
+            return list({feat for c in candidates for feat in cls.match(concept, c, **kwargs)})
+
+        assert issubclass(feature_type, Feature)
+
+        if not isinstance(concept, (region.Region, parcellation.Parcellation, space.Space)):
+            raise ValueError(
+                "Feature.match / siibra.features.get only accepts Region, "
+                "Space and Parcellation objects as concept."
+            )
+
+        msg = f"Matching {feature_type.__name__} to {concept}"
+        instances = [
+            instance
+            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)) if f.matches(concept)]
+
+        live_instances = feature_type.livequery(concept, **kwargs)
+
+        return list(set((preconfigured_instances + live_instances)))
+
+    @classmethod
+    def get_instance_by_id(cls, feature_id: str, **kwargs):
+        try:
+            F, concept, fid = cls.deserialize_query_context(feature_id)
+            return [
+                f
+                for f in F.livequery(concept, **kwargs)
+                if f.id == fid or f.id == feature_id
+            ][0]
+        except ParseLiveQueryIdException:
+            return [
+                inst
+                for Cls in Feature.SUBCLASSES[Feature]
+                for inst in Cls.get_instances()
+                if inst.id == feature_id
+            ][0]
+        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):
+        """
+        Wrap live query features, override only the id attribute.
+
+        Some features do not have setters for the id property. The ProxyFeature class
+        allow the id property to be overridden without touching the underlying class.
+
+        See docstring of serialize_query_context for further context.
+        """
+        class ProxyFeature(feature.__class__):
+
+            # override __class__ property
+            # some instances of features accesses inst.__class__
+            @property
+            def __class__(self):
+                return self.inst.__class__
+
+            def __init__(self, inst: Feature, fid: str):
+                self.inst = inst
+                self.fid = fid
+
+            def __str__(self) -> str:
+                return self.inst.__str__()
+
+            def __repr__(self) -> str:
+                return self.inst.__repr__()
+
+            @property
+            def id(self):
+                return self.fid
+
+            def __getattr__(self, __name: str):
+                return getattr(self.inst, __name)
+
+        return ProxyFeature(feature, fid)

siibra/{samplers → features/image}/__init__.py

@@ -13,4 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from .bigbrain import BigBrainCortexSampler
+from .volume_of_interest import (
+    CellBodyStainedVolumeOfInterest,
+    BlockfaceVolumeOfInterest,
+    PLIVolumeOfInterest,
+    MRIVolumeOfInterest,
+    # SegmentedVolumeOfInterest
+)

siibra/features/{basetypes/volume_of_interest.py → image/image.py}

@@ -13,7 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from . import feature
+from .. import feature
 
 from .. import anchor as _anchor
 
@@ -22,7 +22,7 @@ from ...volumes import volume as _volume
 from typing import List
 
 
-class VolumeOfInterestAnchor(_anchor.AnatomicalAnchor):
+class ImageAnchor(_anchor.AnatomicalAnchor):
 
     def __init__(self, volume: _volume.Volume, region: str = None):
         _anchor.AnatomicalAnchor.__init__(
@@ -35,7 +35,9 @@ class VolumeOfInterestAnchor(_anchor.AnatomicalAnchor):
 
     @property
     def location(self):
-        """ loads the bounding box only if required, since it demands image data access. """
+        """
+        Loads the bounding box only if required, since it demands image data access.
+        """
         if self._location_cached is None:
             self._location_cached = self.volume.boundingbox
         return self._location_cached
@@ -45,10 +47,10 @@ class VolumeOfInterestAnchor(_anchor.AnatomicalAnchor):
         return self.volume.space
 
     def __str__(self):
-        return "bounding box of volume"
+        return f"Bounding box of image in {self.space.name}"
 
 
-class VolumeOfInterest(feature.Feature, _volume.Volume, configuration_folder="features/volumes"):
+class Image(feature.Feature, _volume.Volume):
 
     def __init__(
         self,
@@ -66,13 +68,16 @@ class VolumeOfInterest(feature.Feature, _volume.Volume, configuration_folder="fe
             anchor=None,  # lazy implementation below!
             datasets=datasets
         )
+
         _volume.Volume.__init__(
             self,
             space_spec=space_spec,
             providers=providers,
             name=name,
+            datasets=datasets,
         )
-        self._anchor_cached = VolumeOfInterestAnchor(self, region=region)
+
+        self._anchor_cached = ImageAnchor(self, region=region)
         self._description_cached = None
         self._name_cached = name
 
@@ -87,7 +92,7 @@ class VolumeOfInterest(feature.Feature, _volume.Volume, configuration_folder="fe
     def description(self):
         if self._description_cached is None:
             self._description_cached = (
-                f"Volume of interest with modality {self.modality} "
+                f"Image feature with modality {self.modality} "
                 f"at {self.anchor}"
             )
         return self._description_cached

siibra/features/{external/__init__.py → image/sections.py}

@@ -13,10 +13,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from .ebrains import EbrainsDataFeature
+from . import image
 
 
-def __dir__():
-    return [
-        "EbrainsDataFeature",
-    ]
+class CellbodyStainedSection(
+    image.Image,
+    configuration_folder='features/images/sections/cellbody',
+    category="cellular"
+):
+    def __init__(self, **kwargs):
+        image.Image.__init__(self, **kwargs, modality="cell body staining")

siibra/features/image/volume_of_interest.py

@@ -0,0 +1,70 @@
+# Copyright 2018-2021
+# Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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.
+
+from . import image
+
+
+class CellBodyStainedVolumeOfInterest(
+    image.Image,
+    configuration_folder="features/images/vois/cellbody",
+    category="cellular"
+):
+    def __init__(self, **kwargs):
+        image.Image.__init__(self, **kwargs, modality="cell body staining")
+
+
+class BlockfaceVolumeOfInterest(
+    image.Image,
+    configuration_folder="features/images/vois/blockface",
+    category="macrostructural"
+):
+    def __init__(self, **kwargs):
+        image.Image.__init__(self, **kwargs, modality="blockface")
+
+
+class PLIVolumeOfInterest(
+    image.Image,
+    configuration_folder="features/images/vois/pli",
+    category="fibres"
+):
+    def __init__(self, modality, **kwargs):
+        image.Image.__init__(self, **kwargs, modality=modality)
+
+
+class MRIVolumeOfInterest(
+    image.Image,
+    configuration_folder="features/images/vois/mri",
+    category="macrostructural"
+):
+    def __init__(self, modality, **kwargs):
+        image.Image.__init__(self, **kwargs, modality=modality)
+
+
+class XPCTVolumeOfInterest(
+    image.Image,
+    configuration_folder="features/images/vois/xpct",
+    category="cellular"
+):
+    def __init__(self, modality, **kwargs):
+        image.Image.__init__(self, **kwargs, modality=modality)
+
+
+# class SegmentedVolumeOfInterest(
+#     image.Image,
+#     configuration_folder="features/images/vois/segmentation",
+#     category="segmentation"
+# ):
+#     def __init__(self, **kwargs):
+#         image.Image.__init__(self, **kwargs, modality="segmentation")

siibra/features/{cellular → tabular}/__init__.py

@@ -13,16 +13,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from .cell_density_profile import CellDensityProfile
-from .layerwise_cell_density import LayerwiseCellDensity
 from .bigbrain_intensity_profile import BigBrainIntensityProfile
+from .cell_density_profile import CellDensityProfile
+from .gene_expression import GeneExpressions
 from .layerwise_bigbrain_intensities import LayerwiseBigBrainIntensities
-
-
-def __dir__():
-    return [
-        "CellDensityProfile",
-        "LayerwiseCellDensity",
-        "BigBrainIntensityProfile",
-        "LayerwiseBigBrainIntensities",
-    ]
+from .layerwise_cell_density import LayerwiseCellDensity
+from .receptor_density_fingerprint import ReceptorDensityFingerprint
+from .receptor_density_profile import ReceptorDensityProfile
+from .regional_timeseries_activity  import RegionalTimeseriesActivity
+from .regional_timeseries_activity  import RegionalBOLD

siibra/features/{cellular → tabular}/bigbrain_intensity_profile.py

@@ -13,12 +13,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from ..basetypes import cortical_profile
+from . import cortical_profile
 
 from ...locations import point
 
 
-class BigBrainIntensityProfile(cortical_profile.CorticalProfile):
+class BigBrainIntensityProfile(
+    cortical_profile.CorticalProfile,
+    category='cellular'
+):
 
     DESCRIPTION = (
         "Cortical profiles of BigBrain staining intensities computed by Konrad Wagstyl, "

siibra/features/{cellular → tabular}/cell_density_profile.py

@@ -14,7 +14,7 @@
 # limitations under the License.
 
 from .. import anchor as _anchor
-from ..basetypes import cortical_profile
+from . import cortical_profile
 
 from ...commons import PolyLine, logger, create_key
 from ...retrieval import requests
@@ -26,7 +26,11 @@ import numpy as np
 import pandas as pd
 
 
-class CellDensityProfile(cortical_profile.CorticalProfile, configuration_folder="features/profiles/celldensity"):
+class CellDensityProfile(
+    cortical_profile.CorticalProfile,
+    configuration_folder="features/tabular/corticalprofiles/celldensity",
+    category='cellular'
+):
 
     DESCRIPTION = (
         "Cortical profile of estimated densities of detected cell bodies (in detected cells per 0.1 cube millimeter) "