spatiato 0.2.0__tar.gz

spatiato-0.2.0/.claude/settings.json

@@ -0,0 +1,42 @@
+{
+  "env": {
+    "UV_PROJECT_ENVIRONMENT": ".venv",
+    "PYTHONUNBUFFERED": "1",
+    "PYTHONPYCACHEPREFIX": ".cache/claude/pycache",
+    "XDG_CACHE_HOME": ".cache/claude",
+    "PIP_CACHE_DIR": ".cache/claude/pip",
+    "UV_CACHE_DIR": ".cache/claude/uv",
+    "MPLCONFIGDIR": ".cache/claude/matplotlib",
+    "RUFF_CACHE_DIR": ".cache/claude/ruff_cache"
+  },
+  "permissions": {
+    "allow": [
+      "Bash(source .venv/bin/activate)",
+      "Bash(.venv/bin/pytest:*)",
+      "Bash(.venv/bin/ruff:*)",
+      "Bash(.venv/bin/python:*)",
+      "Bash(.venv/bin/python3:*)",
+      "Bash(.venv/bin/pre-commit run:*)",
+      "Bash(pytest:*)",
+      "Bash(ruff:*)",
+      "Bash(pre-commit run:*)",
+      "Bash(python:*)",
+      "Bash(python3:*)",
+      "Bash(git status)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git show:*)",
+      "Bash(git branch:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(grep:*)",
+      "Bash(rg:*)",
+      "Bash(find:*)",
+      "Bash(shasum *)"
+    ],
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)"
+    ]
+  }
+}

spatiato-0.2.0/.github/workflows/release.yaml

@@ -0,0 +1,39 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+defaults:
+  run:
+    # Fail on errors in multiline statements (-e), pipes (-o pipefail), and unset variables (-u).
+    shell: bash -euo pipefail {0}
+
+# Uses PyPI trusted publishing:
+# https://docs.pypi.org/trusted-publishers/
+jobs:
+  release:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/spatiato
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          filter: blob:none
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          cache-dependency-glob: pyproject.toml
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

spatiato-0.2.0/.gitignore

@@ -0,0 +1,129 @@
+# Custom
+scripts/code_ownership.py
+configs/allocate/*
+configs/annotate/*
+configs/clean/*
+configs/dataset/*
+configs/experiment/*
+configs/local/*
+configs/segmentation/*
+configs/visualize/*
+data
+spatial
+logs
+.env
+.autoenv
+
+notebooks
+
+# Add exection for example configs for resolve and vizgen
+!configs/allocate/resolve_liver.yaml
+!configs/allocate/vizgen_example.yaml
+!configs/annotate/resolve_liver.yaml
+!configs/clean/resolve_liver.yaml
+!configs/clean/vizgen_example.yaml
+!configs/dataset/resolve_liver.yaml
+!configs/dataset/resolve_liver_2.yaml
+!configs/dataset/vizgen_example.yaml
+!configs/experiment/resolve_liver.yaml
+!configs/experiment/vizgen_example.yaml
+!configs/local/default.example.yaml
+!configs/segmentation/cellpose_resolve_liver.yaml
+!configs/segmentation/cellpose_vizgen_example.yaml
+!configs/visualize/resolve_liver.yaml
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+.napari_cache
+.codex
+.codex-home/
+.claude/*
+!.claude/settings.json
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask instance folder
+instance/
+
+# Sphinx documentation
+/docs/generated/
+/docs/_build/
+
+# MkDocs documentation
+/site/
+
+# PyBuilder
+target/
+
+# Pycharm and VSCode
+.idea/
+venv/
+.vscode/
+.venv/
+
+# IPython Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# OS
+.DS_Store
+
+# written by setuptools_scm
+**/_version.py
+
+# asv benchmarks
+.asv/**
+
+agents.md

spatiato-0.2.0/AGENTS.md

@@ -0,0 +1,44 @@
+## Python environment
+Canonical environment: `.venv`
+
+Run Python, tests, lint, and tooling by calling the environment's binaries directly via
+their `.venv/bin/` path.
+
+```bash
+.venv/bin/pytest
+.venv/bin/python -m pytest
+.venv/bin/pre-commit run ruff --all-files
+```
+
+## Test scope
+
+Run only the focused unit tests directly affected by a change.
+
+Do not run the full test suite by default. Run it only when:
+- the user explicitly requests it; or
+- the change is sufficiently broad that focused tests cannot provide reasonable coverage, in which case ask the user first.
+
+Prefer focused commands such as:
+
+```bash
+.venv/bin/pytest -q path/to/test_module.py
+.venv/bin/pytest -q path/to/test_module.py::test_specific_behavior
+```
+
+Run linting only on the changed or directly affected files where possible.
+
+## Code explanation references
+
+When explaining or reviewing repository code:
+
+- Include clickable Markdown links with the exact current line number for the functions, branches, and call sites central to the explanation.
+- For event flows, link each material step to its implementation rather than linking only the containing class or module.
+- Re-check line numbers against the current working tree immediately before responding because edits may move them.
+- Use absolute paths with one starting line, not line ranges.
+- Do not overload explanations with links to incidental symbols.
+
+## Codex config
+Repository-local Codex settings for this project live in `.codex/config.toml`.
+
+When checking or updating Codex sandbox, cache, approval, or environment settings for this repo,
+use `.codex/config.toml` first rather than `~/.codex/config.toml`.

spatiato-0.2.0/CLAUDE.md

@@ -0,0 +1,18 @@
+## Python environment
+Canonical environment: `.venv`. Use it as-is — do NOT sync, update, or install
+into it (e.g. no `uv sync`/`uv run`); the maintainer manages env updates manually.
+
+Run Python, tests, lint, and tooling by calling the environment's binaries directly via
+their `.venv/bin/` path.
+
+```bash
+.venv/bin/pytest
+.venv/bin/python -m pytest
+.venv/bin/pre-commit run ruff --all-files
+```
+
+## Claude config
+Repository-local Claude Code settings for this project live in `.claude/settings.json`.
+
+When checking or updating Claude cache, permission, or environment settings for this repo,
+use `.claude/settings.json` first rather than `~/.claude/settings.json`.

spatiato-0.2.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, VIB spatial catalyst
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. 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.
+
+3. Neither the name of the copyright holder 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.

spatiato-0.2.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.5
+Name: spatiato
+Version: 0.2.0
+Summary: A spatial omics interface for napari.
+Project-URL: Homepage, https://github.com/vibspatial/spatiato
+Project-URL: Documentation, https://github.com/vibspatial/spatiato#readme
+Project-URL: Repository, https://github.com/vibspatial/spatiato
+Project-URL: Issues, https://github.com/vibspatial/spatiato/issues
+Project-URL: Changelog, https://github.com/vibspatial/spatiato/releases
+Project-URL: Paper, https://doi.org/10.1093/bioinformatics/btag122
+Project-URL: SaeysLab, https://saeyslab.sites.vib.be/en
+Project-URL: VIBSpatialCatalyst, https://vib.be/en/technologies/technology-portfolio/spatial-catalyst
+Author: VIB spatial catalyst
+License: BSD 3-Clause License
+        
+        Copyright (c) 2026, VIB spatial catalyst
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. 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.
+        
+        3. Neither the name of the copyright holder 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.
+License-File: LICENSE
+Keywords: anndata,image-analysis,napari,object-classification,plugin,spatialdata
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: napari
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: <3.15,>=3.12
+Requires-Dist: dask[dataframe]
+Requires-Dist: filelock>=3.20.1
+Requires-Dist: harpy-analysis>=0.4.4
+Requires-Dist: joblib
+Requires-Dist: lazy-loader>=0.4
+Requires-Dist: loguru
+Requires-Dist: napari[all]>=0.4.18
+Requires-Dist: pandas<3.0
+Requires-Dist: pyarrow
+Requires-Dist: pyqtgraph>=0.13.7
+Requires-Dist: spatialdata>=0.7.2
+Provides-Extra: dev
+Requires-Dist: myst-nb; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest-qt; extra == 'dev'
+Requires-Dist: pytest-xdist; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: sphinx-autodoc-typehints; extra == 'dev'
+Requires-Dist: sphinx-book-theme>=1.0.0; extra == 'dev'
+Requires-Dist: sphinx-copybutton; extra == 'dev'
+Requires-Dist: sphinx-design; extra == 'dev'
+Requires-Dist: sphinx-rtd-theme; extra == 'dev'
+Requires-Dist: sphinx>=4.5; extra == 'dev'
+Requires-Dist: sphinxcontrib-bibtex>=1.0.0; extra == 'dev'
+Requires-Dist: torchvision; extra == 'dev'
+Requires-Dist: tox; extra == 'dev'
+Requires-Dist: twine>=4.0.2; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: myst-nb; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints; extra == 'docs'
+Requires-Dist: sphinx-book-theme>=1.0.0; extra == 'docs'
+Requires-Dist: sphinx-copybutton; extra == 'docs'
+Requires-Dist: sphinx-design; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme; extra == 'docs'
+Requires-Dist: sphinx>=4.5; extra == 'docs'
+Requires-Dist: sphinxcontrib-bibtex>=1.0.0; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: pytest-qt; extra == 'test'
+Requires-Dist: pytest-xdist; extra == 'test'
+Requires-Dist: tox; extra == 'test'
+Provides-Extra: torch
+Requires-Dist: torchvision; extra == 'torch'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/vibspatial/spatiato/main/src/spatiato/_static/logo.svg" alt="Spatiato logo" width="400">
+</p>
+
+<h1 align="center">spatiato: a spatial omics interface for napari.</h1>
+
+[![PyPI](https://img.shields.io/pypi/v/spatiato.svg)](https://pypi.org/project/spatiato/)
+
+Built around [`SpatialData`](https://spatialdata.scverse.org/en/stable/) and [`Harpy`](https://harpy.readthedocs.io/en/latest/) for interactive exploration, feature extraction, and object classification.
+
+`spatiato` is a napari plugin for viewing, exploring, and analyzing
+`SpatialData` datasets. It includes its own viewer for loading and
+browsing data inside napari, alongside annotation, feature extraction, and
+interactive object classification workflows.
+
+## Installation
+
+Install from [PyPI](https://pypi.org/project/spatiato/):
+
+```bash
+pip install spatiato
+```
+
+## Quickstart
+
+The quickest way to try the plugin is to create a small example `SpatialData`
+object, write it to a temporary zarr store, read it back as an on-disk dataset,
+and launch the Spatiato napari interface with `Interactive`.
+
+```python
+import tempfile
+from pathlib import Path
+
+from spatialdata import read_zarr
+
+from spatiato import Interactive
+from spatiato.datasets import blobs_multi_region
+
+zarr_path = Path(tempfile.mkdtemp()) / "blobs_multi_region.zarr"
+
+sdata = blobs_multi_region()
+sdata.write(zarr_path)
+
+sdata = read_zarr(zarr_path)
+Interactive(sdata)
+```
+
+This opens napari with the Spatiato widgets docked and the
+`blobs_multi_region` dataset available in the shared viewer state.
+Shapes triangulation uses the fast Bermuda backend by default. To use Numba
+instead, launch with `Interactive(sdata, triangulation_backend="numba")`.
+
+The current repository contains four working widgets:
+
+- `Viewer`
+- `Feature Extraction`
+- `Object Classification`
+- `Annotation`
+
+Today the plugin supports:
+
+- loading and viewing `SpatialData` through the Spatiato viewer widget
+- selecting a labels element, optional image, compatible coordinate system, and
+  linked table from the shared loaded `SpatialData`
+- calculating intensity and morphology features through Harpy
+- writing feature matrices into the selected `AnnData` table linked to the
+  labels element, as `.obsm[feature_key]`, with companion metadata in
+  `.uns["feature_matrices"][feature_key]`
+- interactive manual annotation of instances in labels elements
+- interactive creation and editing of polygon shapes annotations
+- background `RandomForestClassifier` retraining on the selected feature
+  matrix stored in `.obsm[feature_key]` of the `AnnData` table linked to the
+  labels element
+- live prediction updates and labels recoloring
+- explicit write-back of in-memory table state to zarr
+- explicit reload of on-disk table state back into memory
+- multi-sample workflows through multi-region tables and explicit
+  labels/image/coordinate-system matching
+- headless feature extraction and classifier application for scripted or batch
+  processing
+
+Example spatiato session:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/vibspatial/spatiato/main/docs/_static/viewer.png" alt="spatiato viewer example screenshot" width="900">
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/vibspatial/spatiato/main/docs/_static/object_classification.png" alt="spatiato object classification example screenshot" width="900">
+</p>
+
+## Headless and Multi-Sample Workflows
+
+For scripted or batch processing, use the public `spatiato.headless` module.
+It can apply an exported classifier to an existing feature matrix, or compute
+the required features before applying the classifier.
+
+The headless APIs accept one labels element or a sequence of labels elements.
+For multi-sample data, pass matching labels, image, and coordinate-system
+sequences so Harpy can build or apply a shared table-level feature matrix across
+the selected samples. When features need image intensities, the channel
+selection is read from the exported classifier's `source_channels` metadata.
+
+```python
+from spatialdata import read_zarr
+
+from spatiato import headless
+
+sdata = read_zarr("experiment.zarr")
+
+result = headless.apply_classifier_with_feature_extraction_from_path(
+    sdata,
+    "classifier.spatiato-classifier.joblib",
+    table_name="table_multi",
+    labels_name=["sample_1_labels", "sample_2_labels"],
+    coordinate_system=["sample_1", "sample_2"],
+    image_name=["sample_1_image", "sample_2_image"],
+)
+```
+
+## Local development
+
+Create the development environment:
+
+```bash
+./create_env.sh
+```
+
+Then launch napari:
+
+```bash
+source .venv/bin/activate
+napari
+```
+
+Open the widgets from the napari plugin menu:
+
+- `Plugins -> spatiato -> Viewer`
+- `Plugins -> spatiato -> Feature Extraction`
+- `Plugins -> spatiato -> Object Classification`
+- `Plugins -> spatiato -> Annotation`
+
+### Optional real-OpenGL renderer qualification
+
+The tiled-points renderer includes one opt-in real-canvas qualification test at
+[`tests/viewer/tiled_points/vispy/test_real_canvas.py`](tests/viewer/tiled_points/vispy/test_real_canvas.py).
+It is skipped during ordinary test runs because it requires a working
+Qt, VisPy, and OpenGL environment. Run it explicitly with:
+
+```bash
+SPATIATO_RUN_REAL_GL_TESTS=1 \
+.venv/bin/pytest -q tests/viewer/tiled_points/vispy/test_real_canvas.py
+```
+
+The focused renderer unit tests remain part of ordinary test runs; this
+additional qualification creates a real canvas, compiles and executes the
+custom shaders, and compares the framebuffer result with standard VisPy
+markers.
+
+## Debug script
+
+A small local debug script is available at
+[`scripts/debug_widget.py`](scripts/debug_widget.py).
+
+It creates a temporary `blobs_multi_region` zarr store, loads it into napari,
+and docks the Spatiato widgets automatically.
+This is useful for quickly reproducing widget behavior during development.
+
+Run it with:
+
+```bash
+source .venv/bin/activate
+python scripts/debug_widget.py
+```