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

siibra/configuration/factory.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");
@@ -20,18 +20,19 @@ from ..features.tabular import (
     receptor_density_fingerprint,
     cell_density_profile,
     layerwise_cell_density,
-    regional_timeseries_activity
+    regional_timeseries_activity,
 )
 from ..features.image import sections, volume_of_interest
 from ..core import atlas, parcellation, space, region
-from ..locations import point, pointset
+from ..locations import point, pointcloud, boundingbox
 from ..retrieval import datasets, repositories
-from ..volumes import gifti, volume, nifti, neuroglancer, sparsemap, parcellationmap
+from ..volumes import volume, sparsemap, parcellationmap
+from ..volumes.providers.provider import VolumeProvider
 
 from os import path
 import json
 import numpy as np
-from typing import List, Type, Dict, Callable
+from typing import List, Dict, Callable
 import pandas as pd
 from io import BytesIO
 from functools import wraps
@@ -47,7 +48,9 @@ def build_type(type_str: str):
         @wraps(fn)
         def inner(*args, **kwargs):
             return fn(*args, **kwargs)
+
         return inner
+
     return outer
 
 
@@ -64,7 +67,9 @@ class Factory:
             )
         if "openminds/DatasetVersion" in spec.get("ebrains", {}):
             result.append(
-                datasets.EbrainsV3DatasetVersion(id=spec["ebrains"]["openminds/DatasetVersion"])
+                datasets.EbrainsV3DatasetVersion(
+                    id=spec["ebrains"]["openminds/DatasetVersion"]
+                )
             )
         if "openminds/Dataset" in spec.get("ebrains", {}):
             result.append(
@@ -77,28 +82,41 @@ class Factory:
                     contributors=pub["authors"],
                     url=pub["url"],
                     description=pub["description"],
-                    license=pub.get("license")
+                    license=pub.get("license"),
                 )
-                for pub in spec["publications"] if pub.get('name')
+                for pub in spec["publications"]
+                if pub.get("name")
             )
         return result
 
     @classmethod
-    def extract_volumes(cls, spec, space_id: str = None, name: str = None):
+    def extract_volumes(
+        cls, spec, space_id: str = None, names: List[str] = None, name_prefix: str = ""
+    ):
         volume_specs = spec.get("volumes", [])
-        for vspec in volume_specs:
+        if names:
+            if len(names) != len(volume_specs) and len(names) == 1:
+                variants = [vol["variant"] for vol in volume_specs]
+                names = [f"{name_prefix}{names[0]} {var} variant" for var in variants]
+        else:
+            names = [f"{name_prefix} - volume {i}" for i in range(len(volume_specs))]
+        for i, vspec in enumerate(volume_specs):
             if space_id:
-                if 'space' in vspec:
-                    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
+                if "space" in vspec:
+                    assert (
+                        vspec["space"]["@id"] == space_id
+                    ), "Space spec {vspec['space']} in volume field must be the same with space field in the configuration."
+                vspec["space"] = {"@id": space_id}
+            if (
+                names and vspec.get("name") is None
+            ):  # only use provided name if the volume has no specific name
+                vspec["name"] = names[i]
         return list(map(cls.build_volume, volume_specs))
 
     @classmethod
     def extract_decoder(cls, spec):
         decoder_spec = spec.get("decoder", {})
-        if decoder_spec["@type"].endswith('csv'):
+        if decoder_spec["@type"].endswith("csv"):
             kwargs = {k: v for k, v in decoder_spec.items() if k != "@type"}
             return lambda b: pd.read_csv(BytesIO(b), **kwargs)
         else:
@@ -106,52 +124,52 @@ class Factory:
 
     @classmethod
     def extract_anchor(cls, spec):
-        if spec.get('region'):
-            region = spec['region']
-        elif spec.get('parcellation', {}).get('@id'):
+        if spec.get("region"):
+            region = spec["region"]
+        elif spec.get("parcellation", {}).get("@id"):
             # a parcellation is a special region,
             # and can be used if no region is found
-            region = spec['parcellation']['@id']
-        elif spec.get('parcellation', {}).get('name'):
-            region = spec['parcellation']['name']
+            region = spec["parcellation"]["@id"]
+        elif spec.get("parcellation", {}).get("name"):
+            region = spec["parcellation"]["name"]
         else:
             region = None
 
-        if 'location' in spec:
-            location = cls.from_json(spec['location'])
+        if "location" in spec:
+            location = cls.from_json(spec["location"])
         else:
             location = None
 
         if (region is None) and (location is None):
             print(spec)
-            raise RuntimeError("Spec provides neither region or location - no anchor can be extracted.")
+            raise RuntimeError(
+                "Spec provides neither region or location - no anchor can be extracted."
+            )
 
-        if 'species' in spec:
-            species = Species.decode(spec['species'])
-        elif ('ebrains' in spec):
-            species = Species.decode(spec['ebrains'])
+        if "species" in spec:
+            species = Species.decode(spec["species"])
+        elif "ebrains" in spec:
+            species = Species.decode(spec["ebrains"])
         else:
             raise ValueError(f"No species information found in spec {spec}")
 
         return anchor.AnatomicalAnchor(
-            region=region,
-            location=location,
-            species=species
+            region=region, location=location, species=species
         )
 
     @classmethod
     def extract_connector(cls, spec):
-        repospec = spec.get('repository', {})
+        repospec = spec.get("repository", {})
         spectype = repospec["@type"]
         if spectype == "siibra/repository/zippedfile/v1.0.0":
-            return repositories.ZipfileConnector(repospec['url'])
+            return repositories.ZipfileConnector(repospec["url"])
         if spectype == "siibra/repository/localfolder/v1.0.0":
-            return repositories.LocalFileRepository(repospec['folder'])
+            return repositories.LocalFileRepository(repospec["folder"])
         if spectype == "siibra/repository/gitlab/v1.0.0":
             return repositories.GitlabConnector(
-                server=repospec['server'],
-                project=repospec['project'],
-                reftag=repospec['branch']
+                server=repospec["server"],
+                project=repospec["project"],
+                reftag=repospec["branch"],
             )
 
         logger.warning(
@@ -166,7 +184,8 @@ class Factory:
         a = atlas.Atlas(
             spec["@id"],
             spec["name"],
-            species=Species.decode(spec.get('species')),
+            species=Species.decode(spec.get("species")),
+            prerelease=spec.get("prerelease", False),
         )
         for space_id in spec["spaces"]:
             a._register_space(space_id)
@@ -180,13 +199,16 @@ class Factory:
         return space.Space(
             identifier=spec["@id"],
             name=spec["name"],
-            species=Species.decode(spec.get('species')),
-            volumes=cls.extract_volumes(spec, space_id=spec.get("@id"), name=spec.get("name")),
+            species=Species.decode(spec.get("species")),
+            volumes=cls.extract_volumes(
+                spec, space_id=spec.get("@id"), names=[spec.get("name")]
+            ),
             shortname=spec.get("shortName", ""),
             description=spec.get("description"),
             modality=spec.get("modality"),
             publications=spec.get("publications", []),
             datasets=cls.extract_datasets(spec),
+            prerelease=spec.get("prerelease", False),
         )
 
     @classmethod
@@ -200,6 +222,7 @@ class Factory:
             datasets=cls.extract_datasets(spec),
             rgb=spec.get("rgb", None),
             spec=spec,
+            prerelease=spec.get("prerelease", False),
         )
 
     @classmethod
@@ -215,17 +238,18 @@ class Factory:
         p = parcellation.Parcellation(
             identifier=spec["@id"],
             name=spec["name"],
-            species=Species.decode(spec.get('species')),
+            species=Species.decode(spec.get("species")),
             regions=regions,
             shortname=spec.get("shortName", ""),
             description=spec.get("description", ""),
-            modality=spec.get('modality', ""),
+            modality=spec.get("modality", ""),
             publications=spec.get("publications", []),
             datasets=cls.extract_datasets(spec),
+            prerelease=spec.get("prerelease", False),
         )
 
         # add version object, if any is specified
-        versionspec = spec.get('@version', None)
+        versionspec = spec.get("@version", None)
         if versionspec is not None:
             version = parcellation.ParcellationVersion(
                 name=versionspec.get("name", None),
@@ -233,44 +257,44 @@ class Factory:
                 collection=versionspec.get("collectionName", None),
                 prev_id=versionspec.get("@prev", None),
                 next_id=versionspec.get("@next", None),
-                deprecated=versionspec.get("deprecated", False)
+                deprecated=versionspec.get("deprecated", False),
             )
             p.version = version
 
         return p
 
     @classmethod
-    @build_type("siibra/volume/v0.0.1")
-    def build_volume(cls, spec):
-        providers: List[volume.VolumeProvider] = []
-        provider_types: List[Type[volume.VolumeProvider]] = [
-            neuroglancer.NeuroglancerProvider,
-            neuroglancer.NeuroglancerMesh,
-            neuroglancer.NeuroglancerSurfaceMesh,
-            nifti.NiftiProvider,
-            nifti.ZipContainedNiftiProvider,
-            gifti.GiftiMesh,
-            gifti.GiftiSurfaceLabeling
-        ]
-
-        for srctype, provider_spec in spec.get("providers", {}).items():
-            for ProviderType in provider_types:
+    def build_volumeproviders(cls, provider_specs: Dict) -> List["VolumeProvider"]:
+        providers: List[VolumeProvider] = []
+        for srctype, provider_spec in provider_specs.items():
+            for ProviderType in VolumeProvider._SUBCLASSES:
                 if srctype == ProviderType.srctype:
                     providers.append(ProviderType(provider_spec))
                     break
             else:
                 if srctype not in cls._warnings_issued:
-                    logger.warning(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(p, VolumeProvider) for p in providers])
+        return providers
 
-        assert all([isinstance(provider, volume.VolumeProvider) for provider in providers])
+    @classmethod
+    @build_type("siibra/volume/v0.0.1")
+    def build_volume(cls, spec):
         result = volume.Volume(
             space_spec=spec.get("space", {}),
-            providers=providers,
-            name=spec.get("name", {}),
+            providers=cls.build_volumeproviders(spec.get("providers")),
+            name=spec.get("name", ""),
             variant=spec.get("variant"),
             datasets=cls.extract_datasets(spec),
+            bbox=cls.build_boundingbox(spec),
         )
+        if result._boundingbox is not None:
+            assert (
+                result._boundingbox._space_spec == result._space_spec
+            ), "BoundingBox of a volume cannot be in a different space than the volume's space."
 
         return result
 
@@ -278,19 +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('_', ' ')
-        identifier = f"{spec['@type'].replace('/','-')}_{basename}"
-        volumes = cls.extract_volumes(spec)
+        identifier = spec.get("@id")
+        volumes = cls.extract_volumes(
+            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", {}),
@@ -299,7 +322,8 @@ class Factory:
             description=spec.get("description"),
             modality=spec.get("modality"),
             publications=spec.get("publications", []),
-            datasets=cls.extract_datasets(spec)
+            datasets=cls.extract_datasets(spec),
+            prerelease=spec.get("prerelease", False),
         )
 
     @classmethod
@@ -316,11 +340,11 @@ class Factory:
     @build_type("https://openminds.ebrains.eu/sands/CoordinatePoint")
     @build_type("siibra/location/point/v0.1")
     def build_point(cls, spec):
-        if spec.get('@type') == "https://openminds.ebrains.eu/sands/CoordinatePoint":
+        if spec.get("@type") == "https://openminds.ebrains.eu/sands/CoordinatePoint":
             space_id = spec["coordinateSpace"]["@id"]
             coord = list(np.float16(c["value"]) for c in spec["coordinates"])
             assert all(c["unit"]["@id"] == "id.link/mm" for c in spec["coordinates"])
-        elif spec.get('@type') == "siibra/location/point/v0.1":
+        elif spec.get("@type") == "siibra/location/point/v0.1":
             space_id = spec.get("space").get("@id")
             coord = spec.get("coordinate")
         else:
@@ -332,88 +356,112 @@ class Factory:
 
     @classmethod
     @build_type("tmp/poly")
-    @build_type("siibra/location/pointset/v0.1")
-    def build_pointset(cls, spec):
-        if spec.get('@type') == 'tmp/poly':
+    @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")
+    def build_boundingbox(cls, spec):
+        bboxspec = spec.get("boundingbox", None)
+        if bboxspec is None:
+            return None
+        space_spec = bboxspec.get("space")
+        coords = [tuple(c) for c in bboxspec.get("coordinates")]
+        return boundingbox.BoundingBox(coords[0], coords[1], space=space_spec)
 
     @classmethod
     @build_type("siibra/feature/fingerprint/receptor/v0.1")
     def build_receptor_density_fingerprint(cls, spec):
         return receptor_density_fingerprint.ReceptorDensityFingerprint(
-            tsvfile=spec['file'],
+            tsvfile=spec["file"],
             anchor=cls.extract_anchor(spec),
             datasets=cls.extract_datasets(spec),
+            id=spec.get("@id", None),
+            prerelease=spec.get("prerelease", False),
         )
 
     @classmethod
     @build_type("siibra/feature/fingerprint/celldensity/v0.1")
     def build_cell_density_fingerprint(cls, spec):
         return layerwise_cell_density.LayerwiseCellDensity(
-            segmentfiles=spec['segmentfiles'],
-            layerfiles=spec['layerfiles'],
+            segmentfiles=spec["segmentfiles"],
+            layerfiles=spec["layerfiles"],
             anchor=cls.extract_anchor(spec),
             datasets=cls.extract_datasets(spec),
+            id=spec.get("@id", None),
+            prerelease=spec.get("prerelease", False),
         )
 
     @classmethod
     @build_type("siibra/feature/profile/receptor/v0.1")
     def build_receptor_density_profile(cls, spec):
         return receptor_density_profile.ReceptorDensityProfile(
-            receptor=spec['receptor'],
-            tsvfile=spec['file'],
+            receptor=spec["receptor"],
+            tsvfile=spec["file"],
             anchor=cls.extract_anchor(spec),
             datasets=cls.extract_datasets(spec),
+            id=spec.get("@id", None),
+            prerelease=spec.get("prerelease", False),
         )
 
     @classmethod
     @build_type("siibra/feature/profile/celldensity/v0.1")
     def build_cell_density_profile(cls, spec):
         return cell_density_profile.CellDensityProfile(
-            section=spec['section'],
-            patch=spec['patch'],
-            url=spec['file'],
+            section=spec["section"],
+            patch=spec["patch"],
+            url=spec["file"],
             anchor=cls.extract_anchor(spec),
             datasets=cls.extract_datasets(spec),
+            id=spec.get("@id", None),
+            prerelease=spec.get("prerelease", False),
         )
 
     @classmethod
     @build_type("siibra/feature/section/v0.1")
     def build_section(cls, spec):
-        vol = cls.build_volume(spec)
         kwargs = {
-            "name": spec.get('name', ""),
-            "region": spec.get('region', None),
-            "space_spec": vol._space_spec,
-            "providers": vol._providers.values(),
+            "name": spec.get("name"),
+            "region": spec.get("region", None),
+            "space_spec": spec.get("space"),
+            "providers": cls.build_volumeproviders(spec.get("providers")),
             "datasets": cls.extract_datasets(spec),
+            "bbox": cls.build_boundingbox(spec),
+            "id": spec.get("@id", None),
+            "prerelease": spec.get("prerelease", False),
         }
-        modality = spec.get('modality', "")
+        modality = spec.get("modality", "")
         if modality == "cell body staining":
             return sections.CellbodyStainedSection(**kwargs)
         else:
-            raise ValueError(f"No method for building image section feature type {modality}.")
+            raise ValueError(
+                f"No method for building image section feature type {modality}."
+            )
 
     @classmethod
     @build_type("siibra/feature/voi/v0.1")
     def build_volume_of_interest(cls, spec):
-        vol = cls.build_volume(spec)
         kwargs = {
-            "name": spec.get('name', ""),
-            "region": spec.get('region', None),
-            "space_spec": vol._space_spec,
-            "providers": vol._providers.values(),
+            "name": spec.get("name"),
+            "region": spec.get("region", None),
+            "space_spec": spec.get("space"),
+            "providers": cls.build_volumeproviders(spec.get("providers")),
             "datasets": cls.extract_datasets(spec),
+            "bbox": cls.build_boundingbox(spec),
+            "id": spec.get("@id", None),
+            "prerelease": spec.get("prerelease", False),
         }
-        modality = spec.get('modality', "")
+        modality = spec.get("modality", "")
         if modality == "cell body staining":
             return volume_of_interest.CellBodyStainedVolumeOfInterest(**kwargs)
         elif modality == "blockface":
@@ -427,25 +475,21 @@ class Factory:
                 modality="transmittance", **kwargs
             )
         elif modality == "XPCT":
-            return volume_of_interest.XPCTVolumeOfInterest(
-                modality="XPCT", **kwargs
-            )
+            return volume_of_interest.XPCTVolumeOfInterest(modality="XPCT", **kwargs)
         elif modality == "DTI":
-            return volume_of_interest.DTIVolumeOfInterest(
-                modality=modality, **kwargs
-            )
+            return volume_of_interest.DTIVolumeOfInterest(modality=modality, **kwargs)
         # elif modality == "segmentation":
         #     return volume_of_interest.SegmentedVolumeOfInterest(**kwargs)
         elif "MRI" in modality:
-            return volume_of_interest.MRIVolumeOfInterest(
-                modality=modality, **kwargs
-            )
+            return volume_of_interest.MRIVolumeOfInterest(modality=modality, **kwargs)
         elif modality == "LSFM":
             return volume_of_interest.LSFMVolumeOfInterest(
                 modality="Light Sheet Fluorescence Microscopy", **kwargs
             )
         else:
-            raise ValueError(f"No method for building image section feature type {modality}.")
+            raise ValueError(
+                f"No method for building image section feature type {modality}."
+            )
 
     @classmethod
     @build_type("siibra/feature/connectivitymatrix/v0.3")
@@ -455,10 +499,14 @@ class Factory:
         try:
             conn_cls = getattr(connectivity, modality)
         except Exception:
-            raise ValueError(f"No method for building connectivity matrix of type {modality}.")
+            raise ValueError(
+                f"No method for building connectivity matrix of type {modality}."
+            )
 
         decoder_func = cls.extract_decoder(spec)
-        repo_connector = cls.extract_connector(spec) if spec.get('repository', None) else None
+        repo_connector = (
+            cls.extract_connector(spec) if spec.get("repository", None) else None
+        )
         if repo_connector is None:
             base_url = spec.get("base_url", "")
         kwargs = {
@@ -469,7 +517,8 @@ class Factory:
             "decode_func": decoder_func,
             "anchor": cls.extract_anchor(spec),
             "description": spec.get("description", ""),
-            "datasets": cls.extract_datasets(spec)
+            "datasets": cls.extract_datasets(spec),
+            "prerelease": spec.get("prerelease", False),
         }
         paradigm = spec.get("paradigm")
         if paradigm:
@@ -478,12 +527,15 @@ class Factory:
         assert files_indexed_by in ["subject", "feature"]
         conn_by_file = []
         for fkey, filename in files.items():
-            kwargs.update({
-                "filename": filename,
-                "subject": fkey if files_indexed_by == "subject" else "average",
-                "feature": fkey if files_indexed_by == "feature" else None,
-                "connector": repo_connector or base_url + filename
-            })
+            kwargs.update(
+                {
+                    "filename": filename,
+                    "subject": fkey if files_indexed_by == "subject" else "average",
+                    "feature": fkey if files_indexed_by == "feature" else None,
+                    "connector": repo_connector or base_url + filename,
+                    "id": spec.get("@id", None),
+                }
+            )
             conn_by_file.append(conn_cls(**kwargs))
         return conn_by_file
 
@@ -506,17 +558,17 @@ class Factory:
             "anchor": cls.extract_anchor(spec),
             "description": spec.get("description", ""),
             "datasets": cls.extract_datasets(spec),
-            "timestep": spec.get("timestep")
+            "timestep": spec.get("timestep"),
+            "prerelease": spec.get("prerelease", False),
         }
         paradigm = spec.get("paradigm")
         if paradigm:
             kwargs["paradigm"] = paradigm
         timeseries_by_file = []
         for fkey, filename in files.items():
-            kwargs.update({
-                "filename": filename,
-                "subject": fkey
-            })
+            kwargs.update(
+                {"filename": filename, "subject": fkey, "id": spec.get("@id", None)}
+            )
             timeseries_by_file.append(timeseries_cls(**kwargs))
         return timeseries_by_file
 
@@ -525,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-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,10 +14,3 @@
 # limitations under the License.
 """:ref:`Main siibra concepts<mainconcepts>`"""
 from . import atlas, parcellation, space
-
-
-def warm_cache():
-    """Preload preconfigured siibra core concepts."""
-    _ = atlas.Atlas.registry()
-    _ = space.Space.registry()
-    _ = parcellation.Parcellation.registry()