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

siibra/core/region.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");
@@ -13,35 +13,31 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 """Representation of a brain region."""
-from . import concept, space as _space, parcellation as _parcellation
-from .relation_qualification import Qualification as RegionRelationship, RelationAssignment
 
-from ..locations import boundingbox, point, pointset
-from ..volumes import parcellationmap
+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, pointcloud, boundingbox as _boundingbox
+from ..volumes import parcellationmap, volume
 from ..commons import (
     logger,
     MapType,
-    affine_scaling,
     create_key,
     clear_name,
-    siibra_tqdm,
     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, Set, Union, Iterable, Dict, Callable
-from nibabel import Nifti1Image
+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
+from functools import wraps, reduce
 from concurrent.futures import ThreadPoolExecutor
+from functools import lru_cache
 
 
 REGEX_TYPE = type(re.compile("test"))
@@ -49,20 +45,7 @@ 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):
+class Region(anytree.NodeMixin, concept.AtlasConcept, structure.BrainStructure):
     """
     Representation of a region with name and more optional attributes
     """
@@ -70,6 +53,9 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
     _regex_re = re.compile(r'^\/(?P<expression>.+)\/(?P<flags>[a-zA-Z]*)$')
     _accepted_flags = "aiLmsux"
 
+    _GETMAP_CACHE = {}
+    _GETMAP_CACHE_MAX_ENTRIES = 1
+
     def __init__(
         self,
         name: str,
@@ -82,6 +68,7 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         datasets: list = [],
         rgb: str = None,
         spec=None,
+        prerelease: bool = False,
     ):
         """
         Constructs a new Region object.
@@ -119,7 +106,8 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
             modality=modality,
             publications=publications,
             datasets=datasets,
-            spec=spec
+            spec=spec,
+            prerelease=prerelease,
         )
 
         # anytree node will take care to use this appropriately
@@ -131,8 +119,8 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
             else tuple(int(rgb[p:p + 2], 16) for p in [1, 3, 5])
         )
         self._supported_spaces = None  # computed on 1st call of self.supported_spaces
-        self._CACHED_REGION_SEARCHES = {}
         self._str_aliases = None
+        self.find = lru_cache(maxsize=3)(self.find)
 
     def get_related_regions(self) -> Iterable["RegionRelationAssessments"]:
         """
@@ -140,11 +128,11 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
 
         Yields
         ------
-        RegionRelationAssessments
+        Qualification
 
         Example
         -------
-        >>> region = siibra.get_region("monkey", "PG")^M
+        >>> region = siibra.get_region("monkey", "PG")
         >>> for assesment in region.get_related_regions():
         >>>    print(assesment)
         'PG' is homologous to 'Area PGa (IPL)'
@@ -255,6 +243,7 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         Parameters
         ----------
         region: Region
+
         Returns
         -------
             bool
@@ -274,9 +263,9 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
 
         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)
+            - 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
             - a Region object
         filter_children : bool, default: False
@@ -285,20 +274,18 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
             If True (requires `filter_children=True`), will return parent
             structures if all children are matched, even though the parent
             itself might not match the specification.
+
         Returns
         -------
         list[Region]
             list of regions matching to the regionspec
+
         Tip
         ---
         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)
             if regex_match:
                 flags = regex_match.group('flags')
@@ -306,7 +293,7 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
 
                 for flag in flags or []:  # catch if flags is nullish
                     if flag not in self._accepted_flags:
-                        raise Exception(f"only accepted flag are in { self._accepted_flags }. {flag} is not within them")
+                        raise Exception(f"only accepted flag are in {self._accepted_flags}. {flag} is not within them")
                 search_regex = (f"(?{flags})" if flags else "") + expression
                 regionspec = re.compile(search_regex)
 
@@ -358,18 +345,15 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         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,
                 key=lambda region: SequenceMatcher(None, str(region), regionspec).ratio(),
             )
-            if type(regionspec) == str
-            else found_regions
+            if isinstance(regionspec, str) else found_regions
         )
 
-        return MEM[key]
-
     def matches(self, regionspec):
         """
         Checks whether this region matches the given region specification.
@@ -386,53 +370,57 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         bool
             If the regionspec matches to the Region.
         """
-        if regionspec is None:
-            return False
-
-        def splitstr(s):
-            return [w for w in re.split(r"[^a-zA-Z0-9.\-]", s) if len(w) > 0]
-
-        if isinstance(regionspec, Region):
-            return self == regionspec
+        if regionspec not in self._CACHED_MATCHES:
+            def splitstr(s):
+                return [w for w in re.split(r"[^a-zA-Z0-9.\-]", s) if len(w) > 0]
+
+            if regionspec is None:
+                self._CACHED_MATCHES[regionspec] = False
+
+            elif isinstance(regionspec, Region):
+                self._CACHED_MATCHES[regionspec] = self == regionspec
+
+            elif isinstance(regionspec, str):
+                # string is given, perform lazy string matching
+                q = regionspec.lower().strip()
+                if q == self.key.lower().strip():
+                    self._CACHED_MATCHES[regionspec] = True
+                elif q == self.id.lower().strip():
+                    self._CACHED_MATCHES[regionspec] = True
+                elif q == self.name.lower().strip():
+                    self._CACHED_MATCHES[regionspec] = True
+                else:
+                    # match if all words of the query are also included in the region name
+                    W = splitstr(clear_name(self.name.lower()))
+                    Q = splitstr(clear_name(regionspec))
+                    self._CACHED_MATCHES[regionspec] = all([any(
+                        q.lower() == w or 'v' + q.lower() == w
+                        for w in W
+                    ) for q in Q])
+
+            # TODO since dropping 3.6 support, maybe reimplement as re.Pattern ?
+            elif isinstance(regionspec, REGEX_TYPE):
+                # match regular expression
+                self._CACHED_MATCHES[regionspec] = any(regionspec.search(s) is not None for s in [self.name, self.key])
+
+            elif isinstance(regionspec, (list, tuple)):
+                self._CACHED_MATCHES[regionspec] = any(self.matches(_) for _ in regionspec)
 
-        elif isinstance(regionspec, str):
-            # string is given, perform lazy string matching
-            q = regionspec.lower().strip()
-            if q == self.key.lower().strip():
-                return True
-            elif q == self.id.lower().strip():
-                return True
-            elif q == self.name.lower().strip():
-                return True
             else:
-                # match if all words of the query are also included in the region name
-                W = splitstr(clear_name(self.name.lower()))
-                Q = splitstr(clear_name(regionspec))
-                return all([any(
-                    q.lower() == w or 'v' + q.lower() == w
-                    for w in W
-                ) for q in Q])
-
-        # TODO since dropping 3.6 support, maybe reimplement as re.Pattern ?
-        elif isinstance(regionspec, REGEX_TYPE):
-            # match regular expression
-            return any(regionspec.search(s) is not None for s in [self.name, self.key])
-        elif isinstance(regionspec, (list, tuple)):
-            return any(self.matches(_) for _ in regionspec)
-        else:
-            raise TypeError(
-                f"Cannot interpret region specification of type '{type(regionspec)}'"
-            )
+                raise TypeError(
+                    f"Cannot interpret region specification of type '{type(regionspec)}'"
+                )
+
+        return self._CACHED_MATCHES[regionspec]
 
-    def fetch_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
-    ):
+        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
@@ -441,100 +429,98 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
             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
         -------
-        Nifti1Image
+        Volume (use fetch() to get a NiftiImage)
         """
         if isinstance(maptype, str):
             maptype = MapType[maptype.upper()]
-        result = None
 
-        # prepare space instances
+        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 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)
 
+        # 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
             ):
-                result = m.fetch(region=self, format='image')
-                if (maptype == MapType.STATISTICAL) and (threshold is not None):
-                    logger.info(f"Thresholding statistical map at {threshold}")
-                    result = Nifti1Image(
-                        (result.get_fdata() > threshold).astype('uint8'),
-                        result.affine
-                    )
-                break
+                return m.get_volume(region=self)
         else:
-            # all children are mapped instead
-            dataobj = None
-            affine = None
-            if all(c.mapped_in_space(fetch_space) for c in self.children):
-                for c in siibra_tqdm(
-                    self.children,
-                    desc=f"Building mask of {self.name}",
-                    leave=False,
-                    unit=" child region"
-                ):
-                    mask = c.fetch_regional_map(fetch_space, maptype, threshold)
-                    if dataobj is None:
-                        dataobj = np.asanyarray(mask.dataobj)
-                        affine = mask.affine
-                    else:
-                        if np.linalg.norm(mask.affine - affine) > 1e-12:
-                            raise NotImplementedError(
-                                f"Child regions of {self.name} have different voxel spaces "
-                                "and the aggregated subtree mask is not supported. "
-                                f"Try fetching masks of the children: {self.children}"
-                            )
-                        updates = mask.get_fdata() > dataobj
-                        dataobj[updates] = mask.get_fdata()[updates]
-            if dataobj is not None:
-                result = Nifti1Image(dataobj, affine)
-
-        if result is None:
-            raise RuntimeError(f"Cannot build mask for {self.name} from {maptype} maps in {fetch_space}")
-
-        if via_space is not None:
-            # fetch used an intermediate reference space provided by 'via_space'.
-            # We will now transform the affine to match the desired target space.
-            bbox = boundingbox.BoundingBox.from_image(result, fetch_space)
-            transform = bbox.estimate_affine(space)
-            result = Nifti1Image(result.dataobj, np.dot(transform, result.affine))
-            logger.info(
-                f"Regional map was fetched from {fetch_space.name}, "
-                f"then linearly corrected to match {space.name}."
+            raise NoMapAvailableError(
+                f"{self.name} is not mapped in {space} as a {str(maptype)} map."
+                " Please try getting the children or getting the mask."
             )
 
-        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.
@@ -565,13 +551,15 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         return False
 
     @property
-    def supported_spaces(self) -> Set[_space.Space]:
+    def supported_spaces(self) -> List[_space.Space]:
         """
         The set of spaces for which a mask could be extracted.
         Overwrites the corresponding method of AtlasConcept.
         """
         if self._supported_spaces is None:
-            self._supported_spaces = {s for s in _space.Space.registry() if self.mapped_in_space(s)}
+            self._supported_spaces = sorted(
+                {s for s in _space.Space.registry() if self.mapped_in_space(s)}
+            )
         return self._supported_spaces
 
     def supports_space(self, space: _space.Space):
@@ -587,11 +575,92 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
             elements={s.key: s for s in self.supported_spaces},
         )
 
-    def __str__(self):
-        return self.name
+    def __contains__(self, other: Union[location.Location, 'Region']) -> bool:
+        if isinstance(other, Region):
+            return len(self.find(other)) > 0
+        else:
+            try:
+                regionmap = self.get_regional_mask(space=other.space)
+                return regionmap.__contains__(other)
+            except NoMapAvailableError:
+                return False
+
+    def assign(self, other: structure.BrainStructure) -> AnatomicalAssignment:
+        """
+        Compute assignment of a location to this region.
+
+        Two cases:
+        1) other is location -> get region map, call regionmap.assign(other)
+        2) other is region -> just do a semantic check for the regions
+
+        Parameters
+        ----------
+        other : Location or Region
 
-    def __repr__(self):
-        return self.name
+        Returns
+        -------
+        AnatomicalAssignment or None
+            None if there is no Qualification found.
+        """
+        if (self, other) in self._ASSIGNMENT_CACHE:
+            return self._ASSIGNMENT_CACHE[self, other]
+        if (other, self) in self._ASSIGNMENT_CACHE:
+            if self._ASSIGNMENT_CACHE[other, self] is None:
+                return None
+            return self._ASSIGNMENT_CACHE[other, self].invert()
+
+        if isinstance(other, (location.Location, volume.Volume)):
+            if self.mapped_in_space(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 targetspace in self.supported_spaces:
+                try:
+                    other_warped = other.warp(targetspace)
+                    regionmap = self.get_regional_mask(targetspace)
+                    assignment_result = regionmap.assign(other_warped)
+                except SpaceWarpingFailedError:
+                    try:
+                        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)
+                except Exception as e:
+                    logger.debug(e)
+                    continue
+                break
+            self._ASSIGNMENT_CACHE[self, other] = assignment_result
+        else:  # other is a Region
+            assert isinstance(other, Region)
+            if self == other:
+                qualification = Qualification.EXACT
+            elif self.__contains__(other):
+                qualification = Qualification.CONTAINS
+            elif other.__contains__(self):
+                qualification = Qualification.CONTAINED
+            else:
+                qualification = None
+            if qualification is None:
+                self._ASSIGNMENT_CACHE[self, other] = None
+            else:
+                self._ASSIGNMENT_CACHE[self, other] = AnatomicalAssignment(self, other, qualification)
+        return self._ASSIGNMENT_CACHE[self, other]
 
     def tree2str(self):
         """Render region-tree as a string"""
@@ -605,13 +674,16 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         """Prints the tree representation of the region"""
         print(self.tree2str())
 
-    def get_bounding_box(
+    def get_boundingbox(
         self,
         space: _space.Space,
         maptype: MapType = MapType.LABELLED,
-        threshold_statistical=None,
-    ):
-        """Compute the bounding box of this region in the given space.
+        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.
 
         Parameters
         ----------
@@ -621,40 +693,61 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
             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.
+
         Returns
         -------
         BoundingBox
         """
         spaceobj = _space.Space.get_instance(space)
         try:
-            mask = self.fetch_regional_map(
+            mask = self.get_regional_mask(
                 spaceobj, maptype=maptype, threshold=threshold_statistical
             )
-            return boundingbox.BoundingBox.from_image(mask, space=spaceobj)
+            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.fetch_regional_map(
+                    mask = self.get_regional_mask(
                         other_space,
                         maptype=maptype,
                         threshold=threshold_statistical,
                     )
-                    logger.warning(
-                        f"No bounding box for {self.name} defined in {spaceobj.name}, "
-                        f"will warp the bounding box from {other_space.name} instead."
-                    )
-                    bbox = boundingbox.BoundingBox.from_image(mask, space=other_space)
+                    bbox = mask.get_boundingbox(clip=True, background=0.0, **fetch_kwargs)
                     if bbox is not None:
-                        return bbox.warp(spaceobj)
+                        try:
+                            bbox_warped = bbox.warp(spaceobj)
+                        except SpaceWarpingFailedError:
+                            continue
+                        logger.debug(
+                            f"No bounding box for {self.name} defined in {spaceobj.name}, "
+                            f"warped the bounding box from {other_space.name} instead."
+                        )
+                        return bbox_warped
                 except RuntimeError:
                     continue
         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.
 
@@ -662,18 +755,33 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         ----------
         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
         )
 
@@ -681,8 +789,10 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         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.
 
@@ -694,59 +804,34 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
             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.fetch_regional_map(
-            space, maptype=maptype, threshold=threshold_statistical
+        return region_vol.compute_spatial_props(
+            split_components=split_components, **fetch_kwargs
         )
 
-        # 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
-
     def __iter__(self):
         """
         Returns an iterator that goes through all regions in this subtree
@@ -754,6 +839,110 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         """
         return anytree.PreOrderIter(self)
 
+    def intersection(self, other: "location.Location") -> "location.Location":
+        """Use this region for filtering a location object."""
+
+        if self.supports_space(other.space):
+            try:
+                volume = self.get_regional_mask(other.space)
+                if volume is not None:
+                    return volume.intersection(other)
+            except NotImplementedError:
+                intersections = [child.intersection(other) for child in self.children]
+                return reduce(lambda a, b: a.union(b), intersections)
+
+        for space in self.supported_spaces:
+            if space.provides_image:
+                try:
+                    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.")
+                        return intersection
+                except SpaceWarpingFailedError:
+                    continue
+
+        return None
+
+
+@cache_user_fn
+def _get_related_regions_str(pe_id: str) -> Tuple[Tuple[str, str, str, str], ...]:
+    logger.info("LONG CALC...", pe_id)
+    return_val = []
+    region_relation_assessments = RegionRelationAssessments.translate_pes(pe_id, pe_id)
+    for asgmt in region_relation_assessments:
+        assert isinstance(asgmt, RegionRelationAssessments), f"Expecting type to be of RegionRelationAssessments, but is {type(asgmt)}"
+        assert isinstance(asgmt.assigned_structure, Region), f"Expecting assigned structure to be of type Region, but is {type(asgmt.assigned_structure)}"
+        return_val.append((
+            asgmt.assigned_structure.parcellation.id,
+            asgmt.assigned_structure.name,
+            asgmt.qualification.name,
+            asgmt.explanation
+        ))
+    return tuple(return_val)
+
+
+def get_peid_from_region(region: Region) -> str:
+    """
+    Given a region, obtain the Parcellation Entity ID.
+
+    Parameters
+    ----------
+    region : Region
+
+    Returns
+    -------
+    str
+    """
+    if region._spec:
+        region_peid = region._spec.get("ebrains", {}).get("openminds/ParcellationEntity")
+        if region_peid:
+            return region_peid
+    # In some cases (e.g. Julich Brain, PE is defined on the parent leaf nodes)
+    if region.parent and region.parent._spec:
+        parent_peid = region.parent._spec.get("ebrains", {}).get("openminds/ParcellationEntity")
+        if parent_peid:
+            return parent_peid
+    return None
+
+
+def get_related_regions(region: Region) -> Iterable["RegionRelationAssessments"]:
+    """
+    Get assements on relations of a region to others defined on EBRAINS.
+
+    Parameters
+    ----------
+    region: Region
+
+    Yields
+    ------
+    Qualification
+
+    Example
+    -------
+    >>> region = siibra.get_region("monkey", "PG")
+    >>> for assesment in siibra.core.region.get_related_regions(region):
+    >>>    print(assesment)
+    'PG' is homologous to 'Area PGa (IPL)'
+    'PG' is homologous to 'Area PGa (IPL) left'
+    'PG' is homologous to 'Area PGa (IPL) right'
+    'PG' is homologous to 'Area PGa (IPL)'
+    'PG' is homologous to 'Area PGa (IPL) left'
+    'PG' is homologous to 'Area PGa (IPL) right'
+    'PG' is homologous to 'Area PGa (IPL)'
+    'PG' is homologous to 'Area PGa (IPL) right'
+    'PG' is homologous to 'Area PGa (IPL) left'
+    """
+    logger.info("get related region called")
+    pe_id = get_peid_from_region(region)
+    if not pe_id:
+        return []
+
+    for parc_id, region_name, qual, explanation in _get_related_regions_str(pe_id):
+        parc = _parcellation.Parcellation.get_instance(parc_id)
+        found_region = parc.get_region(region_name)
+        yield RegionRelationAssessments(region, found_region, qual, explanation)
+
 
 _get_reg_relation_asmgt_types: Dict[str, Callable] = {}
 
@@ -769,12 +958,33 @@ def _register_region_reference_type(ebrain_type: str):
     return outer
 
 
-class RegionRelationAssessments(RelationAssignment[Region]):
+class RegionRelationAssessments(AnatomicalAssignment[Region]):
+    """
+    A collection of methods on finding related regions and the quantification
+    of the relationship.
+    """
 
     anony_client = BucketApiClient()
 
     @staticmethod
-    def get_uuid(long_id: Union[str, Dict]):
+    def get_uuid(long_id: Union[str, Dict]) -> str:
+        """
+        Returns the uuid portion of either a fully formed openminds id, or get
+        the 'id' property first, and extract the uuid portion of the id.
+
+        Parameters
+        ----------
+        long_id: str, dict[str, str]
+
+        Returns
+        -------
+        str
+
+        Raises
+        ------
+        AssertionError
+        RuntimeError
+        """
         if isinstance(long_id, str):
             pass
         elif isinstance(long_id, dict):
@@ -788,6 +998,22 @@ class RegionRelationAssessments(RelationAssignment[Region]):
 
     @staticmethod
     def parse_id_arg(_id: Union[str, List[str]]) -> List[str]:
+        """
+        Normalizes the ebrains id property. The ebrains id field can be either
+        a str or list[str]. This method normalizes it to always be list[str].
+
+        Parameters
+        ----------
+        _id: strl, list[str]
+
+        Returns
+        -------
+        list[str]
+
+        Raises
+        ------
+        RuntimeError
+        """
         if isinstance(_id, list):
             assert all(isinstance(_i, str) for _i in _id), "all instances of pev should be str"
         elif isinstance(_id, str):
@@ -798,11 +1024,34 @@ class RegionRelationAssessments(RelationAssignment[Region]):
 
     @classmethod
     def get_object(cls, obj: str):
+        """
+        Gets given a object (path), loads the content and serializes to json.
+        Relative to the bucket 'reference-atlas-data'.
+
+        Parameters
+        ----------
+        obj: str
+
+        Returns
+        -------
+        dict
+        """
         bucket = cls.anony_client.buckets.get_bucket("reference-atlas-data")
         return json.loads(bucket.get_file(obj).get_content())
 
     @classmethod
     def get_snapshot_factory(cls, type_str: str):
+        """
+        Factory method for given type.
+
+        Parameters
+        ----------
+        type_str: str
+
+        Returns
+        -------
+        Callable[[str|list[str]], dict]
+        """
         def get_objects(_id: Union[str, List[str]]):
             _id = cls.parse_id_arg(_id)
             with ThreadPoolExecutor() as ex:
@@ -815,7 +1064,19 @@ class RegionRelationAssessments(RelationAssignment[Region]):
 
     @classmethod
     def parse_relationship_assessment(cls, src: "Region", assessment):
+        """
+        Given a region, and the fetched assessment json, yield
+        RegionRelationAssignment object.
 
+        Parameters
+        ----------
+        src: Region
+        assessment: dict
+
+        Returns
+        -------
+        Iterable[RegionRelationAssessments]
+        """
         all_regions = [
             region
             for p in _parcellation.Parcellation.registry()
@@ -836,7 +1097,11 @@ class RegionRelationAssessments(RelationAssignment[Region]):
             ]
 
             for found_target in found_targets:
-                yield cls(query_structure=src, assigned_structure=found_target, qualification=RegionRelationship.parse_relation_assessment(overlap))
+                yield cls(
+                    query_structure=src,
+                    assigned_structure=found_target,
+                    qualification=Qualification.parse_relation_assessment(overlap)
+                )
 
             if "https://openminds.ebrains.eu/sands/ParcellationEntity" in target.get("type"):
                 pev_uuids = [
@@ -846,28 +1111,47 @@ class RegionRelationAssessments(RelationAssignment[Region]):
                 ]
                 for reg in all_regions:
                     if reg in pev_uuids:
-                        yield cls(query_structure=src, assigned_structure=reg, qualification=RegionRelationship.parse_relation_assessment(overlap))
+                        yield cls(
+                            query_structure=src,
+                            assigned_structure=reg,
+                            qualification=Qualification.parse_relation_assessment(overlap)
+                        )
 
     @classmethod
     @_register_region_reference_type("openminds/CustomAnatomicalEntity")
     def translate_cae(cls, src: "Region", _id: Union[str, List[str]]):
+        """Register how CustomAnatomicalEntity should be parsed
+
+        Parameters
+        ----------
+        src: Region
+        _id: str|list[str]
+
+        Returns
+        -------
+        Iterable[RegionRelationAssessments]
+        """
         caes = cls.get_snapshot_factory("CustomAnatomicalEntity")(_id)
         for cae in caes:
             for ass in cae.get("relationAssessment", []):
                 yield from cls.parse_relationship_assessment(src, ass)
 
     @classmethod
-    @_register_region_reference_type("openminds/ParcellationEntityVersion")
-    def translate_pevs(cls, src: "Region", _id: Union[str, List[str]]):
-        pe_uuids = [
-            uuid for uuid in
-            {
-                cls.get_uuid(pe)
-                for pev in cls.get_snapshot_factory("ParcellationEntityVersion")(_id)
-                for pe in pev.get("isVersionOf")
-            }
-        ]
-        pes = cls.get_snapshot_factory("ParcellationEntity")(pe_uuids)
+    @_register_region_reference_type("openminds/ParcellationEntity")
+    def translate_pes(cls, src: "Region", _id: Union[str, List[str]]):
+        """
+        Register how ParcellationEntity should be parsed
+
+        Parameters
+        ----------
+        src: Region
+        _id: str|list[str]
+
+        Returns
+        -------
+        Iterable[RegionRelationAssessments]
+        """
+        pes = cls.get_snapshot_factory("ParcellationEntity")(_id)
 
         all_regions = [
             region
@@ -876,30 +1160,15 @@ class RegionRelationAssessments(RelationAssignment[Region]):
         ]
 
         for pe in pes:
-
-            # other versions
-            has_versions = pe.get("hasVersion", [])
-            for has_version in has_versions:
-                uuid = cls.get_uuid(has_version)
-
-                # ignore if uuid is referring to src region
-                if uuid == src:
+            for region in all_regions:
+                if region is src:
                     continue
-
-                found_targets = [
-                    region
-                    for region in all_regions
-                    if region == uuid
-                ]
-                if len(found_targets) == 0:
-                    logger.warning(f"other version with uuid {uuid} not found")
-                    continue
-
-                for found_target in found_targets:
+                region_peid = get_peid_from_region(region)
+                if region_peid and (region_peid in pe.get("id")):
                     yield cls(
                         query_structure=src,
-                        assigned_structure=found_target,
-                        qualification=RegionRelationship.OTHER_VERSION
+                        assigned_structure=region,
+                        qualification=Qualification.OTHER_VERSION
                     )
 
             # homologuous
@@ -907,8 +1176,45 @@ class RegionRelationAssessments(RelationAssignment[Region]):
             for relation in relations:
                 yield from cls.parse_relationship_assessment(src, relation)
 
+    @classmethod
+    @_register_region_reference_type("openminds/ParcellationEntityVersion")
+    def translate_pevs(cls, src: "Region", _id: Union[str, List[str]]):
+        """
+        Register how ParcellationEntityVersion should be parsed
+
+        Parameters
+        ----------
+        src: Region
+        _id: str|list[str]
+
+        Returns
+        -------
+        Iterable[RegionRelationAssessments]
+        """
+        pe_uuids = [
+            uuid for uuid in
+            {
+                cls.get_uuid(pe)
+                for pev in cls.get_snapshot_factory("ParcellationEntityVersion")(_id)
+                for pe in pev.get("isVersionOf")
+            }
+        ]
+        yield from cls.translate_pes(src, pe_uuids)
+
     @classmethod
     def parse_from_region(cls, region: "Region") -> Iterable["RegionRelationAssessments"]:
+        """
+        Main entry on how related regions should be retrieved. Given a region,
+        retrieves all RegionRelationAssessments
+
+        Parameters
+        ----------
+        region: Region
+
+        Returns
+        -------
+        Iterable[RegionRelationAssessments]
+        """
         if not region._spec:
             return None
         for ebrain_type, ebrain_ref in region._spec.get("ebrains", {}).items():