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

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

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

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, 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.