OmicVerse Single-Cell — MetaTiME Tumor Microenvironment Annotation

Goal

Take a batch-corrected, dimension-reduced single-cell AnnData (typically from a tumor scRNA-seq cohort) and annotate it with MetaTiME meta-components (MeCs) — pretrained gene programs derived from millions of single cells across hundreds of tumor scRNA-seq studies. Output is a per-cell obs['MetaTiME'] (fine-grained cell state) and obs['Major_MetaTiME'] (coarse roll-up category). The pipeline is over-cluster → score → write.

MetaTiME's value vs. de-novo annotation is that the meta-components are transferable across cohorts: a TIL-1 (tissue-resident memory CD8+ T cell) annotation in your cohort means the same biology as a TIL-1 annotation in any other cohort that ran MetaTiME.

Quick Workflow

1. Load a batch-corrected AnnData. The canonical MetaTiME demo uses scVI-corrected embedding (adata.obsm['X_scVI']); Harmony / Conos / scanorama corrected embeddings work equivalently.
2. (Optional) Build an MDE projection for downstream visualisation: adata.obsm['X_mde'] = ov.utils.mde(adata.obsm['X_scVI']). MDE is a faster UMAP alternative bundled with OmicVerse.
3. Construct: TiME_object = ov.single.MetaTiME(adata, mode='table'). The mode='table' setting maps meta-component scores to cell-state labels via the bundled lookup table (default; the alternative is hard-cluster mapping but 'table' is canonical).
4. Over-cluster at high resolution: TiME_object.overcluster(resolution=8, clustercol='overcluster'). Writes adata.obs['overcluster']. Resolution=8 (much higher than typical analysis resolutions of 0.5–1.5) is required — MetaTiME's MeC scoring is computed at the cluster level, so over-clustering preserves cell-state granularity.
5. Predict: TiME_object.predictTiME(save_obs_name='MetaTiME'). Scores each cluster against all MeCs, assigns the dominant MeC, and writes both fine-grained (obs['MetaTiME']) and major-category (obs['Major_MetaTiME']) labels.
6. Visualise: TiME_object.plot(cluster_key='MetaTiME', basis='X_mde', dpi=80) — built-in plot with collision-aware label placement, OR fall back to sc.pl.embedding(adata, basis='X_mde', color=['Major_MetaTiME'], frameon=False) for a standard scanpy figure.

Interface Summary