siibra 0.4a35__py3-none-any.whl → 0.4a46__py3-none-any.whl

siibra/VERSION

@@ -1 +1 @@
-0.4a35
+0.4a46

siibra/__init__.py

@@ -119,6 +119,7 @@ def __dir__():
         "use_configuration",
         "extend_configuration",
         "get_region",
+        "find_regions",
         "get_map",
         "get_template",
         "MapType",

siibra/commons.py

@@ -18,9 +18,11 @@ import re
 from enum import Enum
 from nibabel import Nifti1Image
 import logging
+from tqdm import tqdm
 import numpy as np
 from typing import Generic, Iterable, Iterator, List, TypeVar, Union, Dict
 from skimage.filters import gaussian
+from dataclasses import dataclass
 
 logger = logging.getLogger(__name__.split(os.path.extsep)[0])
 ch = logging.StreamHandler()
@@ -36,9 +38,20 @@ KEYCLOAK_CLIENT_SECRET = os.getenv("KEYCLOAK_CLIENT_SECRET")
 SIIBRA_CACHEDIR = os.getenv("SIIBRA_CACHEDIR")
 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")
+
 with open(os.path.join(ROOT_DIR, "VERSION"), "r") as fp:
     __version__ = fp.read().strip()
 
+@dataclass
+class CompareMapsResult:
+    intersection_over_union: float
+    intersection_over_first: float
+    intersection_over_second: float
+    correlation: float
+    weighted_mean_of_first: float
+    weighted_mean_of_second: float
 
 T = TypeVar("T")
 
@@ -233,6 +246,15 @@ QUIET = LoggingContext("ERROR")
 VERBOSE = LoggingContext("DEBUG")
 
 
+def siibra_tqdm(iterable: Iterable[T]=None, *args, **kwargs):
+    return tqdm(
+        iterable,
+        *args,
+        disable=kwargs.pop("disable", False) or (logger.level > 20),
+        **kwargs
+        )
+
+
 def create_key(name: str):
     """
     Creates an uppercase identifier string that includes only alphanumeric
@@ -411,14 +433,14 @@ def compare_maps(map1: Nifti1Image, map2: Nifti1Image):
     m1, m2 = ((_ > 0).astype("uint8") for _ in [v1, v2])
     intersection = np.minimum(m1, m2).sum()
     if intersection == 0:
-        return {
-            "intersection over union": 0,
-            "intersection over first": 0,
-            "intersection over second": 0,
-            "correlation": 0,
-            "weighted mean of first": 0,
-            "weighted mean of second": 0,
-        }
+        return CompareMapsResult(
+            intersection_over_union=0,
+            intersection_over_first=0,
+            intersection_over_second=0,
+            correlation=0,
+            weighted_mean_of_first=0,
+            weighted_mean_of_second=0,
+        )
 
     # Compute the nonzero voxels in map1 with their correspondences in map2
     XYZnz1 = nonzero_coordinates(a1)
@@ -452,15 +474,14 @@ def compare_maps(map1: Nifti1Image, map2: Nifti1Image):
 
     bx = (x > 0).astype("uint8")
     by = (y > 0).astype("uint8")
-
-    return {
-        "intersection over union": intersection / np.maximum(bx, by).sum(),
-        "intersection over first": intersection / N1,
-        "intersection over second": intersection / N2,
-        "correlation": r,
-        "weighted mean of first": np.sum(x * y) / np.sum(y),
-        "weighted mean of second": np.sum(x * y) / np.sum(x),
-    }
+    return CompareMapsResult(
+        intersection_over_union=intersection / np.maximum(bx, by).sum(),
+        intersection_over_first=intersection / N1,
+        intersection_over_second=intersection / N2,
+        correlation=r,
+        weighted_mean_of_first=np.sum(x * y) / np.sum(y),
+        weighted_mean_of_second=np.sum(x * y) / np.sum(x),
+    )
 
 
 class PolyLine:

siibra/configuration/configuration.py

@@ -13,7 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from ..commons import logger, __version__, SIIBRA_USE_CONFIGURATION
+from ..commons import logger, __version__, SIIBRA_USE_CONFIGURATION, siibra_tqdm
 from ..retrieval.repositories import GitlabConnector, RepositoryConnector
 from ..retrieval.exceptions import NoSiibraConfigMirrorsAvailableException
 from ..retrieval.requests import SiibraHttpRequestError
@@ -21,7 +21,6 @@ from ..retrieval.requests import SiibraHttpRequestError
 from typing import Union
 from collections import defaultdict
 from requests.exceptions import ConnectionError
-from tqdm import tqdm
 from os import path
 
 
@@ -47,12 +46,7 @@ class Configuration:
 
     CONFIGURATION_EXTENSIONS = []
 
-    # lists of loaders for json specification files
-    # found in the siibra configuration, stored per
-    # preconfigured class name. These files can
-    # loaded and fed to the Factory.from_json
-    # to produce the corresponding object.
-    spec_loaders = defaultdict(list)
+
 
     _cleanup_funcs = []
 
@@ -65,6 +59,13 @@ class Configuration:
 
     def __init__(self):
 
+        # lists of loaders for json specification files
+        # found in the siibra configuration, stored per
+        # preconfigured class name. These files can
+        # loaded and fed to the Factory.from_json
+        # to produce the corresponding object.
+        self.spec_loaders = defaultdict(list)
+
         # retrieve json spec loaders from the default configuration
         for connector in self.CONFIGURATIONS:
             try:
@@ -122,11 +123,14 @@ 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")
-        logger.info(f"Extending configuration with {str(conn)}")
-        cls.CONFIGURATION_EXTENSIONS.append(conn)
-        # call registered cleanup functions
-        for func in cls._cleanup_funcs:
-            func()
+        if conn in cls.CONFIGURATION_EXTENSIONS:
+            logger.warn(f"The configuration {str(conn)} is already registered.")
+        else:
+            logger.info(f"Extending configuration with {str(conn)}")
+            cls.CONFIGURATION_EXTENSIONS.append(conn)
+            # call registered cleanup functions
+            for func in cls._cleanup_funcs:
+                func()
 
     @classmethod
     def register_cleanup(cls, func):
@@ -143,7 +147,7 @@ class Configuration:
         result = []
 
         if folder not in self.folders:
-            logger.warn(f"No configuration found for building from configuration folder {folder}.")
+            logger.warning(f"No configuration found for building from configuration folder {folder}.")
             return result
 
         from .factory import Factory
@@ -158,12 +162,12 @@ class Configuration:
             )
         )
 
-        for fname, loader in tqdm(
+        for fname, loader in siibra_tqdm(
             specloaders,
             total=len(specloaders),
             desc=f"Loading preconfigured {obj0.__class__.__name__} instances"
         ):
-            # filename is added to allow Factory creating reasonable default object identifiers
+            # filename is added to allow Factory creating reasonable default object identifiers\
             obj = Factory.from_json(dict(loader.data, **{'filename': fname}))
             result.append(obj)
 
@@ -174,5 +178,5 @@ class Configuration:
 
 
 if SIIBRA_USE_CONFIGURATION:
-    logger.warn(f"config.SIIBRA_USE_CONFIGURATION defined, use configuration at {SIIBRA_USE_CONFIGURATION}")
+    logger.warning(f"config.SIIBRA_USE_CONFIGURATION defined, use configuration at {SIIBRA_USE_CONFIGURATION}")
     Configuration.use_configuration(SIIBRA_USE_CONFIGURATION)

siibra/configuration/factory.py

@@ -19,7 +19,8 @@ from ..features.tabular import (
     receptor_density_profile,
     receptor_density_fingerprint,
     cell_density_profile,
-    layerwise_cell_density
+    layerwise_cell_density,
+    regional_timeseries_activity
 )
 from ..features.image import sections, volume_of_interest
 from ..core import atlas, parcellation, space, region
@@ -54,6 +55,7 @@ BUILDFUNCS = {
     "siibra/feature/connectivitymatrix/v0.2": "build_connectivity_matrix",
     "siibra/feature/section/v0.1": "build_section",
     "siibra/feature/voi/v0.1": "build_volume_of_interest",
+    "siibra/feature/timeseries/activity/v0.1": "build_activity_timeseries"
 }
 
 
@@ -68,9 +70,10 @@ class Factory:
             result.append(
                 datasets.EbrainsDataset(id=spec["ebrains"]["minds/core/dataset/v1.0.0"])
             )
-        if "openminds/Dataset" in spec.get("ebrains", {}):
-            # TODO add parser for ebrains kg v3 dataset. see EbrainsV3Dataset 
-            pass
+        if "openminds/DatasetVersion" in spec.get("ebrains", {}):
+            result.append(
+                datasets.EbrainsV3DatasetVersion(id=spec["ebrains"]["openminds/DatasetVersion"])
+            )
         return result
 
     @classmethod
@@ -79,7 +82,7 @@ class Factory:
         for vspec in volume_specs:
             if space_id:
                 if 'space' in vspec:
-                    logger.warn(f"Replacing space spec {vspec['space']} in volume spec with {space_id}")
+                    logger.warning(f"Replacing space spec {vspec['space']} in volume spec with {space_id}")
                 vspec['space'] = {"@id": space_id}
             if name and vspec.get('name') is None:  # only use provided name if the volume has no specific name
                 vspec['name'] = name
@@ -142,7 +145,7 @@ class Factory:
                 reftag=repospec['branch']
             )
         else:
-            logger.warn(
+            logger.warning(
                 "Do not know how to create a repository "
                 f"connector from specification type {spectype}."
             )
@@ -243,7 +246,7 @@ class Factory:
                     break
             else:
                 if srctype not in cls._warnings_issued:
-                    logger.warn(f"No provider defined for volume Source type {srctype}")
+                    logger.warning(f"No provider defined for volume Source type {srctype}")
                     cls._warnings_issued.append(srctype)
 
         assert all([isinstance(provider, volume.VolumeProvider) for provider in providers])
@@ -275,7 +278,7 @@ class Factory:
         else:
             max_z = max(
                 d.get('z', 0)
-                for _, l in spec.get("indices", {}).items()
+                for l in spec.get("indices", {}).values()
                 for d in l
             ) + 1
             if max_z > MIN_VOLUMES_FOR_SPARSE_MAP:
@@ -411,8 +414,12 @@ class Factory:
             return volume_of_interest.PLIVolumeOfInterest(
                 modality="transmittance", **kwargs
             )
-        elif modality == "segmentation":
-            return volume_of_interest.SegmentedVolumeOfInterest(**kwargs)
+        elif modality == "XPCT":
+            return volume_of_interest.XPCTVolumeOfInterest(
+                modality="XPCT", **kwargs
+            )
+        # elif modality == "segmentation":
+        #     return volume_of_interest.SegmentedVolumeOfInterest(**kwargs)
         elif modality == "T2 weighted MRI":
             return volume_of_interest.MRIVolumeOfInterest(
                 modality="T2", **kwargs
@@ -421,8 +428,6 @@ class Factory:
             return volume_of_interest.MRIVolumeOfInterest(
                 modality="T1", **kwargs
             )
-        elif modality == "segmentation":
-            return volume_of_interest.SegmentedVolumeOfInterest(**kwargs)
         else:
             raise ValueError(f"No method for building image section feature type {modality}.")
 
@@ -453,6 +458,27 @@ class Factory:
         else:
             raise ValueError(f"No method for building connectivity matrix of type {modality}.")
 
+    @classmethod
+    def build_activity_timeseries(cls, spec):
+        modality = spec["modality"]
+        kwargs = {
+            "cohort": spec["cohort"],
+            "modality": modality,
+            "regions": spec["regions"],
+            "connector": cls.extract_connector(spec),
+            "decode_func": cls.extract_decoder(spec),
+            "files": spec.get("files", {}),
+            "anchor": cls.extract_anchor(spec),
+            "description": spec.get("description", ""),
+            "datasets": cls.extract_datasets(spec),
+            "timestep": spec.get("timestep", ("1 no_unit"))
+        }
+        if modality == "Regional BOLD signal":
+            kwargs["paradigm"] = spec.get("paradigm", "")
+            return regional_timeseries_activity.RegionalBOLD(**kwargs)
+        else:
+            raise ValueError(f"No method for building signal table of type {modality}.")
+
     @classmethod
     def from_json(cls, spec: dict):
 

siibra/core/atlas.py

@@ -184,17 +184,20 @@ class Atlas(concept.AtlasConcept, configuration_folder="atlases"):
 
         Parameters
         ----------
-        regionspec : any of
-            - a string with a possibly inexact name, which is matched both
-              against the name and the identifier key,
-            - an integer, which is interpreted as a labelindex
-            - a region object
+        regionspec: str, regex, int, Region, MapIndex
+            - 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)
+            - 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.
 
-        Yield
-        -----
-        list of matching regions
+        Returns
+        -------
+        list[Region]
+            list of regions matching to the regionspec
         """
         result = []
         for p in self._parcellation_ids:

siibra/core/concept.py

@@ -85,9 +85,29 @@ class AtlasConcept:
             else Species.decode(species)  # overwritable property implementation below
         self.shortname = shortname
         self.modality = modality
-        self.description = description
-        self.publications = publications
+        self._description = description
+        self._publications = publications
         self.datasets = datasets
+    
+    @property
+    def description(self):
+        if self._description:
+            return self._description
+        for ds in self.datasets:
+            if ds.description:
+                return ds.description
+        return ''
+    
+    @property
+    def publications(self) -> List[TypePublication]:
+        return [
+            *self._publications,
+            *[{
+                'citation': 'DOI',
+                'url': url.get("url")
+            } for ds in self.datasets
+            for url in ds.urls]
+        ]
 
     @property
     def species(self) -> Species:

siibra/core/parcellation.py

@@ -137,7 +137,7 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
                 return True
         return super().matches(spec)
 
-    def get_map(self, space=None, maptype: Union[str, MapType] = MapType.LABELLED):
+    def get_map(self, space=None, maptype: Union[str, MapType] = MapType.LABELLED, spec: str = ""):
         """
         Get the maps for the parcellation in the requested template space.
 
@@ -155,6 +155,11 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
             Type of map requested (e.g., statistical or labelled).
             Use MapType.STATISTICAL to request probability maps.
             Defaults to MapType.LABELLED.
+        spec: str, optional
+            In case of multiple matching maps for the given parcellation, space
+            and type, use this field to specify keywords matching the desired
+            parcellation map name. Otherwise, siibra will default to the first
+            in the list of matches (and inform with a log message)
         Returns
         -------
         parcellationmap.Map or SparseMap
@@ -175,14 +180,29 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
             logger.error(f"No {maptype} map in {space} available for {str(self)}")
             return None
         if len(candidates) > 1:
-            logger.warning(f"Multiple {maptype} maps in {space} available for {str(self)}, choosing the first.")
+            spec_candidates = [
+                c for c in candidates if all(w.lower() in c.name.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
+            if len(spec_candidates) > 1:
+                logger.warning(
+                    f"Multiple maps are available in this specification of space, parcellation, and map type.\n"
+                    f"Choosing the first map from {[c.name for c in spec_candidates]}."
+                )
+            return spec_candidates[0]
         return candidates[0]
 
-    @classmethod
-    def find_regions(cls, region_spec: str, parents_only=True):
+    @staticmethod
+    def find_regions(region_spec: str, parents_only=True):
         """
         Find regions that match the given region specification in the subtree
-        headed by this region.
+        headed by each parcellation in the registry.
+        Note
+        ----
+        Use Region.find() to search for a region in an instance of a
+        parcellation.
 
         Parameters
         ----------
@@ -196,11 +216,11 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
         List[Region]
             list of matching regions
         """
-        MEM = cls._CACHED_REGION_SEARCHES
+        MEM = Parcellation._CACHED_REGION_SEARCHES
         if region_spec not in MEM:
             MEM[region_spec] = [
                 r
-                for p in cls.registry()
+                for p in Parcellation.registry()
                 for r in p.find(regionspec=region_spec)
             ]
         if parents_only:
@@ -239,30 +259,25 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
 
     def get_region(
         self,
-        regionspec: Union[str, int, MapIndex, region.Region],
+        regionspec: Union[str, region.Region],
         find_topmost: bool = True,
         allow_tuple: bool = False
     ):
         """
         Given a unique specification, return the corresponding region.
 
-        The spec could be a label index, a (possibly incomplete) name, or a
-        region object. This method is meant to definitely determine a valid
-        region. Therefore, if no match is found, it raises a ValueError.
-        If multiple matches are found, the method tries to return only the
-        common parent node. If there is no common parent, an exception is
-        raised, except when allow_tuple=True - then a tuple of matched regions
-        is returned.
+        The spec could be a (possibly incomplete) name, or a region object.
+        This method is meant to definitely determine a valid region. Therefore,
+        if no match is found, it raises a ValueError. If multiple matches are
+        found, the method tries to return only the common parent node. If there
+        is no common parent, an exception is raised, except when
+        allow_tuple=True - then a tuple of matched regions is returned.
 
         Parameters
         ----------
-        regionspec: str, regex, int, Region, MapIndex
+        regionspec: str, 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)
-            - a regex applied to region names
-            - an integer (interpreted as a labelindex)
             - a Region object
-            - a full MapIndex object
         find_topmost: bool, default: True
             If True, will automatically return the parent of a decoded region
             the decoded region is its only child.
@@ -282,6 +297,7 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
         ValueError
             If the spec cannot be matched against any region
         """
+        assert isinstance(regionspec, (str, region.Region)), f"get_region takes str or Region but you provided {type(regionspec)}"
         if isinstance(regionspec, region.Region) and (regionspec.parcellation == self):
             return regionspec
 
@@ -294,6 +310,10 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
         else:
             candidates = self.find(regionspec, filter_children=True, find_topmost=find_topmost)
 
+        exact_matches = [r for r in candidates if regionspec == r]
+        if len(exact_matches) == 1:
+            return exact_matches[0]
+
         if len(candidates) > 1 and isinstance(regionspec, str):
             # if we have an exact match of words in one region, discard other candidates.
             querywords = {w.replace(',', '').lower() for w in regionspec.split()}
@@ -313,7 +333,7 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
             if allow_tuple:
                 return tuple(candidates)
             raise RuntimeError(
-                f"Spec {regionspec} resulted in multiple matches: {', '.join(r.name for r in candidates)}."
+                f"Spec {regionspec!r} resulted in multiple matches: {', '.join(r.name for r in candidates)}."
             )
 
     def __str__(self):
@@ -333,7 +353,7 @@ class Parcellation(region.Region, configuration_folder="parcellations"):
         We sort parcellations by their version
         """
         if (self.version is None) or (other.version is None):
-            logger.warn(
+            logger.warning(
                 f"Sorting non-versioned instances of {self.__class__.__name__} "
                 f"by name: {self.name}, {other.name}"
             )