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

siibra/locations/{pointset.py → pointcloud.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");
@@ -18,6 +18,7 @@ from . import location, point, boundingbox as _boundingbox
 
 from ..retrieval.requests import HttpRequest
 from ..commons import logger
+from ..exceptions import SpaceWarpingFailedError, EmptyPointCloudError
 
 from typing import List, Union, Tuple
 import numbers
@@ -31,13 +32,13 @@ except ImportError:
     _HAS_HDBSCAN = False
     logger.warning(
         f"HDBSCAN is not available with your version {sklearn.__version__} of sckit-learn."
-        "`PointSet.find_clusters()` will not be avaiable."
+        "`PointCloud.find_clusters()` will not be avaiable."
     )
 
 
-def from_points(points: List["point.Point"], newlabels: List[Union[int, float, tuple]] = None) -> "PointSet":
+def from_points(points: List["point.Point"], newlabels: List[Union[int, float, tuple]] = None) -> "PointCloud":
     """
-    Create a PointSet from an iterable of Points.
+    Create a PointCloud from an iterable of Points.
 
     Parameters
     ----------
@@ -47,16 +48,17 @@ def from_points(points: List["point.Point"], newlabels: List[Union[int, float, t
 
     Returns
     -------
-    PointSet
+    PointCloud
     """
     if len(points) == 0:
-        return PointSet([])
+        raise EmptyPointCloudError("Cannot create a PointCloud without any points.")
+
     spaces = {p.space for p in points}
-    assert len(spaces) == 1, f"PointSet can only be constructed with points from the same space.\n{spaces}"
+    assert len(spaces) == 1, f"PointCloud can only be constructed with points from the same space.\n{spaces}"
     coords, sigmas, labels = zip(*((p.coordinate, p.sigma, p.label) for p in points))
     if all(lb is None for lb in set(labels)):
         labels = None
-    return PointSet(
+    return PointCloud(
         coordinates=coords,
         space=next(iter(spaces)),
         sigma_mm=sigmas,
@@ -64,7 +66,7 @@ def from_points(points: List["point.Point"], newlabels: List[Union[int, float, t
     )
 
 
-class PointSet(location.Location):
+class PointCloud(location.Location):
     """A set of 3D points in the same reference space,
     defined by a list of coordinates."""
 
@@ -90,6 +92,9 @@ class PointSet(location.Location):
         """
         location.Location.__init__(self, space)
 
+        if len(coordinates) == 0:
+            raise EmptyPointCloudError(f"Cannot create a {self.__class__.__name__} without any coordinates.")
+
         self._coordinates = coordinates
         if not isinstance(coordinates, np.ndarray):
             self._coordinates = np.array(self._coordinates).reshape((-1, 3))
@@ -112,7 +117,7 @@ class PointSet(location.Location):
         NOTE: The affine matrix of the image must be set to warp voxels
         coordinates into the reference space of this Bounding Box.
         """
-        if not isinstance(other, (point.Point, PointSet, _boundingbox.BoundingBox)):
+        if not isinstance(other, (point.Point, PointCloud, _boundingbox.BoundingBox)):
             return other.intersection(self)
 
         intersections = [(i, p) for i, p in enumerate(self) if p.intersects(other)]
@@ -121,7 +126,7 @@ class PointSet(location.Location):
         ids, points = zip(*intersections)
         labels = None if self.labels is None else [self.labels[i] for i in ids]
         sigma = [p.sigma for p in points]
-        intersection = PointSet(
+        intersection = PointCloud(
             points,
             space=self.space,
             sigma_mm=sigma,
@@ -149,7 +154,7 @@ class PointSet(location.Location):
         if spaceobj == self.space:
             return self
         if any(_ not in location.Location.SPACEWARP_IDS for _ in [self.space.id, spaceobj.id]):
-            raise ValueError(
+            raise SpaceWarpingFailedError(
                 f"Cannot convert coordinates between {self.space.id} and {spaceobj.id}"
             )
 
@@ -178,10 +183,14 @@ class PointSet(location.Location):
             ).data
             tgt_points.extend(list(response["target_points"]))
 
+        # TODO: consider using np.isnan(np.dot(arr, arr)). see https://stackoverflow.com/a/45011547
+        if np.any(np.isnan(response['target_points'])):
+            raise SpaceWarpingFailedError(f'Warping {str(self)} to {spaceobj.name} resulted in NaN')
+
         return self.__class__(coordinates=tuple(tgt_points), space=spaceobj, labels=self.labels)
 
     def transform(self, affine: np.ndarray, space=None):
-        """Returns a new PointSet obtained by transforming the
+        """Returns a new PointCloud obtained by transforming the
         coordinates of this one with the given affine matrix.
 
         Parameters
@@ -202,7 +211,7 @@ class PointSet(location.Location):
     def __getitem__(self, index: int):
         if (abs(index) >= self.__len__()):
             raise IndexError(
-                f"Pointset with {self.__len__()} points "
+                f"pointcloud with {self.__len__()} points "
                 f"cannot be accessed with index {index}."
             )
         return point.Point(
@@ -224,10 +233,10 @@ class PointSet(location.Location):
             for i in range(len(self))
         )
 
-    def __eq__(self, other: 'PointSet'):
+    def __eq__(self, other: 'PointCloud'):
         if isinstance(other, point.Point):
             return len(self) == 1 and self[0] == other
-        if not isinstance(other, PointSet):
+        if not isinstance(other, PointCloud):
             return False
         return list(self) == list(other)
 
@@ -235,7 +244,7 @@ class PointSet(location.Location):
         return super().__hash__()
 
     def __len__(self):
-        """The number of points in this PointSet."""
+        """The number of points in this PointCloud."""
         return self.coordinates.shape[0]
 
     def __str__(self):
@@ -243,15 +252,19 @@ class PointSet(location.Location):
 
     @property
     def boundingbox(self):
-        """Return the bounding box of these points.
-        TODO revisit the numerical margin of 1e-6, should not be necessary.
         """
-        XYZ = self.coordinates
-        sigma_min = max(self.sigma[i] for i in XYZ.argmin(0))
-        sigma_max = max(self.sigma[i] for i in XYZ.argmax(0))
+        Return the bounding box of these points, or None in the
+        special case of an empty PointCloud.
+        """
+        if len(self.coordinates) == 0:
+            return None
+        coords = self.coordinates
+        # TODO this needs a more precise treatment of the sigmas
+        sigma_min = max(self.sigma[i] for i in coords.argmin(0))
+        sigma_max = max(self.sigma[i] for i in coords.argmax(0))
         return _boundingbox.BoundingBox(
-            point1=XYZ.min(0) - max(sigma_min, 1e-6),
-            point2=XYZ.max(0) + max(sigma_max, 1e-6),
+            point1=coords.min(0),
+            point2=coords.max(0),
             space=self.space,
             sigma_mm=[sigma_min, sigma_max]
         )
@@ -276,11 +289,38 @@ class PointSet(location.Location):
         """Access the list of 3D point as an Nx4 array of homogeneous coordinates."""
         return np.c_[self.coordinates, np.ones(len(self))]
 
-    def find_clusters(self, min_fraction=1 / 200, max_fraction=1 / 8):
+    def find_clusters(
+        self,
+        min_fraction: float = 1 / 200,
+        max_fraction: float = 1 / 8
+    ) -> List[int]:
+        """
+        Find clusters using HDBSCAN (https://dl.acm.org/doi/10.1145/2733381)
+        implementation of scikit-learn (https://dl.acm.org/doi/10.5555/1953048.2078195).
+
+        Parameters
+        ----------
+        min_fraction: min cluster size as a fraction of total points in the PointCloud
+        max_fraction: max cluster size as a fraction of total points in the PointCloud
+
+        Returns
+        -------
+        List[int]
+            Returns the cluster labels found by skilearn.cluster.HDBSCAN.
+
+            Note
+            ----
+            Replaces the labels of the PointCloud instance with these labels.
+
+        Raises
+        ------
+        RuntimeError
+            If a sklearn version without HDBSCAN is installed.
+        """
         if not _HAS_HDBSCAN:
             raise RuntimeError(
                 f"HDBSCAN is not available with your version {sklearn.__version__} "
-                "of sckit-learn. `PointSet.find_clusters()` will not be avaiable."
+                "of sckit-learn. `PointCloud.find_clusters()` will not be avaiable."
             )
         points = np.array(self.as_list())
         N = points.shape[0]
@@ -289,7 +329,9 @@ class PointSet(location.Location):
             max_cluster_size=int(N * max_fraction),
         )
         if self.labels is not None:
-            logger.warn("Existing labels of PointSet will be overwritten with cluster labels.")
+            logger.warning(
+                "Existing labels of PointCloud will be overwritten with cluster labels."
+            )
         self.labels = clustering.fit_predict(points)
         return self.labels
 

siibra/retrieval/__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/retrieval/cache.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/retrieval/datasets.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/retrieval/exceptions/__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/retrieval/repositories.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");
@@ -19,7 +19,8 @@ from .requests import (
     EbrainsRequest,
     SiibraHttpRequestError,
     find_suitiable_decoder,
-    DECODERS
+    DECODERS,
+    FileLoader
 )
 from .cache import CACHE
 
@@ -124,34 +125,16 @@ class LocalFileRepository(RepositoryConnector):
         self._folder = pathlib.Path(folder)
         assert pathlib.Path.is_dir(self._folder)
 
-    def _build_url(self, folder: str, filename: str):
-        return pathlib.Path.joinpath(self._folder, folder, filename)
-
-    class FileLoader:
-        """
-        Just a loads a local file, but mimics the behaviour
-        of cached http requests used in other connectors.
-        """
-        def __init__(self, file_url, decode_func):
-            self.url = file_url
-            self.func = decode_func
-            self.cached = True
-
-        @property
-        def data(self):
-            with open(self.url, 'rb') as f:
-                return self.func(f.read())
+    def _build_url(self, folder: str, filename: str) -> str:
+        return pathlib.Path.joinpath(self._folder, folder, filename).as_posix()
 
     def get_loader(self, filename, folder="", decode_func=None):
         """Get a lazy loader for a file, for loading data
         only once loader.data is accessed."""
-        url = self._build_url(folder, filename)
-        if url is None:
-            raise RuntimeError(f"Cannot build url for ({folder}, {filename})")
-        if decode_func is None:
-            return self.FileLoader(url, lambda b: self._decode_response(b, filename))
-        else:
-            return self.FileLoader(url, decode_func)
+        filepath = self._build_url(folder, filename)
+        if not pathlib.Path(filepath).is_file():
+            raise RuntimeError(f"No file is found in {filepath}")
+        return FileLoader(filepath, decode_func)
 
     def search_files(self, folder="", suffix=None, recursive=False):
         results = []
@@ -165,7 +148,7 @@ class LocalFileRepository(RepositoryConnector):
     def __str__(self):
         return f"{self.__class__.__name__} at {self._folder}"
 
-    def __eq__(self, other):
+    def __eq__(self, other: "LocalFileRepository"):
         return self._folder == other._folder
 
 

siibra/retrieval/requests.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");
@@ -117,8 +117,7 @@ def find_suitiable_decoder(url: str) -> Callable:
     suitable_decoders = [
         dec for sfx, dec in DECODERS.items() if urlpath.endswith(sfx)
     ]
-    if len(suitable_decoders) > 0:
-        assert len(suitable_decoders) == 1
+    if len(suitable_decoders) == 1:
         return suitable_decoders[0]
     else:
         return None
@@ -270,6 +269,24 @@ class HttpRequest:
         return self.get()
 
 
+class FileLoader(HttpRequest):
+    """
+    Just a loads a local file, but mimics the behaviour
+    of cached http requests used in other connectors.
+    """
+    def __init__(self, filepath, func=None):
+        HttpRequest.__init__(
+            self, filepath, refresh=False,
+            func=func or find_suitiable_decoder(filepath)
+        )
+        self.cachefile = filepath
+
+    def _retrieve(self, **kwargs):
+        if kwargs:
+            logger.info(f"Keywords {list(kwargs.keys())} are supplied but won't be used.")
+        assert os.path.isfile(self.cachefile)
+
+
 class ZipfileRequest(HttpRequest):
     def __init__(self, url, filename, func=None, refresh=False):
         HttpRequest.__init__(

siibra/vocabularies/__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/__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");
@@ -16,7 +16,7 @@
 
 from .parcellationmap import Map
 from .providers import provider
-from .volume import from_array, from_file, from_pointset, from_nifti, Volume
+from .volume import from_array, from_file, from_pointcloud, from_nifti, Volume
 
 from ..commons import logger
 from typing import List, Union