siibra 1.0a14__py3-none-any.whl → 1.0.1a0__py3-none-any.whl

siibra/volumes/parcellationmap.py

@@ -1,4 +1,4 @@
-# Copyright 2018-2023
+# Copyright 2018-2024
 # Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
 
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -32,8 +32,7 @@ from ..commons import (
     generate_uuid
 )
 from ..core import concept, space, parcellation, region as _region
-from ..locations import location, 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
@@ -76,6 +75,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         modality: str = None,
         publications: list = [],
         datasets: list = [],
+        prerelease: bool = False,
     ):
         """
         Constructs a new parcellation object.
@@ -120,12 +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
-        if 'prerelease' in self.parcellation.name.lower():
-            self.name = f"[PRERELEASE] {self.name}"
 
         # Since the volumes might include 4D arrays, where the actual
         # volume index points to a z coordinate, we create subvolume
@@ -160,6 +159,11 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             logger.warning(f"Non unique indices encountered in {self}: {duplicates}")
         self._affine_cached = None
 
+    @property
+    def key(self):
+        _id = self.id
+        return create_key(_id[len("siibra-map-v0.0.1"):])
+
     @property
     def species(self) -> Species:
         # lazy implementation
@@ -319,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 exceptions.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)
@@ -390,19 +352,17 @@ 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."
                 )
                 labels = list(range(len(self.volumes)))
                 merged_volume = _volume.merge(self.volumes, labels, **kwargs)
-                return merged_volume.fetch()
+                return merged_volume
             else:
                 raise exceptions.NoVolumeFound("Map provides no volumes.")
 
-        if "resolution_mm" in kwargs and kwargs.get("format") is None:
-            kwargs["format"] = 'neuroglancer/precomputed'
-
         kwargs_fragment = kwargs.pop("fragment", None)
         if kwargs_fragment is not None:
             if (mapindex.fragment is not None) and (kwargs_fragment != mapindex.fragment):
@@ -418,17 +378,60 @@ 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]
 
-        if result is None:
-            raise RuntimeError(f"Error fetching {mapindex} from {self} as {kwargs.get('format', f'{self.formats}')}.")
+        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
 
-        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):
         """
@@ -531,7 +534,7 @@ 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)
+                img = self.fetch(index=mapindex)
                 if np.allclose(img.affine, result_affine):
                     img_data = np.asanyarray(img.dataobj)
                 else:
@@ -572,32 +575,56 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             )]
         )
 
-    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) -> _volume.Volume:
@@ -722,7 +749,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
 
         Returns
         -------
-        PointSet
+        PointCloud
             Sample points in physcial coordinates corresponding to this
             parcellationmap
         """
@@ -740,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):
         """
@@ -811,10 +838,10 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
 
         if isinstance(item, point.Point):
             return self._assign_points(
-                pointset.PointSet([item], item.space, sigma_mm=item.sigma),
+                pointcloud.PointCloud([item], item.space, sigma_mm=item.sigma),
                 lower_threshold
             )
-        if isinstance(item, pointset.PointSet):
+        if isinstance(item, pointcloud.PointCloud):
             return self._assign_points(item, lower_threshold)
         if isinstance(item, _volume.Volume):
             return self._assign_volume(
@@ -969,9 +996,9 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             .dropna(axis='columns', how='all')
         )
 
-    def _assign_points(self, points: pointset.PointSet, lower_threshold: float) -> List[MapAssignment]:
+    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
         -----------

siibra/volumes/providers/__init__.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");

siibra/volumes/providers/freesurfer.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");

siibra/volumes/providers/gifti.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");

siibra/volumes/providers/neuroglancer.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");
@@ -26,7 +26,7 @@ from ...commons import (
 from ...retrieval import requests, cache
 from ...locations import boundingbox as _boundingbox
 
-from neuroglancer_scripts.precomputed_io import get_IO_for_existing_dataset
+from neuroglancer_scripts.precomputed_io import get_IO_for_existing_dataset, PrecomputedIO
 from neuroglancer_scripts.http_accessor import HttpAccessor
 from neuroglancer_scripts.mesh import read_precomputed_mesh, affine_transform_mesh
 from io import BytesIO
@@ -37,6 +37,37 @@ from typing import Union, Dict, Tuple
 import json
 
 
+def shift_ng_transfrom(
+    transform_nm: np.ndarray, scale_resolution_nm: np.ndarray, max_resolution_nm: np.ndarray
+) -> np.ndarray:
+    """
+    Helper method to get nifti standard affine.
+
+    transfrorm.json stored with neuroglancer precomputed images and meshes
+    are meant to be used for neuroglancer viewers and hence they are not
+    representative of the affine in other tools. This method shifts back
+    half a voxel in each axis.
+    (see https://neuroglancer-scripts.readthedocs.io/en/latest/neuroglancer-info.html#different-conventions-for-coordinate-transformations)
+
+    Parameters
+    ----------
+    transform_nm: np.ndarray
+        Transform array created for dispalying an image correctly from
+        neuroglancer precomputed format in neuroglancer viewer.
+    max_resolution_nm: np.ndarray
+        The voxel resolution of the highest level of resolution.
+
+    Returns
+    -------
+    np.ndarray
+        Standard affine in nm
+    """
+    scaling = np.diag(np.r_[scale_resolution_nm, 1.0])
+    affine = np.dot(transform_nm, scaling)
+    affine[:3, 3] += (max_resolution_nm * 0.5)
+    return affine
+
+
 class NeuroglancerProvider(_provider.VolumeProvider, srctype="neuroglancer/precomputed"):
 
     def __init__(self, url: Union[str, Dict[str, str]]):
@@ -128,26 +159,20 @@ class NeuroglancerProvider(_provider.VolumeProvider, srctype="neuroglancer/preco
                 label = None
             if label is not None:
                 result = nib.Nifti1Image(
-                    (result.get_fdata() == label).astype('uint8'),
-                    result.affine
+                    (np.asanyarray(result.dataobj) == label).astype('uint8'),
+                    result.affine,
+                    dtype='uint8',
                 )
 
         return result
 
-    def get_boundingbox(self, clip=False, background=0, **fetch_kwargs) -> "_boundingbox.BoundingBox":
+    def get_boundingbox(self, **fetch_kwargs) -> "_boundingbox.BoundingBox":
         """
         Return the bounding box in physical coordinates of the union of
         fragments in this neuroglancer volume.
 
         Parameters
         ----------
-        clip: bool, default: True
-            Whether to clip the background of the volume.
-        background: float, default: 0.0
-            The background value to clip.
-            Note
-            ----
-            To use it, clip must be True.
         fetch_kwargs:
             key word arguments that are used for fetchin volumes,
             such as voi or resolution_mm.
@@ -159,23 +184,17 @@ class NeuroglancerProvider(_provider.VolumeProvider, srctype="neuroglancer/preco
                     f"N-D Neuroglancer volume has shape {frag.shape}, but "
                     f"bounding box considers only {frag.shape[:3]}"
                 )
-            if clip:
-                img = frag.fetch(**fetch_kwargs)
-                next_bbox = _boundingbox.from_array(
-                    np.asanyarray(img.dataobj), threshold=background, space=None
-                ).transform(img.affine)  # use the affine of the image matching fetch_kwargs
+            resolution_mm = fetch_kwargs.get("resolution_mm")
+            if resolution_mm is None:
+                affine = frag.affine
+                shape = frag.shape[:3]
             else:
-                resolution_mm = fetch_kwargs.get("resolution_mm")
-                if resolution_mm is None:
-                    affine = frag.affine
-                    shape = frag.shape[:3]
-                else:
-                    scale = frag._select_scale(resolution_mm=resolution_mm)
-                    affine = scale.affine
-                    shape = scale.size[:3]
-                next_bbox = _boundingbox.BoundingBox(
-                    (0, 0, 0), shape, space=None
-                ).transform(affine)
+                scale = frag._select_scale(resolution_mm=resolution_mm)
+                affine = scale.affine
+                shape = scale.size[:3]
+            next_bbox = _boundingbox.BoundingBox(
+                (0, 0, 0), shape, space=None
+            ).transform(affine)
             bbox = next_bbox if bbox is None else bbox.union(next_bbox)
         return bbox
 
@@ -243,10 +262,14 @@ class NeuroglancerVolume:
         self._scales_cached = None
         self._info = None
         self._transform_nm = None
-        self._io = None
+        self._io: PrecomputedIO = None
 
     @property
-    def transform_nm(self):
+    def transform_nm(self) -> np.ndarray:
+        """
+        This is the transformation matrix created to cater neuroglancer viewer
+        for a neuroglancer precomputed images.
+        """
         if self._transform_nm is not None:
             return self._transform_nm
         try:
@@ -266,7 +289,7 @@ class NeuroglancerVolume:
         self._transform_nm = val
 
     @property
-    def io(self):
+    def io(self) -> PrecomputedIO:
         if self._io is None:
             accessor = HttpAccessor(self.url)
             self._io = get_IO_for_existing_dataset(accessor)
@@ -326,7 +349,7 @@ class NeuroglancerVolume:
     ):
         # the caller has to make sure voi is defined in the correct reference space
         scale = self._select_scale(resolution_mm=resolution_mm, bbox=voi, max_bytes=max_bytes)
-        return scale.fetch(voi=voi)
+        return scale.fetch(voi=voi, **kwargs)
 
     def get_shape(self, resolution_mm=None, max_bytes: float = MAX_BYTES):
         scale = self._select_scale(resolution_mm=resolution_mm, max_bytes=max_bytes)
@@ -385,7 +408,7 @@ class NeuroglancerScale:
 
     color_warning_issued = False
 
-    def __init__(self, volume: NeuroglancerProvider, scaleinfo: dict):
+    def __init__(self, volume: NeuroglancerVolume, scaleinfo: dict):
         self.volume = volume
         self.chunk_sizes = np.array(scaleinfo["chunk_sizes"]).squeeze()
         self.encoding = scaleinfo["encoding"]
@@ -445,10 +468,13 @@ class NeuroglancerScale:
 
     @property
     def affine(self):
-        scaling = np.diag(np.r_[self.res_nm, 1.0])
-        affine = np.dot(self.volume.transform_nm, scaling)
-        affine[:3, :] /= 1e6
-        return affine
+        affine_ = shift_ng_transfrom(
+            transform_nm=self.volume.transform_nm,
+            scale_resolution_nm=self.res_nm,
+            max_resolution_nm=self.volume.scales[0].res_nm[0],
+        )
+        affine_[:3, :] /= 1e6
+        return affine_
 
     def _point_to_lower_chunk_idx(self, xyz):
         return (
@@ -508,9 +534,9 @@ class NeuroglancerScale:
         for dim in range(3):
             if bbox_.shape[dim] < 1:
                 logger.warning(
-                    f"Bounding box in voxel space will be enlarged to voxel size 1 along axis {dim}."
+                    f"Bounding box in voxel space will be enlarged to by {self.res_mm[dim]} along axis {dim}."
                 )
-                bbox_.maxpoint[dim] = bbox_.maxpoint[dim] + 1
+                bbox_.maxpoint[dim] = bbox_.maxpoint[dim] + self.res_mm[dim]
 
         # extract minimum and maximum the chunk indices to be loaded
         gx0, gy0, gz0 = self._point_to_lower_chunk_idx(tuple(bbox_.minpoint))
@@ -532,8 +558,8 @@ class NeuroglancerScale:
         # determine the remaining offset from the "chunk mosaic" to the
         # exact bounding box requested, to cut off undesired borders
         data_min = np.array([gx0, gy0, gz0]) * self.chunk_sizes
-        x0, y0, z0 = (np.array(tuple(bbox_.minpoint)) - data_min).astype("int")
-        xd, yd, zd = np.array(bbox_.shape).astype("int")
+        x0, y0, z0 = (np.array(bbox_.minpoint) - data_min).astype("int")
+        xd, yd, zd = np.ceil((np.array(bbox_.maxpoint))).astype(int) - np.floor((np.array(bbox_.minpoint))).astype(int)
         offset = tuple(bbox_.minpoint)
 
         # build the nifti image
@@ -552,7 +578,7 @@ class NeuroglancerMesh(_provider.VolumeProvider, srctype="neuroglancer/precompme
 
     @staticmethod
     def _fragmentinfo(url: str) -> Dict[str, Union[str, np.ndarray, Dict]]:
-        """ Prepare basic mesh fragment information from url. """
+        """Prepare basic mesh fragment information from url."""
         return {
             "url": url,
             "transform_nm": np.array(requests.HttpRequest(f"{url}/transform.json").data),