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

siibra/volumes/parcellationmap.py

@@ -24,40 +24,49 @@ from ..commons import (
     clear_name,
     create_key,
     create_gaussian_kernel,
-    Species
+    siibra_tqdm,
+    Species,
+    CompareMapsResult
 )
 from ..core import concept, space, parcellation, region as _region
 from ..locations import point, pointset
 from ..retrieval import requests
 
 import numpy as np
-from tqdm import tqdm
-from typing import Union, Dict, List, TYPE_CHECKING, Iterable
+from typing import Union, Dict, List, TYPE_CHECKING, Iterable, Tuple
 from scipy.ndimage import distance_transform_edt
 from collections import defaultdict
 from nibabel import Nifti1Image
 from nilearn import image
 import pandas as pd
+from dataclasses import dataclass, asdict
 
 if TYPE_CHECKING:
     from ..core.region import Region
 
 
-class ExcessiveArgumentException(ValueError):
-    pass
+class ExcessiveArgumentException(ValueError): pass
 
 
-class InsufficientArgumentException(ValueError):
-    pass
+class InsufficientArgumentException(ValueError): pass
 
 
-class ConflictingArgumentException(ValueError):
-    pass
+class ConflictingArgumentException(ValueError): pass
 
 
-class NonUniqueIndexError(RuntimeError):
-    pass
+class NonUniqueIndexError(RuntimeError): pass
 
+@dataclass
+class Assignment:
+    input_structure: int
+    centroid: Union[Tuple[np.ndarray], point.Point] 
+    volume: int
+    fragment: str
+    map_value: np.ndarray
+
+
+@dataclass
+class AssignImageResult(CompareMapsResult, Assignment): pass
 
 class Map(concept.AtlasConcept, configuration_folder="maps"):
 
@@ -157,6 +166,9 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         self._parcellation_spec = parcellation_spec
         self._affine_cached = None
         for v in self.volumes:
+            # allow the providers to query their parcellation map if needed
+            for p in v._providers.values():
+                p.parcellation_map = self
             v._space_spec = space_spec
 
     @property
@@ -224,7 +236,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         matched_region_names = set(_.name for _ in (self.parcellation.find(regionname)))
         matches = matched_region_names & self._indices.keys()
         if len(matches) == 0:
-            logger.warn(f"Region {regionname} not defined in {self}")
+            logger.warning(f"Region {regionname} not defined in {self}")
         return {
             idx: regionname
             for regionname in matches
@@ -250,6 +262,8 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         Region
             A region object defined in the parcellation map.
         """
+        if isinstance(label, MapIndex) and index is None:
+            raise TypeError(f"Specify MapIndex with index keyword.")
         if index is None:
             index = MapIndex(volume, label)
         matches = [
@@ -258,13 +272,13 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             if index in indexlist
         ]
         if len(matches) == 0:
-            logger.warn(f"Index {index} not defined in {self}")
+            logger.warning(f"Index {index} not defined in {self}")
             return None
         elif len(matches) == 1:
             return self.parcellation.get_region(matches[0])
         else:
             # this should not happen, already tested in constructor
-            raise RuntimeError(f"Index {index} is not unique in {self}")
+            raise RuntimeError(f"Index {index} is not unique in {self}")
 
     @property
     def space(self):
@@ -278,7 +292,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         for key in ["@id", "name"]:
             if key in self._parcellation_spec:
                 return parcellation.Parcellation.get_instance(self._parcellation_spec[key])
-        logger.warn(
+        logger.warning(
             f"Cannot determine parcellation of {self.__class__.__name__} "
             f"{self.name} from {self._parcellation_spec}"
         )
@@ -410,7 +424,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             print(str(e))
 
         if result is None:
-            raise RuntimeError(f"Error fetching {mapindex} from {self} as {kwargs['format']}.")
+            raise RuntimeError(f"Error fetching {mapindex} from {self} as {kwargs.get('format', f'{self.formats}')}.")
         return result
 
     def fetch_iter(self, **kwargs):
@@ -498,12 +512,12 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         next_labelindex = 1
         region_indices = defaultdict(list)
 
-        for volidx in tqdm(
+        for volidx in siibra_tqdm(
             range(len(self.volumes)), total=len(self.volumes), unit='maps',
             desc=f"Compressing {len(self.volumes)} {self.maptype.name.lower()} volumes into single-volume parcellation",
             disable=(len(self.volumes) == 1)
         ):
-            for frag in tqdm(
+            for frag in siibra_tqdm(
                 self.fragments, total=len(self.fragments), unit='maps',
                 desc=f"Compressing {len(self.fragments)} {self.maptype.name.lower()} fragments into single-fragment parcellation",
                 disable=(len(self.fragments) == 1 or self.fragments is None)
@@ -525,7 +539,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                         mapindex.__setattr__("label", int(label))
                         region = self.get_region(index=mapindex)
                     if region is None:
-                        logger.warn(f"Label index {label} is observed in map volume {self}, but no region is defined for it.")
+                        logger.warning(f"Label index {label} is observed in map volume {self}, but no region is defined for it.")
                         continue
                     region_indices[region.name].append({"volume": 0, "label": next_labelindex})
                     if label is None:
@@ -564,7 +578,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         regions = sorted(self._indices.items(), key=lambda v: min(_.volume for _ in v[1]))
         current_vol_index = MapIndex(volume=0)
         maparr = None
-        for regionname, indexlist in tqdm(regions, unit="regions", desc="Computing centroids"):
+        for regionname, indexlist in siibra_tqdm(regions, unit="regions", desc="Computing centroids"):
             assert len(indexlist) == 1
             index = indexlist[0]
             if index.label == 0:
@@ -582,7 +596,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             )
         return centroids
 
-    def colorize(self, values: dict):
+    def colorize(self, values: dict, **kwargs):
         """Colorize the map with the provided regional values.
 
         Parameters
@@ -596,7 +610,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         """
 
         result = None
-        for volidx, vol in enumerate(self.fetch_iter()):
+        for volidx, vol in enumerate(self.fetch_iter(**kwargs)):
             if isinstance(vol, dict):
                 raise NotImplementedError("Map colorization not yet implemented for meshes.")
             img = np.asanyarray(vol.dataobj)
@@ -747,6 +761,27 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                 for pointindex, value
                 in enumerate(np.asanyarray(volimg.dataobj)[x, y, z])
             ]
+        
+    def _assign(
+        self,
+        item: Union[point.Point, pointset.PointSet, Nifti1Image],
+        minsize_voxel=1,
+        lower_threshold=0.0
+    ) -> List[Union[Assignment,AssignImageResult]]:
+        """
+        For internal use only. Returns a dataclass, which provides better static type checking.
+        """
+        
+        if isinstance(item, point.Point):
+            return self._assign_points(pointset.PointSet([item], item.space, sigma_mm=item.sigma), lower_threshold)
+        if isinstance(item, pointset.PointSet):
+            return self._assign_points(item, lower_threshold)
+        if isinstance(item, Nifti1Image):
+            return self._assign_image(item, minsize_voxel, lower_threshold)
+        
+        raise RuntimeError(
+            f"Items of type {item.__class__.__name__} cannot be used for region assignment."
+        )
 
     def assign(
         self,
@@ -800,16 +835,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             a Point or PointSet, returns None.
         """
 
-        if isinstance(item, point.Point):
-            assignments = self._assign_points(pointset.PointSet([item], item.space, sigma_mm=item.sigma), lower_threshold)
-        elif isinstance(item, pointset.PointSet):
-            assignments = self._assign_points(item, lower_threshold)
-        elif isinstance(item, Nifti1Image):
-            assignments = self._assign_image(item, minsize_voxel, lower_threshold)
-        else:
-            raise RuntimeError(
-                f"Items of type {item.__class__.__name__} cannot be used for region assignment."
-            )
+        assignments = self._assign(item, minsize_voxel, lower_threshold)
 
         # format assignments as pandas dataframe
         columns = [
@@ -827,50 +853,82 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             "input containedness"
         ]
         if len(assignments) == 0:
-            df = pd.DataFrame(columns=columns)
-        else:
-
-            # determine the unique set of observed indices in order to do region lookups
-            # only once for each map index occuring in the point list
-            labelled = self.is_labelled  # avoid calling this in a loop
-            observed_indices = {  # unique set of observed map indices. NOTE: len(observed_indices) << len(assignments)
-                (
-                    a.get('volume'),
-                    a.get('fragment'),
-                    a.get('map value') if labelled else None
-                )
-                for a in assignments
-            }
-            region_lut = {  # lookup table of observed region objects
-                (v, f, l): self.get_region(
-                    index=MapIndex(
-                        volume=int(v),
-                        label=l if l is None else int(l),
-                        fragment=f
-                    )
+            return pd.DataFrame(columns=columns)
+        # determine the unique set of observed indices in order to do region lookups
+        # only once for each map index occuring in the point list
+        labelled = self.is_labelled  # avoid calling this in a loop
+        observed_indices = {  # unique set of observed map indices. NOTE: len(observed_indices) << len(assignments)
+            (
+                a.volume,
+                a.fragment,
+                a.map_value if labelled else None
+            )
+            for a in assignments
+        }
+        region_lut = {  # lookup table of observed region objects
+            (v, f, l): self.get_region(
+                index=MapIndex(
+                    volume=int(v),
+                    label=l if l is None else int(l),
+                    fragment=f
                 )
-                for v, f, l in observed_indices
-            }
-
-            for a in assignments:
-                a["region"] = region_lut[
-                    a.get('volume'),
-                    a.get('fragment'),
-                    a.get('map value') if labelled else None
-                ]
-                a['map containedness'] = a.pop('intersection over first', None)
-                a['input containedness'] = a.pop('intersection over second', None)
-                a['map weighted mean'] = a.pop('weighted mean of first', None)
-                a['input weighted mean'] = a.pop('weighted mean of second', None)
-            df = pd.DataFrame(assignments)
+            )
+            for v, f, l in observed_indices
+        }
 
+        dataframe_list = []
+        for a in assignments:
+            item_to_append = {
+                "input structure": a.input_structure,
+                "centroid": a.centroid,
+                "volume": a.volume,
+                "fragment": a.fragment,
+                "region": region_lut[
+                    a.volume,
+                    a.fragment,
+                    a.map_value if labelled else None
+                ],
+            }
+            # because AssignImageResult is a subclass of Assignment
+            # need to check for isinstance AssignImageResult first
+            if isinstance(a, AssignImageResult):
+                item_to_append = {
+                    **item_to_append,
+                    **{
+                        "correlation": a.correlation,
+                        "intersection over union": a.intersection_over_union,
+                        "map value": a.map_value,
+                        "map weighted mean": a.weighted_mean_of_first,
+                        "map containedness": a.intersection_over_first,
+                        "input weighted mean": a.weighted_mean_of_second,
+                        "input containedness": a.intersection_over_second,
+                    }
+                }
+            elif isinstance(a, Assignment):
+                item_to_append = {
+                    **item_to_append,
+                    **{
+                        "correlation": None,
+                        "intersection over union": None,
+                        "map value": None,
+                        "map weighted mean": None,
+                        "map containedness": None,
+                        "input weighted mean": None,
+                        "input containedness": None,
+                    }
+                }
+            else:
+                raise RuntimeError(f"assignments must be of type Assignment or AssignImageResult!")
+            
+            dataframe_list.append(item_to_append)
+        df = pd.DataFrame(dataframe_list)
         return (
             df
             .convert_dtypes()  # convert will guess numeric column types
             .reindex(columns=columns)
         )
 
-    def _assign_points(self, points, lower_threshold: float):
+    def _assign_points(self, points:pointset.PointSet, lower_threshold: float) -> List[Assignment]:
         """
         assign a PointSet to this parcellation map.
 
@@ -904,20 +962,20 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                     if value > lower_threshold:
                         position = pts_warped[pointindex].coordinate
                         assignments.append(
-                            {
-                                "input structure": pointindex,
-                                "centroid": tuple(np.array(position).round(2)),
-                                "volume": vol,
-                                "fragment": frag,
-                                "map value": value
-                            }
+                            Assignment(
+                                input_structure=pointindex,
+                                centroid=tuple(np.array(position).round(2)),
+                                volume=vol,
+                                fragment=frag,
+                                map_value=value
+                            )
                         )
                 return assignments
 
         # if we get here, we need to handle each point independently.
         # This is much slower but more precise in dealing with the uncertainties
         # of the coordinates.
-        for pointindex, pt in tqdm(
+        for pointindex, pt in siibra_tqdm(
             enumerate(points.warp(self.space.id)),
             total=len(points), desc="Warping points",
         ):
@@ -931,13 +989,13 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                 for _, vol, frag, value in values:
                     if value > lower_threshold:
                         assignments.append(
-                            {
-                                "input structure": pointindex,
-                                "centroid": tuple(pt),
-                                "volume": vol,
-                                "fragment": frag,
-                                "map value": value
-                            }
+                            Assignment(
+                                input_structure=pointindex,
+                                centroid=tuple(pt),
+                                volume=vol,
+                                fragment=frag,
+                                map_value=value
+                            )
                         )
             else:
                 logger.info(
@@ -951,13 +1009,13 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                 # build niftiimage with the Gaussian blob,
                 # then recurse into this method with the image input
                 W = Nifti1Image(dataobj=kernel, affine=np.dot(self.affine, shift))
-                for entry in self.assign(W, lower_threshold=lower_threshold).T.to_dict().values():
-                    entry["input structure"] = pointindex
-                    entry["centroid"] = tuple(pt)
+                for entry in self._assign(W, lower_threshold=lower_threshold):
+                    entry.input_structure=pointindex
+                    entry.centroid=tuple(pt)
                     assignments.append(entry)
         return assignments
 
-    def _assign_image(self, queryimg: Nifti1Image, minsize_voxel: int, lower_threshold: float):
+    def _assign_image(self, queryimg: Nifti1Image, minsize_voxel: int, lower_threshold: float) -> List[AssignImageResult]:
         """
         Assign an image volume to this parcellation map.
 
@@ -991,7 +1049,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             # but only if the sequence is long.
             seqlen = N or len(it)
             return iter(it) if seqlen < min_elements \
-                else tqdm(it, desc=desc, total=N)
+                else siibra_tqdm(it, desc=desc, total=N)
 
         with QUIET and _volume.SubvolumeProvider.UseCaching():
             for frag in self.fragments or {None}:
@@ -1012,14 +1070,16 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                             targetimg = vol_img if label is None \
                                 else Nifti1Image((vol_data == label).astype('uint8'), vol_img.affine)
                             scores = compare_maps(maskimg, targetimg)
-                            if scores["intersection over union"] > 0:
-                                info = {
-                                    "input structure": mode,
-                                    "centroid": tuple(position.round(2)),
-                                    "volume": vol,
-                                    "fragment": frag,
-                                    "map value": label
-                                }
-                                assignments.append(dict(**info, **scores))
+                            if scores.intersection_over_union > 0:
+                                assignments.append(
+                                    AssignImageResult(
+                                        input_structure=mode,
+                                        centroid=tuple(position.round(2)),
+                                        volume=vol,
+                                        fragment=frag,
+                                        map_value=label,
+                                        **asdict(scores)
+                                    )
+                                )
 
         return assignments

siibra/volumes/sparsemap.py

@@ -15,16 +15,15 @@
 """Represents lists of probabilistic brain region maps."""
 from . import parcellationmap, volume as _volume
 
-from ..commons import MapIndex, logger, iterate_connected_components
+from ..commons import MapIndex, logger, iterate_connected_components, siibra_tqdm
 from ..locations import boundingbox
 from ..retrieval import cache
 
 from os import path
 import gzip
-from typing import Dict, Union, TYPE_CHECKING
+from typing import Dict, Union, TYPE_CHECKING, List
 from nilearn import image
 from nibabel import Nifti1Image, load
-from tqdm import tqdm
 import numpy as np
 
 if TYPE_CHECKING:
@@ -163,12 +162,11 @@ class SparseIndex:
 
         with gzip.open(probsfile, "rt") as f:
             lines = f.readlines()
-            for line in tqdm(
+            for line in siibra_tqdm(
                 lines,
                 total=len(lines),
                 desc="Loading sparse index",
-                unit="voxels",
-                disable=logger.level > 20,
+                unit="voxels"
             ):
                 fields = line.strip().split(" ")
                 mapindices = list(map(int, fields[0::2]))
@@ -247,15 +245,14 @@ class SparseMap(parcellationmap.Map):
     @property
     def sparse_index(self):
         if self._sparse_index_cached is None:
-            prefix = f"{self.parcellation.id}_{self.space.id}_{self.maptype}_index"
+            prefix = f"{self.parcellation.id}_{self.space.id}_{self.maptype}_{self.name}_index"
             spind = SparseIndex.from_cache(prefix)
-            with _volume.SubvolumeProvider.UseCaching():
-                if spind is None:
+            if spind is None:
+                with _volume.SubvolumeProvider.UseCaching():
                     spind = SparseIndex()
-                    for vol in tqdm(
+                    for vol in siibra_tqdm(
                         range(len(self)), total=len(self), unit="maps",
-                        desc=f"Fetching {len(self)} volumetric maps",
-                        disable=logger.level > 20,
+                        desc=f"Fetching {len(self)} volumetric maps"
                     ):
                         img = super().fetch(
                             index=MapIndex(volume=vol, label=None)
@@ -265,8 +262,8 @@ class SparseMap(parcellationmap.Map):
                             logger.error(f"Cannot retrieve volume #{vol} for {region.name}, it will not be included in the sparse map.")
                             continue
                         spind.add_img(img)
-                spind.to_cache(prefix)
-                self._sparse_index_cached = spind
+                    spind.to_cache(prefix)
+            self._sparse_index_cached = spind
         assert self._sparse_index_cached.max() == len(self._sparse_index_cached.probs) - 1
         return self._sparse_index_cached
 
@@ -365,7 +362,7 @@ class SparseMap(parcellationmap.Map):
                 for volume, value in spind.probs[voxel].items()
             )
 
-    def _assign_image(self, queryimg: Nifti1Image, minsize_voxel: int, lower_threshold: float):
+    def _assign_image(self, queryimg: Nifti1Image, minsize_voxel: int, lower_threshold: float) -> List[parcellationmap.AssignImageResult]:
         """
         Assign an image volume to this parcellation map.
 
@@ -416,12 +413,11 @@ class SparseMap(parcellationmap.Map):
 
             spind = self.sparse_index
 
-            for volume in tqdm(
+            for volume in siibra_tqdm(
                 range(len(self)),
                 desc=f"Assigning structure #{mode} to {len(self)} sparse maps",
                 total=len(self),
-                unit=" map",
-                disable=logger.level > 20,
+                unit=" map"
             ):
                 bbox1 = boundingbox.BoundingBox(
                     self.sparse_index.bboxes[volume]["minpoint"],
@@ -475,19 +471,19 @@ class SparseMap(parcellationmap.Map):
                 maxval = v1.max()
 
                 assignments.append(
-                    {
-                        "input structure": mode,
-                        "centroid": tuple(position.round(2)),
-                        "volume": volume,
-                        "fragment": None,
-                        "map value": maxval,
-                        "intersection over union": iou,
-                        "intersection over first": intersection / (v1 > 0).sum(),
-                        "intersection over second": intersection / (v2 > 0).sum(),
-                        "correlation": rho,
-                        "weighted mean of first": np.sum(v1 * v2) / np.sum(v2),
-                        "weighted mean of second": np.sum(v1 * v2) / np.sum(v1)
-                    }
+                    parcellationmap.AssignImageResult(
+                        input_structure=mode,
+                        centroid=tuple(position.round(2)),
+                        volume=volume,
+                        fragment=None,
+                        map_value=maxval,
+                        intersection_over_union=iou,
+                        intersection_over_first=intersection / (v1 > 0).sum(),
+                        intersection_over_second=intersection / (v2 > 0).sum(),
+                        correlation=rho,
+                        weighted_mean_of_first=np.sum(v1 * v2) / np.sum(v2),
+                        weighted_mean_of_second=np.sum(v1 * v2) / np.sum(v1)
+                    )
                 )
 
         return assignments

siibra/volumes/volume.py

@@ -84,7 +84,7 @@ class Volume:
         def concat(url: Union[str, Dict[str, str]], concat: str):
             if isinstance(url, str):
                 return url + concat
-            return { key: url[key] + concat for key in url }
+            return {key: url[key] + concat for key in url}
         return {
             srctype: concat(prov._url, f" {prov.label}" if hasattr(prov, "label") else "")
             for srctype, prov in self._providers.items()

{siibra-0.4a35.dist-info → siibra-0.4a46.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: siibra
-Version: 0.4a35
+Version: 0.4a46
 Summary: siibra - Software interfaces for interacting with brain atlases
 Home-page: https://github.com/FZJ-INM1-BDA/siibra-python
 Author: Big Data Analytics Group, Forschungszentrum Juelich, Institute of Neuroscience and Medicine (INM-1)
@@ -22,6 +22,7 @@ Requires-Dist: scikit-image
 Requires-Dist: requests
 Requires-Dist: neuroglancer-scripts
 Requires-Dist: nilearn
+Requires-Dist: filelock
 Requires-Dist: typing-extensions ; python_version < "3.8"
 
 |License| |PyPI version| |Python versions| |Documentation Status|