siibra 1.0a1__1-py3-none-any.whl

siibra/core/assignment.py

@@ -0,0 +1,110 @@
+# Copyright 2018-2024
+# Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Qualification between two BrainStructures"""
+
+from enum import Enum
+from dataclasses import dataclass
+from typing import Dict, Generic, TypeVar, TYPE_CHECKING
+if TYPE_CHECKING:
+    from .structure import BrainStructure
+
+T = TypeVar("T")
+
+
+class Qualification(Enum):
+    EXACT = 1
+    OVERLAPS = 2
+    CONTAINED = 3
+    CONTAINS = 4
+    APPROXIMATE = 5
+    HOMOLOGOUS = 6
+    OTHER_VERSION = 7
+
+    @property
+    def verb(self):
+        """
+        a string that can be used as a verb in a sentence
+        for producing human-readable messages.
+        """
+        transl = {
+            Qualification.EXACT: 'coincides with',
+            Qualification.OVERLAPS: 'overlaps with',
+            Qualification.CONTAINED: 'is contained in',
+            Qualification.CONTAINS: 'contains',
+            Qualification.APPROXIMATE: 'approximates to',
+            Qualification.HOMOLOGOUS: 'is homologous to',
+            Qualification.OTHER_VERSION: 'is another version of'
+        }
+        assert self in transl, f"{str(self)} verb cannot be found."
+        return transl[self]
+
+    def invert(self):
+        """
+        Return qualification with the inverse meaning
+        """
+        inverses = {
+            Qualification.EXACT: Qualification.EXACT,
+            Qualification.OVERLAPS: Qualification.OVERLAPS,
+            Qualification.CONTAINED: Qualification.CONTAINS,
+            Qualification.CONTAINS: Qualification.CONTAINED,
+            Qualification.APPROXIMATE: Qualification.APPROXIMATE,
+            Qualification.HOMOLOGOUS: Qualification.HOMOLOGOUS,
+            Qualification.OTHER_VERSION: Qualification.OTHER_VERSION,
+        }
+        assert self in inverses, f"{str(self)} inverses cannot be found."
+        return inverses[self]
+
+    def __str__(self):
+        return f"{self.__class__.__name__}={self.name.lower()}"
+
+    def __repr__(self):
+        return str(self)
+
+    @staticmethod
+    def parse_relation_assessment(spec: Dict):
+        name = spec.get("name")
+        if name == "is homologous to":
+            return Qualification.HOMOLOGOUS
+        raise Exception(f"Cannot parse spec: {spec}")
+
+
+@dataclass
+class AnatomicalAssignment(Generic[T]):
+    """Represents a qualified assignment between anatomical structures."""
+    query_structure: "BrainStructure"
+    assigned_structure: "BrainStructure"
+    qualification: Qualification
+    explanation: str = ""
+
+    @property
+    def is_exact(self):
+        return self.qualification == Qualification.EXACT
+
+    def __str__(self):
+        msg = f"'{self.query_structure}' {self.qualification.verb} '{self.assigned_structure}'"
+        return msg if self.explanation == "" else f"{msg} - {self.explanation}"
+
+    def invert(self):
+        return AnatomicalAssignment(
+            self.assigned_structure,
+            self.query_structure,
+            self.qualification.invert(),
+            self.explanation
+        )
+
+    def __lt__(self, other: 'AnatomicalAssignment'):
+        if not isinstance(other, AnatomicalAssignment):
+            raise ValueError(f"Cannot compare AnatomicalAssignment with instances of '{type(other)}'")
+        return self.qualification.value < other.qualification.value

siibra/core/atlas.py

@@ -0,0 +1,239 @@
+# Copyright 2018-2024
+# Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Provides reference systems for brains."""
+from . import concept, space as _space, parcellation as _parcellation
+
+from ..commons import MapType, logger, InstanceTable, Species
+
+from typing import List
+
+
+VERSION_BLACKLIST_WORDS = ["beta", "rc", "alpha"]
+
+
+class Atlas(concept.AtlasConcept, configuration_folder="atlases"):
+    """
+    Main class for an atlas, providing access to feasible
+    combinations of available parcellations and reference
+    spaces, as well as common functionalities of those.
+    """
+
+    def __init__(self, identifier: str, name: str, species: Species, **kwargs):
+        """Construct an empty atlas object with a name and identifier."""
+
+        concept.AtlasConcept.__init__(
+            self,
+            identifier=identifier,
+            name=name,
+            species=species,
+            **kwargs
+        )
+        self._parcellation_ids: List[str] = []
+        self._space_ids: List[str] = []
+
+    def _register_space(self, space_id: str):
+        self._space_ids.append(space_id)
+
+    def _register_parcellation(self, parcellation_id: str):
+        self._parcellation_ids.append(parcellation_id)
+
+    @property
+    def spaces(self):
+        """Access a registry of reference spaces supported by this atlas."""
+        return InstanceTable[_space.Space](
+            elements={s.key: s for s in _space.Space.registry() if s.id in self._space_ids},
+            matchfunc=_space.Space.match,
+        )
+
+    @property
+    def parcellations(self):
+        """Access a registry of parcellations supported by this atlas."""
+        return InstanceTable[_parcellation.Parcellation](
+            elements={p.key: p for p in _parcellation.Parcellation.registry() if p.id in self._parcellation_ids},
+            matchfunc=_parcellation.Parcellation.match,
+        )
+
+    def get_parcellation(self, parcellation=None) -> "_parcellation.Parcellation":
+        """
+        Returns a valid parcellation object defined by the atlas. If no
+        specification is provided, the default is returned.
+
+        Parameters
+        ----------
+        parcellation: str, Parcellation
+            specification of a parcellation or a parcellation object
+
+        Returns
+        -------
+            Parcellation
+        """
+
+        if parcellation is None:
+            parcellation_obj = self.parcellations[self._parcellation_ids[0]]
+            if len(self._parcellation_ids) > 1:
+                logger.info(f"No parcellation specified, using default: '{parcellation_obj.name}'.")
+            return parcellation_obj
+
+        if isinstance(parcellation, _parcellation.Parcellation):
+            assert parcellation in self.parcellations
+            return parcellation
+
+        return self.parcellations[parcellation]
+
+    def get_space(self, space=None) -> "_space.Space":
+        """
+        Returns a valid reference space object defined by the atlas. If no
+        specification is provided, the default is returned.
+
+        Parameters
+        ----------
+        space: str, Space
+            specification of a space or a space object
+
+        Returns
+        -------
+            Space
+        """
+        if space is None:
+            space_obj = self.spaces[self._space_ids[0]]
+            if len(self._space_ids) > 1:
+                logger.info(f"No space specified, using default '{space_obj.name}'.")
+            return space_obj
+
+        if isinstance(space, _space.Space):
+            assert space in self.spaces
+            return space
+
+        return self.spaces[space]
+
+    def get_map(
+        self,
+        space: _space.Space = None,
+        parcellation: _parcellation.Parcellation = None,
+        maptype: MapType = MapType.LABELLED,
+    ):
+        """
+        Returns a parcellation map in the given space.
+
+        Parameters
+        ----------
+
+        space: Space
+            The requested reference space. If None, the default is used.
+        parcellation: Parcellation
+            The requested parcellation. If None, the default is used.
+        maptype: MapType
+            Type of the map (labelled or statistical/probabilistic)
+
+        Returns
+        -------
+        ParcellationMap
+        """
+        parc_obj = self.get_parcellation(parcellation)
+        space_obj = self.get_space(space)
+        return parc_obj.get_map(space=space_obj, maptype=maptype)
+
+    def get_region(self, region, parcellation=None):
+        """
+        Returns a valid Region object matching the given specification.
+
+        Parameters
+        ----------
+        region : str or Region
+            Key, approximate name, id or instance of a brain region
+        parcellation : str or Parcellation
+            Key, approximate name, id or instance of a brain parcellation.
+            If None, the default is used.
+        """
+        return self.get_parcellation(parcellation).get_region(region)
+
+    def get_template(self, space: _space.Space = None, variant: str = None):
+        """
+        Returns the reference template in the desired reference space.
+        If no reference space is given, the default from `Atlas.space()` is used.
+
+        Parameters
+        ----------
+        space: Space
+            The desired reference space
+        variant: str (optional)
+            Some templates are provided in different variants, e.g.
+            freesurfer is available as either white matter, pial or
+            inflated surface for left and right hemispheres (6 variants).
+            This field could be used to request a specific variant.
+            Per default, the first found variant is returned.
+        """
+        return self.get_space(space).get_template(variant=variant)
+
+    def get_voi(self, space: _space.Space, point1: tuple, point2: tuple):
+        """Get a volume of interest spanned by two points in the given reference space.
+
+        Parameters
+        ----------
+        space: Space, str
+            The target reference space, or a string specification of the space
+        point1: Tuple
+            A 3D coordinate given in this reference space
+        point2: Tuple
+            Another 3D coordinate given in this reference space
+
+        Returns
+        -------
+            BoundingBox
+        """
+        return self.get_template(space).get_boundingbox(point1, point2)
+
+    def find_regions(
+        self,
+        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.
+
+        Parameters
+        ----------
+        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
+        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
+        -------
+        list[Region]
+            list of regions matching to the regionspec
+        """
+        result = []
+        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

@@ -0,0 +1,308 @@
+# Copyright 2018-2024
+# Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Parent class to siibra main concepts."""
+from ..commons import (
+    create_key,
+    clear_name,
+    logger,
+    InstanceTable,
+    Species,
+    TypePublication
+)
+from ..retrieval import cache
+
+import re
+from typing import TypeVar, Type, Union, List, TYPE_CHECKING, Dict
+
+T = TypeVar("T", bound="AtlasConcept")
+_REGISTRIES: Dict[Type[T], InstanceTable[T]] = {}
+
+
+@cache.Warmup.register_warmup_fn(is_factory=True)
+def _atlas_concept_warmup():
+    return [cls.registry for cls in _REGISTRIES]
+
+
+if TYPE_CHECKING:
+    from ..retrieval.datasets import EbrainsDataset
+    TypeDataset = EbrainsDataset
+
+
+def get_registry(subclass_name: str):
+    subclasses = {c.__name__: c for c in _REGISTRIES}
+    if subclass_name in subclasses:
+        return subclasses[subclass_name].registry()
+    else:
+        logger.warn(f"No registry for atlas concepts named {subclass_name}")
+        return None
+
+
+class AtlasConcept:
+    """
+    Parent class encapsulating commonalities of the basic siibra concept like atlas, parcellation, space, region.
+    These concepts have an id, name, and key, and they are bootstrapped from metadata stored in an online resources.
+    Typically, they are linked with one or more datasets that can be retrieved from the same or another online resource,
+    providing data files or additional metadata descriptions on request.
+    """
+
+    def __init__(
+        self,
+        identifier: str,
+        name: str,
+        species: Union[str, Species],
+        shortname: str = None,
+        description: str = None,
+        modality: str = "",
+        publications: List[TypePublication] = [],
+        datasets: List['TypeDataset'] = [],
+        spec=None,
+        prerelease: bool = False,
+    ):
+        """
+        Construct a new atlas concept base object.
+
+        Parameters
+        ----------
+        identifier : str
+            Unique identifier of the parcellation
+        name : str
+            Human-readable name of the parcellation
+        species: Species or string
+            Specification of the species
+        shortname: str
+            Shortform of human-readable name (optional)
+        description: str
+            Textual description of the parcellation
+        modality  :  str or None
+            Specification of the modality underlying this concept
+        datasets : list
+            list of datasets corresponding to this concept
+        publications: list
+            List of publications, each a dictionary with "doi" and/or "citation" fields
+        spec: dict, default: None
+            The preconfigured specification.
+        """
+        self._id = identifier
+        self.name = name if not prerelease else f"[PRERELEASE] {name}"
+        self._species_cached = None if species is None \
+            else Species.decode(species)  # overwritable property implementation below
+        self.shortname = shortname
+        self.modality = modality
+        self._description = description
+        self._publications = publications
+        self.datasets = datasets
+        self._spec = spec
+        self._CACHED_MATCHES = {}  # we cache match() function results
+        self._prerelease = prerelease
+
+    @property
+    def description(self):
+        if self._description:
+            return self._description
+        for ds in self.datasets:
+            if ds.description:
+                return ds.description
+        return ''
+
+    @property
+    def LICENSE(self) -> str:
+        licenses = []
+        for ds in self.datasets:
+            if ds.LICENSE is None or ds.LICENSE == "No license information is found.":
+                continue
+            if isinstance(ds.LICENSE, str):
+                licenses.append(ds.LICENSE)
+            if isinstance(ds.LICENSE, list):
+                licenses.extend(ds.LICENSE)
+        if len(licenses) == 0:
+            logger.warning("No license information is found.")
+            return ""
+        if len(licenses) > 1:
+            logger.info("Found multiple licenses corresponding to datasets.")
+        return '\n'.join(licenses)
+
+    @property
+    def urls(self) -> List[str]:
+        """The list of URLs (including DOIs) associated with this atlas concept."""
+        return [
+            url.get("url")
+            for ds in self.datasets
+            for url in ds.urls
+        ]
+
+    @property
+    def authors(self):
+        return [
+            contributer['name']
+            for ds in self.datasets
+            for contributer in ds.contributors
+        ]
+
+    @property
+    def publications(self) -> List[TypePublication]:
+        return [
+            *self._publications,
+            *[
+                {'citation': f"Dataset name: {ds.name}", 'url': url.get("url")}
+                for ds in self.datasets
+                for url in ds.urls
+            ]
+        ]
+
+    @property
+    def species(self) -> Species:
+        # Allow derived classes to implement a lazy loader (e.g. in Map)
+        if self._species_cached is None:
+            raise RuntimeError(f"No species defined for {self}.")
+        return self._species_cached
+
+    @classmethod
+    def registry(cls: Type[T]) -> InstanceTable[T]:
+        if cls._configuration_folder is None:
+            return None
+        if _REGISTRIES[cls] is None:
+            from ..configuration import Configuration
+            conf = Configuration()
+            # visit the configuration to provide a cleanup function
+            # in case the user changes the configuration during runtime.
+            Configuration.register_cleanup(cls.clear_registry)
+            assert cls._configuration_folder in conf.folders
+            objects = conf.build_objects(cls._configuration_folder)
+            logger.debug(f"Built {len(objects)} preconfigured {cls.__name__} objects.")
+            assert len(objects) > 0
+            assert all([hasattr(o, 'key') for o in objects])
+
+            # TODO Map.registry() returns InstanceTable that contains two different types, SparseMap and Map
+            # Since we take the objects[0].__class__.match, if the first element happen to be SparseMap, this could result.
+            # Code to reproduce:
+            """
+            import siibra
+            r = siibra.volumes.Map.registry()
+            """
+            if len({o.__class__ for o in objects}) > 1:
+                logger.warning(
+                    f"{cls.__name__} registry contains multiple classes: "
+                    f"{', '.join(list({o.__class__.__name__ for o in objects}))}"
+                )
+            assert hasattr(objects[0].__class__, "match") and callable(objects[0].__class__.match)
+            _REGISTRIES[cls] = InstanceTable(
+                elements={o.key: o for o in objects},
+                matchfunc=objects[0].__class__.match
+            )
+        return _REGISTRIES[cls]
+
+    @classmethod
+    def clear_registry(cls):
+        _REGISTRIES[cls] = None
+
+    @classmethod
+    def get_instance(cls, spec: str):
+        """
+        Parameters
+        ----------
+            spec: str
+                Specification of the class the instance is requested.
+        Returns
+        -------
+            an instance of this class matching the given specification from its
+            registry if possible, otherwise None.
+        Raises
+        ------
+            IndexError
+                If spec cannot match any instance
+        """
+        if cls.registry() is not None:
+            return cls.registry().get(spec)
+
+    @property
+    def id(self):
+        # allows derived classes to assign the id dynamically
+        return self._id
+
+    @property
+    def key(self):
+        return create_key(self.name)
+
+    def __init_subclass__(cls, configuration_folder: str = None):
+        """
+        This method is called whenever AtlasConcept gets subclassed
+        (see https://docs.python.org/3/reference/datamodel.html)
+        """
+        cls._configuration_folder = configuration_folder
+        _REGISTRIES[cls] = None
+        return super().__init_subclass__()
+
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__}(identifier='{self.id}', name='{self.name}', species='{self.species}')>"
+
+    def matches(self, spec) -> bool:
+        """
+        Parameters
+        ----------
+        spec: str
+            Specification checked within the concept name, key or id
+
+        Returns
+        -------
+        bool
+            Whether the given specification matches the name, key or id of the concept.
+        """
+        if spec not in self._CACHED_MATCHES:
+            self._CACHED_MATCHES[spec] = False
+            if isinstance(spec, self.__class__) and (spec == self):
+                self._CACHED_MATCHES[spec] = True
+            elif isinstance(spec, str):
+                if spec == self.key:
+                    self._CACHED_MATCHES[spec] = True
+                elif spec == self.id:
+                    self._CACHED_MATCHES[spec] = True
+                else:
+                    # match the name
+                    words = [w for w in re.split("[ -]", spec)]
+                    squeezedname = clear_name(self.name.lower()).replace(" ", "")
+                    self._CACHED_MATCHES[spec] = any(
+                        [
+                            all(w.lower() in squeezedname for w in words),
+                            spec.replace(" ", "") in squeezedname,
+                        ]
+                    )
+        return self._CACHED_MATCHES[spec]
+
+    @classmethod
+    def match(cls, obj, spec) -> bool:
+        """Match a given object specification. """
+        assert isinstance(obj, cls)
+        return obj.matches(spec)
+
+    def __gt__(self, other: 'AtlasConcept'):
+        """
+        Compare this atlas concept with other atlas concepts of the same kind
+        with it's name.
+        """
+        if self.__class__ is not other.__class__:
+            raise ValueError("Cannot compare different atlas concept types.")
+        return self.name > other.name
+
+    def __lt__(self, other: 'AtlasConcept'):
+        """
+        Compare this atlas concept with other atlas concepts of the same kind
+        with it's name.
+        """
+        if self.__class__ is not other.__class__:
+            raise ValueError("Cannot compare different atlas concept types.")
+        return self.name < other.name