siibra 1.0a1__1-py3-none-any.whl

siibra/core/space.py

@@ -0,0 +1,131 @@
+# 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.
+"""A particular brain reference space."""
+
+
+from .concept import AtlasConcept
+
+from ..commons import logger, Species
+
+from typing import List, TYPE_CHECKING, Union
+
+if TYPE_CHECKING:
+    from ..volumes import volume
+
+
+class Space(AtlasConcept, configuration_folder="spaces"):
+
+    def __init__(
+        self,
+        identifier: str,
+        name: str,
+        species: Union[str, Species],
+        volumes: List['volume.Volume'] = [],
+        shortname: str = "",
+        description: str = "",
+        modality: str = "",
+        publications: list = [],
+        datasets: list = [],
+        prerelease: bool = False,
+    ):
+        """
+        Constructs a new parcellation object.
+
+        Parameters
+        ----------
+            identifier : str
+                Unique identifier of the space
+            name : str
+                Human-readable name of the space
+            species: str or Species
+                Specification of the species
+            volumes: list[Volume]
+                list of template volumes
+            shortname: str, optional
+                Shortform of human-readable name
+            description: str, optional
+                Textual description of the parcellation
+            modality  :  str or None
+                Specification of the modality representing this reference space
+            publications: list
+                List of associated publications, each a dictionary with "doi" and/or "citation" fields
+            ebrains_ids : dict
+                Identifiers of EBRAINS entities corresponding to this Parcellation.
+                Key: EBRAINS KG schema, value: EBRAINS KG @id
+        """
+
+        AtlasConcept.__init__(
+            self,
+            identifier=identifier,
+            name=name,
+            species=species,
+            shortname=shortname,
+            description=description,
+            modality=modality,
+            publications=publications,
+            datasets=datasets,
+            prerelease=prerelease,
+        )
+        self.volumes = volumes
+        for v in self.volumes:
+            v.space_info = {"@id": self.id}
+
+    def get_template(self, variant: str = None):
+        """
+        Get the volumetric reference template for this space.
+
+        Parameters
+        ----------
+            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.
+
+        Returns
+        -------
+            Volume
+                representing the reference template, or None if not available.
+        """
+        tests = []
+        if variant is not None:
+            tests.append(lambda v: hasattr(v, 'variant') and variant.lower() in v.variant.lower())
+        candidates = [v for v in self.volumes if all(t(v) for t in tests)]
+
+        if len(candidates) == 0:
+            msg = f"Volume variant {variant} not available for '{self.name}'. " \
+                if variant else f"No volumes available for '{self.name}'. "
+            raise RuntimeError(msg)
+
+        if len(candidates) > 1:
+            logger.info(
+                f"Multiple template variants available for '{self.name}': "
+                f"{', '.join(c.variant for c in candidates)}. "
+                f"'{candidates[0].variant}' is chosen, but you might specify another with the 'variant' parameter."
+            )
+
+        template = candidates[0]
+        if len(template.datasets) == 0:
+            template.datasets = self.datasets
+        return template
+
+    @property
+    def provides_mesh(self):
+        return any(v.provides_mesh for v in self.volumes)
+
+    @property
+    def provides_image(self):
+        return any(v.provides_image for v in self.volumes)

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}",
+        )