siibra 1.0a19__py3-none-any.whl → 1.0.1a1__py3-none-any.whl

siibra/retrieval/repositories.py

@@ -1,4 +1,4 @@
-# Copyright 2018-2024
+# Copyright 2018-2025
 # 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
 
 
@@ -213,7 +196,7 @@ class GithubConnector(RepositoryConnector):
                 if len(matched_reftags) == 1:
                     self._want_commit_cached = matched_reftags[0]["commit"]
                 else:
-                    raise RuntimeError(f"Found {len(matched_reftags)} mathces to {reftag}")
+                    raise RuntimeError(f"Found {len(matched_reftags)} matches to {reftag}")
                 self._tag_checked = True
             except Exception:
                 logger.warning("Could not connect to GitHub repository.", exc_info=1)
@@ -275,7 +258,7 @@ class GitlabConnector(RepositoryConnector):
             n.b. only archive_mode should only be set for trusted domains. Extraction of archive can result in files created outside the path
             see https://docs.python.org/3/library/tarfile.html#tarfile.TarFile.extractall
         """
-        # TODO: the query builder needs to check wether the reftag is a branch, and then not cache.
+        # TODO: the query builder needs to check whether the reftag is a branch, and then not cache.
         assert server.startswith("http")
         RepositoryConnector.__init__(
             self, base_url=f"{server}/api/v4/projects/{project}/repository"
@@ -601,7 +584,7 @@ class EbrainsPublicDatasetConnector(RepositoryConnector):
             Part of dataset title as an alternative dataset specification (will ignore dataset_id then)
         in_progress: bool (default:False)
             If true, will request datasets that are still under curation.
-            Will only work when autenticated with an appropriately privileged
+            Will only work when authenticated with an appropriately privileged
             user account.
         """
         self.dataset_id = dataset_id

siibra/retrieval/requests.py

@@ -1,4 +1,4 @@
-# Copyright 2018-2024
+# Copyright 2018-2025
 # Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
 
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -94,8 +94,8 @@ DECODERS = {
 def find_suitiable_decoder(url: str) -> Callable:
     """
     By supplying a url or a filename, obtain a suitable decoder function
-    for siibra to digest based on predifined DECODERS. An extra layer of
-    gzip decompresser automatically added for gzipped files.
+    for siibra to digest based on predefined DECODERS. An extra layer of
+    gzip decompressor automatically added for gzipped files.
 
     Parameters
     ----------
@@ -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
@@ -194,7 +193,7 @@ class HttpRequest:
         """
         Populates the file cache with the data from http if required.
         noop if 1/ data is already cached and 2/ refresh flag not set
-        The caller should load the cachefile after _retrieve successfuly executes
+        The caller should load the cachefile after _retrieve successfully executes
         """
         if self.cached and not self.refresh:
             return
@@ -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__(
@@ -440,9 +457,9 @@ class EbrainsRequest(HttpRequest):
 
             if resp.status_code == 200:
                 json_resp = resp.json()
-                logger.debug("Device flow sucessful:", json_resp)
+                logger.debug("Device flow successful:", json_resp)
                 cls._KG_API_TOKEN = json_resp.get("access_token")
-                print("ebrains token successfuly set.")
+                print("ebrains token successfully set.")
                 break
 
             if resp.status_code == 400:

siibra/vocabularies/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2018-2024
+# Copyright 2018-2025
 # 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-2024
+# Copyright 2018-2025
 # 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

siibra/volumes/parcellationmap.py

@@ -1,4 +1,4 @@
-# Copyright 2018-2024
+# Copyright 2018-2025
 # 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
@@ -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]
+
+        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}')}.")
+            Note
+            ----
+            Not all keyword arguments are supported for volume formats. Format
+            is restricted by available formats (check formats property).
 
-        return result
+        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):
         """
@@ -500,7 +503,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         taking the voxelwise maximum across the mapped volumes and fragments,
         and re-labelling regions sequentially.
 
-        Paramaters
+        Parameters
         ----------
         **kwargs: Takes the fetch arguments of its space's template.
 
@@ -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,11 +575,11 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             )]
         )
 
-    def compute_centroids(self, split_components: bool = True) -> Dict[str, pointset.PointSet]:
+    def compute_centroids(self, split_components: bool = True, **fetch_kwargs) -> Dict[str, pointcloud.PointCloud]:
         """
         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 PointSet corresponds to a region component.
+        and each point in the PointCloud corresponds to a region component.
 
         Parameters
         ----------
@@ -589,6 +592,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         Dict[str, point.Point]
             Region names as keys and computed centroids as items.
         """
+        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"
@@ -600,7 +604,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                     merged_volume = _volume.merge(
                         [
                             _volume.from_nifti(
-                                self.fetch(index=index),
+                                self.fetch(index=index, **fetch_kwargs),
                                 self.space,
                                 f"{self.name} - {index}"
                             )
@@ -611,13 +615,16 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                     mapimg = merged_volume.fetch()
                 elif len(indexlist) == 1:
                     index = indexlist[0]
-                    mapimg = self.fetch(index=index)  # returns a mask of the region
+                    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,
             )
-            centroids[regionname] = pointset.from_points([c.centroid for c in props])
+            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:
@@ -683,7 +690,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
             name=f"Custom colorization of {self}"
         )
 
-    def get_colormap(self, region_specs: Iterable = None):
+    def get_colormap(self, region_specs: Iterable = None, *, allow_random_colors: bool = False):
         """
         Generate a matplotlib colormap from known rgb values of label indices.
 
@@ -691,13 +698,23 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         ----------
         region_specs: iterable(regions), optional
             Optional parameter to only color the desired regions.
+        allow_random_colors: bool , optional
 
         Returns
         -------
         ListedColormap
         """
-        from matplotlib.colors import ListedColormap
-        import numpy as np
+        try:
+            from matplotlib.colors import ListedColormap
+        except ImportError as e:
+            logger.error(
+                "matplotlib not available. Please install matplotlib to create a matplotlib colormap."
+            )
+            raise e
+        if allow_random_colors:
+            seed = len(self.regions)
+            np.random.seed(seed)
+            logger.info(f"Random colors are allowed for regions without preconfgirued colors. Random seee: {seed}.")
 
         colors = {}
         if region_specs is not None:
@@ -718,14 +735,25 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                     region = self.get_region(index=index)
                     if region.rgb is not None:
                         colors[index.label] = region.rgb
+                    elif allow_random_colors:
+                        random_clr = [np.random.randint(0, 255) for r in range(3)]
+                        while random_clr in list(colors.values()):
+                            random_clr = [np.random.randint(0, 255) for r in range(3)]
+                        colors[index.label] = random_clr
+
+        if len(colors) == 0:
+            raise exceptions.NoPredifinedColormapException(
+                f"There is no predefined/preconfigured colormap for '{self}'."
+                "Set `allow_random_colors=True` to a colormap with random values"
+            )
 
-        pallette = np.array(
+        palette = np.array(
             [
                 list(colors[i]) + [1] if i in colors else [0, 0, 0, 0]
                 for i in range(max(colors.keys()) + 1)
             ]
         ) / [255, 255, 255, 1]
-        return ListedColormap(pallette)
+        return ListedColormap(palette)
 
     def sample_locations(self, regionspec, numpoints: int):
         """ Sample 3D locations inside a given region.
@@ -742,8 +770,8 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
 
         Returns
         -------
-        PointSet
-            Sample points in physcial coordinates corresponding to this
+        PointCloud
+            Sample points in physical coordinates corresponding to this
             parcellationmap
         """
         index = self.get_index(regionspec)
@@ -760,7 +788,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):
         """
@@ -831,10 +859,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(
@@ -916,7 +944,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         if len(assignments) == 0:
             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
+        # only once for each map index occurring 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)
             (
@@ -989,9 +1017,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
         -----------
@@ -1025,7 +1053,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
                         assignments.append(
                             MapAssignment(
                                 input_structure=pointindex,
-                                centroid=tuple(np.array(position).round(2)),
+                                centroid=tuple(position),
                                 volume=vol,
                                 fragment=frag,
                                 map_value=value

siibra/volumes/providers/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2018-2024
+# Copyright 2018-2025
 # 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-2024
+# Copyright 2018-2025
 # Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
 
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -54,7 +54,7 @@ class FreesurferAnnot(_provider.VolumeProvider, srctype="freesurfer-annot"):
                 frag_labels[selected_label] = 1
                 frag_labels[~selected_label] = 0
             else:
-                frag_labels[frag_labels == -1] = 0  # annot files store backgorund as -1 while siibra uses 0
+                frag_labels[frag_labels == -1] = 0  # annot files store background as -1 while siibra uses 0
             vertex_labels.append(frag_labels)
 
         return {"labels": np.hstack(vertex_labels)}
@@ -98,7 +98,7 @@ class ZippedFreesurferAnnot(_provider.VolumeProvider, srctype="zip/freesurfer-an
                 frag_labels[selected_label] = 1
                 frag_labels[~selected_label] = 0
             else:
-                frag_labels[frag_labels == -1] = 0  # annot files store backgorund as -1 while siibra uses 0
+                frag_labels[frag_labels == -1] = 0  # annot files store background as -1 while siibra uses 0
             vertex_labels.append(frag_labels)
 
         return {"labels": np.hstack(vertex_labels)}

siibra/volumes/providers/gifti.py

@@ -1,4 +1,4 @@
-# Copyright 2018-2024
+# Copyright 2018-2025
 # Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
 
 # Licensed under the Apache License, Version 2.0 (the "License");