toolsandogh 0.2.0__tar.gz → 0.3.2__tar.gz

toolsandogh-0.3.2/.github/workflows/ci.yml

@@ -0,0 +1,78 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Run the full pre-commit suite (ruff, pyright, validate-pyproject, uv-lock,
+  # and the local pytest hook) exactly as developers do locally. Uses the
+  # committed uv.lock via --frozen, so any lockfile drift fails loudly.
+  pre-commit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 8
+    env:
+      # Uniform cache path across OSes so the actions/cache `path` below
+      # matches what conftest.py writes (it honors this env var via
+      # expanduser). Local dev uses the platform-canonical default instead.
+      JAX_COMPILATION_CACHE_DIR: ~/.cache/jax-compilation-cache
+    steps:
+      - uses: actions/checkout@main
+      - uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - name: Cache JAX compilations
+        uses: actions/cache@v5
+        with:
+          path: ~/.cache/jax-compilation-cache
+          key: jax-cc-precommit-py3.12-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            jax-cc-precommit-py3.12-
+      - run: uv run --frozen pre-commit run --all-files --show-diff-on-failure
+
+  # Portability matrix: prove the declared floors and the latest versions both
+  # work across the supported Python versions and operating systems. Each cell
+  # re-resolves dependencies directly from pyproject.toml (--no-project bypasses
+  # uv.lock), so the lowest-direct cell exercises the real lower bounds.
+  test:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 8
+    env:
+      JAX_COMPILATION_CACHE_DIR: ~/.cache/jax-compilation-cache
+      # Self-diagnosing safety net for hangs: dump all thread stacks on
+      # SIGABRT/crash, and log every JAX JIT compilation with its timing so a
+      # stuck job shows exactly which compile/test was in flight.
+      PYTHONFAULTHANDLER: "1"
+      JAX_LOG_COMPILES: "1"
+      # Disable BLAS threads for now because they have shown to cause deadlocks
+      # in our test suite.
+      OMP_NUM_THREADS: "1"
+      OPENBLAS_NUM_THREADS: "1"
+      MKL_NUM_THREADS: "1"
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.12", "3.13"]
+        resolution: [highest, lowest-direct]
+    steps:
+      - uses: actions/checkout@main
+      - uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python }}
+      - name: Cache JAX compilations
+        uses: actions/cache@v5
+        with:
+          path: ~/.cache/jax-compilation-cache
+          key: jax-cc-${{ runner.os }}-py${{ matrix.python }}-${{ matrix.resolution }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            jax-cc-${{ runner.os }}-py${{ matrix.python }}-${{ matrix.resolution }}-
+            jax-cc-${{ runner.os }}-py${{ matrix.python }}-
+      - run: uv run --no-project --with-editable . --with "pytest>=8.0" --with "pytest-timeout>=2.4" --python ${{ matrix.python }} --resolution ${{ matrix.resolution }} pytest --timeout=180 --timeout-method=thread -v --durations=20

toolsandogh-0.3.2/.github/workflows/release.yml

@@ -0,0 +1,60 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+# Never cancel an in-flight release; only one release per tag at a time.
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  # Build the sdist and wheel from the tagged commit. setuptools-scm derives
+  # the version from git, so a full history checkout is required.
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@main
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - run: uv build -o dist
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  # Publish to PyPI via Trusted Publishing (OIDC, no stored tokens) and create
+  # a GitHub Release with the built artifacts attached. Requires a one-time
+  # Trusted Publisher registration on pypi.org pointing at this workflow file
+  # (release.yml), the `pypi` environment, and this repository.
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    environment: pypi
+    permissions:
+      id-token: write   # PyPI Trusted Publishing (OIDC)
+      contents: write   # create GitHub Release
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          name: ${{ github.ref_name }}
+          generate_release_notes: true

{toolsandogh-0.2.0 → toolsandogh-0.3.2}/.gitignore

@@ -122,6 +122,9 @@ tmp/
 *.tsv
 *.parquet
 *.feather
+*.png
+*.jpg
+*.jpeg
 
 # Cache files generated by Dask (e.g., temporary spill to disk)
 .dask/

{toolsandogh-0.2.0 → toolsandogh-0.3.2}/.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v5.0.0
+  rev: v6.0.0
   hooks:
     - id: check-case-conflict
     - id: check-illegal-windows-names
@@ -12,39 +12,41 @@ repos:
     - id: check-added-large-files
 
 - repo: https://github.com/astral-sh/uv-pre-commit
-  rev: 0.9.5
+  rev: 0.11.26
   hooks:
     - id: uv-lock
 
-- repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.14.0
-  hooks:
-    - id: ruff-check
-      args: [ --fix ]
-    - id: ruff-format
-
-- repo: https://github.com/numpy/numpydoc
-  rev: v1.9.0
-  hooks:
-    - id: numpydoc-validation
-
 - repo: https://github.com/abravalheri/validate-pyproject
-  rev: v0.24.1
+  rev: v0.25
   hooks:
     - id: validate-pyproject
       additional_dependencies: ["validate-pyproject-schema-store[all]"]
 
-- repo: https://github.com/RobertCraigie/pyright-python
-  rev: v1.1.406
-  hooks:
-    - id: pyright
-
 - repo: local
   hooks:
-  - id: pytest
-    name: pytest
-    entry: uv run ./.venv/bin/pytest
-    language: system
-    types: [python]
-    pass_filenames: false
-    always_run: true
+    - id: ruff-check
+      name: ruff check
+      entry: uv run ruff check --fix --exit-non-zero-on-fix
+      language: system
+      types: [python]
+      require_serial: true
+    - id: ruff-format
+      name: ruff format
+      entry: uv run ruff format
+      language: system
+      types: [python]
+      require_serial: true
+    - id: pyright
+      name: pyright
+      entry: uv run pyright
+      language: system
+      types: [python]
+      pass_filenames: false
+      always_run: true
+    - id: pytest
+      name: pytest
+      entry: uv run pytest
+      language: system
+      types: [python]
+      pass_filenames: false
+      always_run: true

toolsandogh-0.3.2/DESIGN.md

@@ -0,0 +1,255 @@
+# Design & Architecture Overview for the toolsandogh package
+
+*Last updated: 2026-07-02*
+
+---
+
+## Project Overview
+
+toolsandogh is a Python library (>= 3.12) for processing large-scale scientific data sets (e.g., microscopy volumes, multi-modal imaging, high-throughput experiments).
+
+The library embraces **lazy, parallel computation** via Dask, **labeled, N-dimensional arrays** via xarray, and **type-safe, well-documented** code.
+
+### Demos
+
+Standalone demos live in the top-level `demos/` directory. They import `toolsandogh` and exercise its public API. Demos should keep dependencies to a minimum (ideally only the library itself plus a rendering backend like Matplotlib), so they remain runnable without pulling in heavy dev dependencies.
+
+---
+
+## Repository Layout
+
+```
+toolsandogh/
+|
+|-- DESIGN.md                 # <- THIS FILE (design & conventions)
+|-- README.md                 # User-oriented introduction, installation, examples
+|-- pyproject.toml            # Build system, metadata, dependencies, ruff config
+|-- .pre-commit-config.yaml   # Pre-commit hooks (ruff, isort, pyright, etc.)
+|-- .gitignore                # Files/folders that Git should ignore
+|-- uv.lock                   # Deterministic lockfile generated by uv
+|
+|-- demos/                    # Standalone demo scripts (import toolsandogh; keep deps light)
+|   `-- demo_iscat_50nm_bead.py
+|
+`-- src/
+    `-- toolsandogh/           # The actual Python package
+        |-- __init__.py
+        |-- _canonicalize_video.py  # All file names start with an underscore
+        |-- _generate_video.py
+        |-- _link.py
+        |-- _load_video.py
+        |-- _locate.py
+        |-- _rolling.py
+        |-- _rvt.py
+        |-- _simulate_particles.py
+        |-- _simulate_psf.py
+        |-- _store_video.py
+        |-- _validate_video.py
+        |
+        `-- tests/                # Tests for all toolsandogh functionality
+            |-- __init__.py
+            |-- conftest.py
+            |-- test_io.py
+            |-- test_link.py
+            |-- test_locate.py
+            |-- test_rolling.py
+            |-- test_simulate_particles.py
+            `-- test_simulate_psf.py
+```
+
+---
+
+## Coding Conventions
+
+### 1. Coding Guidelines
+
+The following guidelines apply to all code in the toolsandogh package. They are intended to keep the codebase consistent, readable, and easy to maintain for both human contributors and AI assistants. Where a guideline and a deadline conflict, correctness always wins.
+
+#### 1.1 Naming and module layout
+
+* Use ``snake_case`` for functions and variables, ``PascalCase`` for classes, and ``UPPER_CASE`` for module-level constants.
+* Every module file name starts with an underscore (e.g. ``_locate.py``). Modules are private by default; only objects explicitly re-exported from ``toolsandogh/__init__.py`` form the public API. Importing from a private module directly is unsupported and may break without notice.
+* New code should live in a new module when it addresses a distinct concern; otherwise it belongs in the existing module that covers the same concern. As a guideline rather than a hard rule, prefer one file per feature or workflow stage.
+
+#### 1.2 Type hints
+
+* All public functions, methods, and class attributes carry full type hints. Private helpers may omit them only when the annotation would be redundant with the surrounding context.
+* Hints should be as specific as possible without becoming brittle: prefer ``Literal["r", "w"]`` over ``str`` for closed sets of options; prefer concrete container types over bare ``Any``; avoid ``Optional`` where ``X | None`` reads more clearly.
+* Document variance explicitly when it matters (e.g., on protocols or abstract base classes).
+
+#### 1.3 Inputs and outputs
+
+* Publicly visible functions should be liberal in what they accept and conservative in what they emit.
+* Accept the widest reasonable input: file paths, raw arrays, tuples, or plain lists where convenient, and let the function coerce them into the canonical representation.
+* Always emit stable, well-typed values (typically ``xarray.DataArray`` or ``polars.DataFrame``). Do not leak implementation types such as NumPy arrays or pandas DataFrames through the public API.
+
+#### 1.4 Data structures
+
+* Array data is encoded as ``xarray.DataArray``, ideally lazily backed by Dask so that operations stay parallel and out-of-core.
+* Tabular data is encoded as ``polars.DataFrame``.
+
+#### 1.5 Simplicity
+
+* Prefer free functions over classes. Functionality should be provided mainly through free functions, with classes reserved for genuine stateful objects.
+* Each function should have one clear purpose that can be summed up in a single-line docstring. If a function's purpose resists a one-line summary, it is probably doing too much.
+* Keep classes small and focused. Prefer composition over inheritance.
+
+#### 1.6 Error handling
+
+* Raise specific, informative exceptions that explain what went wrong and why. Include the offending value where helpful.
+* Never silently coerce types or swallow exceptions. A bare ``except`` or an unchecked type coercion hides bugs and should be avoided.
+* Validate inputs at the boundary of the public API; prefer explicit checks over defensive programming scattered through the internals.
+
+### 2. Documentation -- numpydoc
+
+All public objects (functions, classes, methods) must be documented using the **numpydoc** style. This format is machine-parsable (e.g., for Sphinx) and familiar to scientific Python users.
+
+#### 2.1 Required and optional sections
+
+Every public docstring must contain the following sections **in this exact order**. Optional sections may be omitted when they carry no content, but if present they must appear at the position shown:
+
+1. **Short summary** -- a single, imperative line ending with a period. No blank line between the signature and the summary. Avoid restating the function name.
+2. *(blank line)*
+3. **Extended summary** -- one or more paragraphs giving context, assumptions, and edge cases. May be omitted if the short summary is self-explanatory.
+4. **Parameters** -- always present for any object that accepts arguments.
+5. **Returns** -- always present for any object that returns a value other than `None`.
+6. *(optional)* **Yields** -- for generators, instead of (not in addition to) **Returns**.
+7. *(optional)* **Raises** -- one ``exception_type`` per entry, followed by a description of the condition that triggers it. List every exception the function may raise intentionally.
+8. *(optional)* **Notes** -- implementation details, algorithmic notes, performance caveats, and limitations.
+9. *(optional)* **References** -- numbered citations using the ``.. [1]`` reST footnote syntax. Each reference is cited in the body text as ``[1]_``.
+10. *(optional)* **Examples** -- runnable code in doctest form.
+
+Do **not** invent sections outside this list (no *Todo*, no *Author*, no *Version*). Use the project changelog and metadata for that information.
+
+#### 2.2 Section headers
+
+Each section header is a single line of the form
+
+```rst
+Parameters
+----------
+```
+
+i.e. the title (capitalised as shown above, with the exact spelling and singular/plural form from the numpydoc spec) followed by a line of hyphens of matching length. Section titles are not underlined with ``=`` or ``~``. There is exactly one blank line before and after each header.
+
+#### 2.3 Parameters section
+
+* One entry per parameter, in the same order as the function signature.
+* Each entry begins with ``name`` followed by `` : `` and a type description, then a newline and an indented description.
+* The type uses the **runtime expression**, not the annotation verbatim: write ``int or tuple of int`` rather than ``int | tuple[int, ...]``. Reserved words ``True``, ``False``, ``None`` are written in full, not as types.
+* Append ``, optional`` to the type for any parameter that has a default value (including keyword-only and positional-or-keyword parameters with a default). Do **not** append it for required parameters, not even required keyword-only ones.
+* The description states the **default** in prose, e.g. "The default is ``3``." For boolean defaults, write the behaviour out: "If ``True`` (default), ...".
+* Parameters that accept ``*args`` / ``**kwargs`` are documented with the names ``*args`` and ``**kwargs`` respectively.
+
+#### 2.4 Returns section
+
+* For a single return value: a type line, then an indented description. Do not invent a name.
+* For multiple named return values (e.g. a ``NamedTuple``), document each component with its name, type, and description, mirroring the Parameters layout.
+* If the function returns `None` as a meaningful sentinel, document it. If it returns nothing, the **Returns** section is omitted entirely.
+
+#### 2.5 Types and type hints
+
+* Type hints live in the signature and should be as specific as possible. The docstring repeats the type in prose for the benefit of readers and Sphinx, but does not introduce new type information.
+* Use `Literal` types for closed sets of string options (e.g. ``Literal["r", "w"]``) and document the accepted values explicitly in the parameter description.
+* Write collection types out in prose (``list of str``) rather than ``list[str]`` in the docstring.
+
+#### 2.6 Cross-references and formatting
+
+* Use reST roles for cross-references: ``:func:`package.module.func``` for functions, ``:class:`package.module.Class``` for classes, ``:meth:`` for methods, ``:attr:`` for attributes, ``:mod:`` for modules. Always give the fully qualified path.
+* Inline code is written as double backticks (```` ``code`` ````), not single backticks.
+* Math may be written with ``:math:`expr``` inline or the ``.. math::`` directive for display equations.
+* Keep paragraphs wrapped at a reasonable column (around 79 characters) and separated by a single blank line.
+
+#### 2.7 Examples section
+
+* Examples use the doctest ``>>>`` prompt and must be **runnable** in isolation (all imports shown, no reliance on prior cells).
+* Prefer showing the expected output as a comment or repr block, so the example doubles as a regression test when run with ``pytest --doctest-modules``.
+* Avoid side effects that modify global state or the filesystem. Where unavoidable, clean up within the example.
+* Each example should illustrate one feature; do not bundle unrelated demonstrations.
+
+#### 2.8 Comprehensive example
+
+```python
+def median_filter(
+    data: xr.DataArray,
+    size: int | tuple[int, ...] = 3,
+    *,
+    preserve_nan: bool = True,
+) -> xr.DataArray:
+    """
+    Apply a median filter to an ``xarray.DataArray`` using a sliding window.
+
+    Parameters
+    ----------
+    data : xarray.DataArray
+        The input array.  The array can be lazily backed by Dask; the
+        operation will therefore be executed in parallel when the result
+        is computed.
+
+    size : int or tuple of int, optional
+        The size of the filtering window along each dimension.  If a
+        single integer is supplied it is used for all dimensions.  The
+        default is ``3`` (a 3x3x... window).
+
+    preserve_nan : bool, optional
+        If ``True`` (default), NaN values are ignored when computing the
+        median, i.e. they act as "missing data".  If ``False`` any window
+        containing a NaN will produce a NaN in the output.
+
+    Returns
+    -------
+    xarray.DataArray
+        A new ``DataArray`` with the same coordinates and attributes as
+        ``data`` but containing the filtered values.  The returned object
+        retains the original chunking layout, so the computation remains
+        lazy until ``compute()`` or ``persist()`` is called.
+
+    Notes
+    -----
+    * The implementation uses :func:`dask.array.map_overlap` under the
+      hood, which means that the filter works on arbitrarily large
+      datasets that do not fit into memory.
+    * For integer ``size`` values larger than the chunk size along a
+      dimension, the function will rechunk automatically.  This may
+      trigger a temporary increase in memory usage.
+
+    References
+    ----------
+    .. [1] J. R. Smith, *Median filtering of large image stacks*, J. Imaging,
+           2023, https://doi.org/10.1234/jim.2023.001
+
+    Examples
+    --------
+    >>> import xarray as xr, numpy as np
+    >>> arr = xr.DataArray(np.random.rand(100, 100), dims=('y', 'x'))
+    >>> filtered = median_filter(arr, size=5)
+    >>> filtered.compute()  # triggers Dask execution
+    <xarray.DataArray (y: 100, x: 100)>
+    """
+    # implementation follows ...
+```
+
+### 3. Testing
+
+Tests live in ``src/toolsandogh/tests/`` and use **pytest** as the sole test runner. The project keeps the testing story simple: plain pytest tests, no property-based testing frameworks, no separate test harnesses.
+
+#### 3.1 Test files and naming
+
+* One test file per feature or workflow stage under test (e.g. ``test_locate.py``, ``test_link.py``, ``test_io.py``), mirroring the module layout.
+* Test functions are named ``test_<unit>_<scenario>`` so that names describe what is being verified and under which conditions (e.g. ``test_locate_empty_image_returns_empty_dataframe``).
+* Shared fixtures live in ``conftest.py``; keep fixtures small, focused, and reusable across files.
+
+#### 3.2 Writing tests
+
+* Write tests that exercise correctness, not coverage numbers. Coverage is a useful signal but never a goal in itself: a passing test that proves the right behaviour is worth more than a percentage point.
+* Cover edge cases explicitly: empty arrays, single-element arrays, NaN inputs, mismatched shapes, and boundary conditions.
+* Prefer deterministic inputs. Where randomness is unavoidable, set a fixed seed within the test so that runs are reproducible.
+* Exercise both lazy and computed paths where relevant: assert that an operation returns a lazy result and that calling ``.compute()`` produces the expected values.
+
+#### 3.3 Doctests
+
+* Docstring examples (see section 2.7) double as regression tests when run with ``pytest --doctest-modules``. Keep them runnable in isolation and free of side effects that could break the suite.
+
+### 4. Linting
+
+Formatting and import style are enforced by **ruff**, configured in ``pyproject.toml``. In short: code must be free of pycodestyle and pyflakes errors and follow PEP-8, with imports sorted as with **isort**. Refer to the ruff configuration for the authoritative list of rules.

toolsandogh-0.3.2/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: toolsandogh
+Version: 0.3.2
+Summary: A collection of Python scripts for iSCAT microscopy data analysis
+Author-email: Marco Heisig <marco.heisig@mpl.mpg.de>
+License-Expression: GPL-3.0-or-later
+Project-URL: Repository, https://github.com/SandoghdarLab/toolsandogh
+Project-URL: Issues, https://github.com/SandoghdarLab/toolsandogh/issues
+Keywords: tools,utilities,python,microscopy
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bioio>=3.4
+Requires-Dist: bioio-dv>=1.2
+Requires-Dist: bioio-imageio>=1.3
+Requires-Dist: bioio-lif>=1.3
+Requires-Dist: bioio-nd2>=2.0
+Requires-Dist: bioio-ome-tiff>=1.4
+Requires-Dist: bioio-ome-zarr>=3.5
+Requires-Dist: bioio-tifffile>=1.3
+Requires-Dist: bioio-tiff-glob>=1.2
+Requires-Dist: dask>=2026.1
+Requires-Dist: fsspec>=2025.3
+Requires-Dist: imageio[ffmpeg]>=2.37
+Requires-Dist: imgrvt>=1.0
+Requires-Dist: jax>=0.10.2
+Requires-Dist: jaxtyping>=0.3
+Requires-Dist: numpy>=2.3
+Requires-Dist: ome-types>=0.6
+Requires-Dist: polars>=1.0
+Requires-Dist: pyarrow>=22.0
+Requires-Dist: scikit-image>=0.23
+Requires-Dist: scipy>=1.17
+Requires-Dist: tifffile>=2026.5
+Requires-Dist: tqdm>=4.66
+Requires-Dist: xarray>=2026.1
+Dynamic: license-file
+
+# toolsandogh
+
+A Python toolbox for iSCAT microscopy data analysis, developed by the Sandoghdar Division of the Max Planck Institute for the Science of Light (MPL).
+
+## Overview
+
+`toolsandogh` provides a small, reusable library for loading, processing, analyzing, and storing microscopy videos.  It is designed around a canonical 5D data model---`T` (time), `C` (channel), `Z` (slice), `Y` (row), `X` (column)---implemented as lazy [xarray](https://docs.xarray.dev/) arrays backed by [Dask](https://www.dask.org/).
+
+## Features
+
+- **Lazy, out-of-core computation**: Videos are kept as Dask arrays so you can work with datasets larger than memory.
+- **Labeled, metadata-rich arrays**: Results are `xarray.DataArray` objects with `TCZYX` dimensions and OME metadata.
+- **Multiple microscopy formats**: Read and write RAW/BIN, TIFF, OME-TIFF, OME-Zarr, ND2, and other formats supported by [bioio](https://github.com/bioio-devs/bioio).
+- **Reusable analysis primitives**: Rolling statistics, radial variance transform, synthetic data generation, and more.
+
+## Installation
+
+This project uses the [uv package manager](https://docs.astral.sh/uv/).  Clone the repository and run:
+
+```bash
+uv sync
+```
+
+To install in editable mode for development:
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+import toolsandogh as sand
+
+# Load a video (any bioio-supported format or raw BIN/RAW file).
+video = sand.load_video("movie.nd2")
+
+# Apply a rolling average along the time axis.
+smoothed = sand.rolling_average(video, window_size=5, dim="T")
+
+# Save the result back to disk.
+sand.store_video(smoothed, "smoothed.ome.tiff")
+```
+
+Use `help(sand.load_video)` or `help(sand.store_video)` for details on the available arguments.
+
+## Repository layout
+
+- `src/toolsandogh/` --- the main Python package.
+- `src/toolsandogh/tests/` --- `pytest` test suite.
+- `DESIGN.md` --- design conventions and coding standards.
+
+## Contributing
+
+Please see `DESIGN.md` for coding conventions, documentation standards, and architecture decisions.  In brief:
+
+- All public functions must be type-hinted and documented in numpydoc style.
+- Code is linted with `ruff` and type-checked with `pyright`.
+- Prefer free functions; keep data in `xarray.DataArray`/`Dataset` form.
+- Tests go in `src/toolsandogh/tests/`.
+
+## License
+
+GPL-3.0-or-later.

toolsandogh-0.3.2/README.md

@@ -0,0 +1,64 @@
+# toolsandogh
+
+A Python toolbox for iSCAT microscopy data analysis, developed by the Sandoghdar Division of the Max Planck Institute for the Science of Light (MPL).
+
+## Overview
+
+`toolsandogh` provides a small, reusable library for loading, processing, analyzing, and storing microscopy videos.  It is designed around a canonical 5D data model---`T` (time), `C` (channel), `Z` (slice), `Y` (row), `X` (column)---implemented as lazy [xarray](https://docs.xarray.dev/) arrays backed by [Dask](https://www.dask.org/).
+
+## Features
+
+- **Lazy, out-of-core computation**: Videos are kept as Dask arrays so you can work with datasets larger than memory.
+- **Labeled, metadata-rich arrays**: Results are `xarray.DataArray` objects with `TCZYX` dimensions and OME metadata.
+- **Multiple microscopy formats**: Read and write RAW/BIN, TIFF, OME-TIFF, OME-Zarr, ND2, and other formats supported by [bioio](https://github.com/bioio-devs/bioio).
+- **Reusable analysis primitives**: Rolling statistics, radial variance transform, synthetic data generation, and more.
+
+## Installation
+
+This project uses the [uv package manager](https://docs.astral.sh/uv/).  Clone the repository and run:
+
+```bash
+uv sync
+```
+
+To install in editable mode for development:
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+import toolsandogh as sand
+
+# Load a video (any bioio-supported format or raw BIN/RAW file).
+video = sand.load_video("movie.nd2")
+
+# Apply a rolling average along the time axis.
+smoothed = sand.rolling_average(video, window_size=5, dim="T")
+
+# Save the result back to disk.
+sand.store_video(smoothed, "smoothed.ome.tiff")
+```
+
+Use `help(sand.load_video)` or `help(sand.store_video)` for details on the available arguments.
+
+## Repository layout
+
+- `src/toolsandogh/` --- the main Python package.
+- `src/toolsandogh/tests/` --- `pytest` test suite.
+- `DESIGN.md` --- design conventions and coding standards.
+
+## Contributing
+
+Please see `DESIGN.md` for coding conventions, documentation standards, and architecture decisions.  In brief:
+
+- All public functions must be type-hinted and documented in numpydoc style.
+- Code is linted with `ruff` and type-checked with `pyright`.
+- Prefer free functions; keep data in `xarray.DataArray`/`Dataset` form.
+- Tests go in `src/toolsandogh/tests/`.
+
+## License
+
+GPL-3.0-or-later.