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

siibra/features/feature.py

@@ -15,12 +15,11 @@
 
 from . import anchor as _anchor
 
-from ..commons import logger, InstanceTable
+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
-from tqdm import tqdm
+from typing import Union, TYPE_CHECKING, List, Dict, Type, Tuple
 from hashlib import md5
 from collections import defaultdict
 
@@ -29,6 +28,18 @@ if TYPE_CHECKING:
     TypeDataset = EbrainsDataset
 
 
+class ParseLiveQueryIdException(Exception):
+    pass
+
+
+class EncodeLiveQueryIdException(Exception):
+    pass
+
+
+class NotFoundException(Exception):
+    pass
+
+
 class Feature:
     """
     Base class for anatomically anchored data features.
@@ -37,7 +48,7 @@ class Feature:
     SUBCLASSES: Dict[Type['Feature'], List[Type['Feature']]] = defaultdict(list)
 
     CATEGORIZED: Dict[str, Type['InstanceTable']] = defaultdict(InstanceTable)
-    
+
     category: str = None
 
     def __init__(
@@ -166,6 +177,121 @@ class Feature:
             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']:
         """
@@ -181,22 +307,17 @@ class Feature:
         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 sum((cls.match(concept, t, **kwargs) 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 = [
-                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
-            ]
+            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 [feat for c in candidates for feat in cls.match(concept, c, **kwargs)]
+            return list({feat for c in candidates for feat in cls.match(concept, c, **kwargs)})
 
         assert issubclass(feature_type, Feature)
 
@@ -213,24 +334,30 @@ class Feature:
             for instance in f_type.get_instances()
         ]
 
-        if logger.getEffectiveLevel() > 20:
-            preconfigured_instances = [f for f in instances if f.matches(concept)]
-        else:
-            preconfigured_instances = [f for f in tqdm(instances, desc=msg, total=len(instances)) if f.matches(concept)]
+        preconfigured_instances = [f for f in siibra_tqdm(instances, desc=msg, total=len(instances)) if f.matches(concept)]
 
-        live_instances = []
-        if hasattr(feature_type, "_live_queries"):
-            for QueryType in feature_type._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)
-                live_instances.extend(q.query(concept))
-
-        return preconfigured_instances + live_instances
+        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):
@@ -254,3 +381,40 @@ class Feature:
             "%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/features/image/__init__.py

@@ -18,5 +18,5 @@ from .volume_of_interest import (
     BlockfaceVolumeOfInterest,
     PLIVolumeOfInterest,
     MRIVolumeOfInterest,
-    SegmentedVolumeOfInterest
+    # SegmentedVolumeOfInterest
 )

siibra/features/image/image.py

@@ -74,6 +74,7 @@ class Image(feature.Feature, _volume.Volume):
             space_spec=space_spec,
             providers=providers,
             name=name,
+            datasets=datasets,
         )
 
         self._anchor_cached = ImageAnchor(self, region=region)

siibra/features/image/volume_of_interest.py

@@ -52,10 +52,19 @@ class MRIVolumeOfInterest(
         image.Image.__init__(self, **kwargs, modality=modality)
 
 
-class SegmentedVolumeOfInterest(
+class XPCTVolumeOfInterest(
     image.Image,
-    configuration_folder="features/images/vois/segmentation",
-    category="segmentation"
+    configuration_folder="features/images/vois/xpct",
+    category="cellular"
 ):
-    def __init__(self, **kwargs):
-        image.Image.__init__(self, **kwargs, modality="segmentation")
+    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/tabular/__init__.py

@@ -20,3 +20,5 @@ from .layerwise_bigbrain_intensities import 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/tabular/regional_timeseries_activity.py

@@ -0,0 +1,213 @@
+# 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 tabular
+
+from .. import anchor as _anchor
+
+from ...commons import logger, QUIET, siibra_tqdm
+from ...core import region as _region
+from ...locations import pointset
+from ...retrieval.repositories import RepositoryConnector
+
+from typing import Callable, Dict, Union
+import pandas as pd
+import numpy as np
+
+
+class RegionalTimeseriesActivity(tabular.Tabular):
+    """
+    Datasets that provide regional activity over time.
+    """
+
+    DESCRIPTION = (
+        ""
+    )
+
+    def __init__(
+        self,
+        cohort: str,
+        modality: str,
+        regions: list,
+        connector: RepositoryConnector,
+        decode_func: Callable,
+        files: Dict[str, str],
+        anchor: _anchor.AnatomicalAnchor,
+        timestep: str,
+        description: str = "",
+        datasets: list = [],
+        paradigm: str = ""
+    ):
+        """
+        """
+        tabular.Tabular.__init__(
+            self,
+            modality=modality,
+            description=description,
+            anchor=anchor,
+            datasets=datasets,
+            data=None  # lazy loading below
+        )
+        self.cohort = cohort.upper()
+        self._connector = connector
+        self._files = files
+        self._decode_func = decode_func
+        self.regions = regions
+        self._tables = {}
+        self.paradigm = paradigm
+        self.timestep = timestep
+
+    @property
+    def subjects(self):
+        """
+        Returns the subject identifiers for which signal tables are available.
+        """
+        return list(self._files.keys())
+
+    @property
+    def name(self):
+        supername = super().name
+        return f"{supername} with paradigm {self.paradigm}"
+
+    def get_table(self, subject: str = None):
+        """
+        Returns a pandas dataframe where the column headers are regions and the
+        indcies indicate disctrete timesteps.
+
+        Parameters
+        ----------
+        subject: str, default: None
+            Name of the subject (see RegionalTimeseriesActivity.subjects for available names).
+            If None, the mean is taken in case of multiple available data tables.
+        Returns
+        -------
+        pd.DataFrame
+            A table with region names as the column and timesteps as indices.
+        """
+        assert len(self) > 0
+        if (subject is None) and (len(self) > 1):
+            # multiple signal tables available, but no subject given - return mean table
+            logger.info(
+                f"No subject name supplied, returning mean signal table across {len(self)} subjects. "
+                "You might alternatively specify an individual subject."
+            )
+            if "mean" not in self._tables:
+                all_arrays = [
+                    self._connector.get(fname, decode_func=self._decode_func)
+                    for fname in siibra_tqdm(
+                        self._files.values(),
+                        total=len(self),
+                        desc=f"Averaging {len(self)} signal tables"
+                    )
+                ]
+                self._tables['mean'] = self._array_to_dataframe(np.stack(all_arrays).mean(0))
+            return self._tables['mean'].copy()
+        if subject is None:
+            subject = next(iter(self._files.keys()))
+        if subject not in self._files:
+            raise ValueError(f"Subject name '{subject}' not known, use one of: {', '.join(self._files)}")
+        if subject not in self._tables:
+            self._tables[subject] = self._load_table(subject)
+        return self._tables[subject].copy()
+
+    def _load_table(self, subject: str):
+        """
+        Extract the timeseries table.
+        """
+        assert subject in self.subjects
+        array = self._connector.get(self._files[subject], decode_func=self._decode_func)
+        return self._array_to_dataframe(array)
+
+    def __len__(self):
+        return len(self._files)
+
+    def __str__(self):
+        return "{} with paradigm {} for {} from {} cohort ({} signal tables)".format(
+            self.modality, self.paradigm,
+            "_".join(p.name for p in self.anchor.parcellations),
+            self.cohort,
+            len(self._files),
+        )
+
+    def compute_centroids(self, space):
+        """
+        Computes the list of centroid coordinates corresponding to
+        dataframe columns, in the given reference space.
+
+        Parameters
+        ----------
+        space: Space, str
+
+        Returns
+        -------
+        list[tuple(float, float, float)]
+        """
+        result = []
+        parcellations = self.anchor.represented_parcellations()
+        assert len(parcellations) == 1
+        parcmap = next(iter(parcellations)).get_map(space)
+        all_centroids = parcmap.compute_centroids()
+        for regionname in self.regions:
+            region = parcmap.parcellation.get_region(regionname, allow_tuple=True)
+            if isinstance(region, tuple):  # deal with sets of matched regions
+                found = [c for r in region for c in r if c.name in all_centroids]
+            else:
+                found = [r for r in region if r.name in all_centroids]
+            assert len(found) > 0
+            result.append(
+                tuple(pointset.PointSet(
+                    [all_centroids[r.name] for r in found], space=space
+                ).centroid)
+            )
+        return result
+
+    def _array_to_dataframe(self, array: np.ndarray) -> pd.DataFrame:
+        """
+        Convert a numpy array with the regional activity data to
+        a DataFrame with regions as column headers and timesteps as indices.
+        """
+        df = pd.DataFrame(array)
+        parcellations = self.anchor.represented_parcellations()
+        assert len(parcellations) == 1
+        parc = next(iter(parcellations))
+        with QUIET:
+            indexmap = {
+                i: parc.get_region(regionname, allow_tuple=True)
+                for i, regionname in enumerate(self.regions)
+            }
+        ncols = array.shape[1]
+        if len(indexmap) == ncols:
+            remapper = {
+                label - min(indexmap.keys()): region
+                for label, region in indexmap.items()
+            }
+            df = df.rename(columns=remapper)
+        return df
+
+    def plot(self, subject: str = None, **kwargs):
+        table = self.get_table(subject)
+        return table.mean().plot(kind="bar", **kwargs)
+
+
+class RegionalBOLD(
+    RegionalTimeseriesActivity,
+    configuration_folder="features/tabular/activity_timeseries/bold",
+    category="activity_timeseries"
+):
+    """
+    Blood-oxygen-level-dependent (BOLD) signals per region.
+    """
+
+    pass

siibra/livequeries/ebrains.py

@@ -16,7 +16,7 @@
 from ..features.dataset import ebrains as _ebrains
 from . import query
 
-from ..commons import logger
+from ..commons import logger, siibra_tqdm
 from ..features import anchor as _anchor
 from ..retrieval import requests, datasets
 from ..core import parcellation, region
@@ -24,7 +24,6 @@ from ..core import parcellation, region
 from collections import defaultdict
 import re
 from distutils.version import LooseVersion
-from tqdm import tqdm
 from tempfile import NamedTemporaryFile
 
 
@@ -70,7 +69,7 @@ class EbrainsFeatureQuery(query.LiveQuery, args=[], FeatureType=_ebrains.Ebrains
         invalid_species_datasets = {}
         results = self.loader.data.get("results", [])
 
-        for r in tqdm(results, total=len(results)):
+        for r in siibra_tqdm(results, total=len(results)):
 
             regionname = r.get("name", None)
             alias = r.get("alias", None)

siibra/locations/location.py

@@ -17,6 +17,7 @@
 import numpy as np
 from abc import ABC, abstractmethod
 from nibabel import Nifti1Image
+from typing import Union
 
 
 class Location(ABC):
@@ -48,14 +49,14 @@ class Location(ABC):
         pass
 
     @abstractmethod
-    def intersects(self, mask: Nifti1Image):
+    def intersects(self, other: Union[Nifti1Image, 'Location']) -> bool:
         """
         Verifies wether this 3D location intersects the given mask.
 
         NOTE: The affine matrix of the image must be set to warp voxels
         coordinates into the reference space of this Bounding Box.
         """
-        pass
+        raise NotImplementedError
 
     @abstractmethod
     def warp(self, space):
@@ -114,7 +115,7 @@ class WholeBrain(Location):
     def __init__(self, space=None):
         Location.__init__(self, space)
 
-    def intersects(self, mask: Nifti1Image):
+    def intersects(self, *_args, **_kwargs):
         """Always true for whole brain features"""
         return True
 

siibra/locations/pointset.py

@@ -74,8 +74,8 @@ class PointSet(location.Location):
                 sigma_mm=[p.sigma for p in inside],
             )
 
-    def intersects(self, mask: Nifti1Image):
-        return len(self.intersection(mask)) > 0
+    def intersects(self, other: Union[location.Location, Nifti1Image]):
+        return len(self.intersection(other)) > 0
 
     @property
     def sigma(self):