auroraomics 0.1.0.dev0__tar.gz

auroraomics-0.1.0.dev0/LICENSE

@@ -0,0 +1,131 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Kalin Nonchev / ETH Zurich (https://github.com/ratschlab/DeepSpotM)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

auroraomics-0.1.0.dev0/MANIFEST.in

@@ -0,0 +1,7 @@
+# The published source distribution carries the package and its metadata, and
+# nothing else. The tests only mean anything next to the checkout that defines
+# the contracts — from an unpacked distribution they would skip — and every
+# file that ships is a file the boundary guards have to keep clean forever.
+# Smaller surface, same package. (The release scripts are outside the sdist's
+# source list already, so they need no rule here.)
+prune tests

auroraomics-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: auroraomics
+Version: 0.1.0.dev0
+Summary: Virtual spatial transcriptomics from H&E histology: patch QC, tile packing and the .h5ad result contract.
+Author: Kalin Nonchev
+License-Expression: PolyForm-Noncommercial-1.0.0
+Keywords: histopathology,spatial-transcriptomics,h5ad,anndata,whole-slide-image
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: h5py>=3.9
+Requires-Dist: opencv-python-headless>=4.5
+Requires-Dist: pillow>=9
+Provides-Extra: client
+Requires-Dist: httpx>=0.27; extra == "client"
+Requires-Dist: pydantic>=2; extra == "client"
+Requires-Dist: anndata>=0.10; extra == "client"
+Provides-Extra: deepspotm
+Provides-Extra: slide
+Requires-Dist: tifffile>=2023.7.10; extra == "slide"
+Requires-Dist: imagecodecs>=2023.3.16; extra == "slide"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: setuptools>=77; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: anndata<0.12,>=0.10; extra == "dev"
+Requires-Dist: tifffile>=2023.7.10; extra == "dev"
+Requires-Dist: imagecodecs>=2023.3.16; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: numpy<2; extra == "dev"
+Dynamic: license-file
+
+# auroraomics
+
+Virtual spatial transcriptomics from H&E histology.
+
+This package holds the pieces of that pipeline that are pure Python, so the
+same code runs on your laptop, in a GPU container and on the service:
+
+- **`auroraomics.qc`** — the three patch-quality predicates (foreground, blur,
+  stained tissue) applied to every candidate tile before a model sees it, and
+  the short-circuiting cascade that combines them.
+- **`auroraomics.pack`** — build the `patches` archive a prediction takes as
+  input (`pack_tiles`), and validate one you have been handed (`read_archive`).
+- **`auroraomics.h5ad`** — write the standard `.h5ad` result with `h5py`
+  alone, streaming the expression matrix batch by batch so peak memory is one
+  batch rather than the whole matrix.
+- **`auroraomics.subsample`** — pick the densest contiguous square of spots
+  when a slide yields more tiles than a run is allowed to spend.
+- **`auroraomics.contracts`** — the shared contract values (container layout,
+  input-kind caps, result layout) as data, so nothing here re-types a number
+  the service also reads.
+
+## Install
+
+```
+pip install auroraomics
+```
+
+The core needs only numpy, h5py, OpenCV and Pillow. Extras add the API client
+(`client`), a local model runtime (`deepspotm`) and pyramidal slide reading
+(`slide`).
+
+## Pack tiles, then look at the report
+
+```python
+import auroraomics as ao
+
+report = ao.pack_tiles(tiles, "sample.zip", mpp=0.499, thumbnail=thumb)
+print(report.written, "tiles kept,", report.rejected, "dropped")
+print(report.rejected_by_reason)          # {'foreground_ratio': 12, ...}
+```
+
+`tiles` is any iterable of `ao.Tile(image, x, y)`, where `image` is an RGB
+`uint8` array and `x`/`y` are the tile's top-left position in full-resolution
+pixels. Tiles are quality-checked as they stream past, and only the ones that
+pass are written, so an iterable that reads a slide lazily never has to hold
+more than one tile in memory.
+
+## Validate an archive before trusting it
+
+```python
+archive = ao.read_archive("sample.zip")   # raises ArchiveError on anything odd
+for tile in archive.tiles():              # decoded one at a time
+    ...
+```
+
+`read_archive` checks the member names, the manifest, the tile geometry and the
+declared sizes *before* decoding a single pixel, and refuses an archive whose
+members do not match the container contract.
+
+## Write a result
+
+```python
+ao.write_result(
+    "result.h5ad",
+    obs=obs,                    # per-spot columns, as plain arrays
+    var=var,                    # per-gene columns, indexed by gene id
+    spatial=coords,             # (n_spots, 2) array -> obsm["spatial"]
+    x=batches,                  # an array, or an iterable of row batches
+    uns={"model": {"id": "..."}},
+    layers={"image_only": other_batches},
+)
+```
+
+The file reads back as an ordinary `AnnData` in anndata 0.10 and 0.11. Passing
+an iterable for `x` streams it: each batch is compressed into the file as it
+arrives and then dropped, which is what makes a matrix larger than memory
+writable.
+
+## Typing
+
+The package ships `py.typed`, so annotations are visible to type checkers in
+your project.
+
+## Licence
+
+The code in this package is licensed under
+[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0),
+which permits use for any purpose that is not commercial. It is the same licence the
+model package this client is built for carries, so installing both puts you under one
+rule rather than two.
+
+The model weights are licensed separately by whoever publishes them, and access to them
+may be gated. Read those terms before you use a model: they are not this licence, and a
+permission granted here is not a permission granted there.
+

auroraomics-0.1.0.dev0/README.md

@@ -0,0 +1,95 @@
+# auroraomics
+
+Virtual spatial transcriptomics from H&E histology.
+
+This package holds the pieces of that pipeline that are pure Python, so the
+same code runs on your laptop, in a GPU container and on the service:
+
+- **`auroraomics.qc`** — the three patch-quality predicates (foreground, blur,
+  stained tissue) applied to every candidate tile before a model sees it, and
+  the short-circuiting cascade that combines them.
+- **`auroraomics.pack`** — build the `patches` archive a prediction takes as
+  input (`pack_tiles`), and validate one you have been handed (`read_archive`).
+- **`auroraomics.h5ad`** — write the standard `.h5ad` result with `h5py`
+  alone, streaming the expression matrix batch by batch so peak memory is one
+  batch rather than the whole matrix.
+- **`auroraomics.subsample`** — pick the densest contiguous square of spots
+  when a slide yields more tiles than a run is allowed to spend.
+- **`auroraomics.contracts`** — the shared contract values (container layout,
+  input-kind caps, result layout) as data, so nothing here re-types a number
+  the service also reads.
+
+## Install
+
+```
+pip install auroraomics
+```
+
+The core needs only numpy, h5py, OpenCV and Pillow. Extras add the API client
+(`client`), a local model runtime (`deepspotm`) and pyramidal slide reading
+(`slide`).
+
+## Pack tiles, then look at the report
+
+```python
+import auroraomics as ao
+
+report = ao.pack_tiles(tiles, "sample.zip", mpp=0.499, thumbnail=thumb)
+print(report.written, "tiles kept,", report.rejected, "dropped")
+print(report.rejected_by_reason)          # {'foreground_ratio': 12, ...}
+```
+
+`tiles` is any iterable of `ao.Tile(image, x, y)`, where `image` is an RGB
+`uint8` array and `x`/`y` are the tile's top-left position in full-resolution
+pixels. Tiles are quality-checked as they stream past, and only the ones that
+pass are written, so an iterable that reads a slide lazily never has to hold
+more than one tile in memory.
+
+## Validate an archive before trusting it
+
+```python
+archive = ao.read_archive("sample.zip")   # raises ArchiveError on anything odd
+for tile in archive.tiles():              # decoded one at a time
+    ...
+```
+
+`read_archive` checks the member names, the manifest, the tile geometry and the
+declared sizes *before* decoding a single pixel, and refuses an archive whose
+members do not match the container contract.
+
+## Write a result
+
+```python
+ao.write_result(
+    "result.h5ad",
+    obs=obs,                    # per-spot columns, as plain arrays
+    var=var,                    # per-gene columns, indexed by gene id
+    spatial=coords,             # (n_spots, 2) array -> obsm["spatial"]
+    x=batches,                  # an array, or an iterable of row batches
+    uns={"model": {"id": "..."}},
+    layers={"image_only": other_batches},
+)
+```
+
+The file reads back as an ordinary `AnnData` in anndata 0.10 and 0.11. Passing
+an iterable for `x` streams it: each batch is compressed into the file as it
+arrives and then dropped, which is what makes a matrix larger than memory
+writable.
+
+## Typing
+
+The package ships `py.typed`, so annotations are visible to type checkers in
+your project.
+
+## Licence
+
+The code in this package is licensed under
+[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0),
+which permits use for any purpose that is not commercial. It is the same licence the
+model package this client is built for carries, so installing both puts you under one
+rule rather than two.
+
+The model weights are licensed separately by whoever publishes them, and access to them
+may be gated. Read those terms before you use a model: they are not this licence, and a
+permission granted here is not a permission granted there.
+

auroraomics-0.1.0.dev0/pyproject.toml

@@ -0,0 +1,91 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "auroraomics"
+version = "0.1.0.dev0"
+description = "Virtual spatial transcriptomics from H&E histology: patch QC, tile packing and the .h5ad result contract."
+readme = "README.md"
+requires-python = ">=3.10"
+# Non-commercial, and the same licence as the model package this client is built
+# for, so a user installing both faces one rule rather than two. PEP 639 forbids
+# a licence CLASSIFIER beside an expression, so this line is the whole
+# declaration; the model weights carry their own separate terms.
+license = "PolyForm-Noncommercial-1.0.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Kalin Nonchev" }]
+keywords = ["histopathology", "spatial-transcriptomics", "h5ad", "anndata", "whole-slide-image"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "Typing :: Typed",
+]
+
+# The CORE runtime, and nothing else. These four are what the modules in this
+# distribution actually import at run time, and they are deliberately the set a
+# GPU pipeline image can already satisfy: no torch, no pandas, no anndata, no
+# slide reader. Anything heavier belongs in an extra, so a user who only wants
+# to pack tiles or read a result never pays for a runtime they will not run.
+dependencies = [
+  "numpy>=1.23",
+  "h5py>=3.9",
+  "opencv-python-headless>=4.5",
+  "pillow>=9",
+]
+
+[project.optional-dependencies]
+# The API client. Declared here so the install line in the documentation is
+# stable from the first release; the code that imports these lands with it.
+client = ["httpx>=0.27", "pydantic>=2", "anndata>=0.10"]
+# The local model runtime. Intentionally EMPTY, not a guess: pinning a package
+# that nothing in this distribution imports would install weight-bearing
+# dependencies for dead code. The pin arrives in the same change as the
+# runtime that imports it, so `pip install "auroraomics[deepspotm]"` never
+# means something different from what the package can do.
+deepspotm = []
+# Reading pyramidal slide formats, for callers who want this package to cut
+# their tiles rather than handing it tiles they cut themselves.
+slide = ["tifffile>=2023.7.10", "imagecodecs>=2023.3.16"]
+# The test environment. anndata is a TEST dependency on purpose: it is the
+# reader whose behaviour the h5py-only writer is held to, and depending on it
+# at run time would put pandas and its stack into every install.
+#
+# numpy<2 is not a preference. This package is installed into image builds
+# whose compiled stack is ABI-pinned to the numpy 1.x series, so the suite has
+# to pass on the numpy those images resolve — a test matrix that only ever ran
+# on 2.x would go green here and fail where the code actually runs.
+dev = [
+  "pytest>=7",
+  # setuptools and wheel are TEST dependencies as well as build ones: the
+  # release guard builds with --no-isolation so that it needs no network, and
+  # a virtual environment on a recent Python ships neither by default. Without
+  # them the guard cannot build the thing it is meant to check.
+  "setuptools>=77",
+  "wheel",
+  "anndata>=0.10,<0.12",
+  "tifffile>=2023.7.10",
+  "imagecodecs>=2023.3.16",
+  "build>=1.0",
+  "numpy<2",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# py.typed makes the annotations visible to a type checker in a consuming
+# project; the vendored contract JSON is data the package reads at import, so
+# both have to be in the wheel. The two glob depths are spelled out rather than
+# using `**`, which older setuptools does not expand in package-data.
+[tool.setuptools.package-data]
+auroraomics = ["py.typed", "_contracts/*.json", "_contracts/*/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q --strict-markers"

auroraomics-0.1.0.dev0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

auroraomics-0.1.0.dev0/src/auroraomics/__init__.py

@@ -0,0 +1,74 @@
+"""Virtual spatial transcriptomics from H&E histology.
+
+The pieces of that pipeline that are pure Python live here, so the same code
+runs on a laptop, inside a GPU image and on the hosted service:
+
+* :mod:`auroraomics.qc` — the three patch-quality predicates and the cascade
+  that decides which tiles are worth predicting on.
+* :mod:`auroraomics.pack` — build the ``patches`` archive a prediction takes
+  (:func:`pack_tiles`), and validate one before trusting it
+  (:func:`read_archive`).
+* :mod:`auroraomics.h5ad` — write the standard result file with ``h5py``
+  alone, streaming the matrix so peak memory is one batch.
+* :mod:`auroraomics.subsample` — choose the densest contiguous square when a
+  slide yields more tiles than a run may spend.
+* :mod:`auroraomics.contracts` — the shared contract values, as data.
+
+Nothing here reaches the network, and nothing here sends anything anywhere.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .h5ad import ResultError, write_result
+from .pack import (
+    ArchiveError,
+    ArchiveRow,
+    PackError,
+    PackReport,
+    PatchArchive,
+    Rejection,
+    Tile,
+    pack_tiles,
+    read_archive,
+)
+from .qc import (
+    QcResult,
+    QcThresholds,
+    blur_filter,
+    foreground_mask,
+    hsv_filter,
+    qc_tile,
+)
+from .subsample import subsample_spatial_square
+
+try:
+    # One source for the version: the installed distribution metadata, which
+    # the build fills in from the project file. A string spelled here as well
+    # would be the copy that goes stale.
+    __version__ = version("auroraomics")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0+unknown"
+
+__all__ = [
+    "ArchiveError",
+    "ArchiveRow",
+    "PackError",
+    "PackReport",
+    "PatchArchive",
+    "QcResult",
+    "QcThresholds",
+    "Rejection",
+    "ResultError",
+    "Tile",
+    "__version__",
+    "blur_filter",
+    "foreground_mask",
+    "hsv_filter",
+    "pack_tiles",
+    "qc_tile",
+    "read_archive",
+    "subsample_spatial_square",
+    "write_result",
+]

auroraomics-0.1.0.dev0/src/auroraomics/_contracts/MANIFEST.json

@@ -0,0 +1,11 @@
+{
+  "_comment": "Contract documents vendored into this package, with the sha256 of each. Generated - do not edit by hand.",
+  "files": {
+    "genes/gene-table.2026-09-05.json": "0dbf97f69b37e4fdb1a13e5c05088c717f8f6cec7fb04c49a4987f8c6495a5c9",
+    "public-api-counters.tokens.json": "82544d49ca90897172ad5064daae45008175fc7152b8ead6411b49408df9979d",
+    "public-api-input-kinds.tokens.json": "654b45f740485ac6e77bd3fc8fd0e91b7453da38c445b37af460bda280351158",
+    "public-api.tokens.json": "a77e48b6aaed8ee4020fbfd99796dbfb6dd818ca6fb01c9e2102b4f4a07a3ce7",
+    "public-api/golden-16-tiles.manifest.json": "2d93fbfd2aa4542cc75d0c2dea34f199c6cf87f5123201f952b58de4b7d14094",
+    "qc-thresholds.tokens.json": "d65de3c306d75ab6588a3a13fedfe2e562c84e12921ebee08f810cd8b0b9ae47"
+  }
+}