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

siibra/core/region.py

@@ -20,12 +20,11 @@ from ..volumes import parcellationmap
 
 from ..commons import (
     logger,
-    MapIndex,
     MapType,
-    compare_maps,
     affine_scaling,
     create_key,
     clear_name,
+    siibra_tqdm,
     InstanceTable,
     SIIBRA_DEFAULT_MAPTYPE,
     SIIBRA_DEFAULT_MAP_THRESHOLD
@@ -37,12 +36,25 @@ import anytree
 from typing import List, Set, Union
 from nibabel import Nifti1Image
 from difflib import SequenceMatcher
+from dataclasses import dataclass, field
 
 
 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):
     """
@@ -71,19 +83,20 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         ----------
         name : str
             Human-readable name of the region
-        children: list of Regions,
+        children: list[Region]
         parent: Region
         shortname: str
             Shortform of human-readable name (optional)
         description: str
             Textual description of the parcellation
-        modality  :  str or None
+        modality:  str or None
             Specification of the modality used for specifying this region
         publications: list
-            List of ssociated publications, each a dictionary with "doi" and/or "citation" fields
-        datasets : list
+            List of associated publications, each a dictionary with "doi"
+            and/or "citation" fields
+        datasets: list
             datasets associated with this region
-        rgb: str, default None
+        rgb: str, default: None
             Hexcode of preferred color of this region (e.g. "#9FE770")
         """
         anytree.NodeMixin.__init__(self)
@@ -134,7 +147,7 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
     @staticmethod
     def copy(other: 'Region'):
         """
-        copy contructor must detach the parent to avoid problems with
+        copy constructor must detach the parent to avoid problems with
         the Anytree implementation.
         """
         # create an isolated object, detached from the other's tree
@@ -153,13 +166,9 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
             c.parent = region
         return region
 
-    @property
-    def labels(self):
-        return {r.index.label for r in self if r.index.label is not None}  # Potenially a BUG
-
     @property
     def names(self):
-        return {r.key for r in self}
+        return {r.name for r in self}
 
     def __eq__(self, other):
         """
@@ -171,9 +180,7 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         elif isinstance(other, str):
             return any([self.name == other, self.key == other, self.id == other])
         else:
-            raise ValueError(
-                f"Cannot compare object of type {type(other)} to {self.__class__.__name__}"
-            )
+            return False
 
     def __hash__(self):
         return hash(self.id)
@@ -183,7 +190,15 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
 
     def includes(self, region):
         """
-        Determine wether this regiontree includes the given region.
+        Determine whether this region-tree includes the given region.
+
+        Parameters
+        ----------
+        region: Region
+        Returns
+        -------
+            bool
+                True if the region is in the region-tree.
         """
         return region == self or region in self.descendants
 
@@ -199,23 +214,24 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
 
         Parameters
         ----------
-        regionspec : any of
-            - a string with a possibly inexact name, which is matched both
-              against the name and the identifier key,
-            - a string in '/pattern/flags' format to use regex search (acceptable flags: aiLmsux),
-            - a regex applied to region names,
-            - an integer, which is interpreted as a labelindex,
-            - a full MapIndex
-            - a region object
-        filter_children : Boolean
-            If true, children of matched parents will not be returned
-        find_topmost : Bool, default: True
-            If True, will return parent structures if all children are matched,
-            even though the parent itself might not match the specification.
-
-        Yield
-        -----
-        list of matching regions
+        regionspec: str, regex, int, 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 regex applied to region names
+            - a Region object
+        filter_children : bool, default: False
+            If True, children of matched parents will not be returned
+        find_topmost : bool, default: True
+            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
@@ -234,40 +250,19 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
                 search_regex = (f"(?{flags})" if flags else "") + expression
                 regionspec = re.compile(search_regex)
 
-            if regionspec in self.names:
-                # key is given, this gives us an exact region
-                match = anytree.search.find_by_attr(self, regionspec, name="key")
-                MEM[key] = [] if match is None else [match]
-                return list(MEM[key])
-
         candidates = list(
-            set(anytree.search.findall(self, lambda node: node.matches(regionspec)))
+            anytree.search.findall(self, lambda node: node.matches(regionspec))
         )
 
         if len(candidates) > 1 and filter_children:
-
             filtered = []
             for region in candidates:
                 children_included = [c for c in region.children if c in candidates]
-                # if the parcellation index matches only approximately,
-                # while a child has an exact matching index, use the child.
                 if len(children_included) > 0:
-                    if not (
-                        isinstance(regionspec, MapIndex)
-                        and (region.index != regionspec)
-                        and any(c.index == regionspec for c in children_included)
-                    ):
-                        filtered.append(region)
+                    filtered.append(region)
                 else:
                     if region.parent not in candidates:
                         filtered.append(region)
-                    else:
-                        if (
-                            isinstance(regionspec, MapIndex)
-                            and (region.index == regionspec)
-                            and (region.parent.index != regionspec)
-                        ):
-                            filtered.append(region)
 
             # find any non-matched regions of which all children are matched
             if find_topmost:
@@ -285,7 +280,10 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
                 else:
                     # filter child regions again
                     filtered += complete_parents
-                    candidates = [r for r in filtered if r.parent not in filtered]
+                    candidates = [
+                        r for r in filtered
+                        if (r.parent not in filtered) or r == regionspec
+                    ]
             else:
                 candidates = filtered
 
@@ -297,12 +295,12 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         else:
             candidates = list(candidates)
 
-        found_regions = sorted(candidates, key=lambda r: r.depth)
+        found_regions = sorted(set(candidates), key=lambda r: r.depth)
 
         # reverse is set to True, since SequenceMatcher().ratio(), higher == better
         MEM[key] = (
             sorted(
-                set(found_regions),
+                found_regions,
                 reverse=True,
                 key=lambda region: SequenceMatcher(None, str(region), regionspec).ratio(),
             )
@@ -314,20 +312,19 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
 
     def matches(self, regionspec):
         """
-        Checks wether this region matches the given region specification.
+        Checks whether this region matches the given region specification.
 
         Parameters
-        ---------
-
-        regionspec : any of
-            - a string with a possibly inexact name, which is matched both
-              against the name and the identifier key,
+        ----------
+        regionspec: str, regex, Region
+            - a string with a possibly inexact name, which is matched both against the name and the identifier key,
             - a regex applied to region names,
             - a region object
 
-        Yield
-        -----
-        True or False
+        Returns
+        -------
+        bool
+            If the regionspec matches to the Region.
         """
         if regionspec is None:
             return False
@@ -360,6 +357,8 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         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)}'"
@@ -374,27 +373,37 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
     ):
         """
         Attempts to build a binary mask of this region in the given space,
-        using the specified maptypes.
+        using the specified MapTypes.
 
         Parameters
         ----------
-        space: Space object or space name
+        space: Space or str
             The requested reference space
-        maptype: MapType
-            the type of map to be used (labelled or statistical)
-        threshold: float
-            (optional) When fetching a statistical map, use this
-            threshold to convert it to a binary mask
-        via_space: Space object or space name
+        maptype: MapType, default: SIIBRA_DEFAULT_MAPTYPE
+            The type of map to be used ('labelled' or 'statistical')
+        threshold: float, optional
+            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.
-            You might want to use this if a map in the requested space is not available.
-            Note that this linear warping is an affine approximation of the
-            nonlinear deformation, computed from the warped corenr points
-            of the bounding box (see siibra.location.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 not supported in siibra-python for images so far.
+
+            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.
+        Returns
+        -------
+        Nifti1Image
         """
         if isinstance(maptype, str):
             maptype = MapType[maptype.upper()]
@@ -408,14 +417,12 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
             fetch_space = _space.Space.get_instance(fetch_space)
 
         for m in parcellationmap.Map.registry():
-            if all(
-                [
-                    m.space.matches(fetch_space),
-                    m.parcellation == self.parcellation,
-                    m.provides_image,
-                    m.maptype == maptype,
-                    self.name in m.regions
-                ]
+            if (
+                m.space.matches(fetch_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):
@@ -430,7 +437,12 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
             dataobj = None
             affine = None
             if all(c.mapped_in_space(fetch_space) for c in self.children):
-                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)
@@ -466,6 +478,16 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
     def mapped_in_space(self, space, recurse: bool = True) -> bool:
         """
         Verifies wether this region is defined by an explicit map in the given space.
+
+        Parameters
+        ----------
+        space: Space or str
+            reference space
+        recurse: bool, default: True
+            If True, check if all child regions are mapped instead
+        Returns
+        -------
+        bool
         """
         from ..volumes.parcellationmap import Map
         for m in Map.registry():
@@ -505,42 +527,6 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
             elements={s.key: s for s in self.supported_spaces},
         )
 
-    def __getitem__(self, labelindex):
-        """
-        Given an integer label index, return the corresponding region.
-        If multiple matches are found, return the unique parent if possible.
-        Otherwise, return None
-
-        Parameters
-        ----------
-
-        regionlabel: int
-            label index of the desired region.
-
-        Return
-        ------
-        Region object
-        """
-        if not isinstance(labelindex, int):
-            raise TypeError(
-                "Index access into the regiontree expects label indices of integer type"
-            )
-
-        # first test this head node
-        if self.index.label == labelindex:
-            return self
-
-        # Consider children, and return the one with smallest depth
-        matches = list(
-            filter(lambda x: x is not None, [c[labelindex] for c in self.children])
-        )
-        if matches:
-            parentmatches = [m for m in matches if m.parent not in matches]
-            if len(parentmatches) == 1:
-                return parentmatches[0]
-
-        return None
-
     def __str__(self):
         return self.name
 
@@ -548,6 +534,7 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         return self.name
 
     def tree2str(self):
+        """Render region-tree as a string"""
         return "\n".join(
             "%s%s" % (pre, node.name)
             for pre, _, node
@@ -555,6 +542,7 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         )
 
     def render_tree(self):
+        """Prints the tree representation of the region"""
         print(self.tree2str())
 
     def get_bounding_box(
@@ -567,17 +555,18 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
 
         Parameters
         ----------
-        space : Space or str):
+        space: Space or str
             Requested reference space
-        maptype: MapType
+        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 )
+            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.
-        Returns:
-            BoundingBox
+        Returns
+        -------
+        BoundingBox
         """
         spaceobj = _space.Space.get_instance(space)
         try:
@@ -593,7 +582,7 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
                         maptype=maptype,
                         threshold=threshold_statistical,
                     )
-                    logger.warn(
+                    logger.warning(
                         f"No bounding box for {self.name} defined in {spaceobj.name}, "
                         f"will warp the bounding box from {other_space.name} instead."
                     )
@@ -606,14 +595,25 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         return None
 
     def compute_centroids(self, space: _space.Space) -> pointset.PointSet:
-        """Compute the centroids of the region in the given space.
+        """
+        Compute the centroids of the region in the given space.
 
-        Note that a region can generally have multiple centroids
-        if it has multiple connected components in the map.
+        Parameters
+        ----------
+        space: Space
+            reference space in which the computation will be performed
+        Returns
+        -------
+        PointSet
+            Found centroids (as Point objects) in a PointSet
+        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(
-            [tuple(c["centroid"]) for c in props["components"] if "centroid" in c],
+            [c.centroid for c in props.components],
             space=space
         )
 
@@ -622,34 +622,36 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
         space: _space.Space,
         maptype: MapType = MapType.LABELLED,
         threshold_statistical=None,
-    ):
+    ) -> SpatialProp:
         """
         Compute spatial properties for connected components of this region in the given space.
 
         Parameters
         ----------
-        space : _space.Space
-            the space in which the computation shall be performed
-        maptype: MapType
+        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 )
+            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.
 
-        Return
-        ------
-        dictionary of regionprops.
+        Returns
+        -------
+        Dict
+            Dictionary of region's spatial properties
         """
-        result = {"space": space, "components": []}
         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.warn(
+            logger.warning(
                 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)}"
@@ -670,50 +672,21 @@ class Region(anytree.NodeMixin, concept.AtlasConcept):
 
         # compute spatial properties of each connected component
         for label in range(1, C.max() + 1):
-            props = {}
             nonzero = np.c_[np.nonzero(C == label)]
-            props["centroid"] = point.Point(
-                np.dot(pimg.affine, np.r_[nonzero.mean(0), 1])[:3], space=space
+            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,
+                )
             )
-            props["volume"] = nonzero.shape[0] * scale
 
-            result["components"].append(props)
+        # sort by volume
+        result.components.sort(key=lambda cmp: cmp.volume, reverse=True)
 
         return result
 
-    def compare(
-        self,
-        img: Nifti1Image,
-        space: _space.Space,
-        use_maptype: MapType = MapType.STATISTICAL,
-        threshold_statistical: float = None,
-        resolution_mm: float = None,
-    ):
-        """
-        Compare the given image to the map of this region in the specified space.
-
-        Parameters:
-        -----------
-        img: Nifti1Image
-            Image to compare with
-        space: Space
-            Reference space to use
-        use_maptype: MapType
-            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.
-        """
-        mask = self.fetch_regional_map(
-            space,
-            resolution_mm,
-            maptype=use_maptype,
-            threshold=threshold_statistical,
-        )
-        return compare_maps(mask, img)
-
     def __iter__(self):
         """
         Returns an iterator that goes through all regions in this subtree