Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

auroraomics

Virtual spatial transcriptomics from H&E images.

This package is the client of the Aurora API, the hosted service that runs the prediction: from Python, from a shell with the auroraomics command, or from an agent through its MCP server.

This package holds the pieces of that pipeline that are pure Python, so the same code runs on your machine 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.postprocess — apply a model card's postprocess entries to a result file: a registry of entries, one runner, h5py alone, streaming one chunk at a time. Ships the unmeasured-gene mask, which blanks the genes the model never measured.
  • auroraomics.subsample — pick the densest contiguous square of spots when a slide yields more tiles than one submission takes.
  • auroraomics.genes — Ensembl stable gene ids, which is what every result's var index is keyed by, and the shape a gene the service resolved comes back in.
  • 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.
  • auroraomics.export — write a result as a SpatialData Zarr store (extra) or as a folder Seurat loads, with the same matrix, coordinates and gene names as the .h5ad.
  • auroraomics.embed (extra) — run a pinned image encoder over your tiles locally and write the embeddings container, so a prediction can be made from numbers instead of pixels.

One module describes work that does not happen here:

  • auroraomics.runtimes.deepspotm — the models the service will run, as data: what each one accepts, what it returns, and whether an archive matches it. There is no install that makes one of them run locally; the definition is not distributed, and predict_local refuses and says where prediction happens.

Install

pip install auroraomics

That is the whole documented path: open a slide, judge and pack its tiles, submit, and read the result. One extra adds local embedding extraction (embed), and one writes a result as a SpatialData store (spatialdata). No extra brings the model: predicting gene expression runs on the service, not here.

Pack tiles, then look at the report

import auroraomics as ao

with ao.Client() as client:
    thresholds = client.qc_thresholds()   # the service's quality floors, no key needed

report = ao.pack_tiles(tiles, "sample.zip", mpp=0.499, thresholds=thresholds, 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
    var_index=gene_ids,         # the Ensembl gene id of each column
    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.

Embed locally, and send numbers instead of pixels

pip install "auroraomics[embed]"
import auroraomics as ao
from auroraomics.embed import available_encoders, describe_encoders

with ao.Client() as client:
    # Both are the service's, so the file records the encoder and the
    # thresholds the model it is submitted to was served with. There is no
    # list of encoders inside this package: every name comes from the registry
    # the service publishes, which is why these calls take one.
    registry = client.encoders()
    thresholds = client.qc_thresholds()
    # The tile size the model's card states, for the model the file is for.
    patch_um = client.model_card(model_id)["input_spec"]["patch_um"]

print(available_encoders(registry))   # the names this package will run today
encoder = ao.resolve_encoder(registry)

report = ao.embed_tiles(
    slide, "sample.npz", mpp=0.499, patch_um=patch_um, encoder=encoder, thresholds=thresholds
)
print(report.rows, "rows of", report.dim, "numbers from", report.encoder.name)

slide is anything with a (height, width, 3) RGB uint8 shape that can be sliced — an array, or a memory-mapped or lazily-read one, so a slide larger than memory works: only one crop exists at a time. Crops are taken at the tile size the model's card states, using the mpp you give, and quality-checked with the same three predicates as pack_tiles.

Every encoder is pinned to an exact revision. describe_encoders(registry) returns the whole registry, including the encoders this package refuses to run: a refusal says why, and which encoders remain.

The written file carries one extra embedding, calibration: computed from a fixed image shipped inside this package, through the same encoder and revision as your rows. Comparing that one embedding against a known reference tells a reader whether the file was produced by the model it claims, before they look at a single row.

The weights are downloaded on first use. Pass allow_download=False to guarantee no request is made: for the duration of that load, name resolution and internet sockets are refused in this process.

An encoder runs at the input size the registry pins for it. resize_px is checked against that pin rather than obeyed, because an embedding computed at another size cannot be compared with the served model's.

Where a prediction runs

Predicting gene expression runs on the service, and predict_local refuses.

DeepSpot-H, the foundation model for H&E images, turns each tile of your slide into one embedding. It can run on your machine or on ours. DeepSpot-M turns those embeddings into spatial gene expression. It only ever runs on ours.

from auroraomics.runtimes.deepspotm import check_archive, describe_models

with ao.Client() as client:
    cards = client.models()                                # the catalogue is the service's
describe_models(cards)                                     # what it will run, and on what
check_archive("sample.zip", model=model_id, cards=cards)   # are my tiles the right size?

Then submit with the API client and read the result back — the same .h5ad contract whichever runtime ran it.

Post-process a result

from auroraomics.postprocess import apply_card

apply_card("result.h5ad", card=card)        # -> ('unmeasured_gene_mask',)

Or, from a pipeline rule, without writing a script:

python -m auroraomics.postprocess result.h5ad --card card.json

The card's postprocess list decides what runs. Every entry writes only where the result contract says its product lives — a matrix under layers/, a per-gene statement as a var column — and an entry the installed version does not implement is refused by name, before the file is opened, rather than skipped: a card is the description of a file, and a reader promised a layer cannot tell a missing one from a model that predicted zeros.

The entry this version ships states what the model measured. var gains measured_in_training, which is False for a gene the model never saw measured. Such a gene becomes nan in X and in every layer, not zero: zero is a measurement, and an unmeasured gene left as one averages, correlates and colours a heat map exactly like a prediction.

Read a result in SpatialData or Seurat

Every result is an .h5ad, which is an HDF5 file: anndata reads it, and so does any HDF5 library. For tools that read other formats, write it again:

auroraomics export result.h5ad --format seurat    # result_seurat/, for Read10X
auroraomics export result.h5ad --format zarr      # result.zarr, a SpatialData store
from auroraomics.export import write_seurat_dir, write_zarr

write_seurat_dir("result.h5ad", "result_seurat")
write_zarr("result.h5ad", "result.zarr")    # pip install "auroraomics[spatialdata]"

Both keep the result's own values: a gene the model never measured stays blank (nan) in either format, never zero.

Prepare a bulk RNA profile

with ao.Client() as client:
    report = ao.bulk_rna(
        "sample.star_gene_counts.tsv", "sample.bulk.tsv", units="counts",
        card=client.model_card(model_id), resolve=client.resolve_keys,
    )
print(report.rows, "genes;", f"{report.coverage:.0%} of", report.coverage_of)

A long or wide table, CSV or TSV, or a GDC STAR gene-counts file exactly as downloaded. Gene names are resolved to unversioned Ensembl ids through the same table every result is keyed by; the value column of the written table is named by the unit you declared, so the file states its own units; and a table that is already log-transformed is refused rather than logged a second time. Given the model's card, a profile that covers less of the model's measured genes than the service requires is refused here, with the service's own code, before anything is uploaded.

Typing

The package ships py.typed, so annotations are visible to type checkers in your project.

Licence

The code in this package is licensed for non-commercial use; its terms are in the LICENSE file it ships with. Commercial evaluation and use are governed by a written agreement with Aurora.

Metadata

Release files for auroraomics 0.1.0.dev4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for auroraomics 0.1.0.dev4
File Size Uploaded Provenance Actions
auroraomics-0.1.0.dev4.tar.gz 244.4 kB Without provenance Details for auroraomics-0.1.0.dev4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for auroraomics 0.1.0.dev4
File Interpreter ABI Platform Actions
auroraomics-0.1.0.dev4-py3-none-any.whl Python 3 none any Details for auroraomics-0.1.0.dev4-py3-none-any.whl

Total release size: 496.7 kB

Release files / auroraomics-0.1.0.dev4.tar.gz

Download URL auroraomics-0.1.0.dev4.tar.gz
Size 244.4 kB
Tags Source
SHA-256 checksum
How to use checksums
65f2ed9f8d81406cc9cbd3a1ef65a07dd0e1039f20ca7bdc25b929c7632a43a3
BLAKE2b-256 checksum
How to use checksums
eb4a3ced14321bb36a5675e09d150f3ec7cd73aae433334e99a0444a3fd785b1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.12

Release files / auroraomics-0.1.0.dev4-py3-none-any.whl

Download URL auroraomics-0.1.0.dev4-py3-none-any.whl
Size 252.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b5a2b9f560017e9bb7633ba7a54c6f3c1ebbc36b612ba6acdd472b379f965d6c
BLAKE2b-256 checksum
How to use checksums
0ba28a1327e2f1356f01b99196a44a51d78ce25ef11ba51efb4dda595552fdc0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.12

Security for auroraomics 0.1.0.dev4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page