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

siibra/VERSION

@@ -1 +1 @@
-0.5a02
+1.0.0-alpha.1

siibra/__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");
@@ -33,10 +33,13 @@ from .retrieval.requests import (
     EbrainsRequest as _EbrainsRequest,
     CACHE as cache
 )
+from .retrieval.cache import Warmup, WarmupLevel
+
 from . import configuration
+from . import experimental
 from .configuration import factory
 from . import features, livequeries
-from siibra.locations import Point, PointSet
+from siibra.locations import Point, PointCloud
 
 import os as _os
 logger.info(f"Version: {__version__}")
@@ -48,7 +51,7 @@ logger.info(
 # forward access to some functions
 set_ebrains_token = _EbrainsRequest.set_token
 fetch_ebrains_token = _EbrainsRequest.fetch_token
-find_regions = _parcellation.Parcellation.find_regions
+find_regions = _parcellation.find_regions
 from_json = factory.Factory.from_json
 
 
@@ -104,6 +107,14 @@ def set_feasible_download_size(maxsize_gbyte):
 
 
 def set_cache_size(maxsize_gbyte: int):
+    """
+    siibra runs maintainance on its local cache to keep it under a predetermined
+    size of 2 gigabytes. This method changes the cache size.
+
+    Parameters
+    ----------
+    maxsize_gbyte : int
+    """
     assert maxsize_gbyte >= 0
     cache.SIZE_GIB = maxsize_gbyte
     logger.info(f"Set cache size to {maxsize_gbyte} GiB.")
@@ -113,7 +124,7 @@ if "SIIBRA_CACHE_SIZE_GIB" in _os.environ:
     set_cache_size(float(_os.environ.get("SIIBRA_CACHE_SIZE_GIB")))
 
 
-def warm_cache():
+def warm_cache(level=WarmupLevel.INSTANCE):
     """
     Preload preconfigured siibra concepts.
 
@@ -122,12 +133,7 @@ def warm_cache():
     features. By preloading the instances, siibra commits all preconfigurations
     to the memory at once instead of commiting them when required.
     """
-    _ = _atlas.Atlas.registry()
-    _ = _space.Space.registry()
-    _ = _parcellation.Parcellation.registry()
-    _ = _parcellationmap.Map.registry()
-    features.warm_cache()
-    livequeries.warm_cache()
+    Warmup.warmup(level)
 
 
 def __dir__():
@@ -144,7 +150,7 @@ def __dir__():
         "get_template",
         "MapType",
         "Point",
-        "PointSet",
+        "PointCloud",
         "QUIET",
         "VERBOSE",
         "fetch_ebrains_token",
@@ -152,5 +158,7 @@ def __dir__():
         "vocabularies",
         "__version__",
         "cache",
-        "warm_cache"
+        "warm_cache",
+        "set_cache_size",
+        "from_json",
     ]

siibra/commons.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,19 +18,24 @@ import os
 import re
 from enum import Enum
 from nibabel import Nifti1Image
+from nilearn.image import resample_to_img
 import logging
 from tqdm import tqdm
 import numpy as np
 import pandas as pd
-from typing import Generic, Iterable, Iterator, List, TypeVar, Union, Dict
+from typing import Generic, Iterable, Iterator, List, TypeVar, Union, Dict, Generator, Tuple
 from skimage.filters import gaussian
 from dataclasses import dataclass
+from hashlib import md5
+from uuid import UUID
+import math
 try:
     from typing import TypedDict
 except ImportError:
     # support python 3.7
     from typing_extensions import TypedDict
 
+logging.addLevelName(21, "INFO_WO_PROGRESS_BARS")
 logger = logging.getLogger(__name__.split(os.path.extsep)[0])
 ch = logging.StreamHandler()
 formatter = logging.Formatter("[{name}:{levelname}] {message}", style="{")
@@ -47,7 +52,7 @@ SIIBRA_LOG_LEVEL = os.getenv("SIIBRA_LOG_LEVEL", "INFO")
 SIIBRA_USE_CONFIGURATION = os.getenv("SIIBRA_USE_CONFIGURATION")
 SIIBRA_USE_LOCAL_SNAPSPOT = os.getenv("SIIBRA_USE_LOCAL_SNAPSPOT")
 SKIP_CACHEINIT_MAINTENANCE = os.getenv("SKIP_CACHEINIT_MAINTENANCE")
-NEUROGLANCER_MAX_GIB = os.getenv("NEUROGLANCER_MAX_GIB", 0.2)
+SIIBRA_MAX_FETCH_SIZE_GIB = float(os.getenv("SIIBRA_MAX_FETCH_SIZE_GIB", 0.2))
 
 with open(os.path.join(ROOT_DIR, "VERSION"), "r") as fp:
     __version__ = fp.read().strip()
@@ -99,9 +104,11 @@ class InstanceTable(Generic[T], Iterable):
         self._dataframe_cached = None
 
     def add(self, key: str, value: T) -> None:
-        """Add a key/value pair to the registry.
+        """
+        Add a key/value pair to the registry.
 
-        Args:
+        Parameters
+        ----------
             key (string): Unique name or key of the object
             value (object): The registered object
         """
@@ -124,6 +131,9 @@ class InstanceTable(Generic[T], Iterable):
         else:
             return f"Empty {self.__class__.__name__}"
 
+    def __repr__(self):
+        return f"<{self.__class__.__name__} of {self[0].__class__}>"
+
     def __iter__(self) -> Iterator[T]:
         """Iterate over all objects in the registry"""
         return (w for w in self._elements.values())
@@ -147,10 +157,13 @@ class InstanceTable(Generic[T], Iterable):
         the first in sorted order is returned. If the specification does not match,
         a RuntimeError is raised.
 
-        Args:
-            spec [int or str]: Index or string specification of an object
+        Parameters
+        ----------
+        spec: int, str
+            Index or string specification of an object
 
-        Returns:
+        Returns
+        -------
             Matched object
         """
         if spec is None:
@@ -159,10 +172,9 @@ class InstanceTable(Generic[T], Iterable):
             raise IndexError(f"{__class__.__name__} indexed with empty string")
         matches = self.find(spec)
         if len(matches) == 0:
-            print(str(self))
             raise IndexError(
-                f"{__class__.__name__} has no entry matching the specification '{spec}'.\n"
-                f"Possible values are: " + ", ".join(self._elements.keys())
+                f"{__class__.__name__} has no entry matching the specification '{spec}'."
+                f"Possible values are:\n" + str(self)
             )
         elif len(matches) == 1:
             return matches[0]
@@ -286,7 +298,7 @@ def siibra_tqdm(iterable: Iterable[T] = None, *args, **kwargs):
     return tqdm(
         iterable,
         *args,
-        disable=kwargs.pop("disable", False) or (logger.level > 20),
+        disable=kwargs.pop("disable", False) or (logger.level > logging.INFO),
         **kwargs
     )
 
@@ -334,10 +346,11 @@ class MapIndex:
         return f"(volume:{self.volume}, label:{self.label}, fragment:{self.fragment})"
 
     def __repr__(self):
-        return f"{self.__class__.__name__}{str(self)}"
+        frag = f"'{self.fragment}'" if self.fragment else self.fragment
+        return f"<{self.__class__.__name__}(volume={self.volume}, label={self.label}, fragment={frag})>"
 
     def __eq__(self, other):
-        assert isinstance(other, self.__class__)
+        assert isinstance(other, self.__class__), f'Cannot compare {self.__class__} and {other.__class__}'
         return all([
             self.volume == other.volume,
             self.label == other.label,
@@ -353,9 +366,6 @@ class MapType(Enum):
     STATISTICAL = 2
 
 
-SIIBRA_DEFAULT_MAPTYPE = MapType.LABELLED
-SIIBRA_DEFAULT_MAP_THRESHOLD = None
-
 REMOVE_FROM_NAME = [
     "hemisphere",
     " -",
@@ -392,10 +402,8 @@ NZCACHE = {}
 
 
 def nonzero_coordinates(arr):
-    obj_id = id(arr)
-    if obj_id not in NZCACHE:
-        NZCACHE[obj_id] = np.c_[np.nonzero(arr > 0)]
-    return NZCACHE[obj_id]
+    # TODO: fix caching
+    return np.c_[np.nonzero(arr > 0)]
 
 
 def affine_scaling(affine):
@@ -408,34 +416,18 @@ def affine_scaling(affine):
     return np.prod(unit_lengths)
 
 
-def iterate_connected_components(img: Nifti1Image):
-    """
-    Provide an iterator over masks of connected components in the given image.
-    """
-    from skimage import measure
-    imgdata = np.asanyarray(img.dataobj).squeeze()
-    components = measure.label(imgdata > 0)
-    component_labels = np.unique(components)
-    assert component_labels[0] == 0
-    return (
-        (label, Nifti1Image((components == label).astype('uint8'), img.affine))
-        for label in component_labels[1:]
-    )
-
-
-def compare_maps(map1: Nifti1Image, map2: Nifti1Image):
+def compare_arrays(arr1: np.ndarray, affine1: np.ndarray, arr2: np.ndarray, affine2: np.ndarray):
     """
-    Compare two maps, given as Nifti1Image objects.
-    This function exploits that nibabel's get_fdata() caches the numerical arrays,
-    so we can use the object id to cache extraction of the nonzero coordinates.
+    Compare two arrays in physical space as defined by the given affine matrices.
+    Matrices map voxel coordinates to physical coordinates.
+    This function uses the object id to cache extraction of the nonzero coordinates.
     Repeated calls involving the same map will therefore be much faster as they
     will only access the image array if overlapping pixels are detected.
 
     It is recommended to install the indexed-gzip package,
     which will further speed this up.
     """
-
-    a1, a2 = [m.get_fdata().squeeze() for m in (map1, map2)]
+    a1, a2 = arr1.squeeze(), arr2.squeeze()
 
     def homog(XYZ):
         return np.c_[XYZ, np.ones(XYZ.shape[0])]
@@ -446,7 +438,7 @@ def compare_maps(map1: Nifti1Image, map2: Nifti1Image):
     # Compute the nonzero voxels in map2 and their correspondences in map1
     XYZnz2 = nonzero_coordinates(a2)
     N2 = XYZnz2.shape[0]
-    warp2on1 = np.dot(np.linalg.inv(map1.affine), map2.affine)
+    warp2on1 = np.dot(np.linalg.inv(affine1), affine2)
     XYZnz2on1 = (np.dot(warp2on1, homog(XYZnz2).T).T[:, :3] + 0.5).astype("int")
 
     # valid voxel pairs
@@ -454,9 +446,9 @@ def compare_maps(map1: Nifti1Image, map2: Nifti1Image):
         np.logical_and.reduce(
             [
                 XYZnz2on1 >= 0,
-                XYZnz2on1 < map1.shape[:3],
+                XYZnz2on1 < arr1.shape[:3],
                 XYZnz2 >= 0,
-                XYZnz2 < map2.shape[:3],
+                XYZnz2 < arr2.shape[:3],
             ]
         ),
         1,
@@ -481,14 +473,14 @@ def compare_maps(map1: Nifti1Image, map2: Nifti1Image):
     # Compute the nonzero voxels in map1 with their correspondences in map2
     XYZnz1 = nonzero_coordinates(a1)
     N1 = XYZnz1.shape[0]
-    warp1on2 = np.dot(np.linalg.inv(map2.affine), map1.affine)
+    warp1on2 = np.dot(np.linalg.inv(affine2), affine1)
 
     # Voxels referring to the union of the nonzero pixels in both maps
     XYZa1 = np.unique(np.concatenate((XYZnz1, XYZnz2on1)), axis=0)
     XYZa2 = (np.dot(warp1on2, homog(XYZa1).T).T[:, :3] + 0.5).astype("int")
     valid = np.all(
         np.logical_and.reduce(
-            [XYZa1 >= 0, XYZa1 < map1.shape[:3], XYZa2 >= 0, XYZa2 < map2.shape[:3]]
+            [XYZa1 >= 0, XYZa1 < arr1.shape[:3], XYZa2 >= 0, XYZa2 < arr2.shape[:3]]
         ),
         1,
     )
@@ -520,47 +512,75 @@ def compare_maps(map1: Nifti1Image, map2: Nifti1Image):
     )
 
 
-class PolyLine:
-    """Simple polyline representation which allows equidistant sampling.."""
-
-    def __init__(self, pts):
-        self.pts = pts
-        self.lengths = [
-            np.sqrt(np.sum((pts[i, :] - pts[i - 1, :]) ** 2))
-            for i in range(1, pts.shape[0])
-        ]
+def resample_img_to_img(
+    source_img: Nifti1Image,
+    target_img: Nifti1Image,
+    interpolation: str = ""
+) -> Nifti1Image:
+    """
+    Resamples to source image to match the target image according to target's
+    affine. (A wrapper of `nilearn.image.resample_to_img`.)
+
+    Parameters
+    ----------
+    source_img : Nifti1Image
+    target_img : Nifti1Image
+    interpolation : str, Default: "nearest" if the source image is a mask otherwise "linear".
+        Can be 'continuous', 'linear', or 'nearest'. Indicates the resample method.
+
+    Returns
+    -------
+    Nifti1Image
+    """
+    interpolation = "nearest" if np.array_equal(np.unique(source_img.dataobj), [0, 1]) else "linear"
+    resampled_img = resample_to_img(
+        source_img=source_img,
+        target_img=target_img,
+        interpolation=interpolation
+    )
+    return resampled_img
 
-    def length(self):
-        return sum(self.lengths)
 
-    def sample(self, d):
+def connected_components(
+    imgdata: np.ndarray,
+    background: int = 0,
+    connectivity: int = 2,
+    threshold: float = 0.0,
+) -> Generator[Tuple[int, np.ndarray], None, None]:
+    """
+    Provide an iterator over connected components in the array. If the image
+    data is float (such as probability maps), it will convert to a mask and
+    then find the connected components.
+
+    Note
+    ----
+    `Uses skimage.measure.label()` to determine foreground compenents.
+
+    Parameters
+    ----------
+    imgdata : np.ndarray
+    background_value : int, Default: 0
+    connectivity : int, Default: 2
+    threshold: float, Default: 0.0
+        The threshold used to create mask from probability maps, i.e, anything
+        below set to 0 and rest to 1.
+
+    Yields
+    ------
+    Generator[Tuple[int, np.ndarray], None, None]
+        tuple of integer label of the component and component as an nd.array in
+        the shape of the original image.
+    """
+    from skimage import measure
 
-        # if d is interable, we assume a list of sample positions
-        try:
-            iter(d)
-        except TypeError:
-            positions = [d]
-        else:
-            positions = d
-
-        samples = []
-        for s_ in positions:
-            s = min(max(s_, 0), 1)
-            target_distance = s * self.length()
-            current_distance = 0
-            for i, length in enumerate(self.lengths):
-                current_distance += length
-                if current_distance >= target_distance:
-                    p1 = self.pts[i, :]
-                    p2 = self.pts[i + 1, :]
-                    r = (target_distance - current_distance + length) / length
-                    samples.append(p1 + (p2 - p1) * r)
-                    break
-
-        if len(samples) == 1:
-            return samples[0]
-        else:
-            return np.array(samples)
+    mask = (imgdata > threshold).astype('uint8')
+    components = measure.label(mask, connectivity=connectivity, background=background)
+    component_labels = np.unique(components)
+    return (
+        (label, (components == label).astype('uint8'))
+        for label in component_labels
+        if label > 0
+    )
 
 
 def unify_stringlist(L: list):
@@ -606,11 +626,15 @@ def MI(arr1, arr2, nbins=100, normalized=True):
     """
     Compute the mutual information between two 3D arrays, which need to have the same shape.
 
-    Parameters:
-    arr1 : First 3D array
-    arr2 : Second 3D array
-    nbins : number of bins to use for computing the joint histogram (applies to intensity range)
-    normalized : Boolean, default:True
+    Parameters
+    ----------
+    arr1: np.ndarray
+        First 3D array
+    arr2: np.ndarray
+        Second 3D array
+    nbins: int
+        number of bins to use for computing the joint histogram (applies to intensity range)
+    normalized: Boolean. Default: True
         if True, the normalized MI of arrays X and Y will be returned,
         leading to a range of values between 0 and 1. Normalization is
         achieved by NMI = 2*MI(X,Y) / (H(X) + H(Y)), where  H(x) is the entropy of X
@@ -766,3 +790,34 @@ class Species(Enum):
 
     def __repr__(self):
         return f"{self.__class__.__name__}: {str(self)}"
+
+
+def generate_uuid(string: str):
+    if isinstance(string, str):
+        b = string.encode("UTF-8")
+    elif isinstance(string, Nifti1Image):
+        b = string.to_bytes()
+    else:
+        raise ValueError(f"Cannot build uuid for parameter type {type(string)}")
+    hex_string = md5(b).hexdigest()
+    return str(UUID(hex=hex_string))
+
+
+def translation_matrix(tx: float, ty: float, tz: float):
+    """Construct a 3D homoegneous translation matrix."""
+    return np.array([
+        [1, 0, 0, tx],
+        [0, 1, 0, ty],
+        [0, 0, 1, tz],
+        [0, 0, 0, 1]
+    ])
+
+
+def y_rotation_matrix(alpha: float):
+    """Construct a 3D y axis rotation matrix."""
+    return np.array([
+        [math.cos(alpha), 0, math.sin(alpha), 0],
+        [0, 1, 0, 0],
+        [-math.sin(alpha), 0, math.cos(alpha), 0],
+        [0, 0, 0, 1]
+    ])

siibra/configuration/__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/configuration/configuration.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,11 +14,11 @@
 # limitations under the License.
 
 from ..commons import logger, __version__, SIIBRA_USE_CONFIGURATION, siibra_tqdm
-from ..retrieval.repositories import GitlabConnector, RepositoryConnector
+from ..retrieval.repositories import GitlabConnector, RepositoryConnector, GithubConnector
 from ..retrieval.exceptions import NoSiibraConfigMirrorsAvailableException
 from ..retrieval.requests import SiibraHttpRequestError
 
-from typing import Union
+from typing import Union, List
 from collections import defaultdict
 from requests.exceptions import ConnectionError
 from os import path
@@ -35,16 +35,20 @@ class Configuration:
     """
 
     CONFIG_REPOS = [
-        ("https://jugit.fz-juelich.de", 3484),
-        ("https://gitlab.ebrains.eu", 93),
+        (GithubConnector, "FZJ-INM1-BDA", "siibra-configurations"),
+        (GitlabConnector, "https://gitlab.ebrains.eu", 892)
     ]
-
-    CONFIGURATIONS = [
-        GitlabConnector(server, project, "siibra-{}".format(__version__), skip_branchtest=True)
-        for server, project in CONFIG_REPOS
+    CONFIG_CONNECTORS: List[RepositoryConnector] = [
+        conn(
+            server_or_owner,
+            project_or_repo,
+            reftag="siibra-{}".format(__version__),
+            skip_branchtest=True
+        )
+        for conn, server_or_owner, project_or_repo in CONFIG_REPOS
     ]
 
-    CONFIGURATION_EXTENSIONS = []
+    CONFIG_EXTENSIONS = []
 
     _cleanup_funcs = []
 
@@ -65,7 +69,7 @@ class Configuration:
         self.spec_loaders = defaultdict(list)
 
         # retrieve json spec loaders from the default configuration
-        for connector in self.CONFIGURATIONS:
+        for connector in self.CONFIG_CONNECTORS:
             try:
                 for folder in self.get_folders(connector):
                     loaders = connector.get_loaders(folder, suffix='.json')
@@ -74,7 +78,7 @@ class Configuration:
                 break
             except (ConnectionError, SiibraHttpRequestError):
                 logger.error(f"Cannot load configuration from {str(connector)}")
-                *_, last = self.CONFIGURATIONS
+                *_, last = self.CONFIG_CONNECTORS
                 if connector is last:
                     raise NoSiibraConfigMirrorsAvailableException(
                         "Tried all mirrors, none available."
@@ -83,7 +87,7 @@ class Configuration:
             raise RuntimeError("Cannot pull any default siibra configuration.")
 
         # add additional spec loaders from extension configurations
-        for connector in self.CONFIGURATION_EXTENSIONS:
+        for connector in self.CONFIG_EXTENSIONS:
             try:
                 for folder in self.get_folders(connector):
                     self.spec_loaders[folder].extend(
@@ -110,7 +114,7 @@ class Configuration:
         if not isinstance(conn, RepositoryConnector):
             raise RuntimeError("Configuration needs to be an instance of RepositoryConnector or a valid str")
         logger.info(f"Using custom configuration from {str(conn)}")
-        cls.CONFIGURATIONS = [conn]
+        cls.CONFIG_CONNECTORS = [conn]
         # call registered cleanup functions
         for func in cls._cleanup_funcs:
             func()
@@ -121,11 +125,11 @@ class Configuration:
             conn = RepositoryConnector._from_url(conn)
         if not isinstance(conn, RepositoryConnector):
             raise RuntimeError("conn needs to be an instance of RepositoryConnector or a valid str")
-        if conn in cls.CONFIGURATION_EXTENSIONS:
+        if conn in cls.CONFIG_EXTENSIONS:
             logger.warning(f"The configuration {str(conn)} is already registered.")
         else:
             logger.info(f"Extending configuration with {str(conn)}")
-            cls.CONFIGURATION_EXTENSIONS.append(conn)
+            cls.CONFIG_EXTENSIONS.append(conn)
             # call registered cleanup functions
             for func in cls._cleanup_funcs:
                 func()
@@ -164,7 +168,8 @@ class Configuration:
         for fname, loader in siibra_tqdm(
             specloaders,
             total=len(specloaders),
-            desc=f"Loading preconfigured {obj_class} instances"
+            desc=f"Loading preconfigured {obj_class} instances",
+            unit=obj_class
         ):
             # filename is added to allow Factory creating reasonable default object identifiers\
             obj = Factory.from_json(dict(loader.data, **{'filename': fname}))