siibra 1.0a19__tar.gz → 1.0.1a0__tar.gz

{siibra-1.0a19/siibra.egg-info → siibra-1.0.1a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: siibra
-Version: 1.0a19
+Version: 1.0.1a0
 Summary: siibra - Software interfaces for interacting with brain atlases
 Home-page: https://github.com/FZJ-INM1-BDA/siibra-python
 Author: Big Data Analytics Group, Forschungszentrum Juelich, Institute of Neuroscience and Medicine (INM-1)
@@ -34,7 +34,7 @@ Requires-Dist: ebrains-drive>=0.6.0
 siibra - Software interface for interacting with brain atlases
 ==============================================================
 
-Copyright 2020-2023, Forschungszentrum Jülich GmbH
+Copyright 2020-2024, Forschungszentrum Jülich GmbH
 
 *Authors: Big Data Analytics Group, Institute of Neuroscience and
 Medicine (INM-1), Forschungszentrum Jülich GmbH*
@@ -145,3 +145,16 @@ https://doi.org/10.5281/zenodo.7885728`.
    :target: https://siibra-python.readthedocs.io/en/latest/?badge=latest
 .. |doi| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.7885728.svg
    :target: https://doi.org/10.5281/zenodo.7885728
+
+
+Versioning
+==========
+Given a version number MAJOR.MINOR.PATCH, increments imply:
+   - MAJOR: incompatible API changes
+   - MINOR: a functionality in a backward compatible manner is added
+   - PATCH: backward compatible bug fixes and new configuration added such as new maps or features
+
+Pre-release
+-----------
+For x.y.z, a full release,
+- `x.y.z-alpha.t` is the development prerelease. By changing `t`, different siibra-configurations are targeted.

{siibra-1.0a19 → siibra-1.0.1a0}/README.rst

@@ -4,7 +4,7 @@
 siibra - Software interface for interacting with brain atlases
 ==============================================================
 
-Copyright 2020-2023, Forschungszentrum Jülich GmbH
+Copyright 2020-2024, Forschungszentrum Jülich GmbH
 
 *Authors: Big Data Analytics Group, Institute of Neuroscience and
 Medicine (INM-1), Forschungszentrum Jülich GmbH*
@@ -115,3 +115,16 @@ https://doi.org/10.5281/zenodo.7885728`.
    :target: https://siibra-python.readthedocs.io/en/latest/?badge=latest
 .. |doi| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.7885728.svg
    :target: https://doi.org/10.5281/zenodo.7885728
+
+
+Versioning
+==========
+Given a version number MAJOR.MINOR.PATCH, increments imply:
+   - MAJOR: incompatible API changes
+   - MINOR: a functionality in a backward compatible manner is added
+   - PATCH: backward compatible bug fixes and new configuration added such as new maps or features
+
+Pre-release
+-----------
+For x.y.z, a full release,
+- `x.y.z-alpha.t` is the development prerelease. By changing `t`, different siibra-configurations are targeted.

siibra-1.0.1a0/siibra/VERSION

@@ -0,0 +1 @@
+1.0.1-alpha.0

{siibra-1.0a19 → siibra-1.0.1a0}/siibra/__init__.py

@@ -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
 
 
@@ -150,7 +150,7 @@ def __dir__():
         "get_template",
         "MapType",
         "Point",
-        "PointSet",
+        "PointCloud",
         "QUIET",
         "VERBOSE",
         "fetch_ebrains_token",

{siibra-1.0a19 → siibra-1.0.1a0}/siibra/commons.py

@@ -366,9 +366,6 @@ class MapType(Enum):
     STATISTICAL = 2
 
 
-SIIBRA_DEFAULT_MAPTYPE = MapType.LABELLED
-SIIBRA_DEFAULT_MAP_THRESHOLD = 0.0
-
 REMOVE_FROM_NAME = [
     "hemisphere",
     " -",
@@ -586,49 +583,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.

{siibra-1.0a19 → siibra-1.0.1a0}/siibra/configuration/factory.py

@@ -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-1.0a19 → siibra-1.0.1a0}/siibra/core/atlas.py

@@ -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-1.0a19 → siibra-1.0.1a0}/siibra/core/parcellation.py

@@ -17,11 +17,21 @@ from . import region
 
 from ..commons import logger, MapType, Species
 from ..volumes import parcellationmap
+from ..exceptions import NoMapMatchingValues
 
-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 NoMapMatchingValues(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 NoMapMatchingValues(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)
@@ -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 registery.
+
+    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