Result file reference¶

Read Aurora results as AnnData for analysis in your own tools.

Every prediction is one .h5ad file.

The file¶

Part	Contract
Format	`h5ad`
Coordinates	`obsm["spatial"]` — the tile's centre, in full-resolution slide pixels
Gene axis index	`ensembl_gene_id`
Gene axis columns	`feature_name`, `hgnc_id`, `biotype`, `measured_in_training`, `model_token`
Provenance keys	`model`, `input_spec`, `job`, `resolution`

One row per tile, in the order you sent them. One column per gene. Each row is a spot, and its coordinates under obsm["spatial"] are the centre of its tile.

The provenance keys record what produced the result, so it can be traced after the job has expired.

An .h5ad file is an HDF5 file, so any HDF5 library, such as h5py, can read it without anndata.

Open an existing result¶

Install anndata to read the downloaded file in Python:

Not executed — needs anndata and a downloaded result

Use your own prediction.h5ad file.

import anndata

adata = anndata.read_h5ad("prediction.h5ad")
print(adata.shape)
print(adata.var[["feature_name", "measured_in_training"]].head())

Open it in SpatialData¶

The Python package writes the result as a SpatialData Zarr store. Each spot is a circle at its coordinates, and the result is the store's table.

pip install "auroraomics[spatialdata]"
auroraomics export prediction.h5ad --format zarr

Not executed — needs spatialdata and a downloaded result

Use the store written from your own prediction.h5ad file.

import spatialdata

sdata = spatialdata.read_zarr("prediction.zarr")
print(sdata.tables["table"])
print(sdata.shapes["spots"])

Open it in R¶

The package also writes a folder Seurat loads: the matrix in the layout Read10X reads, with each spot's coordinates and metadata as CSV files.

auroraomics export prediction.h5ad --format seurat

library(Seurat)

folder <- "prediction_seurat"
values <- Read10X(folder)  # gene.column = 1 keys genes by Ensembl identifier
seu <- CreateSeuratObject(CreateAssayObject(data = values), assay = "Spatial")
seu <- AddMetaData(seu, read.csv(file.path(folder, "metadata.csv"), row.names = 1))

xy <- as.matrix(read.csv(file.path(folder, "coordinates.csv"), row.names = 1))
colnames(xy) <- c("spatial_1", "spatial_2")
seu[["spatial"]] <- CreateDimReducObject(embeddings = xy, key = "spatial_", assay = "Spatial")
FeaturePlot(seu, "COL1A1", reduction = "spatial") + ggplot2::scale_y_reverse()

The values are predictions, so they go in the assay's data, not its counts. A blank gene stays blank. To read the .h5ad itself in R, use anndataR or zellkonverter.

The gene axis¶

The gene axis is indexed by Ensembl stable gene identifier, and the gene symbol travels in a column beside it.

Symbols are renamed, retired and occasionally reassigned. An identifier is not.

Identifiers are stored unversioned. ENSG00000141510.16 is stored as ENSG00000141510. A table carrying one version joins the same gene as a reference carrying another.

One versioned table on the service maps every symbol the model can predict to its identifier.

Find a gene¶

A result carries every gene the model predicts. To find a gene's column, resolve the names you hold into identifiers through the same table, then look the column up by identifier.

POST /genes/resolve takes 1 to 500 names in one request and answers with symbol, ensembl_gene_id, hgnc_id, biotype, in_ensembl for each.

A previous symbol or a recorded alias resolves to its gene. Two cases are refused, and neither is guessed at. A name that is not in the table answers gene_unknown. A name that names more than one gene answers gene_ambiguous.

Send the identifier when you have it

An identifier cannot be ambiguous. A symbol can be: OI4 is a recorded alias of two different genes.

The scale it was cut at¶

uns["resolution"] holds the micrometres per pixel the tiles were cut at, and whether the slide file agrees. agrees_with_slide is False when the two would cut different tiles: find which one is wrong before you read the map against the slide.