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

siibra/VERSION

@@ -1 +1 @@
-1.0a19
+1.0.1-alpha.1

siibra/__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");
@@ -39,7 +39,7 @@ 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__}")
@@ -51,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
 
 
@@ -108,7 +108,7 @@ 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
+    siibra runs maintenance on its local cache to keep it under a predetermined
     size of 2 gigabytes. This method changes the cache size.
 
     Parameters
@@ -129,9 +129,9 @@ def warm_cache(level=WarmupLevel.INSTANCE):
     Preload preconfigured siibra concepts.
 
     Siibra relies on preconfigurations that simplify integrating various
-    concepts such as parcellations, refernce spaces, and multimodal data
+    concepts such as parcellations, reference spaces, and multimodal data
     features. By preloading the instances, siibra commits all preconfigurations
-    to the memory at once instead of commiting them when required.
+    to the memory at once instead of committing them when required.
     """
     Warmup.warmup(level)
 
@@ -150,7 +150,7 @@ def __dir__():
         "get_template",
         "MapType",
         "Point",
-        "PointSet",
+        "PointCloud",
         "QUIET",
         "VERBOSE",
         "fetch_ebrains_token",

siibra/commons.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");
@@ -139,7 +139,7 @@ class InstanceTable(Generic[T], Iterable):
         return (w for w in self._elements.values())
 
     def __contains__(self, key: Union[str, T]) -> bool:
-        """Test wether the given key or element is defined by the registry."""
+        """Test whether the given key or element is defined by the registry."""
         if isinstance(key, str):
             return key in self._elements
         return key in [item for _, item in self._elements.values()]
@@ -366,9 +366,6 @@ class MapType(Enum):
     STATISTICAL = 2
 
 
-SIIBRA_DEFAULT_MAPTYPE = MapType.LABELLED
-SIIBRA_DEFAULT_MAP_THRESHOLD = 0.0
-
 REMOVE_FROM_NAME = [
     "hemisphere",
     " -",
@@ -539,7 +536,8 @@ def resample_img_to_img(
     resampled_img = resample_to_img(
         source_img=source_img,
         target_img=target_img,
-        interpolation=interpolation
+        interpolation=interpolation,
+        force_resample=True,  # False is intended for testing. see nilearn docs
     )
     return resampled_img
 
@@ -557,7 +555,7 @@ def connected_components(
 
     Note
     ----
-    `Uses skimage.measure.label()` to determine foreground compenents.
+    `Uses skimage.measure.label()` to determine foreground components.
 
     Parameters
     ----------
@@ -571,7 +569,7 @@ def connected_components(
     Yields
     ------
     Generator[Tuple[int, np.ndarray], None, None]
-        tuple of integer label of the component and component as an nd.array in
+        tuple of integer label of the component and component as an ndarray in
         the shape of the original image.
     """
     from skimage import measure
@@ -586,49 +584,6 @@ def connected_components(
     )
 
 
-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 length(self):
-        return sum(self.lengths)
-
-    def sample(self, d):
-
-        # 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)
-
-
 def unify_stringlist(L: list):
     """Adds asterisks to strings that appear multiple times, so the resulting
     list has only unique strings but still the same length, order, and meaning.
@@ -690,11 +645,11 @@ def MI(arr1, arr2, nbins=100, normalized=True):
     assert (all(arr.size > 0) for arr in [arr1, arr2])
 
     # compute the normalized joint 2D histogram as an
-    # empirical measure of the joint probabily of arr1 and arr2
+    # empirical measure of the joint probability of arr1 and arr2
     pxy, _, _ = np.histogram2d(arr1.ravel(), arr2.ravel(), bins=nbins)
     pxy /= pxy.sum()
 
-    # extract the empirical propabilities of intensities
+    # extract the empirical probabilities of intensities
     # from the joint histogram
     px = np.sum(pxy, axis=1)  # marginal for x over y
     py = np.sum(pxy, axis=0)  # marginal for y over x

siibra/configuration/__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/configuration/configuration.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/configuration/factory.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");
@@ -24,7 +24,7 @@ from ..features.tabular import (
 )
 from ..features.image import sections, volume_of_interest
 from ..core import atlas, parcellation, space, region
-from ..locations import point, pointset, boundingbox
+from ..locations import point, pointcloud, boundingbox
 from ..retrieval import datasets, repositories
 from ..volumes import volume, sparsemap, parcellationmap
 from ..volumes.providers.provider import VolumeProvider
@@ -302,25 +302,18 @@ class Factory:
     @build_type("siibra/map/v0.0.1")
     def build_map(cls, spec):
         # maps have no configured identifier - we require the spec filename to build one
-        assert "filename" in spec
-        basename = path.splitext(path.basename(spec["filename"]))[0]
-        name = (
-            basename.replace("-", " ")
-            .replace("_", " ")
-            .replace("continuous", "statistical")
-        )
-        identifier = f"{spec['@type'].replace('/', '-')}_{basename}"
+        identifier = spec.get("@id")
         volumes = cls.extract_volumes(
-            spec, space_id=spec["space"].get("@id"), name_prefix=basename
+            spec, space_id=spec["space"].get("@id"), name_prefix=identifier
         )
 
-        if spec.get("sparsemap", {}).get("is_sparsemap"):
+        if spec.get("represented_as_sparsemap", False):
             Maptype = sparsemap.SparseMap
         else:
             Maptype = parcellationmap.Map
         return Maptype(
-            identifier=spec.get("@id", identifier),
-            name=spec.get("name", name),
+            identifier=identifier,
+            name=spec.get("name"),
             space_spec=spec.get("space", {}),
             parcellation_spec=spec.get("parcellation", {}),
             indices=spec.get("indices", {}),
@@ -363,18 +356,18 @@ class Factory:
 
     @classmethod
     @build_type("tmp/poly")
-    @build_type("siibra/location/pointset/v0.1")
-    def build_pointset(cls, spec):
+    @build_type("siibra/location/pointcloud/v0.1")
+    def build_pointcloud(cls, spec):
         if spec.get("@type") == "tmp/poly":
             space_id = spec["coordinateSpace"]["@id"]
             coords = []
             for coord in spec["coordinates"]:
                 assert all(c["unit"]["@id"] == "id.link/mm" for c in coord)
                 coords.append(list(np.float16(c["value"]) for c in coord))
-        elif spec.get("@type") == "siibra/location/pointset/v0.1":
+        elif spec.get("@type") == "siibra/location/pointcloud/v0.1":
             space_id = spec.get("space").get("@id")
             coords = [tuple(c) for c in spec.get("coordinates")]
-        return pointset.PointSet(coords, space=space_id)
+        return pointcloud.PointCloud(coords, space=space_id)
 
     @classmethod
     @build_type("siibra/location/boundingbox/v0.1")
@@ -584,11 +577,8 @@ class Factory:
 
         if isinstance(spec, str):
             if path.isfile(spec):
-                fname = spec
                 with open(spec, "r") as f:
                     spec = json.load(f)
-                    assert "filename" not in spec
-                    spec["filename"] = fname
             else:
                 spec = json.loads(spec)
 

siibra/core/__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/core/assignment.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/core/atlas.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");
@@ -197,27 +197,29 @@ class Atlas(concept.AtlasConcept, configuration_folder="atlases"):
 
     def find_regions(
         self,
-        regionspec,
-        all_versions=False,
-        filter_children=True,
-        **kwargs
+        regionspec: str,
+        all_versions: bool = False,
+        filter_children: bool = True,
+        find_topmost: bool = False
     ):
         """
-        Find regions with the given specification in all
-        parcellations offered by the atlas. Additional kwargs
-        are passed on to Parcellation.find().
+        Find regions with the given specification in all parcellations offered
+        by the atlas.
 
         Parameters
         ----------
-        regionspec: str, regex, int, Region, MapIndex
+        regionspec: str, regex
             - a string with a possibly inexact name (matched both against the name and the identifier key)
             - a string in '/pattern/flags' format to use regex search (acceptable flags: aiLmsux, see at https://docs.python.org/3/library/re.html#flags)
             - a regex applied to region names
-            - a Region object
         all_versions : Bool, default: False
             If True, matched regions for all versions of a parcellation are returned.
         filter_children : bool, default: True
             If False, children of matched parents will be returned.
+        find_topmost : bool, default: False
+            If True (requires `filter_children=True`), will return parent
+            structures if all children are matched, even though the parent
+            itself might not match the specification.
 
         Returns
         -------
@@ -225,9 +227,13 @@ class Atlas(concept.AtlasConcept, configuration_folder="atlases"):
             list of regions matching to the regionspec
         """
         result = []
-        for p in self._parcellation_ids:
-            parcobj = _parcellation.Parcellation.get_instance(p)
-            if parcobj.is_newest_version or all_versions:
-                match = parcobj.find(regionspec, filter_children=filter_children, **kwargs)
-                result.extend(match)
+        for p in self.parcellations:
+            if p.is_newest_version or all_versions:
+                result.extend(
+                    p.find(
+                        regionspec=regionspec,
+                        filter_children=filter_children,
+                        find_topmost=find_topmost
+                    )
+                )
         return result

siibra/core/concept.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");
@@ -145,9 +145,9 @@ class AtlasConcept:
     @property
     def authors(self):
         return [
-            contributer['name']
+            contributor['name']
             for ds in self.datasets
-            for contributer in ds.contributors
+            for contributor in ds.contributors
         ]
 
     @property

siibra/core/parcellation.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");
@@ -17,11 +17,21 @@ from . import region
 
 from ..commons import logger, MapType, Species
 from ..volumes import parcellationmap
+from ..exceptions import MapNotFound
 
-from typing import Union, List, Dict
+from functools import lru_cache
 import re
+from typing import Union, List, TYPE_CHECKING
+try:
+    from typing import Literal
+except ImportError:
+    # support python 3.7
+    from typing_extensions import Literal
 
 
+if TYPE_CHECKING:
+    from .space import Space
+
 # NOTE : such code could be used to automatically resolve
 # multiple matching parcellations for a short spec to the newset version:
 #               try:
@@ -68,8 +78,6 @@ class ParcellationVersion:
 
 class Parcellation(region.Region, configuration_folder="parcellations"):
 
-    _CACHED_REGION_SEARCHES: Dict[str, List[region.Region]] = {}
-
     def __init__(
         self,
         identifier: str,
@@ -140,7 +148,12 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
                     self._CACHED_MATCHES[spec] = True
         return super().matches(spec)
 
-    def get_map(self, space=None, maptype: Union[str, MapType] = MapType.LABELLED, spec: str = ""):
+    def get_map(
+        self,
+        space: Union[str, "Space"],
+        maptype: Union[Literal['labelled', 'statistical'], MapType] = MapType.LABELLED,
+        spec: str = ""
+    ):
         """
         Get the maps for the parcellation in the requested template space.
 
@@ -153,8 +166,8 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
         Parameters
         ----------
         space: Space or str
-            template space specification
-        maptype: MapType
+            reference space specification such as name, id, or a `Space` instance.
+        maptype: MapType or str
             Type of map requested (e.g., statistical or labelled).
             Use MapType.STATISTICAL to request probability maps.
             Defaults to MapType.LABELLED.
@@ -169,26 +182,24 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
             A ParcellationMap representing the volumetric map or
             a SparseMap representing the list of statistical maps.
         """
-        if not isinstance(maptype, MapType):
+        if isinstance(maptype, str):
             maptype = MapType[maptype.upper()]
+        assert isinstance(maptype, MapType), "Possible values of `maptype` are `MapType`s, 'labelled', 'statistical'."
 
         candidates = [
             m for m in parcellationmap.Map.registry()
             if m.space.matches(space)
             and m.maptype == maptype
-            and m.parcellation
             and m.parcellation.matches(self)
         ]
         if len(candidates) == 0:
-            logger.error(f"No {maptype} map in {space} available for {str(self)}")
-            return None
+            raise MapNotFound(f"No '{maptype}' map in '{space}' available for {str(self)}")
         if len(candidates) > 1:
             spec_candidates = [
-                c for c in candidates if all(w.lower() in c.name.lower() for w in spec.split())
+                c for c in candidates if all(w.lower() in c.id.lower() for w in spec.split())
             ]
             if len(spec_candidates) == 0:
-                logger.warning(f"'{spec}' does not match any options from {[c.name for c in candidates]}.")
-                return None
+                raise MapNotFound(f"'{spec}' does not match any options from {[c.name for c in candidates]}.")
             if len(spec_candidates) > 1:
                 logger.warning(
                     f"Multiple maps are available in this specification of space, parcellation, and map type.\n"
@@ -197,43 +208,6 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
             return spec_candidates[0]
         return candidates[0]
 
-    @staticmethod
-    def find_regions(region_spec: str, parents_only=True):
-        """
-        Find regions that match the given region specification in the subtree
-        headed by each parcellation in the registry.
-        Note
-        ----
-        Use Region.find() to search for a region in an instance of a
-        parcellation.
-
-        Parameters
-        ----------
-        regionspec: str
-            a string with a possibly inexact name, which is matched both
-            against the name and the identifier key,
-        parents_only: bool
-            If true, children of matched parents will not be returned
-        Returns
-        -------
-        List[Region]
-            list of matching regions
-        """
-        MEM = Parcellation._CACHED_REGION_SEARCHES
-        if region_spec not in MEM:
-            MEM[region_spec] = [
-                r
-                for p in Parcellation.registry()
-                for r in p.find(regionspec=region_spec)
-            ]
-        if parents_only:
-            return [
-                r for r in MEM[region_spec]
-                if (r.parent is None) or (r.parent not in MEM[region_spec])
-            ]
-        else:
-            return MEM[region_spec]
-
     @property
     def is_newest_version(self):
         return (self.version is None) or (self.version.next_id is None)
@@ -247,7 +221,7 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
         """
         spec = re.sub(r'Group: *', '', spec)
         for substr in re.findall(r'\(.*?\)', spec):
-            # temporarilty replace commas inside brackets with a placeholder
+            # temporarily replace commas inside brackets with a placeholder
             # because these are not region spec delimiters
             spec = spec.replace(substr, re.sub(r', *', '##', substr))
         # process the comma separated substrings
@@ -263,7 +237,7 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
     def get_region(
         self,
         regionspec: Union[str, region.Region],
-        find_topmost: bool = True,
+        find_topmost: bool = False,
         allow_tuple: bool = False
     ):
         """
@@ -281,7 +255,7 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
         regionspec: str, Region
             - a string with a possibly inexact name (matched both against the name and the identifier key)
             - a Region object
-        find_topmost: bool, default: True
+        find_topmost: bool, default: False
             If True, will automatically return the parent of a decoded region
             the decoded region is its only child.
         allow_tuple: bool, default: False
@@ -370,3 +344,44 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
             )
             return self.name < other.name
         return self.version.__lt__(other.version)
+
+
+@lru_cache(maxsize=128)
+def find_regions(
+    regionspec: str,
+    filter_children=True,
+    find_topmost=False
+):
+    """
+    Find regions matching the given region specification across all parcellation
+    instances in the registry.
+
+    Parameters
+    ----------
+    regionspec: str, regex, Region
+        - a string with a possibly inexact name (matched both against the name and the identifier key)
+        - a string in '/pattern/flags' format to use regex search (acceptable flags: aiLmsux) (see https://docs.python.org/3/library/re.html#flags)
+        - a regex applied to region names
+        - a Region object
+    filter_children : bool, default: True
+        If True, children of matched parents will not be returned
+    find_topmost : bool, default: False
+        If True (requires `filter_children=True`), will return parent
+        structures if all children are matched, even though the parent
+        itself might not match the specification.
+
+    Returns
+    -------
+    list[Region]
+        list of regions matching to the regionspec
+    """
+    result = []
+    for p in Parcellation.registry():
+        result.extend(
+            p.find(
+                regionspec=regionspec,
+                filter_children=filter_children,
+                find_topmost=find_topmost
+            )
+        )
+    return result