siibra 1.0a14__py3-none-any.whl → 1.0.1a0__py3-none-any.whl

siibra/core/region.py

@@ -1,4 +1,4 @@
-# Copyright 2018-2023
+# Copyright 2018-2024
 # Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
 
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -18,30 +18,26 @@ from . import concept, structure, space as _space, parcellation as _parcellation
 from .assignment import Qualification, AnatomicalAssignment
 
 from ..retrieval.cache import cache_user_fn
-from ..locations import location, point, pointset
+from ..locations import location, pointcloud, boundingbox as _boundingbox
 from ..volumes import parcellationmap, volume
 from ..commons import (
     logger,
     MapType,
-    affine_scaling,
     create_key,
     clear_name,
     InstanceTable,
-    SIIBRA_DEFAULT_MAPTYPE,
-    SIIBRA_DEFAULT_MAP_THRESHOLD
 )
 from ..exceptions import NoMapAvailableError, SpaceWarpingFailedError
 
-import numpy as np
 import re
 import anytree
 from typing import List, Union, Iterable, Dict, Callable, Tuple
 from difflib import SequenceMatcher
-from dataclasses import dataclass, field
 from ebrains_drive import BucketApiClient
 import json
 from functools import wraps, reduce
 from concurrent.futures import ThreadPoolExecutor
+from functools import lru_cache
 
 
 REGEX_TYPE = type(re.compile("test"))
@@ -49,19 +45,6 @@ REGEX_TYPE = type(re.compile("test"))
 THRESHOLD_STATISTICAL_MAPS = None
 
 
-@dataclass
-class SpatialPropCmpt:
-    centroid: point.Point
-    volume: int
-
-
-@dataclass
-class SpatialProp:
-    cog: SpatialPropCmpt = None
-    components: List[SpatialPropCmpt] = field(default_factory=list)
-    space: _space.Space = None
-
-
 class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
     """
     Representation of a region with name and more optional attributes
@@ -85,6 +68,7 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
         datasets: list = [],
         rgb: str = None,
         spec=None,
+        prerelease: bool = False,
     ):
         """
         Constructs a new Region object.
@@ -122,7 +106,8 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
             modality=modality,
             publications=publications,
             datasets=datasets,
-            spec=spec
+            spec=spec,
+            prerelease=prerelease,
         )
 
         # anytree node will take care to use this appropriately
@@ -135,7 +120,7 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
         )
         self._supported_spaces = None  # computed on 1st call of self.supported_spaces
         self._str_aliases = None
-        self._CACHED_REGION_SEARCHES = {}
+        self.find = lru_cache(maxsize=3)(self.find)
 
     def get_related_regions(self) -> Iterable["RegionRelationAssessments"]:
         """
@@ -278,7 +263,7 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
 
         Parameters
         ----------
-        regionspec: str, regex, int, Region
+        regionspec: str, regex, Region
             - a string with a possibly inexact name (matched both against the name and the identifier key)
             - a string in '/pattern/flags' format to use regex search (acceptable flags: aiLmsux, see at https://docs.python.org/3/library/re.html#flags)
             - a regex applied to region names
@@ -299,11 +284,6 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
         ---
         See example 01-003, find regions.
         """
-        key = (regionspec, filter_children, find_topmost)
-        MEM = self._CACHED_REGION_SEARCHES
-        if key in MEM:
-            return MEM[key]
-
         if isinstance(regionspec, str):
             # convert the specified string into a regex for matching
             regex_match = self._regex_re.match(regionspec)
@@ -365,7 +345,7 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
         found_regions = sorted(set(candidates), key=lambda r: r.depth)
 
         # reverse is set to True, since SequenceMatcher().ratio(), higher == better
-        MEM[key] = (
+        return (
             sorted(
                 found_regions,
                 reverse=True,
@@ -374,8 +354,6 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
             if isinstance(regionspec, str) else found_regions
         )
 
-        return MEM[key]
-
     def matches(self, regionspec):
         """
         Checks whether this region matches the given region specification.
@@ -435,15 +413,14 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
 
         return self._CACHED_MATCHES[regionspec]
 
-    def get_regional_map(
+    def get_regional_mask(
         self,
         space: Union[str, _space.Space],
-        maptype: MapType = SIIBRA_DEFAULT_MAPTYPE,
-        threshold: float = SIIBRA_DEFAULT_MAP_THRESHOLD,
-        via_space: Union[str, _space.Space] = None
-    ) -> volume.Volume:
+        maptype: MapType = MapType.LABELLED,
+        threshold: float = 0.0,
+    ) -> volume.FilteredVolume:
         """
-        Attempts to build a binary mask of this region in the given space,
+        Get a binary mask of this region in the given space,
         using the specified MapTypes.
 
         Parameters
@@ -452,106 +429,98 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
             The requested reference space
         maptype: MapType, default: SIIBRA_DEFAULT_MAPTYPE
             The type of map to be used ('labelled' or 'statistical')
-        threshold: float, optional
+        threshold: float, default: 0.0
             When fetching a statistical map, use this threshold to convert
-            it to a binary mask
-        via_space: Space or str
-            If specified, fetch the map in this space first, and then perform
-            a linear warping from there to the requested space.
-
-            Tip
-            ---
-                You might want to use this if a map in the requested space
-                is not available.
-
-            Note
-            ----
-                This linear warping is an affine approximation of the
-                nonlinear deformation, computed from the warped corner points
-                of the bounding box (see siibra.locations.BoundingBox.estimate_affine()).
-                It does not require voxel resampling, just replaces the affine
-                matrix, but is less accurate than a full nonlinear warping,
-                which is currently not supported in siibra-python for images.
+            it to a binary mask.
+
         Returns
         -------
         Volume (use fetch() to get a NiftiImage)
         """
-        # check for a cached object
+        if isinstance(maptype, str):
+            maptype = MapType[maptype.upper()]
 
-        getmap_hash = hash(f"{self.id}{space}{maptype}{threshold}{via_space}")
-        if getmap_hash in self._GETMAP_CACHE:
-            return self._GETMAP_CACHE[getmap_hash]
+        threshold_info = "" if maptype == MapType.LABELLED else f"(threshold: {threshold}) "
+        name = f"Mask {threshold_info}of '{self.name} ({self.parcellation})' in "
+        try:
+            regional_map = self.get_regional_map(space=space, maptype=maptype)
+            if maptype == MapType.LABELLED:
+                assert threshold == 0.0, f"threshold can only be set for {MapType.STATISTICAL} maps."
+                result = regional_map
+                result._boundingbox = None
+            if maptype == MapType.STATISTICAL:
+                result = volume.FilteredVolume(
+                    parent_volume=regional_map,
+                    threshold=threshold
+                )
+                if threshold == 0.0:
+                    result._boundingbox = regional_map._boundingbox
+            name += f"'{result.space}'"
+        except NoMapAvailableError:
+            # This region is not mapped directly in any map in the registry.
+            # Try building a map from the child regions
+            if (len(self.children) > 0) and all(c.mapped_in_space(space) for c in self.children):
+                logger.info(f"{self.name} is not mapped in {space}. Merging the masks of its {len(self.children)} child regions.")
+                child_volumes = [
+                    child.get_regional_mask(space=space, maptype=maptype, threshold=threshold)
+                    for child in self.children
+                ]
+                result = volume.FilteredVolume(
+                    volume.merge(child_volumes),
+                    label=1
+                )
+                name += f"'{result.space}' (built by merging the mask {threshold_info} of its decendants)"
+        result._name = name
+        return result
 
+    def get_regional_map(
+        self,
+        space: Union[str, _space.Space],
+        maptype: MapType = MapType.LABELLED,
+    ) -> Union[volume.FilteredVolume, volume.Volume, volume.Subvolume]:
+        """
+        Get a volume reprsenting this region in the given space and MapType.
+
+        Note
+        ----
+        If a region is not mapped in any of the `Map`s in the registry, then
+        siibra will get the maps of its children recursively and merge them.
+        If no map is available this way as well, an exception is raised.
+
+        Parameters
+        ----------
+        space: Space or str
+            The requested reference space
+        maptype: MapType, default: SIIBRA_DEFAULT_MAPTYPE
+            The type of map to be used ('labelled' or 'statistical')
+
+        Returns
+        -------
+        Volume (use fetch() to get a NiftiImage)
+        """
         if isinstance(maptype, str):
             maptype = MapType[maptype.upper()]
 
-        # prepare space instances
+        # prepare space instance
         if isinstance(space, str):
             space = _space.Space.get_instance(space)
-        fetch_space = space if via_space is None else via_space
-        if isinstance(fetch_space, str):
-            fetch_space = _space.Space.get_instance(fetch_space)
-
-        result = None  # try to replace this with the actual regionmap volume
 
         # see if we find a map supporting the requested region
         for m in parcellationmap.Map.registry():
             if (
-                m.space.matches(fetch_space)
+                m.space.matches(space)
                 and m.parcellation == self.parcellation
                 and m.provides_image
                 and m.maptype == maptype
                 and self.name in m.regions
             ):
-                region_img = m.fetch(region=self, format='image')
-                imgdata = np.asanyarray(region_img.dataobj)
-                if maptype == MapType.STATISTICAL:  # compute thresholded statistical map, default is 0.0
-                    logger.info(f"Thresholding statistical map at {threshold}")
-                    imgdata = (imgdata > threshold).astype('uint8')
-                    name = f"Statistical mask of {self} on {fetch_space}{f' thresholded by {threshold}' if threshold else ''}"
-                else:  # compute region mask from labelled parcellation map
-                    name = f"Mask of {self} in {m.parcellation} on {fetch_space}"
-                result = volume.from_array(
-                    data=imgdata,
-                    affine=region_img.affine,
-                    space=fetch_space,
-                    name=name,
-                )
-            if result is not None:
-                break
-
-        if result is None:
-            # No region map available. Then see if we can build a map from the child regions
-            if (len(self.children) > 0) and all(c.mapped_in_space(fetch_space) for c in self.children):
-                logger.debug(f"Building regional map of {self.name} in {self.parcellation} from {len(self.children)} child regions.")
-                child_volumes = [
-                    child.get_regional_map(fetch_space, maptype, threshold, via_space)
-                    for child in self.children
-                ]
-                result = volume.merge(child_volumes)
-                result._name = f"Subtree {'mask' if maptype == MapType.LABELLED else 'statistical map of'} built from {self.name}"
-
-        if result is None:
-            raise NoMapAvailableError(f"Cannot build region map for {self.name} from {str(maptype)} maps in {fetch_space}")
-
-        if via_space is not None:
-            # the map volume is taken from an intermediary reference space
-            # provided by 'via_space'. Now transform the affine to match the
-            # desired target space.
-            intermediary_result = result
-            transform = intermediary_result.get_boundingbox(clip=True, background=0.0).estimate_affine(space)
-            result = volume.from_array(
-                imgdata,
-                np.dot(transform, region_img.affine),
-                space,
-                f"{result.name} fetched from {fetch_space} and linearly corrected to match {space}"
+                return m.get_volume(region=self)
+        else:
+            raise NoMapAvailableError(
+                f"{self.name} is not mapped in {space} as a {str(maptype)} map."
+                " Please try getting the children or getting the mask."
             )
 
-        while len(self._GETMAP_CACHE) > self._GETMAP_CACHE_MAX_ENTRIES:
-            self._GETMAP_CACHE.pop(next(iter(self._GETMAP_CACHE)))
-        self._GETMAP_CACHE[getmap_hash] = result
-        return result
-
     def mapped_in_space(self, space, recurse: bool = True) -> bool:
         """
         Verifies wether this region is defined by an explicit map in the given space.
@@ -611,7 +580,7 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
             return len(self.find(other)) > 0
         else:
             try:
-                regionmap = self.get_regional_map(space=other.space)
+                regionmap = self.get_regional_mask(space=other.space)
                 return regionmap.__contains__(other)
             except NoMapAvailableError:
                 return False
@@ -640,23 +609,35 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
                 return None
             return self._ASSIGNMENT_CACHE[other, self].invert()
 
-        if isinstance(other, location.Location):
+        if isinstance(other, (location.Location, volume.Volume)):
             if self.mapped_in_space(other.space):
-                regionmap = self.get_regional_map(other.space)
+                regionmap = self.get_regional_mask(other.space)
                 self._ASSIGNMENT_CACHE[self, other] = regionmap.assign(other)
                 return self._ASSIGNMENT_CACHE[self, other]
 
+            if isinstance(other, _boundingbox.BoundingBox):  # volume.intersection(bbox) gets boundingbox anyway
+                try:
+                    regionbbox_otherspace = self.get_boundingbox(other.space, restrict_space=False)
+                    if regionbbox_otherspace is not None:
+                        self._ASSIGNMENT_CACHE[self, other] = regionbbox_otherspace.assign(other)
+                        return self._ASSIGNMENT_CACHE[self, other]
+                except Exception as e:
+                    logger.debug(e)
+
             assignment_result = None
-            for space in self.supported_spaces:
+            for targetspace in self.supported_spaces:
                 try:
-                    other_warped = other.warp(space)
-                    regionmap = self.get_regional_map(space)
+                    other_warped = other.warp(targetspace)
+                    regionmap = self.get_regional_mask(targetspace)
                     assignment_result = regionmap.assign(other_warped)
                 except SpaceWarpingFailedError:
                     try:
-                        regionbbox_warped = self.get_boundingbox(
-                            space, restrict_space=True
-                        ).warp(other.space)
+                        regionbbox_targetspace = self.get_boundingbox(
+                            targetspace, restrict_space=True
+                        )
+                        if regionbbox_targetspace is None:
+                            continue
+                        regionbbox_warped = regionbbox_targetspace.warp(other.space)
                     except SpaceWarpingFailedError:
                         continue
                     assignment_result = regionbbox_warped.assign(other)
@@ -697,10 +678,10 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
         self,
         space: _space.Space,
         maptype: MapType = MapType.LABELLED,
-        threshold_statistical=None,
-        restrict_space=False,
+        threshold_statistical: float = 0.0,
+        restrict_space: bool = True,
         **fetch_kwargs
-    ):
+    ) -> Union[_boundingbox.BoundingBox, None]:
         """
         Compute the bounding box of this region in the given space.
 
@@ -712,9 +693,9 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
             Type of map to build ('labelled' will result in a binary mask,
             'statistical' attempts to build a statistical mask, possibly by
             elementwise maximum of statistical maps of children)
-        threshold_statistical: float, or None
-            if not None, masks will be preferably constructed by thresholding
-            statistical maps with the given value.
+        threshold_statistical: float, default: 0.0
+            When masking a statistical map, use this threshold to convert
+            it to a binary mask before finding its bounding box.
         restrict_space: bool, default: False
             If True, it will not try to fetch maps from other spaces and warp
             its boundingbox to requested space.
@@ -725,16 +706,20 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
         """
         spaceobj = _space.Space.get_instance(space)
         try:
-            mask = self.get_regional_map(
+            mask = self.get_regional_mask(
                 spaceobj, maptype=maptype, threshold=threshold_statistical
             )
-            return mask.get_boundingbox(clip=True, background=0.0, **fetch_kwargs)
+            return mask.get_boundingbox(
+                clip=True,
+                background=0.0,
+                **fetch_kwargs
+            )
         except (RuntimeError, ValueError):
             if restrict_space:
                 return None
             for other_space in self.parcellation.spaces - spaceobj:
                 try:
-                    mask = self.get_regional_map(
+                    mask = self.get_regional_mask(
                         other_space,
                         maptype=maptype,
                         threshold=threshold_statistical,
@@ -745,7 +730,7 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
                             bbox_warped = bbox.warp(spaceobj)
                         except SpaceWarpingFailedError:
                             continue
-                        logger.warning(
+                        logger.debug(
                             f"No bounding box for {self.name} defined in {spaceobj.name}, "
                             f"warped the bounding box from {other_space.name} instead."
                         )
@@ -755,7 +740,14 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
         logger.error(f"Could not compute bounding box for {self.name}.")
         return None
 
-    def compute_centroids(self, space: _space.Space) -> pointset.PointSet:
+    def compute_centroids(
+        self,
+        space: _space.Space,
+        maptype: MapType = MapType.LABELLED,
+        threshold_statistical: float = 0.0,
+        split_components: bool = True,
+        **fetch_kwargs,
+    ) -> pointcloud.PointCloud:
         """
         Compute the centroids of the region in the given space.
 
@@ -763,20 +755,33 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
         ----------
         space: Space
             reference space in which the computation will be performed
+        maptype: MapType, default: MapType.LABELLED
+            Type of map to build ('labelled' will result in a binary mask,
+            'statistical' attempts to build a statistical mask, possibly by
+            elementwise maximum of statistical maps of children)
+        threshold_statistical: float, default: 0.0
+            When masking a statistical map, use this threshold to convert
+            it to a binary mask before finding its centroids.
 
         Returns
         -------
-        PointSet
-            Found centroids (as Point objects) in a PointSet
+        PointCloud
+            Found centroids (as Point objects) in a PointCloud
 
         Note
         ----
         A region can generally have multiple centroids if it has multiple
         connected components in the map.
         """
-        props = self.spatial_props(space)
-        return pointset.PointSet(
-            [c.centroid for c in props.components],
+        props = self.spatial_props(
+            space=space,
+            maptype=maptype,
+            threshold_statistical=threshold_statistical,
+            split_components=split_components,
+            **fetch_kwargs,
+        )
+        return pointcloud.PointCloud(
+            [c.centroid for c in props],
             space=space
         )
 
@@ -784,13 +789,13 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
         self,
         space: _space.Space,
         maptype: MapType = MapType.LABELLED,
-        threshold_statistical=None,
-    ) -> SpatialProp:
+        threshold_statistical: float = 0.0,
+        split_components: bool = True,
+        **fetch_kwargs,
+    ):
         """
         Compute spatial properties for connected components of this region in the given space.
 
-        TODO: this should go to the Volume class and just be called from here.
-
         Parameters
         ----------
         space: Space
@@ -799,58 +804,33 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
             Type of map to build ('labelled' will result in a binary mask,
             'statistical' attempts to build a statistical mask, possibly by
             elementwise maximum of statistical maps of children)
-        threshold_statistical: float, or None
+        threshold_statistical: float, default: 0.0
             if not None, masks will be preferably constructed by thresholding
             statistical maps with the given value.
 
         Returns
         -------
-        Dict
-            Dictionary of region's spatial properties
+        List
+            List of region's component spatial properties
         """
-        from skimage import measure
-
         if not isinstance(space, _space.Space):
             space = _space.Space.get_instance(space)
 
-        result = SpatialProp(space=space)
-
-        if not self.mapped_in_space(space):
-            logger.warning(
+        # build binary mask of the image
+        try:
+            region_vol = self.get_regional_mask(
+                space, maptype=maptype, threshold=threshold_statistical
+            )
+        except NoMapAvailableError:
+            raise ValueError(
                 f"Spatial properties of {self.name} cannot be computed in {space.name}. "
                 "This region is only mapped in these spaces: "
                 f"{', '.join(s.name for s in self.supported_spaces)}"
             )
-            return result
-
-        # build binary mask of the image
-        pimg = self.get_regional_map(
-            space, maptype=maptype, threshold=threshold_statistical
-        ).fetch()
-
-        # determine scaling factor from voxels to cube mm
-        scale = affine_scaling(pimg.affine)
-
-        # compute properties of labelled volume
-        A = np.asarray(pimg.get_fdata(), dtype=np.int32).squeeze()
-        C = measure.label(A)
-
-        # compute spatial properties of each connected component
-        for label in range(1, C.max() + 1):
-            nonzero = np.c_[np.nonzero(C == label)]
-            result.components.append(
-                SpatialPropCmpt(
-                    centroid=point.Point(
-                        np.dot(pimg.affine, np.r_[nonzero.mean(0), 1])[:3], space=space
-                    ),
-                    volume=nonzero.shape[0] * scale,
-                )
-            )
-
-        # sort by volume
-        result.components.sort(key=lambda cmp: cmp.volume, reverse=True)
 
-        return result
+        return region_vol.compute_spatial_props(
+            split_components=split_components, **fetch_kwargs
+        )
 
     def __iter__(self):
         """
@@ -864,7 +844,7 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
 
         if self.supports_space(other.space):
             try:
-                volume = self.get_regional_map(other.space)
+                volume = self.get_regional_mask(other.space)
                 if volume is not None:
                     return volume.intersection(other)
             except NotImplementedError:
@@ -874,7 +854,7 @@ class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
         for space in self.supported_spaces:
             if space.provides_image:
                 try:
-                    volume = self.get_regional_map(space)
+                    volume = self.get_regional_mask(space)
                     if volume is not None:
                         intersection = volume.intersection(other)
                         logger.info(f"Warped {other} to {space} to find the intersection.")

siibra/core/space.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");
@@ -38,6 +38,7 @@ class Space(AtlasConcept, configuration_folder="spaces"):
         modality: str = "",
         publications: list = [],
         datasets: list = [],
+        prerelease: bool = False,
     ):
         """
         Constructs a new parcellation object.
@@ -75,6 +76,7 @@ class Space(AtlasConcept, configuration_folder="spaces"):
             modality=modality,
             publications=publications,
             datasets=datasets,
+            prerelease=prerelease,
         )
         self.volumes = volumes
         for v in self.volumes:

siibra/core/structure.py

@@ -1,5 +1,4 @@
-
-# Copyright 2018-2023
+# Copyright 2018-2024
 # Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
 
 # Licensed under the Apache License, Version 2.0 (the "License");

siibra/exceptions.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");
@@ -45,3 +45,19 @@ class NoVolumeFound(RuntimeError):
 
 class WarmupRegException(Exception):
     pass
+
+
+class ZeroVolumeBoundingBox(Exception):
+    pass
+
+
+class NoneCoordinateSuppliedError(ValueError):
+    pass
+
+
+class NoMapMatchingValues(ValueError):
+    pass
+
+
+class EmptyPointCloudError(ValueError):
+    pass