Skip to main content
A gene signature is a named group of genes reduced to one score per tile — for example, the mean predicted expression of a T-cell marker set. This guide scores signatures on M-Optimus predictions, stores the per-tile scores beside the predictions, and stores the signature definitions in the cohort manifest so an analysis can be reloaded and reproduced later.
A score is a per-tile aggregate of predicted expression, not a statistical test. No p-values are computed and no control-gene baseline is subtracted.

1. Define signatures

A GeneSet names the genes; a GeneSignature adds how to reduce them to a score. Genes are identified by Ensembl gene ID, the same identifiers as the prediction panel.

2. Score a prediction store

Load the predictions that M-Optimus wrote (see Spatial transcriptomics) and score them. score returns a GeneSignatureScores with one row per tile and one column per signature; nothing is written yet.
Plot a signature over the slide with the same tile coordinates:
Gene sets with HGNC symbols (the default id_type="symbol") are matched to the Ensembl panel by passing a symbol-to-Ensembl mapping to score(...).

3. Save the scores and the definitions

The two halves are stored separately (cohort is the cohort you ran inference with; see Cohorts). The scores are per-tile arrays, so they go into the prediction store, row-aligned with its tiles. The definitions are small and describe the analysis, so they go into the cohort manifest under extras.
save raises a BIO-CFG-001 error if the number of scores doesn’t match the store’s tile count. If the store already holds signature scores, on_conflict controls what happens:
Zarr and HDF5 stores are appended in place. NPZ has no append API, so save rewrites the whole file and logs a warning; prefer Zarr (the default) for large slides.

4. Reload

In a later session, read the scores from the store and rebuild the signatures from the cohort manifest.
The stored definition lists every gene, so the rebuilt collection scores new predictions exactly as the original did. Because extras is plain YAML, the definitions are also readable and diffable in the manifest.

5. Apply across a cohort

Score each slide’s predictions with the same collection and save them into that slide’s store:
get_stage_path resolves paths relative to the manifest directory, so this works wherever the cohort is loaded from.
cohort.extras is a general place for analysis definitions. Namespace each analysis under its own key (here "gene_signatures") so analyses don’t overwrite each other.