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

siibra/core/parcellation.py

@@ -96,7 +96,7 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
             Specification of the species
         regions: list or Region
         shortname: str
-            Shortform of human-readable name (optional)
+            Short form of human-readable name (optional)
         description: str
             Textual description of the parcellation
         version : str or None
@@ -104,7 +104,8 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
         modality  :  str or None
             Specification of the modality used for creating the parcellation
         publications: list
-            List of ssociated publications, each a dictionary with "doi" and/or "citation" fields
+            List of associated publications, each a dictionary with "doi"
+            and/or "citation" fields
         datasets : list
             datasets associated with this region
         """
@@ -136,25 +137,34 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
                 return True
         return super().matches(spec)
 
-    def get_map(self, space=None, maptype: Union[str, MapType] = MapType.LABELLED):
+    def get_map(self, space=None, maptype: Union[str, MapType] = MapType.LABELLED, spec: str = ""):
         """
-        Get the maps for the parcellation in the requested
-        template space. This might in general include multiple
-        3D volumes. For example, the Julich-Brain atlas provides two separate
-        maps, one per hemisphere. Per default, multiple maps are concatenated into a 4D
-        array, but you can choose to retrieve a dict of 3D volumes instead using `return_dict=True`.
+        Get the maps for the parcellation in the requested template space.
+
+        This might in general include multiple 3D volumes. For example,
+        the Julich-Brain atlas provides two separate maps, one per hemisphere.
+        Per default, multiple maps are concatenated into a 4D array, but you
+        can choose to retrieve a dict of 3D volumes instead using
+        `return_dict=True`.
 
         Parameters
         ----------
-        space : Space or str
+        space: Space or str
             template space specification
-        maptype : MapType (default: MapType.LABELLED)
-            Type of map requested (e.g., continous or labelled, see _commons.MapType)
+        maptype: MapType
+            Type of map requested (e.g., statistical or labelled).
             Use MapType.STATISTICAL to request probability maps.
-
-        Yields
-        ------
-        A ParcellationMap representing the volumetric map.
+            Defaults to MapType.LABELLED.
+        spec: str, optional
+            In case of multiple matching maps for the given parcellation, space
+            and type, use this field to specify keywords matching the desired
+            parcellation map name. Otherwise, siibra will default to the first
+            in the list of matches (and inform with a log message)
+        Returns
+        -------
+        parcellationmap.Map or SparseMap
+            A ParcellationMap representing the volumetric map or
+            a SparseMap representing the list of statistical maps.
         """
         if not isinstance(maptype, MapType):
             maptype = MapType[maptype.upper()]
@@ -170,16 +180,47 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
             logger.error(f"No {maptype} map in {space} available for {str(self)}")
             return None
         if len(candidates) > 1:
-            logger.warning(f"Multiple {maptype} maps in {space} available for {str(self)}, choosing the first.")
+            spec_candidates = [
+                c for c in candidates if all(w.lower() in c.name.lower() for w in spec.split())
+            ]
+            if len(spec_candidates) == 0:
+                logger.warning(f"'{spec}' does not match any options from {[c.name for c in candidates]}.")
+                return None
+            if len(spec_candidates) > 1:
+                logger.warning(
+                    f"Multiple maps are available in this specification of space, parcellation, and map type.\n"
+                    f"Choosing the first map from {[c.name for c in spec_candidates]}."
+                )
+            return spec_candidates[0]
         return candidates[0]
 
-    @classmethod
-    def find_regions(cls, region_spec: str, parents_only=True):
-        MEM = cls._CACHED_REGION_SEARCHES
+    @staticmethod
+    def find_regions(region_spec: str, parents_only=True):
+        """
+        Find regions that match the given region specification in the subtree
+        headed by each parcellation in the registry.
+        Note
+        ----
+        Use Region.find() to search for a region in an instance of a
+        parcellation.
+
+        Parameters
+        ----------
+        regionspec: str
+            a string with a possibly inexact name, which is matched both
+            against the name and the identifier key,
+        parents_only: bool
+            If true, children of matched parents will not be returned
+        Returns
+        -------
+        List[Region]
+            list of matching regions
+        """
+        MEM = Parcellation._CACHED_REGION_SEARCHES
         if region_spec not in MEM:
             MEM[region_spec] = [
                 r
-                for p in cls.registry()
+                for p in Parcellation.registry()
                 for r in p.find(regionspec=region_spec)
             ]
         if parents_only:
@@ -216,41 +257,47 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
         else:
             return [spec]
 
-    def get_region(self, regionspec: Union[str, int, MapIndex, region.Region], find_topmost=True, allow_tuple=False):
+    def get_region(
+        self,
+        regionspec: Union[str, region.Region],
+        find_topmost: bool = True,
+        allow_tuple: bool = False
+    ):
         """
         Given a unique specification, return the corresponding region.
-        The spec could be a label index, a (possibly incomplete) name, or a
-        region object.
+
+        The spec could be a (possibly incomplete) name, or a region object.
         This method is meant to definitely determine a valid region. Therefore,
-        if no match is found, it raises a ValueError.
-        If multiple matches are found, the method tries to return only the common parent node.
-        If there is no common parent, an exception is raised, except when
-        allow_tuple=True - then a tuple of matched regions is returned
+        if no match is found, it raises a ValueError. If multiple matches are
+        found, the method tries to return only the common parent node. If there
+        is no common parent, an exception is raised, except when
+        allow_tuple=True - then a tuple of matched regions is returned.
 
         Parameters
         ----------
-        regionspec : any of
-            - a string with a possibly inexact name, which is matched both
-              against the name and the identifier key,
-            - an integer, which is interpreted as a labelindex,
-            - a region object
-            - a full MapIndex
-        find_topmost : Bool, default: True
+        regionspec: str, Region
+            - a string with a possibly inexact name (matched both against the name and the identifier key)
+            - a Region object
+        find_topmost: bool, default: True
             If True, will automatically return the parent of a decoded region
             the decoded region is its only child.
-        allow_tuple: Bool, default: False
+        allow_tuple: bool, default: False
             If multiple candidates without a common parent are found,
             return a tuple of matches instead of raising an exception.
-
-        Return
-        ------
-        Region object
+            
+        Returns
+        -------
+        Region
+            A region object defined in the parcellation
 
         Raises
         ------
-        RuntimeError: if the spec matches multiple regions
-        ValueError: if the spec cannot be matched against any region
+        RuntimeError
+            If the spec matches multiple regions
+        ValueError
+            If the spec cannot be matched against any region
         """
+        assert isinstance(regionspec, (str, region.Region)), f"get_region takes str or Region but you provided {type(regionspec)}"
         if isinstance(regionspec, region.Region) and (regionspec.parcellation == self):
             return regionspec
 
@@ -263,6 +310,10 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
         else:
             candidates = self.find(regionspec, filter_children=True, find_topmost=find_topmost)
 
+        exact_matches = [r for r in candidates if regionspec == r]
+        if len(exact_matches) == 1:
+            return exact_matches[0]
+
         if len(candidates) > 1 and isinstance(regionspec, str):
             # if we have an exact match of words in one region, discard other candidates.
             querywords = {w.replace(',', '').lower() for w in regionspec.split()}
@@ -282,7 +333,7 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
             if allow_tuple:
                 return tuple(candidates)
             raise RuntimeError(
-                f"Spec {regionspec} resulted in multiple matches: {', '.join(r.name for r in candidates)}."
+                f"Spec {regionspec!r} resulted in multiple matches: {', '.join(r.name for r in candidates)}."
             )
 
     def __str__(self):
@@ -302,7 +353,7 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
         We sort parcellations by their version
         """
         if (self.version is None) or (other.version is None):
-            logger.warn(
+            logger.warning(
                 f"Sorting non-versioned instances of {self.__class__.__name__} "
                 f"by name: {self.name}, {other.name}"
             )