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

siibra/volumes/parcellationmap.py

@@ -1,4 +1,4 @@
-# Copyright 2018-2021
+# Copyright 2018-2024
 # Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
 
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,29 +14,30 @@
 # limitations under the License.
 """Provides spatial representations for parcellations and regions."""
 
-from . import volume as _volume, nifti
-from .. import logger, QUIET
+from . import volume as _volume
+from .providers import provider
+from .. import logger, QUIET, exceptions
 from ..commons import (
     MapIndex,
     MapType,
-    compare_maps,
-    iterate_connected_components,
+    compare_arrays,
+    resample_img_to_img,
+    connected_components,
     clear_name,
     create_key,
     create_gaussian_kernel,
     siibra_tqdm,
     Species,
-    CompareMapsResult
+    CompareMapsResult,
+    generate_uuid
 )
 from ..core import concept, space, parcellation, region as _region
-from ..locations import point, pointset
-from ..retrieval import requests
+from ..locations import location, point, pointcloud
 
 import numpy as np
 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
@@ -45,31 +46,18 @@ if TYPE_CHECKING:
     from ..core.region import Region
 
 
-class ExcessiveArgumentException(ValueError): pass
-
-
-class InsufficientArgumentException(ValueError): pass
-
-
-class ConflictingArgumentException(ValueError): pass
-
-
-class NonUniqueIndexError(RuntimeError): pass
-
-
-class NoVolumeFound(RuntimeError): pass
-
 @dataclass
-class Assignment:
+class MapAssignment:
     input_structure: int
-    centroid: Union[Tuple[np.ndarray], point.Point] 
+    centroid: Union[Tuple[np.ndarray], point.Point]
     volume: int
     fragment: str
     map_value: np.ndarray
 
 
 @dataclass
-class AssignImageResult(CompareMapsResult, Assignment): pass
+class AssignImageResult(CompareMapsResult, MapAssignment):
+    pass
 
 
 class Map(concept.AtlasConcept, configuration_folder="maps"):
@@ -80,13 +68,14 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         name: str,
         space_spec: dict,
         parcellation_spec: dict,
-        indices: Dict[str, Dict],
+        indices: Dict[str, List[Dict]],
         volumes: list = [],
         shortname: str = "",
         description: str = "",
         modality: str = None,
         publications: list = [],
         datasets: list = [],
+        prerelease: bool = False,
     ):
         """
         Constructs a new parcellation object.
@@ -131,8 +120,11 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             description=description,
             publications=publications,
             datasets=datasets,
-            modality=modality
+            modality=modality,
+            prerelease=prerelease,
         )
+        self._space_spec = space_spec
+        self._parcellation_spec = parcellation_spec
 
         # Since the volumes might include 4D arrays, where the actual
         # volume index points to a z coordinate, we create subvolume
@@ -165,15 +157,12 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         duplicates = {x for x in all_indices if x in seen or seen.add(x)}
         if len(duplicates) > 0:
             logger.warning(f"Non unique indices encountered in {self}: {duplicates}")
-
-        self._space_spec = space_spec
-        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
+    def key(self):
+        _id = self.id
+        return create_key(_id[len("siibra-map-v0.0.1"):])
 
     @property
     def species(self) -> Species:
@@ -205,12 +194,18 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         """
         matches = self.find_indices(region)
         if len(matches) > 1:
-            raise NonUniqueIndexError(
+            # if there is an exact match, we still use it. If not, we cannot proceed.
+            regionname = region.name if isinstance(region, _region.Region) \
+                else region
+            for index, matched_name in matches.items():
+                if matched_name == regionname:
+                    return index
+            raise exceptions.NonUniqueIndexError(
                 f"The specification '{region}' matches multiple mapped "
                 f"structures in {str(self)}: {list(matches.values())}"
             )
         elif len(matches) == 0:
-            raise NonUniqueIndexError(
+            raise exceptions.NonUniqueIndexError(
                 f"The specification '{region}' does not match to any structure mapped in {self}"
             )
         else:
@@ -328,69 +323,27 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
     def regions(self):
         return list(self._indices)
 
-    def fetch(
+    def get_volume(
         self,
-        region_or_index: Union[str, "Region", MapIndex] = None,
+        region: Union[str, "Region"] = None,
         *,
         index: MapIndex = None,
-        region: Union[str, "Region"] = None,
-        **kwargs
-    ):
-        """
-        Fetches one particular volume of this parcellation map.
-
-        If there's only one volume, this is the default, otherwise further
-        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.
-
-        Parameters
-        ----------
-        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: 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
-        """
+        **kwargs,
+    ) -> Union[_volume.Volume, _volume.FilteredVolume, _volume.Subvolume]:
         try:
-            length = len([arg for arg in [region_or_index, region, index] if arg is not None])
+            length = len([arg for arg in [region, index] if arg is not None])
             assert length == 1
         except AssertionError:
             if length > 1:
-                raise ExcessiveArgumentException("One and only one of region_or_index, region, index can be defined for fetch")
-            # user can provide no arguments, which assumes one and only one volume present
-
-        if isinstance(region_or_index, MapIndex):
-            index = region_or_index
-
-        if isinstance(region_or_index, (str, _region.Region)):
-            region = region_or_index
-
+                raise exceptions.ExcessiveArgumentException(
+                    "One and only one of region or index can be defined for `get_volume`."
+                )
         mapindex = None
         if region is not None:
-            assert isinstance(region, (str, _region.Region))
+            try:
+                assert isinstance(region, (str, _region.Region))
+            except AssertionError:
+                raise TypeError(f"Please provide a region name or region instance, not a {type(region)}")
             mapindex = self.get_index(region)
         if index is not None:
             assert isinstance(index, MapIndex)
@@ -399,34 +352,21 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             if len(self) == 1:
                 mapindex = MapIndex(volume=0, label=None)
             elif len(self) > 1:
+                assert self.maptype == MapType.LABELLED, f"Cannot merge multiple volumes of map type {self.maptype}. Please specify a region or index."
                 logger.info(
                     "Map provides multiple volumes and no specification is"
-                    "provided. Resampling all volumes to the space."
-                )
-                resolution = kwargs.get("resolution_mm")
-                template = self.space.get_template().fetch(
-                    resolution_mm=resolution
+                    " provided. Resampling all volumes to the space."
                 )
-                aggregated_volume = np.zeros(template.shape, dtype='uint8')
-                for i, region in siibra_tqdm(
-                    enumerate(self.regions),
-                    unit=" volume", desc="Fetching", total=len(self)
-                ):
-                    regionlabel = i + 1
-                    regionmap = image.resample_to_img(
-                        self.fetch(region=region, resolution_mm=resolution),
-                        template,
-                        interpolation='nearest'
-                    )
-                    aggregated_volume[regionmap.get_fdata() > 0] = regionlabel
-                return Nifti1Image(aggregated_volume, affine=template.affine)
+                labels = list(range(len(self.volumes)))
+                merged_volume = _volume.merge(self.volumes, labels, **kwargs)
+                return merged_volume
             else:
-                raise NoVolumeFound("Map provides no volumes.")
+                raise exceptions.NoVolumeFound("Map provides no volumes.")
 
         kwargs_fragment = kwargs.pop("fragment", None)
         if kwargs_fragment is not None:
             if (mapindex.fragment is not None) and (kwargs_fragment != mapindex.fragment):
-                raise ConflictingArgumentException(
+                raise exceptions.ConflictingArgumentException(
                     "Conflicting specifications for fetching volume fragment: "
                     f"{mapindex.fragment} / {kwargs_fragment}"
                 )
@@ -438,28 +378,74 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             raise IndexError(
                 f"{self} provides {len(self)} mapped volumes, but #{mapindex.volume} was requested."
             )
-        try:
-            result = self.volumes[mapindex.volume or 0].fetch(
-                fragment=mapindex.fragment, label=mapindex.label, **kwargs
-            )
-        except requests.SiibraHttpRequestError as e:
-            print(str(e))
+        if mapindex.label is None and mapindex.fragment is None:
+            return self.volumes[mapindex.volume]
+
+        return _volume.FilteredVolume(
+            parent_volume=self.volumes[mapindex.volume],
+            label=mapindex.label,
+            fragment=mapindex.fragment,
+        )
+
+    def fetch(
+        self,
+        region: Union[str, "Region"] = None,
+        *,
+        index: MapIndex = None,
+        **fetch_kwargs
+    ):
+        """
+        Fetches one particular volume of this parcellation map.
+
+        If there's only one volume, this is the default, otherwise further
+        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.
+
+        Parameters
+        ----------
+        region: str, Region
+            Specification of a region name, resulting in a regional map
+            (mask or statistical map) to be returned.
+        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.
+        **fetch_kwargs
+            - resolution_mm: resolution in millimeters
+            - format: the format of the volume, like "mesh" or "nii"
+            - voi: a BoundingBox of interest
 
-        if result is None:
-            raise RuntimeError(f"Error fetching {mapindex} from {self} as {kwargs.get('format', f'{self.formats}')}.")
-        return result
+
+            Note
+            ----
+            Not all keyword arguments are supported for volume formats. Format
+            is restricted by available formats (check formats property).
+
+        Returns
+        -------
+        An image or mesh
+        """
+        vol = self.get_volume(region=region, index=index, **fetch_kwargs)
+        return vol.fetch(**fetch_kwargs)
 
     def fetch_iter(self, **kwargs):
         """
         Returns an iterator to fetch all mapped volumes sequentially.
 
-        All arguments are passed on to function Map.fetch().
+        All arguments are passed on to function Map.fetch(). By default, it
+        will go through all fragments as well.
         """
-        fragment = kwargs.pop('fragment') if 'fragment' in kwargs else None
+        fragments = {kwargs.pop('fragment', None)} or self.fragments or {None}
         return (
             self.fetch(
-                index=MapIndex(volume=i, label=None, fragment=fragment), **kwargs
+                index=MapIndex(volume=i, label=None, fragment=frag), **kwargs
             )
+            for frag in fragments
             for i in range(len(self))
         )
 
@@ -529,10 +515,10 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             raise RuntimeError("The map cannot be merged since there are no multiple volumes or fragments.")
 
         # initialize empty volume according to the template
-        template = self.space.get_template().fetch(**kwargs)
-        result_data = np.zeros_like(np.asanyarray(template.dataobj))
-        voxelwise_max = np.zeros_like(result_data)
-        result_nii = Nifti1Image(result_data, template.affine)
+        template_img = self.space.get_template().fetch(**kwargs)
+        result_arr = np.zeros_like(np.asanyarray(template_img.dataobj))
+        result_affine = template_img.affine
+        voxelwise_max = np.zeros_like(result_arr)
         interpolation = 'nearest' if self.is_labelled else 'linear'
         next_labelindex = 1
         region_indices = defaultdict(list)
@@ -548,11 +534,14 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                 disable=(len(self.fragments) == 1 or self.fragments is None)
             ):
                 mapindex = MapIndex(volume=volidx, fragment=frag)
-                img = self.fetch(mapindex)
-                if np.linalg.norm(result_nii.affine - img.affine) > 1e-14:
+                img = self.fetch(index=mapindex)
+                if np.allclose(img.affine, result_affine):
+                    img_data = np.asanyarray(img.dataobj)
+                else:
                     logger.debug(f"Compression requires to resample volume {volidx} ({interpolation})")
-                    img = image.resample_to_img(img, result_nii, interpolation)
-                img_data = np.asanyarray(img.dataobj)
+                    img_data = np.asanyarray(
+                        resample_img_to_img(img, template_img).dataobj
+                    )
 
                 if self.is_labelled:
                     labels = set(np.unique(img_data)) - {0}
@@ -571,7 +560,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                         update_voxels = (img_data > voxelwise_max)
                     else:
                         update_voxels = (img_data == label)
-                    result_data[update_voxels] = next_labelindex
+                    result_arr[update_voxels] = next_labelindex
                     voxelwise_max[update_voxels] = img_data[update_voxels]
                     next_labelindex += 1
 
@@ -581,43 +570,64 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             space_spec=self._space_spec,
             parcellation_spec=self._parcellation_spec,
             indices=region_indices,
-            volumes=[
-                _volume.Volume(
-                    space_spec=self._space_spec,
-                    providers=[nifti.NiftiProvider(result_nii)]
-                )
-            ]
+            volumes=[_volume.from_array(
+                result_arr, result_affine, self._space_spec, name=self.name + " compressed"
+            )]
         )
 
-    def compute_centroids(self) -> Dict[str, point.Point]:
+    def compute_centroids(self, split_components: bool = True, **fetch_kwargs) -> Dict[str, pointcloud.PointCloud]:
         """
-        Compute a dictionary of the centroids of all regions in this map.
+        Compute a dictionary of all regions in this map to their centroids.
+        By default, the regional masks will be split to connected components
+        and each point in the PointCloud corresponds to a region component.
+
+        Parameters
+        ----------
+        split_components: bool, default: True
+            If True, finds the spatial properties for each connected component
+            found by skimage.measure.label.
 
         Returns
         -------
         Dict[str, point.Point]
             Region names as keys and computed centroids as items.
         """
-        centroids = {}
-        maparr = None
+        assert self.provides_image, "Centroid computation for meshes is not supported yet."
+        centroids = dict()
         for regionname, indexlist in siibra_tqdm(
             self._indices.items(), unit="regions", desc="Computing centroids"
         ):
-            assert len(indexlist) == 1
-            index = indexlist[0]
-            if index.label == 0:
-                continue
-            with QUIET:
-                mapimg = self.fetch(index=index)  # returns a mask of the region
-            maparr = np.asanyarray(mapimg.dataobj)
-            centroid_vox = np.mean(np.where(maparr == 1), axis=1)
             assert regionname not in centroids
-            centroids[regionname] = point.Point(
-                np.dot(mapimg.affine, np.r_[centroid_vox, 1])[:3], space=self.space
+            # get the mask of the region in this map
+            with QUIET:
+                if len(indexlist) >= 1:
+                    merged_volume = _volume.merge(
+                        [
+                            _volume.from_nifti(
+                                self.fetch(index=index, **fetch_kwargs),
+                                self.space,
+                                f"{self.name} - {index}"
+                            )
+                            for index in indexlist
+                        ],
+                        labels=[1] * len(indexlist)
+                    )
+                    mapimg = merged_volume.fetch()
+                elif len(indexlist) == 1:
+                    index = indexlist[0]
+                    mapimg = self.fetch(index=index, **fetch_kwargs)  # returns a mask of the region
+            props = _volume.ComponentSpatialProperties.compute_from_image(
+                img=mapimg,
+                space=self.space,
+                split_components=split_components,
             )
+            try:
+                centroids[regionname] = pointcloud.from_points([c.centroid for c in props])
+            except exceptions.EmptyPointCloudError:
+                centroids[regionname] = None
         return centroids
 
-    def get_resampled_template(self, **fetch_kwargs) -> Nifti1Image:
+    def get_resampled_template(self, **fetch_kwargs) -> _volume.Volume:
         """
         Resample the reference space template to fetched map image. Uses
         nilearn.image.resample_to_img to resample the template.
@@ -628,17 +638,19 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
 
         Returns
         -------
-        Nifti1Image
+        Volume
         """
         source_template = self.space.get_template().fetch()
         map_image = self.fetch(**fetch_kwargs)
-        return image.resample_to_img(
-            source_template,
-            map_image,
-            interpolation='continuous'
+        img = image.resample_to_img(source_template, map_image, interpolation='continuous')
+        return _volume.from_array(
+            data=img.dataobj,
+            affine=img.affine,
+            space=self.space,
+            name=f"{source_template} resampled to coordinate system of {self}"
         )
 
-    def colorize(self, values: dict, **kwargs) -> Nifti1Image:
+    def colorize(self, values: dict, **kwargs) -> _volume.Volume:
         """Colorize the map with the provided regional values.
 
         Parameters
@@ -671,7 +683,12 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                 else:
                     result[img == index.label] = value
 
-        return Nifti1Image(result, affine)
+        return _volume.from_array(
+            data=result,
+            affine=affine,
+            space=self.space,
+            name=f"Custom colorization of {self}"
+        )
 
     def get_colormap(self, region_specs: Iterable = None):
         """
@@ -732,7 +749,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
 
         Returns
         -------
-        PointSet
+        PointCloud
             Sample points in physcial coordinates corresponding to this
             parcellationmap
         """
@@ -750,7 +767,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             np.unravel_index(np.random.choice(len(p), numpoints, p=p), W.shape)
         ).T
         XYZ = np.dot(mask.affine, np.c_[XYZ_, np.ones(numpoints)].T)[:3, :].T
-        return pointset.PointSet(XYZ, space=self.space)
+        return pointcloud.PointCloud(XYZ, space=self.space)
 
     def to_sparse(self):
         """
@@ -810,44 +827,52 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
 
     def _assign(
         self,
-        item: Union[point.Point, pointset.PointSet, Nifti1Image],
+        item: location.Location,
         minsize_voxel=1,
         lower_threshold=0.0,
         **kwargs
-    ) -> List[Union[Assignment,AssignImageResult]]:
+    ) -> List[Union[MapAssignment, 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(
+                pointcloud.PointCloud([item], item.space, sigma_mm=item.sigma),
+                lower_threshold
+            )
+        if isinstance(item, pointcloud.PointCloud):
             return self._assign_points(item, lower_threshold)
-        if isinstance(item, Nifti1Image):
-            return self._assign_image(item, minsize_voxel, lower_threshold, **kwargs)
-        
+        if isinstance(item, _volume.Volume):
+            return self._assign_volume(
+                queryvolume=item,
+                lower_threshold=lower_threshold,
+                minsize_voxel=minsize_voxel,
+                **kwargs
+            )
+
         raise RuntimeError(
             f"Items of type {item.__class__.__name__} cannot be used for region assignment."
         )
 
     def assign(
         self,
-        item: Union[point.Point, pointset.PointSet, Nifti1Image],
+        item: location.Location,
         minsize_voxel=1,
         lower_threshold=0.0,
         **kwargs
-    ):
-        """Assign an input image to brain regions.
+    ) -> "pd.DataFrame":
+        """Assign an input Location to brain regions.
 
-        The input image is assumed to be defined in the same coordinate space
+        The input is assumed to be defined in the same coordinate space
         as this parcellation map.
 
         Parameters
         ----------
-        item: Point, PointSet, Nifti1Image
+        item: Location
             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
+            image volume. 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.
@@ -859,7 +884,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
 
         Returns
         -------
-        assignments: pandas.DataFrame
+        pandas.DataFrame
             A table of associated regions and their scores per component found
             in the input image, or per coordinate provided. The scores are:
 
@@ -876,11 +901,6 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                 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.
         """
 
         assignments = self._assign(item, minsize_voxel, lower_threshold, **kwargs)
@@ -952,7 +972,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                         "input containedness": a.intersection_over_second,
                     }
                 }
-            elif isinstance(a, Assignment):
+            elif isinstance(a, MapAssignment):
                 item_to_append = {
                     **item_to_append,
                     **{
@@ -969,18 +989,18 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                 raise RuntimeError("assignments must be of type Assignment or AssignImageResult!")
 
             dataframe_list.append(item_to_append)
-        df = pd.DataFrame(dataframe_list)
         return (
-            df
+            pd.DataFrame(dataframe_list)
             .convert_dtypes()  # convert will guess numeric column types
             .reindex(columns=columns)
+            .dropna(axis='columns', how='all')
         )
 
-    def _assign_points(self, points: pointset.PointSet, lower_threshold: float) -> List[Assignment]:
+    def _assign_points(self, points: pointcloud.PointCloud, lower_threshold: float) -> List[MapAssignment]:
         """
-        assign a PointSet to this parcellation map.
+        assign a PointCloud to this parcellation map.
 
-        Parameters:
+        Parameters
         -----------
         lower_threshold: float, default: 0
             Lower threshold on values in the statistical map. Values smaller than
@@ -1010,7 +1030,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                     if value > lower_threshold:
                         position = pts_warped[pointindex].coordinate
                         assignments.append(
-                            Assignment(
+                            MapAssignment(
                                 input_structure=pointindex,
                                 centroid=tuple(np.array(position).round(2)),
                                 volume=vol,
@@ -1025,7 +1045,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         # of the coordinates.
         for pointindex, pt in siibra_tqdm(
             enumerate(points.warp(self.space.id)),
-            total=len(points), desc="Warping points",
+            total=len(points), desc="Assigning points",
         ):
             sigma_vox = pt.sigma / scaling
             if sigma_vox < 3:
@@ -1037,7 +1057,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                 for _, vol, frag, value in values:
                     if value > lower_threshold:
                         assignments.append(
-                            Assignment(
+                            MapAssignment(
                                 input_structure=pointindex,
                                 centroid=tuple(pt),
                                 volume=vol,
@@ -1046,91 +1066,214 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                             )
                         )
             else:
-                logger.info(
+                logger.debug(
                     f"Assigning uncertain coordinate {tuple(pt)} to {len(self)} maps."
                 )
                 kernel = create_gaussian_kernel(sigma_vox, 3)
                 r = int(kernel.shape[0] / 2)  # effective radius
-                xyz_vox = (np.dot(phys2vox, pt.homogeneous) + 0.5).astype("int")
+                assert pt.homogeneous.shape[0] == 1
+                xyz_vox = (np.dot(phys2vox, pt.homogeneous.T) + 0.5).astype("int")
                 shift = np.identity(4)
-                shift[:3, -1] = xyz_vox[:3] - r
+                shift[:3, -1] = xyz_vox[:3, 0] - r
                 # 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):
+                gaussian_kernel = _volume.from_array(
+                    data=kernel,
+                    affine=np.dot(self.affine, shift),
+                    space=self.space,
+                    name=f"Gaussian kernel of {pt}"
+                )
+                for entry in self._assign(
+                    item=gaussian_kernel,
+                    lower_threshold=lower_threshold,
+                    split_components=False
+                ):
                     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, split_components: bool = True) -> List[AssignImageResult]:
+    def _assign_volume(
+        self,
+        queryvolume: "_volume.Volume",
+        lower_threshold: float,
+        split_components: bool = True,
+        **kwargs
+    ) -> List[AssignImageResult]:
         """
         Assign an image volume to this parcellation map.
 
-        Parameters:
+        Parameters
         -----------
+        queryvolume: Volume
+            the volume to be compared with maps
         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.
+        split_components: bool, default: True
+            Whether to split the query volume into disjoint components.
         """
-        assignments = []
+        # TODO: split_components is not known to `assign`
+        # TODO: `minsize_voxel` is not used here. Consider the implementation of `assign` again.
+        if kwargs:
+            logger.info(f"The keywords {[k for k in kwargs]} are not passed on during volume assignment.")
 
-        def resample(img: Nifti1Image, affine: np.ndarray, shape: tuple):
-            # resample query image into this image's voxel space, if required
-            if (img.affine - affine).sum() == 0:
-                return img
-            else:
-                interp = "nearest" \
-                    if issubclass(np.asanyarray(img.dataobj).dtype.type, np.integer) \
-                    else "linear"
-                return image.resample_img(
-                    img,
-                    target_affine=affine,
-                    target_shape=shape,
-                    interpolation=interp,
-                )
+        assert queryvolume.space == self.space, ValueError("Assigned volume must be in the same space as the map.")
 
-        def progress(it, N: int = None, desc: str = "", min_elements=5):
-            # wraps a progress indicator around the given iterator,
-            # but only if the sequence is long.
-            seqlen = N or len(it)
-            return iter(it) if seqlen < min_elements \
-                else siibra_tqdm(it, desc=desc, total=N)
-        
-        iter_func = iterate_connected_components if split_components \
-            else lambda img: [(1, img)]
-
-        with QUIET and _volume.SubvolumeProvider.UseCaching():
-            for frag in self.fragments or {None}:
-                for vol, vol_img in progress(
-                    enumerate(self.fetch_iter(fragment=frag)),
-                    N=len(self),
-                    desc=f"Assigning to {len(self)} volumes"
-                ):
-                    queryimg_res = resample(queryimg, vol_img.affine, vol_img.shape)
-                    for mode, maskimg in iter_func(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}
-                        for label in progress(
-                            labels,
-                            desc=f"Assigning to {len(labels)} labelled structures"
-                        ):
-                            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:
-                                assignments.append(
-                                    AssignImageResult(
-                                        input_structure=mode,
-                                        centroid=tuple(position.round(2)),
-                                        volume=vol,
-                                        fragment=frag,
-                                        map_value=label,
-                                        **asdict(scores)
-                                    )
-                                )
+        if split_components:
+            iter_components = lambda arr: connected_components(arr)
+        else:
+            iter_components = lambda arr: [(0, arr)]
+
+        queryimg = queryvolume.fetch()
+        assignments = []
+        all_indices = [
+            index
+            for regionindices in self._indices.values()
+            for index in regionindices
+        ]
+        with QUIET and provider.SubvolumeProvider.UseCaching():
+            for index in siibra_tqdm(
+                all_indices,
+                desc=f"Assigning {queryvolume} to {self}",
+                disable=len(all_indices) < 5,
+                unit="map",
+                leave=False
+            ):
+                region_map = self.fetch(index=index)
+                region_map_arr = np.asanyarray(region_map.dataobj)
+                # the shape and affine are checked by `nilearn.image.resample_to_img()`
+                # and returns the original data if resampling is not necessary.
+                queryimgarr_res = np.asanyarray(
+                    resample_img_to_img(queryimg, region_map).dataobj
+                )
+                for compmode, voxelmask in iter_components(queryimgarr_res):
+                    scores = compare_arrays(
+                        voxelmask,
+                        region_map.affine,  # after resampling, both should have the same affine
+                        region_map_arr,
+                        region_map.affine
+                    )
+                    component_position = np.array(np.where(voxelmask)).T.mean(0)
+                    if scores.intersection_over_union > lower_threshold:
+                        assignments.append(
+                            AssignImageResult(
+                                input_structure=compmode,
+                                centroid=tuple(component_position.round(2)),
+                                volume=index.volume,
+                                fragment=index.fragment,
+                                map_value=index.label,
+                                **asdict(scores)
+                            )
+                        )
 
         return assignments
+
+
+def from_volume(
+    name: str,
+    volume: Union[_volume.Volume, List[_volume.Volume]],
+    regionnames: List[str],
+    regionlabels: List[int],
+    parcellation_spec: Union[str, "parcellation.Parcellation"] = None
+) -> 'Map':
+    """
+    Add a custom labelled parcellation map to siibra from a labelled NIfTI file.
+
+    Parameters
+    ------------
+    name: str
+        Human-readable name of the parcellation.
+    volume: Volume, or a list of Volumes.
+    space_spec: str, Space
+        Specification of the reference space (space object, name, keyword, or id - e.g. 'mni152').
+    regionnames: list[str]
+        List of human-readable names of the mapped regions.
+    regionlabels: list[int]
+        List of integer labels in the nifti file corresponding to the list of regions.
+    parcellation: str or Parcellation. Optional.
+        If the related parcellation already defined or preconfigured in siibra.
+    """
+    # providers and map indices
+    providers = []
+    volumes = volume if isinstance(volume, list) else [volume]
+    map_space = volumes[0].space
+    assert all(v.space == map_space for v in volumes), "Volumes have to be in the same space"
+    for vol_idx, vol in enumerate(volumes):
+        image = vol.fetch()
+        arr = np.asanyarray(image.dataobj)
+        labels_in_volume = np.unique(arr)[1:].astype('int')
+
+        # populate region indices from given name/label lists
+        indices = dict()
+        for label, regionname in zip(regionlabels, regionnames):
+            if label not in labels_in_volume:
+                logger.warning(
+                    f"Label {label} not mapped in the provided NIfTI volume -> "
+                    f"region '{regionname} will not be in the map."
+                )
+            elif label in [v[0]['label'] for v in indices.values() if v[0]['volume'] == vol_idx]:
+                logger.warning(f"Label {label} already defined in the same volume; will not map it to '{regionname}'.")
+            else:
+                assert regionname not in indices, f"'{regionname}' must be unique in `regionnames`."
+                indices[regionname] = [{'volume': vol_idx, 'label': label}]
+
+        # check for any remaining labels in the NIfTI volume
+        unnamed_labels = list(set(labels_in_volume) - set(regionlabels))
+        if unnamed_labels:
+            logger.warning(
+                f"The following labels appear in the NIfTI volume {vol_idx}, but not in "
+                f"the specified regions: {', '.join(str(lb) for lb in unnamed_labels)}. "
+                "They will be removed from the nifti volume."
+            )
+            for label in unnamed_labels:
+                arr[arr == label] = 0
+        providers.extend(vol._providers.values())
+
+    # parcellation
+    if parcellation_spec is None:
+        parcellation_spec = name
+    try:
+        parcobj = parcellation.Parcellation.registry().get(parcellation_spec)
+        logger.info(f"Using '{parcellation_spec}', siibra decoded the parcellation as '{parcobj}'")
+    except Exception:
+        logger.info(
+            f"Using '{parcellation_spec}', siibra could not decode the "
+            " parcellation. Building a new parcellation."
+        )
+        # build a new parcellation
+        parcobj = parcellation.Parcellation(
+            identifier=generate_uuid(','.join(regionnames)),
+            name=name,
+            species=vol.space.species,
+            regions=list(map(_region.Region, regionnames)),
+        )
+        if parcobj.key not in list(parcellation.Parcellation.registry()):
+            parcellation.Parcellation.registry().add(parcobj.key, parcobj)
+
+    for region in siibra_tqdm(
+        indices.keys(),
+        desc="Checking if provided regions are defined in the parcellation."
+    ):
+        try:
+            _ = parcobj.get_region(region)
+        except Exception:
+            logger.warning(f"'{region}' is missing in the parcellation.")
+
+    # build the parcellation map object
+    parcmap = Map(
+        identifier=generate_uuid(name),
+        name=f"{name} map in {map_space.name}",
+        space_spec={"@id": map_space.id},
+        parcellation_spec={'name': parcobj.name},
+        indices=indices,
+        volumes=volumes
+    )
+
+    # add it to siibra's registry
+    Map.registry().add(parcmap.key, parcmap)
+
+    # return the map - note that it has a pointer to the parcellation
+    return parcmap