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

siibra/core/space.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");
@@ -17,7 +17,6 @@
 
 from .concept import AtlasConcept
 
-from ..locations import Point, BoundingBox
 from ..commons import logger, Species
 
 from typing import List, TYPE_CHECKING, Union
@@ -39,6 +38,7 @@ class Space(AtlasConcept, configuration_folder="spaces"):
         modality: str = "",
         publications: list = [],
         datasets: list = [],
+        prerelease: bool = False,
     ):
         """
         Constructs a new parcellation object.
@@ -76,6 +76,7 @@ class Space(AtlasConcept, configuration_folder="spaces"):
             modality=modality,
             publications=publications,
             datasets=datasets,
+            prerelease=prerelease,
         )
         self.volumes = volumes
         for v in self.volumes:
@@ -116,7 +117,10 @@ class Space(AtlasConcept, configuration_folder="spaces"):
                 f"'{candidates[0].variant}' is chosen, but you might specify another with the 'variant' parameter."
             )
 
-        return candidates[0]
+        template = candidates[0]
+        if len(template.datasets) == 0:
+            template.datasets = self.datasets
+        return template
 
     @property
     def provides_mesh(self):
@@ -125,39 +129,3 @@ class Space(AtlasConcept, configuration_folder="spaces"):
     @property
     def provides_image(self):
         return any(v.provides_image for v in self.volumes)
-
-    def __getitem__(self, slices):
-        """
-        Get a volume of interest specification from this space.
-
-        Parameters
-        ----------
-            slices: triple of slice
-                Defines the x, y and z range
-        """
-        if len(slices) != 3:
-            raise TypeError(
-                "Slice access to spaces needs to define x,y and z ranges (e.g. Space[10:30,0:10,200:300])"
-            )
-        point1 = [0 if s.start is None else s.start for s in slices]
-        point2 = [s.stop for s in slices]
-        if None in point2:
-            # fill upper bounds with maximum physical coordinates
-            T = self.get_template()
-            shape = Point(T.get_shape(-1), None).transform(T.build_affine(-1))
-            point2 = [shape[i] if v is None else v for i, v in enumerate(point2)]
-        return self.get_bounding_box(point1, point2)
-
-    def get_bounding_box(self, point1, point2):
-        """
-        Get a volume of interest specification from this space.
-
-        Parameters
-        ----------
-            point1: 3D tuple defined in physical coordinates of this reference space
-            point2: 3D tuple defined in physical coordinates of this reference space
-        Returns
-        -------
-            BoundingBox
-        """
-        return BoundingBox(point1, point2, self)

siibra/core/structure.py

@@ -0,0 +1,111 @@
+# 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.
+"""
+Abstract base class for any kind of brain structure.
+A brain structure is more general than a brain region. It refers to any object
+defining a spatial extent in one or more reference spaces, and can thus be
+used to compute intersections with other structures in space. For example,
+a brain region is a structure which is at the same time an AtlasConcept. A
+bounding box in MNI space is a structure, but not an AtlasConcept.
+"""
+
+from . import assignment, region as _region
+
+from abc import ABC, abstractmethod
+from typing import Tuple, Dict
+
+
+class BrainStructure(ABC):
+    """Abstract base class for types who can act as a location filter."""
+
+    # cache assignment results at class level
+    _ASSIGNMENT_CACHE: Dict[
+        Tuple["BrainStructure", "BrainStructure"],
+        "assignment.AnatomicalAssignment"
+    ] = {}
+
+    def intersects(self, other: "BrainStructure") -> bool:
+        """
+        Whether or not two BrainStructures have any intersection.
+        """
+        return self.intersection(other) is not None
+
+    def __contains__(self, other: "BrainStructure") -> bool:
+        return self.intersection(other) == other
+
+    def __hash__(self) -> int:
+        return hash(self.__repr__())
+
+    @abstractmethod
+    def __repr__(self) -> str:
+        raise NotImplementedError
+
+    @abstractmethod
+    def intersection(self, other: "BrainStructure") -> "BrainStructure":
+        """
+        Return the intersection of two BrainStructures,
+        ie. the other BrainStructure filtered by this BrainStructure.
+        """
+        pass
+
+    def assign(self, other: "BrainStructure") -> assignment.AnatomicalAssignment:
+        """
+        Compute assignment of a BrainStructure to this filter.
+
+        Parameters
+        ----------
+        other : Location or Region
+
+        Returns
+        -------
+        assignment.AnatomicalAssignment or None
+            None if there is no AssignmentQualification found.
+        """
+        # Two cases:
+        # 1) self is location, other is location -> look at spatial intersection/relationship, do it here
+        # 2) self is location, other is region -> get region map, then call again. do it here
+        # If self is region -> Region overwrite this method, adressed there
+
+        assert not isinstance(self, _region.Region)  # method is overwritten by Region!
+        if (self, other) in self._ASSIGNMENT_CACHE:
+            return self._ASSIGNMENT_CACHE[self, other]
+        if (other, self) in self._ASSIGNMENT_CACHE:
+            return self._ASSIGNMENT_CACHE[other, self].invert()
+
+        if isinstance(other, _region.Region):
+            inverse_assignment = other.assign(self)
+            if inverse_assignment is None:
+                self._ASSIGNMENT_CACHE[self, other] = None
+            else:
+                self._ASSIGNMENT_CACHE[self, other] = inverse_assignment.invert()
+            return self._ASSIGNMENT_CACHE[self, other]
+        else:  # other is a location object, just check spatial relationships
+            qualification = None
+            if self == other:
+                qualification = assignment.Qualification.EXACT
+            else:
+                intersection = self.intersection(other)
+                if intersection is not None:
+                    if intersection == other:
+                        qualification = assignment.Qualification.CONTAINS
+                    elif intersection == self:
+                        qualification = assignment.Qualification.CONTAINED
+                    else:
+                        qualification = assignment.Qualification.OVERLAPS
+            if qualification is None:
+                self._ASSIGNMENT_CACHE[self, other] = None
+            else:
+                self._ASSIGNMENT_CACHE[self, other] = assignment.AnatomicalAssignment(self, other, qualification)
+        return self._ASSIGNMENT_CACHE[self, other]

siibra/exceptions.py

@@ -0,0 +1,63 @@
+# 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.
+"""Siibra specific exceptions"""
+
+
+class ExcessiveArgumentException(ValueError):
+    pass
+
+
+class InsufficientArgumentException(ValueError):
+    pass
+
+
+class ConflictingArgumentException(ValueError):
+    pass
+
+
+class NonUniqueIndexError(RuntimeError):
+    pass
+
+
+class NoMapAvailableError(RuntimeError):
+    pass
+
+
+class SpaceWarpingFailedError(RuntimeError):
+    pass
+
+
+class NoVolumeFound(RuntimeError):
+    pass
+
+
+class WarmupRegException(Exception):
+    pass
+
+
+class ZeroVolumeBoundingBox(Exception):
+    pass
+
+
+class NoneCoordinateSuppliedError(ValueError):
+    pass
+
+
+class NoMapMatchingValues(ValueError):
+    pass
+
+
+class EmptyPointCloudError(ValueError):
+    pass

siibra/experimental/__init__.py

@@ -0,0 +1,19 @@
+# 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.
+
+from .plane3d import Plane3D
+from .contour import Contour
+from .cortical_profile_sampler import CorticalProfileSampler
+from .patch import Patch

siibra/experimental/contour.py

@@ -0,0 +1,61 @@
+# 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.
+
+from ..locations import point, pointcloud, boundingbox
+
+import numpy as np
+
+
+class Contour(pointcloud.PointCloud):
+    """
+    A PointCloud that represents a contour line.
+    The only difference is that the point order is relevant,
+    and consecutive points are thought as being connected by an edge.
+
+    In fact, PointCloud assumes order as well, but no connections between points.
+    """
+
+    def __init__(self, coordinates, space=None, sigma_mm=0, labels: list = None):
+        pointcloud.PointCloud.__init__(self, coordinates, space, sigma_mm, labels)
+
+    def crop(self, voi: boundingbox.BoundingBox):
+        """
+        Crop the contour with a volume of interest.
+        Since the contour might be split from the cropping,
+        returns a set of contour segments.
+        """
+        segments = []
+
+        # set the contour point labels to a linear numbering
+        # so we can use them after the intersection to detect splits.
+        old_labels = self.labels
+        self.labels = list(range(len(self)))
+        cropped = self.intersection(voi)
+
+        if cropped is not None and not isinstance(cropped, point.Point):
+            assert isinstance(cropped, pointcloud.PointCloud)
+            # Identifiy contour splits are by discontinuouities ("jumps")
+            # of their labels, which denote positions in the original contour
+            jumps = np.diff([self.labels.index(lb) for lb in cropped.labels])
+            splits = [0] + list(np.where(jumps > 1)[0] + 1) + [len(cropped)]
+            for i, j in zip(splits[:-1], splits[1:]):
+                segments.append(
+                    self.__class__(cropped.coordinates[i:j, :], space=cropped.space)
+                )
+
+        # reset labels of the input contour points.
+        self.labels = old_labels
+
+        return segments

siibra/experimental/cortical_profile_sampler.py

@@ -0,0 +1,57 @@
+# 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.
+
+from . import contour
+from ..locations import point
+from ..core import parcellation
+
+import numpy as np
+
+
+class CorticalProfileSampler:
+    """Samples cortical profiles from the cortical layer maps."""
+
+    def __init__(self):
+        self.layermap = parcellation.Parcellation.get_instance(
+            "cortical layers"
+        ).get_map(space="bigbrain", maptype="labelled")
+
+    def query(self, query_point: point.Point):
+        q = query_point.warp(self.layermap.space)
+        smallest_dist = np.inf
+        best_match = None
+        for layername in self.layermap.regions:
+            vertices = self.layermap.fetch(region=layername, format="mesh")["verts"]
+            dists = np.sqrt(((vertices - q.coordinate) ** 2).sum(1))
+            best = np.argmin(dists)
+            if dists[best] < smallest_dist:
+                best_match = (layername, best)
+                smallest_dist = dists[best]
+
+        best_vertex = best_match[1]
+        hemisphere = "left" if "left" in best_match[0] else "right"
+        print(f"Best match is vertex #{best_match[1]} in {best_match[0]}.")
+
+        profile = [
+            (_, self.layermap.fetch(region=_, format="mesh")["verts"][best_vertex])
+            for _ in self.layermap.regions
+            if hemisphere in _
+        ]
+
+        return contour.Contour(
+            [p[1] for p in profile],
+            space=self.layermap.space,
+            labels=[p[0] for p in profile],
+        )

siibra/experimental/patch.py

@@ -0,0 +1,98 @@
+# 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.
+
+from ..volumes import volume
+from ..locations import pointcloud, boundingbox
+from ..commons import translation_matrix, y_rotation_matrix
+
+import numpy as np
+import math
+from nilearn import image
+
+
+class Patch:
+
+    def __init__(self, corners: pointcloud.PointCloud):
+        """Construct a patch in physical coordinates.
+        As of now, only patches aligned in the y plane of the physical space
+        are supported."""
+        # TODO: need to ensure that the points are planar, if more than 3
+        assert len(corners) == 4
+        assert len(np.unique(corners.coordinates[:, 1])) == 1
+        self.corners = corners
+
+    @property
+    def space(self):
+        return self.corners.space
+
+    def flip(self):
+        """Flips the patch. """
+        self.corners._coordinates = self.corners.coordinates[[2, 3, 0, 1]]
+
+    def extract_volume(self, image_volume: volume.Volume, resolution_mm: float):
+        """
+        fetches image data in a planar patch.
+        TODO The current implementation only covers patches which are strictly
+        define in the y plane. A future implementation should accept arbitrary
+        oriented patches.accept arbitrary oriented patches.
+        """
+        assert image_volume.space == self.space
+
+        # Extend the 2D patch into a 3D structure
+        # this is only valid if the patch plane lies within the image canvas.
+        canvas = image_volume.get_boundingbox()
+        assert canvas.minpoint[1] <= self.corners.coordinates[0, 1]
+        assert canvas.maxpoint[1] >= self.corners.coordinates[0, 1]
+        XYZ = self.corners.coordinates
+        voi = boundingbox.BoundingBox(
+            XYZ.min(0)[:3], XYZ.max(0)[:3], space=image_volume.space
+        )
+        # enforce the patch to have the same y dimensions
+        voi.minpoint[1] = canvas.minpoint[1]
+        voi.maxpoint[1] = canvas.maxpoint[1]
+        patch = image_volume.fetch(voi=voi, resolution_mm=resolution_mm)
+        assert patch is not None
+
+        # patch rotation defined in physical space
+        vx, vy, vz = XYZ[1] - XYZ[0]
+        alpha = -math.atan2(-vz, -vx)
+        cx, cy, cz = XYZ.mean(0)
+        rot_phys = np.linalg.multi_dot(
+            [
+                translation_matrix(cx, cy, cz),
+                y_rotation_matrix(alpha),
+                translation_matrix(-cx, -cy, -cz),
+            ]
+        )
+
+        # rotate the patch in physical space
+        affine_rot = np.dot(rot_phys, patch.affine)
+
+        # crop in the rotated space
+        pixels = (
+            np.dot(np.linalg.inv(affine_rot), self.corners.homogeneous.T)
+            .astype("int")
+            .T
+        )
+        # keep a pixel distance to avoid black border pixels
+        xmin, ymin, zmin = pixels.min(0)[:3] + 1
+        xmax, ymax, zmax = pixels.max(0)[:3] - 1
+        h, w = xmax - xmin, zmax - zmin
+        affine = np.dot(affine_rot, translation_matrix(xmin, 0, zmin))
+        return volume.from_nifti(
+            image.resample_img(patch, target_affine=affine, target_shape=[h, 1, w]),
+            space=image_volume.space,
+            name=f"Rotated patch with corner points {self.corners} sampled from {image_volume.name}",
+        )