anu-ctlab-io 1.0.0__tar.gz

anu_ctlab_io-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+      - name: install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "0.6.3"
+      - name: run tests
+        run: uvx --with tox-uv tox
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+      - name: install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "0.6.3"
+      - name: run pre-commit checks
+        run: |
+          uv run pre-commit run --all-files --show-diff-on-failure

anu_ctlab_io-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install UV
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.6.3"
+      - name: Build source distribution
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pypi-files-sdist
+          path: dist
+
+  pypi-publish:
+    name: "build and publish release"
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          pattern: pypi-files-*
+          merge-multiple: true
+          path: dist/
+      - run: ls -lh dist/
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

anu_ctlab_io-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+docs/_autosummary/
+docs/_build/
+
+# Virtual environments
+.venv

anu_ctlab_io-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,57 @@
+ci:
+  autoupdate_commit_msg: "chore: update pre-commit hooks"
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: check-toml
+      - id: end-of-file-fixer
+        exclude: "^tests/(data|schema)/"
+      - id: trailing-whitespace
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: "v3.1.0"
+    hooks:
+      - id: prettier
+        exclude: "^tests/(data|schema)/"
+        types_or: [yaml, markdown, html, css, scss, javascript, json]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.9.2
+    hooks:
+      # Run the linter.
+      - id: ruff
+        args: ["--fix", "--show-fixes"]
+      # Run the formatter.
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.15.0
+    hooks:
+      - id: mypy
+        pass_filenames: false
+        always_run: true
+        args: [src]
+        additional_dependencies:
+          - pandas-stubs
+          - numpy
+          - xarray
+          - matplotlib
+          - lark
+          - zarr
+          - dask
+          - deprecation
+  - repo: https://github.com/adamchainz/blacken-docs
+    rev: "v1.12.1"
+    hooks:
+      - id: blacken-docs
+        additional_dependencies:
+          - black==22.12.0
+  - repo: https://github.com/crate-ci/typos
+    rev: v1.36.2
+    hooks:
+      - id: typos
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: "v3.6.2"
+    hooks:
+      - id: prettier

anu_ctlab_io-1.0.0/.prettierignore

@@ -0,0 +1 @@
+tests/data/*

anu_ctlab_io-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

anu_ctlab_io-1.0.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2025-09-12
+
+### Added
+
+- Github CI for build and release to PyPI
+- Documentation using Sphinx
+- justfile to build docs and run tests
+- Support for units to `VoxelUnit` to match MANGO support: `angstrom`, `centimeters`, `voxels`
+- Tests for `DataType.from_basename`
+
+### Changed
+
+- Replace README.md with README.rst
+- Improve typehinting
+- Privatise unintentionally public modules: `dataset`, `datatype`, `parse_history`, `version`, `voxel_properties`
+- Privatise objects not intended to be public:
+  - `_datatype.DataTypeProperties`
+  - `_datatype.DATATYPE_PROPERTIES`
+  - `netcdf._read_netcdf`
+- Rename `_datatype.storage_dtypes` to `_datatype.StorageDType` (PEP8)
+- Capitalise `DataType` members (PEP8)
+- Capitalise `VoxelUnit` members (PEP8)
+- Move zarr and netcdf dependencies to extras
+- Improve `tox` testing configuration, including testing with and without extras
+- Update changelog formatting to better match the Keep a Changelog format.
+
+### Removed
+
+- Remove features which were deprecated in 0.2.0:
+  - NetCDFDataset
+  - Xarray dataset support
+- Remove `UnknownVoxelUnitException`
+- Remove `DatasetFormatException`
+
+## [0.2.0] - 2025-09-07
+
+### Added
+
+- Support for reading ANU CTLab Zarr files
+- Direct access to the data loaded as Dask arrays
+
+### Changed
+
+- Interface changed to use the Dataset class for both Zarr and NetCDF files
+- Xarray output deprecated (to be removed in 1.0.0)
+
+## [0.0.1]
+
+### Added
+
+- Support for reading ANU CTLab NetCDF files
+- Support for outputting Xarray data
+
+[unreleased]: https://github.com/MaterialsPhysicsANU/anu_ctlab_io/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/MaterialsPhysicsANU/anu_ctlab_io/releases/tag/v1.0.0
+[0.2.0]: https://github.com/MaterialsPhysicsANU/anu_ctlab_io/releases/tag/v0.2.0

anu_ctlab_io-1.0.0/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025, the Australian National University (ANU)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

anu_ctlab_io-1.0.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: anu-ctlab-io
+Version: 1.0.0
+Summary: python I/O for the ANU CTLab array storage format(s)
+Project-URL: Repository, https://github.com/MaterialsPhysicsANU/anu_ctlab_io
+Project-URL: Issues, https://github.com/MaterialsPhysicsANU/anu_ctlab_io/issues
+Project-URL: Changelog, https://github.com/MaterialsPhysicsANU/anu_ctlab_io/main/CHANGELOG.md
+Author-email: Owen Dowley <owen.dowley@anu.edu.au>, Bogdan Maviichuk <bogdan.maviichuk@anu.edu.au>, Lachlan Deakin <lachlan.deakin@anu.edu.au>
+Maintainer-email: Owen Dowley <owen.dowley@anu.edu.au>
+License-Expression: MIT
+License-File: LICENSE.md
+Requires-Python: >=3.12
+Requires-Dist: dask[array]>=2025.2.0
+Requires-Dist: deprecation>=2.1.0
+Requires-Dist: dictdiffer>=0.9.0
+Requires-Dist: lark>=1.2.2
+Requires-Dist: numpy>=2.2.3
+Requires-Dist: xarray>=2025.1.2
+Provides-Extra: netcdf
+Requires-Dist: netcdf4>=1.7.2; extra == 'netcdf'
+Requires-Dist: scipy>=1.16.1; extra == 'netcdf'
+Provides-Extra: zarr
+Requires-Dist: zarr>=3.1.1; extra == 'zarr'
+Description-Content-Type: text/x-rst
+
+Introduction
+------------
+python I/O for the ANU CTLab array storage format(s).
+
+This package loads data provided in the specific NetCDF and Zarr formats produced by the ANU CTLab.
+The intention is that the consumers of the data we produce should be able to load that data and then
+work with that directly in standard scientific python workflows, rather than needing to use the
+pre-existing MANGO toolchain.
+
+Examples
+--------
+.. code-block :: python3
+
+    import anu_ctlab_io
+    from dask_image import ndfilters
+
+    dataset = anu_ctlab_io.Dataset.from_path(<path-to-your-data>)
+    blurred = ndfilters.gaussian_filter(dataset.data, sigma=3)
+    print(blurred.mean().compute())

anu_ctlab_io-1.0.0/README.rst

@@ -0,0 +1 @@
+docs/introduction.rst

anu_ctlab_io-1.0.0/_typos.toml

@@ -0,0 +1,6 @@
+[files]
+extend-exclude = ["tests/data/*"]
+
+[default.extend-words]
+# Don't correct "ome" to "some"
+ome = "ome"

anu_ctlab_io-1.0.0/docs/conf.py

@@ -0,0 +1,30 @@
+import importlib.metadata
+
+# Sphinx configuration for anu-ctlab-io docs
+project = "anu-ctlab-io"
+copyright = "2025, the Australian National University (ANU)"
+author = "Materials Physics, ANU"  # Can only be a single author, so can't match pyproject.toml. Find actual authors there.
+release = importlib.metadata.version("anu_ctlab_io")
+extensions = [
+    # 'myst_parser',
+    "sphinx_rtd_theme",
+    "sphinx.ext.autodoc",
+    # "sphinx.ext.napoleon",
+    "sphinx.ext.autosummary",
+    "sphinx_autodoc_typehints",
+]
+html_theme = "sphinx_rtd_theme"
+autosummary_generate = True
+source_suffix = {
+    # '.md': 'markdown',
+    ".rst": "restructuredtext",
+}
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "member-order": "bysource",
+    "show-inheritance": True,
+    "inherited-members": True,
+    "special-members": "__init__",
+}

anu_ctlab_io-1.0.0/docs/index.rst

@@ -0,0 +1,15 @@
+anu_ctlab_io package
+====================
+.. toctree::
+   introduction
+
+.. .. automodule:: anu_ctlab_io
+..     :members:
+..     :undoc-members:
+..     :show-inheritance:
+
+.. autosummary::
+   :toctree: _autosummary
+   :recursive:
+
+   anu_ctlab_io

anu_ctlab_io-1.0.0/docs/introduction.rst

@@ -0,0 +1,19 @@
+Introduction
+------------
+python I/O for the ANU CTLab array storage format(s).
+
+This package loads data provided in the specific NetCDF and Zarr formats produced by the ANU CTLab.
+The intention is that the consumers of the data we produce should be able to load that data and then
+work with that directly in standard scientific python workflows, rather than needing to use the
+pre-existing MANGO toolchain.
+
+Examples
+--------
+.. code-block :: python3
+
+    import anu_ctlab_io
+    from dask_image import ndfilters
+
+    dataset = anu_ctlab_io.Dataset.from_path(<path-to-your-data>)
+    blurred = ndfilters.gaussian_filter(dataset.data, sigma=3)
+    print(blurred.mean().compute())

anu_ctlab_io-1.0.0/justfile

@@ -0,0 +1,7 @@
+docs:
+    rm -rf docs/_autosummary
+    rm -rf docs/_build
+    uv run sphinx-build -M html docs docs/_build
+
+test:
+    uvx --with tox-uv tox

anu_ctlab_io-1.0.0/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "anu-ctlab-io"
+version = "1.0.0"
+description = "python I/O for the ANU CTLab array storage format(s)"
+readme = "README.rst"
+requires-python = ">=3.12"
+dependencies = [
+    "dask[array]>=2025.2.0",
+    "xarray>=2025.1.2",
+    "numpy>=2.2.3",
+    "lark>=1.2.2",
+    "dictdiffer>=0.9.0",
+    "deprecation>=2.1.0",
+]
+default-optional-dependency-keys = [
+    "netcdf",
+    "zarr",
+]
+
+license = "MIT"
+license-files = ["LICENSE.md"]
+authors = [
+    {name = "Owen Dowley", email = "owen.dowley@anu.edu.au"},
+    {name = "Bogdan Maviichuk", email = "bogdan.maviichuk@anu.edu.au"},
+    {name = "Lachlan Deakin", email = "lachlan.deakin@anu.edu.au"},
+]
+maintainers = [
+    {name = "Owen Dowley", email = "owen.dowley@anu.edu.au"},
+]
+
+[project.optional-dependencies]
+netcdf = [
+    "netcdf4>=1.7.2",
+    "scipy>=1.16.1", # netCDF 3 support
+]
+zarr = [
+    "zarr>=3.1.1",
+]
+
+[project.urls]
+# FIXME: Add Homepage on v1.0.0 release
+Repository = "https://github.com/MaterialsPhysicsANU/anu_ctlab_io"
+Issues = "https://github.com/MaterialsPhysicsANU/anu_ctlab_io/issues"
+Changelog = "https://github.com/MaterialsPhysicsANU/anu_ctlab_io/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.1.0",
+    "ruff>=0.9.5",
+    "pytest>=8.3.5",
+    "sphinx>=8.2.3",
+    "sphinx-rtd-theme>=3.0.2",
+    "sphinx-autodoc-typehints>=3.2.0",
+]
+
+[tool.pytest.ini_options]
+filterwarnings = [
+    # known behaviour, caused by numpy changes which are ABI compatible with older versions,
+    # but which cython flags as a warning despite everything being fine
+    # See https://github.com/cython/cython/issues/2498, https://github.com/cython/cython/issues/4366
+    'ignore:numpy.ndarray size changed, may indicate binary incompatibility.'
+]
+addopts = [
+    "--import-mode=importlib", # recommended by pytest
+    "-ra",
+    "--strict-config",
+    "--strict-markers"
+]
+minversion = "7.0"
+testpaths = ["tests"]
+log_cli_level = "INFO"
+xfail_strict = true
+
+[tool.mypy]
+strict = true
+warn_unreachable = true
+enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
+
+[tool.ruff.lint]
+extend-select = [
+  "B", # flake8-bugbear
+  "I", # isort
+  "UP", # pyupgrade
+]

anu_ctlab_io-1.0.0/src/anu_ctlab_io/__init__.py

@@ -0,0 +1,22 @@
+from contextlib import suppress
+
+from anu_ctlab_io._dataset import Dataset
+from anu_ctlab_io._datatype import DataType, StorageDType
+from anu_ctlab_io._version import version as __version__
+from anu_ctlab_io._voxel_properties import VoxelUnit
+
+with suppress(ImportError):
+    import anu_ctlab_io.netcdf as netcdf
+
+with suppress(ImportError):
+    import anu_ctlab_io.zarr as zarr
+
+__all__ = [
+    "Dataset",  # out of sorted order so it comes first in the docs
+    "DataType",
+    "StorageDType",
+    "VoxelUnit",
+    "__version__",
+    "netcdf",
+    "zarr",
+]

anu_ctlab_io-1.0.0/src/anu_ctlab_io/_dataset.py

@@ -0,0 +1,189 @@
+from abc import ABC, abstractmethod, abstractproperty
+from importlib import import_module
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Self
+
+import dask.array as da
+import numpy as np
+
+from anu_ctlab_io._datatype import DataType, StorageDType
+from anu_ctlab_io._voxel_properties import VoxelUnit
+
+
+class AbstractDataset(ABC):
+    @classmethod
+    @abstractmethod
+    def from_path(
+        cls, path: Path, *, parse_history: bool = True, **kwargs: Any
+    ) -> Self:
+        pass
+
+    @abstractproperty
+    def voxel_size(self) -> tuple[np.float32, np.float32, np.float32]:
+        pass
+
+    @abstractproperty
+    def voxel_unit(self) -> VoxelUnit:
+        pass
+
+    @abstractproperty
+    def dimension_names(self) -> tuple[str, ...]:
+        pass
+
+    @abstractproperty
+    def history(self) -> dict[Any, Any] | str:
+        pass
+
+    @abstractproperty
+    def mask_value(self) -> StorageDType | None:
+        pass
+
+    @abstractproperty
+    def data(self) -> da.Array:
+        pass
+
+
+class Dataset(AbstractDataset):
+    """A :any:`Dataset`, containing the data and metadata read from one of the ANU CTLab file formats.
+
+    :any:`Dataset`\\ s are the primary interface to the :py:mod:`anu_ctlab_io` package, and should generally be
+    constructed by users via the :any:`Dataset.from_path` classmethod.
+
+    The initializer of this class should only be used when manually constructing a :any:`Dataset`, which is not
+    the primary usage of this library.
+    """
+
+    _data: da.Array
+    _datatype: DataType
+    _voxel_unit: VoxelUnit
+    _voxel_size: tuple[np.float32, np.float32, np.float32]
+    _history: dict[Any, Any] | str
+
+    def __init__(
+        self,
+        data: da.Array,
+        *,
+        dimension_names: tuple[str, ...],
+        voxel_unit: VoxelUnit,
+        voxel_size: tuple[np.float32, np.float32, np.float32],
+        datatype: DataType,
+        history: dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Manually constructs a :any:`Dataset`.
+
+        :param data: The data contained in the :any:`Dataset`.
+        :param dimension_names: The names of the dimensions of the :any:`Dataset`.
+        :param voxel_unit: The unit the `voxel_size` is in terms of.
+        :param voxel_size: The size of each voxel in the :any:`Dataset`.
+        :param datatype: The mango datatype of the data. This is an implementation detail only required for parsing NetCDF files.
+        :param history: The history of the :any:`Dataset`.
+        """
+        if history is None:
+            history = {}
+
+        self._data = data
+        self._dimension_names = dimension_names
+        self._datatype = datatype
+        self._voxel_unit = voxel_unit
+        self._voxel_size = voxel_size
+        self._history = history
+
+    @staticmethod
+    def _import_with_extra(module: str, extra: str) -> ModuleType:
+        try:
+            return import_module(module)
+        except ImportError as e:
+            raise ImportError(
+                f"{module} is missing. Please install with the '{extra}' extra: pip install anu-ctlab-io[{extra}]"
+            ) from e
+
+    @classmethod
+    def from_path(
+        cls,
+        path: Path | str,
+        *,
+        filetype: str = "auto",
+        parse_history: bool = True,
+        **kwargs: Any,
+    ) -> "Dataset":
+        """Creates a :any:`Dataset` from the data at the given ``path``.
+
+        The data at ``path`` must be in one of the ANU mass data storage formats, and the optional dependencies required for the specific
+        file format must be installed.
+
+        :param path: The ``path`` to read data from.
+        :rtype: :any:`Dataset`
+        """
+        if isinstance(path, str):
+            path = Path(path)
+
+        match filetype:
+            case "NetCDF":
+                netcdf_mod = cls._import_with_extra("anu_ctlab_io.netcdf", "netcdf")
+                return netcdf_mod.dataset_from_netcdf(  # type: ignore[no-any-return]
+                    path, parse_history=parse_history, **kwargs
+                )
+            case "zarr":
+                zarr_mod = cls._import_with_extra("anu_ctlab_io.zarr", "zarr")
+                return zarr_mod.dataset_from_zarr(  # type: ignore[no-any-return]
+                    path, parse_history=parse_history, **kwargs
+                )
+            case "auto":
+                if path.name[-2:] == "nc":
+                    netcdf_mod = cls._import_with_extra("anu_ctlab_io.netcdf", "netcdf")
+                    return netcdf_mod.dataset_from_netcdf(  # type: ignore[no-any-return]
+                        path, parse_history=parse_history, **kwargs
+                    )
+
+                if path.name[-4:] == "zarr":
+                    zarr_mod = cls._import_with_extra("anu_ctlab_io.zarr", "zarr")
+                    return zarr_mod.dataset_from_zarr(  # type: ignore[no-any-return]
+                        path, parse_history=parse_history, **kwargs
+                    )
+
+        raise (
+            ValueError(
+                "Unable to construct Dataset from given `path`, perhaps specify `filetype`?",
+                path,
+            )
+        )
+
+    @property
+    def voxel_size(self) -> tuple[np.float32, np.float32, np.float32]:
+        """The voxel size of the data."""
+        return self._voxel_size
+
+    @property
+    def voxel_unit(self) -> VoxelUnit:
+        """The unit the data's voxel size is in."""
+        return self._voxel_unit
+
+    @property
+    def dimension_names(self) -> tuple[str, ...]:
+        """The names of the data's dimensions. Usually ``("z", "y", "x")``."""
+        return self._dimension_names
+
+    @property
+    def history(self) -> dict[Any, Any] | str:
+        """The history metadata associated with the :any:`Dataset`.
+
+        If parsing is enabled this will be a nested dict, otherwise it will be a dictionary
+        without any guaranteed structure."""
+        return self._history
+
+    @property
+    def mask_value(self) -> StorageDType | None:
+        """The mask value being used by the data."""
+        return self._datatype.mask_value
+
+    @property
+    def data(self) -> da.Array:
+        """The data contained within the :any:`Dataset`.
+
+        This is a `Dask Array <https://docs.dask.org/en/stable/array.html>`_."""
+        return self._data
+
+
+AbstractDataset.register(Dataset)