hoa-tools 1.0__py3-none-any.whl

hoa_tools/registration.py

@@ -0,0 +1,112 @@
+"""
+Registration inventory and helpers.
+
+A registration defines a transform between two datasets.
+The transform is defined in physical space, and in this library data is always
+in units of micro-meters (μm).
+
+Transforms are defined using the `SimpleITK` library.
+"""
+
+import numpy as np
+import SimpleITK as sitk
+
+from hoa_tools.dataset import _DATASETS, Dataset
+from hoa_tools.types import PhysicalCoordinate
+
+
+class RegistrationInventory:
+    """
+    Inventory of transforms between datasets.
+
+    Transforms are defined as acting on the zyx axes in that order. Note that this
+    is different from the order in which the SimpleITK API defines axes in its function
+    signatures.
+    """
+
+    def __init__(self) -> None:
+        """
+        Create registration inventory.
+        """
+        self._registrations: dict[tuple[str, str], sitk.Transform] = {}
+
+    def __contains__(self, item: tuple[Dataset, Dataset]) -> bool:
+        """
+        Check for existence of registration between two datasets.
+        """
+        return (item[0].name, item[1].name) in self._registrations
+
+    def get_registration(
+        self, *, source_dataset: Dataset, target_dataset: Dataset
+    ) -> sitk.Transform:
+        """
+        Get a registration.
+        """
+        return self._registrations[(source_dataset.name, target_dataset.name)]
+
+    def add_registration(
+        self,
+        *,
+        source_dataset: Dataset,
+        target_dataset: Dataset,
+        transform: sitk.Transform,
+    ) -> None:
+        """
+        Add a new transform to the inventory.
+
+        Notes
+        -----
+        This will override any already defined transforms for these two datasets.
+
+        """
+        self._registrations[(source_dataset.name, target_dataset.name)] = transform
+        self._registrations[(target_dataset.name, source_dataset.name)] = (
+            transform.GetInverse()  # type: ignore[no-untyped-call]
+        )
+
+
+def build_transform(
+    *, translation: PhysicalCoordinate, rotation_deg: float, scale: float
+) -> sitk.Similarity3DTransform:
+    """
+    Build a transform from a translation, scale, and rotation.
+    """
+    axis = (1, 0, 0)
+    center = (0, 0, 0)
+    return sitk.Similarity3DTransform(  # type: ignore[no-untyped-call]
+        scale,
+        axis,
+        np.deg2rad(rotation_deg),
+        (translation.z, translation.y, translation.x),
+        center,
+    )
+
+
+Inventory = RegistrationInventory()
+
+
+def _populate_registrations_from_metadata(inventory: RegistrationInventory) -> None:
+    for dataset_name in _DATASETS:
+        dataset = _DATASETS[dataset_name]
+        if (registration := dataset.registration) is not None:
+            source_dataset = _DATASETS[registration.source_dataset]
+            target_dataset = _DATASETS[registration.target_dataset]
+            transform = build_transform(
+                translation=PhysicalCoordinate(
+                    x=registration.translation[0] * target_dataset.data.voxel_size_um,
+                    y=registration.translation[1] * target_dataset.data.voxel_size_um,
+                    z=registration.translation[2] * target_dataset.data.voxel_size_um,
+                ),
+                rotation_deg=registration.rotation,
+                scale=registration.scale
+                * target_dataset.data.voxel_size_um
+                / source_dataset.data.voxel_size_um,
+            )
+            Inventory.add_registration(
+                source_dataset=_DATASETS[registration.source_dataset],
+                target_dataset=_DATASETS[registration.target_dataset],
+                transform=transform,
+            )
+
+
+_populate_registrations_from_metadata(Inventory)

hoa_tools/types.py

@@ -0,0 +1,59 @@
+"""
+Common types used across the library.
+"""
+
+from math import floor
+from typing import Self
+
+import SimpleITK as sitk
+from pydantic import BaseModel
+
+
+class PhysicalCoordinate(BaseModel):
+    """
+    A single coordinate in physical space.
+    """
+
+    x: float
+    y: float
+    z: float
+
+    def to_array_coordinate(self, *, voxel_size: float) -> "ArrayCoordinate":
+        """
+        Given a voxel size, convert this physical coordinate to an array coordinate.
+        """
+        return ArrayCoordinate(
+            x=floor(self.x / voxel_size),
+            y=floor(self.y / voxel_size),
+            z=floor(self.z / voxel_size),
+        )
+
+    def transform(self, t: sitk.Transform) -> Self:
+        """
+        Transform this coordinate.
+
+        Notes
+        -----
+        The transform is applied in zyx order.
+
+        """
+        new_coord = t.TransformPoint((self.z, self.y, self.x))  # type: ignore[no-untyped-call]
+        return self.__class__(z=new_coord[0], y=new_coord[1], x=new_coord[2])
+
+
+class ArrayCoordinate(BaseModel):
+    """
+    A single coordinate in array space.
+    """
+
+    x: int
+    y: int
+    z: int
+
+    def to_physical_coordinate(self, *, voxel_size: float) -> "PhysicalCoordinate":
+        """
+        Given a voxel size, convert this array coordinate to a physical coordinate.
+        """
+        return PhysicalCoordinate(
+            x=self.x * voxel_size, y=self.y * voxel_size, z=self.z * voxel_size
+        )

hoa_tools/voi.py

@@ -0,0 +1,230 @@
+"""
+Tools for working with volumes of interest (VOIs).
+
+A volume of interest is a sub-volume contained within a full dataset.
+It is represented by the [`VOI`][hoa_tools.voi.VOI] class.
+
+All coordinates are given in 'array coordinates',
+where 0 is the centre of the first voxel, 1 is the centre of the second voxel etc.
+"""
+
+import itertools
+from math import ceil, floor
+from typing import Any
+
+import SimpleITK as sitk
+import xarray as xr
+from pydantic import BaseModel
+
+from hoa_tools.dataset import Dataset
+from hoa_tools.registration import Inventory as RegInventory
+from hoa_tools.types import ArrayCoordinate
+
+
+class VOI(BaseModel):
+    """
+    A volume of interest attached to a given dataset.
+    """
+
+    dataset: Dataset
+    """Dataset that this VOI is in."""
+    downsample_level: int
+    """Downsampling level of the dataset that this VOI is defined in."""
+    lower_corner: ArrayCoordinate
+    """Index of lower corner in array coordinates."""
+    size: ArrayCoordinate
+    """Size of VOI in array coordinates."""
+
+    @property
+    def voxel_size_um(self) -> float:
+        """
+        Voxel size in micrometers.
+        """
+        return float(self.dataset.data.voxel_size_um * 2 ** (self.downsample_level))
+
+    @property
+    def upper_corner(self) -> ArrayCoordinate:
+        """
+        Upper corner of the VOI.
+        """
+        return ArrayCoordinate(
+            x=self.lower_corner.x + self.size.x,
+            y=self.lower_corner.y + self.size.y,
+            z=self.lower_corner.z + self.size.z,
+        )
+
+    @property
+    def corners(self) -> list[ArrayCoordinate]:
+        """
+        All 8 corners of the VOI.
+        """
+        corner_tuples: list[tuple[int, int, int]] = list(
+            itertools.product(  # type: ignore[arg-type]
+                *zip(
+                    [self.lower_corner.x, self.lower_corner.y, self.lower_corner.z],
+                    [self.upper_corner.x, self.upper_corner.y, self.upper_corner.z],
+                    strict=True,
+                )
+            )
+        )
+        return [ArrayCoordinate(x=i[0], y=i[1], z=i[2]) for i in corner_tuples]
+
+    def get_data_array(self) -> xr.DataArray:
+        """
+        Get data array for this VOI.
+        """
+        da = self.dataset.data_array(downsample_level=self.downsample_level)
+        return da.isel(
+            x=slice(self.lower_corner.x, self.upper_corner.x),
+            y=slice(self.lower_corner.y, self.upper_corner.y),
+            z=slice(self.lower_corner.z, self.upper_corner.z),
+        )
+
+    def get_sitk_image(self) -> sitk.Image:
+        """
+        Get a SimpleITK image of this VOI.
+        """
+        data_array = self.get_data_array()
+        image = sitk.GetImageFromArray(data_array.transpose("x", "y", "z").values)
+        image.SetSpacing((self.voxel_size_um, self.voxel_size_um, self.voxel_size_um))  # type: ignore[no-untyped-call]
+        image.SetOrigin(  # type: ignore[no-untyped-call]
+            (
+                float(data_array.coords["z"][0]),
+                float(data_array.coords["y"][0]),
+                float(data_array.coords["x"][0]),
+            )
+        )
+        return image
+
+    def get_data_array_on_voi(
+        self,
+        target_voi: "VOI",
+        *,
+        interpolator: Any = sitk.sitkLinear,
+        transform: sitk.Transform | None = None,
+    ) -> xr.DataArray:
+        """
+        Get data array for this VOI resampled to the grid of another VOI.
+
+        If the transform isn't given, uses the transform between two datasets in the
+        registration inventory.
+
+        Parameters
+        ----------
+        target_voi :
+            VOI to resample data in this VOI on to.
+        interpolator :
+            Interpolation method to use.
+            See https://simpleitk.org/doxygen/v2_4/html/namespaceitk_1_1simple.html#a7cb1ef8bd02c669c02ea2f9f5aa374e5
+        transform :
+            If given, transform used to map this VOI on to the target VOI.
+            If not given, transform is taken from the registration inventory.
+
+        """
+        if transform is None:
+            transform = RegInventory.get_registration(
+                source_dataset=self.dataset, target_dataset=target_voi.dataset
+            )
+        default_value = 0
+        new_image = sitk.Resample(
+            self.get_sitk_image(),
+            target_voi.get_sitk_image(),
+            transform.GetInverse(),  # type: ignore[no-untyped-call]
+            interpolator,
+            default_value,
+        )
+
+        new_array = target_voi.get_data_array().copy()
+        new_array.values = sitk.GetArrayFromImage(new_image).T
+        return new_array
+
+    def change_downsample_level(self, *, new_downsample_level: int) -> "VOI":
+        """
+        Return a new VOI at a different downsample level.
+        """
+        resolution_ratio = (2**self.downsample_level) / (2**new_downsample_level)
+        new_lower_corner = ArrayCoordinate(
+            x=floor(self.lower_corner.x * resolution_ratio),
+            y=floor(self.lower_corner.y * resolution_ratio),
+            z=floor(self.lower_corner.z * resolution_ratio),
+        )
+        new_size = ArrayCoordinate(
+            x=ceil(self.size.x * resolution_ratio),
+            y=ceil(self.size.y * resolution_ratio),
+            z=ceil(self.size.z * resolution_ratio),
+        )
+        return VOI(
+            dataset=self.dataset,
+            downsample_level=new_downsample_level,
+            lower_corner=new_lower_corner,
+            size=new_size,
+        )
+
+    def transform_to(
+        self,
+        dataset: Dataset,
+        *,
+        transform: sitk.Transform | None = None,
+    ) -> "VOI":
+        """
+        Transform this VOI to another dataset.
+
+        The new VOI will completely contain the transformed original VOI.
+
+        Parameters
+        ----------
+        dataset :
+            Dataset to transform to.
+        transform :
+            If given, transform used to map this VOI on to the target VOI.
+            If not given, transform is taken from the registration inventory.
+
+        """
+        if transform is None:
+            if (self.dataset, dataset) not in RegInventory:
+                msg = (
+                    f"Transform between {self.dataset.name} and {dataset.name} "
+                    "not found in registration inventory."
+                )
+                raise RuntimeError(msg)
+
+            transform = RegInventory.get_registration(
+                source_dataset=self.dataset, target_dataset=dataset
+            )
+
+        old_voi = self.change_downsample_level(new_downsample_level=0)
+
+        # Convert to physical space
+        physical_corners = [
+            c.to_physical_coordinate(voxel_size=self.dataset.data.voxel_size_um)
+            for c in old_voi.corners
+        ]
+        # Transform
+        physical_corners_transformed = [
+            c.transform(transform) for c in physical_corners
+        ]
+        # Convert back to array space
+        corners_transformed = [
+            c.to_array_coordinate(voxel_size=dataset.data.voxel_size_um)
+            for c in physical_corners_transformed
+        ]
+        lower_corner = ArrayCoordinate(
+            z=min([c.z for c in corners_transformed]),
+            y=min([c.y for c in corners_transformed]),
+            x=min([c.x for c in corners_transformed]),
+        )
+        upper_corner = ArrayCoordinate(
+            z=max([c.z for c in corners_transformed]) + 1,
+            y=max([c.y for c in corners_transformed]) + 1,
+            x=max([c.x for c in corners_transformed]) + 1,
+        )
+        return VOI(
+            dataset=dataset,
+            downsample_level=0,
+            lower_corner=lower_corner,
+            size=ArrayCoordinate(
+                x=upper_corner.x - lower_corner.x,
+                y=upper_corner.y - lower_corner.y,
+                z=upper_corner.z - lower_corner.z,
+            ),
+        )

hoa_tools-1.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: hoa-tools
+Version: 1.0
+Summary: Tools for working with the Human Organ Atlas
+Author-email: David Stansby <d.stansby@ucl.ac.uk>
+License: Copyright (c) 2024, David Stansby
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        - Redistributions of source code must retain the above copyright notice, this
+          list of conditions and the following disclaimer.
+        
+        - Redistributions in binary form must reproduce the above copyright notice,
+          this list of conditions and the following disclaimer in the documentation
+          and/or other materials provided with the distribution.
+        
+        - Neither the name of HOA Tools nor the names of its
+          contributors may be used to endorse or promote products derived from
+          this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: homepage, https://github.com/HumanOrganAtlas/hoa-tools
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: dask[array]
+Requires-Dist: gcsfs>2023
+Requires-Dist: pandas>=2
+Requires-Dist: pydantic>=2
+Requires-Dist: simpleitk
+Requires-Dist: xarray
+Requires-Dist: zarr<3,>2.16
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: jupyterlab; extra == "dev"
+Requires-Dist: jupytext; extra == "dev"
+Requires-Dist: pandas-stubs; extra == "dev"
+Requires-Dist: datamodel-code-generator; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocstrings-python; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocs-jupyter; extra == "docs"
+Requires-Dist: griffe-pydantic; extra == "docs"
+Requires-Dist: matplotlib; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
+Requires-Dist: scikit-image; extra == "docs"
+Provides-Extra: test
+Requires-Dist: matplotlib; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-accept; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-doctestplus; extra == "test"
+Requires-Dist: pytest-vcr; extra == "test"
+Requires-Dist: scikit-image; extra == "test"
+Dynamic: license-file
+
+# HOA Tools
+
+[![Tests status][tests-badge]][tests-link]
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/HumanOrganAtlas/hoa-tools/main.svg)](https://results.pre-commit.ci/latest/github/HumanOrganAtlas/hoa-tools/main)
+[![Documentation Status](https://readthedocs.org/projects/hoa-tools/badge/?version=latest)](https://hoa-tools.readthedocs.io/en/latest/?badge=latest)
+
+[![License][license-badge]](./LICENSE.md)
+
+<!--
+[![PyPI version][pypi-version]][pypi-link]
+[![Conda-Forge][conda-badge]][conda-link]
+[![PyPI platforms][pypi-platforms]][pypi-link]
+-->
+
+<!-- prettier-ignore-start -->
+[tests-badge]:              https://github.com/HumanOrganAtlas/hoa-tools/actions/workflows/tests.yml/badge.svg
+[tests-link]:               https://github.com/HumanOrganAtlas/hoa-tools/actions/workflows/tests.yml
+[conda-badge]:              https://img.shields.io/conda/vn/conda-forge/hoa-tools
+[conda-link]:               https://github.com/conda-forge/hoa-tools-feedstock
+[pypi-link]:                https://pypi.org/project/hoa-tools/
+[pypi-platforms]:           https://img.shields.io/pypi/pyversions/hoa-tools
+[pypi-version]:             https://img.shields.io/pypi/v/hoa-tools
+[license-badge]:            https://img.shields.io/badge/License-BSD_3--Clause-blue.svg
+<!-- prettier-ignore-end -->
+
+Tools for working with data from the [Human Organ Atlas](https://human-organ-atlas.esrf.eu/).
+Documentation at https://hoa-tools.readthedocs.io.