siibra 1.0.1a0__py3-none-any.whl → 1.0.1a2__py3-none-any.whl

siibra/retrieval/datasets.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");
@@ -14,19 +14,18 @@
 # limitations under the License.
 """Metadata connection to EBRAINS datasets."""
 
-from .requests import MultiSourcedRequest, GitlabProxy, GitlabProxyEnum
-
 import re
-from typing import Union, List
-from abc import ABC, abstractproperty
+from abc import ABC, abstractmethod
 from hashlib import md5
-
+from typing import Union, List
 try:
     from typing import TypedDict
 except ImportError:
     # support python 3.7
     from typing_extensions import TypedDict
 
+from .requests import MultiSourcedRequest, GitlabProxy, GitlabProxyEnum
+
 
 class EbrainsDatasetUrl(TypedDict):
     url: str
@@ -48,31 +47,38 @@ EbrainsDatasetEmbargoStatus = TypedDict("EbrainsDatasetEmbargoStatus", {
 
 
 class EbrainsBaseDataset(ABC):
-    @abstractproperty
+    @property
+    @abstractmethod
     def id(self) -> str:
         raise NotImplementedError
 
-    @abstractproperty
+    @property
+    @abstractmethod
     def name(self) -> str:
         raise NotImplementedError
 
-    @abstractproperty
+    @property
+    @abstractmethod
     def urls(self) -> List[EbrainsDatasetUrl]:
         raise NotImplementedError
 
-    @abstractproperty
+    @property
+    @abstractmethod
     def description(self) -> str:
         raise NotImplementedError
 
-    @abstractproperty
+    @property
+    @abstractmethod
     def contributors(self) -> List[EbrainsDatasetPerson]:
         raise NotImplementedError
 
-    @abstractproperty
+    @property
+    @abstractmethod
     def ebrains_page(self) -> str:
         raise NotImplementedError
 
-    @abstractproperty
+    @property
+    @abstractmethod
     def custodians(self) -> List[EbrainsDatasetPerson]:
         raise NotImplementedError
 
@@ -319,12 +325,12 @@ class EbrainsV3Dataset(EbrainsBaseDataset):
     @property
     def contributors(self):
         if self._contributers is None:
-            contributers = {}
+            contributors = {}
             for version_id in self.version_ids:
-                contributers.update(
+                contributors.update(
                     {c['@id']: c for c in EbrainsV3DatasetVersion(version_id).contributors}
                 )
-            self._contributers = list(contributers.values())
+            self._contributers = list(contributors.values())
         return self._contributers
 
     @property
@@ -342,7 +348,7 @@ class EbrainsV3Dataset(EbrainsBaseDataset):
         return [version.get("id") for version in self._detail.get("versions", [])]
 
 
-class GenericDataset():
+class GenericDataset:
 
     def __init__(
         self,

siibra/retrieval/exceptions/__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/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");
@@ -14,25 +14,24 @@
 # limitations under the License.
 """Connect to repositories to browse and pull files within."""
 
+from abc import ABC, abstractmethod
+from urllib.parse import quote
+import pathlib
+import os
+from zipfile import ZipFile
+from typing import List
+
+from .cache import CACHE
 from .requests import (
     HttpRequest,
     EbrainsRequest,
     SiibraHttpRequestError,
-    find_suitiable_decoder,
+    find_suitable_decoder,
     DECODERS,
     FileLoader
 )
-from .cache import CACHE
-
 from ..commons import logger, siibra_tqdm
 
-from abc import ABC, abstractmethod
-from urllib.parse import quote
-import pathlib
-import os
-from zipfile import ZipFile
-from typing import List
-
 
 class RepositoryConnector(ABC):
     """
@@ -67,7 +66,7 @@ class RepositoryConnector(ABC):
         pass
 
     def _decode_response(self, response, filename: str):
-        decoder = find_suitiable_decoder(filename)
+        decoder = find_suitable_decoder(filename)
         return decoder(response) if decoder else response
 
     def get(self, filename, folder="", decode_func=None):
@@ -196,7 +195,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)
@@ -258,7 +257,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"
@@ -584,7 +583,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");
@@ -14,35 +14,37 @@
 # limitations under the License.
 """Request files with decoders, lazy loading, and caching."""
 
-from .cache import CACHE, cache_user_fn
-from .exceptions import EbrainsAuthenticationError
-from ..commons import (
-    logger,
-    HBP_AUTH_TOKEN,
-    KEYCLOAK_CLIENT_ID,
-    KEYCLOAK_CLIENT_SECRET,
-    siibra_tqdm,
-    SIIBRA_USE_LOCAL_SNAPSPOT,
-)
-from .. import __version__
-
 import json
 from zipfile import ZipFile
 import requests
 import os
-from nibabel import Nifti1Image, GiftiImage, streamlines, freesurfer
-from skimage import io as skimage_io
 import gzip
 from io import BytesIO
 import urllib.parse
-import pandas as pd
-import numpy as np
 from typing import List, Callable, TYPE_CHECKING
 from enum import Enum
 from functools import wraps
 from time import sleep
 import sys
+
 from filelock import FileLock as Lock
+import numpy as np
+import pandas as pd
+from skimage import io as skimage_io
+from nibabel import Nifti1Image, GiftiImage, streamlines, freesurfer
+
+from . import exceptions as _exceptions
+from .cache import CACHE, cache_user_fn
+from .. import __version__
+from ..commons import (
+    logger,
+    HBP_AUTH_TOKEN,
+    KEYCLOAK_CLIENT_ID,
+    KEYCLOAK_CLIENT_SECRET,
+    siibra_tqdm,
+    SIIBRA_USE_LOCAL_SNAPSPOT,
+)
+
 if TYPE_CHECKING:
     from .repositories import GitlabConnector
 
@@ -91,11 +93,11 @@ DECODERS = {
 }
 
 
-def find_suitiable_decoder(url: str) -> Callable:
+def find_suitable_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
     ----------
@@ -108,7 +110,7 @@ def find_suitiable_decoder(url: str) -> Callable:
     """
     urlpath = urllib.parse.urlsplit(url).path
     if urlpath.endswith(".gz"):
-        dec = find_suitiable_decoder(urlpath[:-3])
+        dec = find_suitable_decoder(urlpath[:-3])
         if dec is None:
             return lambda b: gzip.decompress(b)
         else:
@@ -183,7 +185,7 @@ class HttpRequest:
         ----------
         func : Callable, default: None
         """
-        self.func = func or find_suitiable_decoder(self.url)
+        self.func = func or find_suitable_decoder(self.url)
 
     @property
     def cached(self):
@@ -193,7 +195,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
@@ -277,7 +279,7 @@ class FileLoader(HttpRequest):
     def __init__(self, filepath, func=None):
         HttpRequest.__init__(
             self, filepath, refresh=False,
-            func=func or find_suitiable_decoder(filepath)
+            func=func or find_suitable_decoder(filepath)
         )
         self.cachefile = filepath
 
@@ -291,7 +293,7 @@ class ZipfileRequest(HttpRequest):
     def __init__(self, url, filename, func=None, refresh=False):
         HttpRequest.__init__(
             self, url, refresh=refresh,
-            func=func or find_suitiable_decoder(filename)
+            func=func or find_suitable_decoder(filename)
         )
         self.filename = filename
 
@@ -388,7 +390,7 @@ class EbrainsRequest(HttpRequest):
                 ),  # if explicitly enabled by env var, do not raise
             ]
         ):
-            raise EbrainsAuthenticationError(
+            raise _exceptions.EbrainsAuthenticationError(
                 "sys.stdout is not tty, SIIBRA_ENABLE_DEVICE_FLOW is not set,"
                 "and not running in a notebook. Are you running in batch mode?"
             )
@@ -444,7 +446,7 @@ class EbrainsRequest(HttpRequest):
                     f"exceeded max attempts: {cls._IAM_DEVICE_MAXTRIES}, aborting..."
                 )
                 logger.error(message)
-                raise EbrainsAuthenticationError(message)
+                raise _exceptions.EbrainsAuthenticationError(message)
             attempt_number += 1
             resp = requests.post(
                 url=cls._IAM_TOKEN_ENDPOINT,
@@ -457,9 +459,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:
@@ -470,7 +472,7 @@ class EbrainsRequest(HttpRequest):
                 logger.debug(f"400 error: {resp.content}")
                 continue
 
-            raise EbrainsAuthenticationError(resp.content)
+            raise _exceptions.EbrainsAuthenticationError(resp.content)
 
     @classmethod
     def set_token(cls, token):

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");
@@ -14,11 +14,10 @@
 # limitations under the License.
 """Abbreviations and aliases."""
 
-from ..commons import InstanceTable
-
 import json
 from os import path
 
+from ..commons import InstanceTable
 
 RT_DIR = path.dirname(__file__)
 

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");
@@ -14,10 +14,11 @@
 # limitations under the License.
 """Package handling variety of volumes and volume operations"""
 
+from typing import List, Union
+
+import numpy as np
+
 from .parcellationmap import Map
 from .providers import provider
 from .volume import from_array, from_file, from_pointcloud, from_nifti, Volume
-
 from ..commons import logger
-from typing import List, Union
-import numpy as np

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");
@@ -14,9 +14,18 @@
 # limitations under the License.
 """Provides spatial representations for parcellations and regions."""
 
+from collections import defaultdict
+from dataclasses import dataclass, asdict
+from typing import Union, Dict, List, TYPE_CHECKING, Iterable, Tuple
+
+import numpy as np
+import pandas as pd
+from scipy.ndimage import distance_transform_edt
+from nilearn import image
+
 from . import volume as _volume
 from .providers import provider
-from .. import logger, QUIET, exceptions
+from .. import exceptions
 from ..commons import (
     MapIndex,
     MapType,
@@ -29,19 +38,13 @@ from ..commons import (
     siibra_tqdm,
     Species,
     CompareMapsResult,
-    generate_uuid
+    generate_uuid,
+    logger,
+    QUIET,
 )
 from ..core import concept, space, parcellation, region as _region
 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 nilearn import image
-import pandas as pd
-from dataclasses import dataclass, asdict
-
 if TYPE_CHECKING:
     from ..core.region import Region
 
@@ -503,7 +506,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.
 
@@ -690,7 +693,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, *, fill_uncolored: bool = False):
         """
         Generate a matplotlib colormap from known rgb values of label indices.
 
@@ -698,13 +701,24 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         ----------
         region_specs: iterable(regions), optional
             Optional parameter to only color the desired regions.
+        fill_uncolored: bool , optional
+            If a region has no preconfigured color, a color will be randomly (reproducible) created.
 
         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 fill_uncolored:
+            seed = len(self.regions)
+            np.random.seed(seed)
+            logger.info(f"Random colors are allowed for regions without preconfgirued colors. Random seed: {seed}.")
 
         colors = {}
         if region_specs is not None:
@@ -714,6 +728,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         else:
             include_region_names = None
 
+        no_predefined_color = []
         for regionname, indices in self._indices.items():
             for index in indices:
                 if index.label is None:
@@ -725,14 +740,34 @@ 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 fill_uncolored:
+                        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
+                    else:
+                        no_predefined_color.append(region.name)
+
+        if len(colors) == 0:
+            raise exceptions.NoPredifinedColormapException(
+                f"There is no predefined/preconfigured colormap for '{self}'."
+                "Set `fill_uncolored=True` to get a reproducible colormap."
+            )
+
+        if no_predefined_color:
+            logger.info(
+                f"No preconfigured color found for the following regions."
+                "Use `fill_uncolored=True` to display with a non-background color.\n"
+                f"{no_predefined_color}"
+            )
 
-        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.
@@ -750,7 +785,7 @@ class Map(concept.AtlasConcept, configuration_folder="maps"):
         Returns
         -------
         PointCloud
-            Sample points in physcial coordinates corresponding to this
+            Sample points in physical coordinates corresponding to this
             parcellationmap
         """
         index = self.get_index(regionspec)
@@ -923,7 +958,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)
             (
@@ -1032,7 +1067,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");
@@ -14,12 +14,12 @@
 # limitations under the License.
 """Handles reading and preparing gii files."""
 
-from . import provider as _provider
-
-from ...retrieval.requests import HttpRequest, ZipfileRequest
+from typing import Union, Dict, TYPE_CHECKING
 
 import numpy as np
-from typing import Union, Dict, TYPE_CHECKING
+
+from . import provider as _provider
+from ...retrieval.requests import HttpRequest, ZipfileRequest
 
 if TYPE_CHECKING:
     from ...locations import boundingbox as _boundingbox
@@ -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");
@@ -14,15 +14,15 @@
 # limitations under the License.
 """Handles reading and preparing gii files."""
 
-from . import provider as _provider
+from typing import Union, Dict
+
+import numpy as np
 
+from . import provider as _provider
 from ...retrieval import requests
 from ...commons import logger, merge_meshes
 from ...locations import boundingbox as _boundingbox
 
-import numpy as np
-from typing import Union, Dict
-
 
 class GiftiMesh(_provider.VolumeProvider, srctype="gii-mesh"):
     """