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

siibra/volumes/parcellationmap.py

@@ -16,36 +16,58 @@
 
 from . import volume as _volume, nifti
 from .. import logger, QUIET
-from ..commons import MapIndex, MapType, compare_maps, clear_name, create_key, create_gaussian_kernel, Species
+from ..commons import (
+    MapIndex,
+    MapType,
+    compare_maps,
+    iterate_connected_components,
+    clear_name,
+    create_key,
+    create_gaussian_kernel,
+    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
+
+@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"):
 
     def __init__(
@@ -67,9 +89,9 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
 
         Parameters
         ----------
-        identifier : str
+        identifier: str
             Unique identifier of the parcellation
-        name : str
+        name: str
             Human-readable name of the parcellation
         space_spec: dict
             Specification of the space (use @id or name fields)
@@ -81,18 +103,18 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             Per region name, a list of dictionaries with fields "volume" and "label" is expected,
             where "volume" points to the index of the Volume object where this region is mapped,
             and optional "label" is the voxel label for that region.
-            For contiuous / probability maps, the "label" can be null or omitted.
+            For continuous / probability maps, the "label" can be null or omitted.
             For single-volume labelled maps, the "volume" can be null or omitted.
-        volumes: list of Volume
+        volumes: list[Volume]
             parcellation volumes
-        shortname: str
-            Shortform of human-readable name (optional)
-        description: str
+        shortname: str, optional
+            Shortform of human-readable name
+        description: str, optional
             Textual description of the parcellation
-        modality  :  str or None
+        modality: str, default: 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 concept
         """
@@ -144,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
@@ -155,28 +180,53 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
 
     def get_index(self, region: Union[str, "Region"]):
         """
-        Returns the unique index corresponding to the specified region,
-        assuming that the specification matches one unique region
-        defined in this parcellation map.
-        If not unique, or not defined, an exception will be thrown.
-        See find_indices() for a less strict search returning all matches.
+        Returns the unique index corresponding to the specified region.
+
+        Tip
+        ----
+        Use find_indices() method for a less strict search returning all matches.
+
+        Parameters
+        ----------
+        region: str or Region
+
+        Returns
+        -------
+        MapIndex
+
+        Raises
+        ------
+        NonUniqueIndexError
+            If not unique or not defined in this parcellation map.
         """
         matches = self.find_indices(region)
         if len(matches) > 1:
-            raise RuntimeError(
+            raise NonUniqueIndexError(
                 f"The specification '{region}' matches multiple mapped "
                 f"structures in {str(self)}: {list(matches.values())}"
             )
         elif len(matches) == 0:
-            raise RuntimeError(
+            raise NonUniqueIndexError(
                 f"The specification '{region}' does not match to any structure mapped in {self}"
             )
         else:
             return next(iter(matches))
 
     def find_indices(self, region: Union[str, "Region"]):
-        """ Returns the volume/label indices in this map
-        which match the given region specification"""
+        """
+        Returns the volume/label indices in this map which match the given
+        region specification.
+
+        Parameters
+        ----------
+        region: str or Region
+
+        Returns
+        -------
+        dict
+            - keys: MapIndex
+            - values: region name
+        """
         if region in self._indices:
             return {
                 idx: region
@@ -186,15 +236,34 @@ 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
             for idx in self._indices[regionname]
         }
 
-    def get_region(self, label: int = None, volume: int = None, index: MapIndex = None):
-        """ Returns the region mapped by the given index, if any. """
+    def get_region(self, label: int = None, volume: int = 0, index: MapIndex = None):
+        """
+        Returns the region mapped by the given index, if any.
+
+        Tip
+        ----
+        Use get_index() or find_indices() methods to obtain the MapIndex.
+
+        Parameters
+        ----------
+        label: int, default: None
+        volume: int, default: 0
+        index: MapIndex, default: None
+
+        Returns
+        -------
+        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 = [
@@ -203,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):
@@ -223,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}"
         )
@@ -232,8 +301,8 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
     @property
     def labels(self):
         """
-        The set of all label indices defined in this map,
-        including "None" if not defined for one or more regions.
+        The set of all label indices defined in this map, including "None" if
+        not defined for one or more regions.
         """
         return {d.label for v in self._indices.values() for d in v}
 
@@ -265,26 +334,41 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
     ):
         """
         Fetches one particular volume of this parcellation map.
+
         If there's only one volume, this is the default, otherwise further
-        specication is requested:
+        specification is requested:
         - the volume index,
         - the MapIndex (which results in a regional map being returned)
 
-        You might also consider fetch_iter() to iterate the volumes, or compress()
-        to produce a single-volume parcellation map.
+        You might also consider fetch_iter() to iterate the volumes, or
+        compress() to produce a single-volume parcellation map.
 
         Parameters
         ----------
-        region_or_index: Union[str, Region, MapIndex]
+        region_or_index: str, Region, MapIndex
             Lazy match the specification.
         index: MapIndex
             Explicit specification of the map index, typically resulting
             in a regional map (mask or statistical map) to be returned.
             Note that supplying 'region' will result in retrieving the map index of that region
             automatically.
-        region: Union[str, Region]
+        region: str, Region
             Specification of a region name, resulting in a regional map
             (mask or statistical map) to be returned.
+        **kwargs
+            - resolution_mm: resolution in millimeters
+            - format: the format of the volume, like "mesh" or "nii"
+            - voi: a BoundingBox of interest
+
+
+            Note
+            ----
+            Not all keyword arguments are supported for volume formats. Format
+            is restricted by available formats (check formats property).
+
+        Returns
+        -------
+        An image or mesh
         """
         try:
             length = len([arg for arg in [region_or_index, region, index] if arg is not None])
@@ -340,13 +424,14 @@ 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):
         """
         Returns an iterator to fetch all mapped volumes sequentially.
-        All arguments are passed on to func:`~siibra.Map.fetch`
+
+        All arguments are passed on to function Map.fetch().
         """
         fragment = kwargs.pop('fragment') if 'fragment' in kwargs else None
         return (
@@ -403,9 +488,17 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
 
     def compress(self, **kwargs):
         """
-        Converts this map into a labelled 3D parcellation map, obtained
-        by taking the voxelwise maximum across the mapped volumes, and
-        re-labelling regions sequentially.
+        Converts this map into a labelled 3D parcellation map, obtained by
+        taking the voxelwise maximum across the mapped volumes and fragments,
+        and re-labelling regions sequentially.
+
+        Paramaters
+        ----------
+        **kwargs: Takes the fetch arguments of its space's template.
+
+        Returns
+        -------
+        parcellationmap.Map
         """
         if len(self.volumes) == 1 and (self.fragments is None):
             raise RuntimeError("The map cannot be merged since there are no multiple volumes or fragments.")
@@ -419,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)
@@ -446,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:
@@ -474,13 +567,18 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
     def compute_centroids(self) -> Dict[str, point.Point]:
         """
         Compute a dictionary of the centroids of all regions in this map.
+
+        Returns
+        -------
+        Dict[str, point.Point]
+            Region names as keys and computed centroids as items.
         """
         centroids = {}
         # list of regions sorted by mapindex
         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:
@@ -498,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
@@ -512,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)
@@ -537,17 +635,14 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         """
         Generate a matplotlib colormap from known rgb values of label indices.
 
-        The probability distribution is approximated from the region mask
-        based on the squared distance transform.
-
         Parameters
         ----------
-        region_specs: An iterable selection of regions
+        region_specs: iterable(regions), optional
             Optional parameter to only color the desired regions.
 
-        Return
-        ------
-        samples : PointSet in physcial coordinates corresponding to this parcellationmap.
+        Returns
+        -------
+        ListedColormap
         """
         from matplotlib.colors import ListedColormap
         import numpy as np
@@ -583,18 +678,21 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
     def sample_locations(self, regionspec, numpoints: int):
         """ Sample 3D locations inside a given region.
 
-        The probability distribution is approximated from the region mask
-        based on the squared distance transform.
+        The probability distribution is approximated from the region mask based
+        on the squared distance transform.
 
-        regionspec: valid region specification
+        Parameters
+        ----------
+        regionspec: Region or str
             Region to be used
         numpoints: int
             Number of samples to draw
 
-        Return
-        ------
-        samples : PointSet in physcial coordinates corresponding to this parcellationmap.
-
+        Returns
+        -------
+        PointSet
+            Sample points in physcial coordinates corresponding to this
+            parcellationmap
         """
         index = self.get_index(regionspec)
         mask = self.fetch(index=index)
@@ -612,23 +710,14 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         XYZ = np.dot(mask.affine, np.c_[XYZ_, np.ones(numpoints)].T)[:3, :].T
         return pointset.PointSet(XYZ, space=self.space)
 
-    @staticmethod
-    def iterate_connected_components(img: Nifti1Image):
-        """
-        Provide an iterator over masks of connected components in the given image.
+    def to_sparse(self):
         """
-        from skimage import measure
-        imgdata = np.asanyarray(img.dataobj).squeeze()
-        components = measure.label(imgdata > 0)
-        component_labels = np.unique(components)
-        assert component_labels[0] == 0
-        return (
-            (label, Nifti1Image((components == label).astype('uint8'), img.affine))
-            for label in component_labels[1:]
-        )
+        Creates a SparseMap object from this parcellation map object.
 
-    def to_sparse(self):
-        """ Creates a sparse parcellation map from this object. """
+        Returns
+        -------
+        SparseMap
+        """
         from .sparsemap import SparseMap
         indices = {
             regionname: [
@@ -672,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,
@@ -686,99 +796,139 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
 
         Parameters
         ----------
-        item: Point, PointSet, or Nifti1Image
-            A spatial object defined in the same physical reference space as this
-            parcellation map, which could be a point, set of points, or image.
-            If it is an image, it will be resampled to the same voxel space if its affine
-            transforation differs from that of the parcellation map.
-            Resampling will use linear interpolation for float image types,
-            otherwise nearest neighbor.
+        item: Point, PointSet, Nifti1Image
+            A spatial object defined in the same physical reference space as
+            this parcellation map, which could be a point, set of points, or
+            image. If it is an image, it will be resampled to the same voxel
+            space if its affine transformation differs from that of the
+            parcellation map. Resampling will use linear interpolation for float
+            image types, otherwise nearest neighbor.
         minsize_voxel: int, default: 1
             Minimum voxel size of image components to be taken into account.
         lower_threshold: float, default: 0
-            Lower threshold on values in the statistical map. Values smaller than
-            this threshold will be excluded from the assignment computation.
-
-        Return
-        ------
-        assignments : pandas Dataframe
-            A table of associated regions and their scores per component found in the input image,
-            or per coordinate provived.
-            The scores are:
-                - Value: Maximum value of the voxels in the map covered by an input coordinate or
-                  input image signal component.
-                - Pearson correlation coefficient between the brain region map and an input image signal
-                  component (NaN for exact coordinates)
-                - "Contains": Percentage of the brain region map contained in an input image signal component,
-                  measured from their binarized masks as the ratio between the volume of their interesection
-                  and the volume of the brain region (NaN for exact coordinates)
-                - "Contained"": Percentage of an input image signal component contained in the brain region map,
-                  measured from their binary masks as the ratio between the volume of their interesection
-                  and the volume of the input image signal component (NaN for exact coordinates)
-        components: Nifti1Image, or None
-            If the input was an image, this is a labelled volume mapping the detected components
-            in the input image, where pixel values correspond to the "component" column of the
-            assignment table. If the input was a Point or PointSet, this is None.
+            Lower threshold on values in the statistical map. Values smaller
+            than this threshold will be excluded from the assignment computation.
+
+        Returns
+        -------
+        assignments: pandas.DataFrame
+            A table of associated regions and their scores per component found
+            in the input image, or per coordinate provided. The scores are:
+
+                - Value: Maximum value of the voxels in the map covered by an
+                input coordinate or input image signal component.
+                - Pearson correlation coefficient between the brain region map
+                and an input image signal component (NaN for exact coordinates)
+                - Contains: Percentage of the brain region map contained in an
+                input image signal component, measured from their binarized
+                masks as the ratio between the volume of their intersection
+                and the volume of the brain region (NaN for exact coordinates)
+                - Contained: Percentage of an input image signal component
+                contained in the brain region map, measured from their binary
+                masks as the ratio between the volume of their intersection and
+                the volume of the input image signal component (NaN for exact
+                coordinates)
+        components: Nifti1Image or None
+            If the input was an image, this is a labelled volume mapping the
+            detected components in the input image, where pixel values correspond
+            to the "component" column of the assignment table. If the input was
+            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 = [
+            "input structure",
+            "centroid",
+            "volume",
+            "fragment",
+            "region",
+            "correlation",
+            "intersection over union",
+            "map value",
+            "map weighted mean",
+            "map containedness",
+            "input weighted mean",
+            "input containedness"
+        ]
         if len(assignments) == 0:
-            df = pd.DataFrame(
-                columns=["Structure", "Centroid", "Volume", "Fragment", "Region", "Value", "Correlation", "IoU", "Contains", "Contained"]
+            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
             )
-        else:
-            result = np.array(assignments, dtype=object)
-            ind = np.lexsort((-result[:, -1].astype('float'), result[:, 0].astype('float')))
-
-            # 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 long loop
-
-            def format_label(label):
-                return int(label) if (label != 'nan') and (labelled) else None
-
-            observed_indices = {
-                (v, f, format_label(l))
-                for _, _, v, f, l, _, _, _, _ in result[ind]
-            }
-            region_lut = {
-                (v, f, l): self.get_region(
-                    index=MapIndex(volume=int(v), label=format_label(l), fragment=f)
+            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
-            }
-            regions = [
-                region_lut[v, f, format_label(l)] for _, _, v, f, l, _, _, _, _ in result[ind]
-            ]
-            df = pd.DataFrame(
-                {
-                    "Structure": result[ind, 0].astype("int"),
-                    "Centroid": result[ind, 1],
-                    "Volume": result[ind, 2].astype("int"),
-                    "Fragment": result[ind, 3],
-                    "Region": regions,
-                    "Value": result[ind, 4],
-                    "Correlation": result[ind, 8],
-                    "IoU": result[ind, 5],
-                    "Contains": result[ind, 7],
-                    "Contained": result[ind, 6],
-                }
             )
+            for v, f, l in observed_indices
+        }
 
-        return df.convert_dtypes()  # convert will guess numeric column types
+        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.
 
@@ -812,14 +962,20 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                     if value > lower_threshold:
                         position = pts_warped[pointindex].coordinate
                         assignments.append(
-                            [pointindex, tuple(np.array(position).round(2)), vol, frag, value, np.nan, np.nan, np.nan, np.nan]
+                            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",
         ):
@@ -833,7 +989,13 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                 for _, vol, frag, value in values:
                     if value > lower_threshold:
                         assignments.append(
-                            [pointindex, tuple(pt), vol, frag, value, np.nan, np.nan, np.nan, np.nan]
+                            Assignment(
+                                input_structure=pointindex,
+                                centroid=tuple(pt),
+                                volume=vol,
+                                fragment=frag,
+                                map_value=value
+                            )
                         )
             else:
                 logger.info(
@@ -847,16 +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))
-                T = self.assign(W, lower_threshold=lower_threshold)
-                assignments.extend(
-                    [
-                        [pointindex, tuple(pt), volume, fragment, value, iou, contained, contains, rho]
-                        for (_, _, volume, fragment, _, value, rho, iou, contains, contained) in T.values
-                    ]
-                )
+                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.
 
@@ -890,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}:
@@ -900,7 +1059,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                     desc=f"Assigning to {len(self)} volumes"
                 ):
                     queryimg_res = resample(queryimg, vol_img.affine, vol_img.shape)
-                    for mode, maskimg in Map.iterate_connected_components(queryimg_res):
+                    for mode, maskimg in iterate_connected_components(queryimg_res):
                         vol_data = np.asanyarray(vol_img.dataobj)
                         position = np.array(np.where(maskimg.get_fdata())).T.mean(0)
                         labels = {v.label for L in self._indices.values() for v in L if v.volume == vol}
@@ -911,18 +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["IoU"] > 0:
+                            if scores.intersection_over_union > 0:
                                 assignments.append(
-                                    [
-                                        mode,
-                                        tuple(position.round(2)),
-                                        vol,
-                                        frag,
-                                        label,
-                                        scores["IoU"],
-                                        scores["contained"],
-                                        scores["contains"],
-                                        scores["correlation"]]
+                                    AssignImageResult(
+                                        input_structure=mode,
+                                        centroid=tuple(position.round(2)),
+                                        volume=vol,
+                                        fragment=frag,
+                                        map_value=label,
+                                        **asdict(scores)
+                                    )
                                 )
 
         return assignments