Single-cell annotation skills with omicverse

Overview

Use this skill to reproduce and adapt the single-cell annotation playbook captured in omicverse tutorials: SCSA [tcellanno.ipynb](../../../omicverseguide/docs/Tutorials-single/tcellanno.ipynb), MetaTiME [tmetatime.ipynb](../../../omicverseguide/docs/Tutorials-single/tmetatime.ipynb), CellVote [tcellvote.md](../../../omicverseguide/docs/Tutorials-single/tcellvote.md) & [tcellvotepbmc3k.ipynb](../../../omicverseguide/docs/Tutorials-single/tcellvotepbmc3k.ipynb), CellMatch [tcellmatch.ipynb](../../../omicverseguide/docs/Tutorials-single/tcellmatch.ipynb), GPTAnno [tgptanno.ipynb](../../../omicverseguide/docs/Tutorials-single/tgptanno.ipynb), and label transfer [tannotrans.ipynb](../../../omicverseguide/docs/Tutorials-single/tanno_trans.ipynb). Each section below highlights required inputs, training/inference steps, and how to read the outputs.

Instructions

1. SCSA automated cluster annotation

- Data requirements: PBMC3k raw counts from 10x Genomics (pbmc3kfilteredgenebcmatrices.tar.gz) or the processed sample/rna.h5ad. Download instructions are embedded in the notebook; unpack to data/filteredgenebcmatrices/hg19/. Ensure an SCSA SQLite database is available (e.g. pySCSA2024v1plus.db from the Figshare/Drive links listed in the tutorial) and point modelpath to its location. - Preprocessing & model fit: Load with ov.io.read10xmtx, run QC (ov.pp.qc), normalization and HVG selection (ov.pp.preprocess), scaling (ov.pp.scale), PCA (ov.pp.pca), neighbors, Leiden clustering, and compute rank markers (sc.tl.rankgenesgroups). Instantiate scsa = ov.single.pySCSA(...) choosing target='cellmarker' or 'panglaodb', tissue scope, and thresholds (foldchange, pvalue). - Inference & interpretation: Call scsa.cellanno(clustertype='leiden', resultkey='scsacelltypecellmarker') or scsa.cellautoanno to append predictions to adata.obs. Compare to manual marker-based labels via ov.pl.embedding or sc.pl.dotplot, inspect marker dictionaries (ov.single.getcelltypemarker), and query supported tissues with scsa.getmodeltissue(). Use the ROI/ROE helpers (ov.utils.roe, ov.utils.plotcellproportion) to validate abundance trends.

1. MetaTiME tumour microenvironment states

- Data requirements: Batched TME AnnData with an scVI latent embedding. The tutorial uses TiMEadatascvi.h5ad from Figshare (https://figshare.com/ndownloader/files/41440050). If starting from counts, run scVI (scvi.model.SCVI) first to populate adata.obsm['XscVI']. - Preprocessing & model fit: Optionally subset to non-malignant cells via adata.obs['isTME']. Rebuild neighbors on the latent representation (sc.pp.neighbors(adata, userep="XscVI")) and embed with umap (adata.obsm['Xumap'] = ov.pp.umap(...)). Initialise TiMEobject = ov.single.MetaTiME(adata, mode='table') and, if finer granularity is desired, over-cluster with TiMEobject.overcluster(resolution=8, clustercol='overcluster'). - Inference & interpretation: Run TiMEobject.predictTiME(saveobsname='MetaTiME') to assign minor states and MajorMetaTiME. Visualise using TiMEobject.plot or sc.pl.embedding. Interpret the outputs by comparing cluster-level distributions and confirming that MetaTiME and MajorMetaTiME columns align with expected niches.

1. CellVote consensus labelling

- Data requirements: A clustered AnnData (e.g. PBMC3k stored as CELLVOTEPBMC3K env var or data/pbmc3k.h5ad) plus at least two precomputed annotation columns (simulated in the tutorial as scsaannotation, gptcelltype, gbicelltype). Prepare per-cluster marker genes via sc.tl.rankgenesgroups. - Preprocessing & model fit: After standard preprocessing (normalize, log1p, HVGs, PCA, neighbors, Leiden) build a marker dictionary markerdict = topmarkersfromrgg(adata, 'leiden', topn=10) or via ov.single.getcelltypemarker. Instantiate cv = ov.single.CellVote(adata). - Inference & interpretation: Call cv.vote(clusterskey='leiden', clustermarkers=markerdict, celltypekeys=[...], species='human', organization='PBMC', provider='openai', model='gpt-4o-mini'). Offline examples monkey-patch arbitration to avoid API calls; online voting requires valid credentials. Final consensus labels live in adata.obs['CellVotecelltype']. Compare each cluster’s majority vote with the input sources (adata.obs[['leiden', 'scsaannotation', ...]]) to justify decisions.

1. CellMatch ontology mapping

- Data requirements: Annotated AnnData such as pertpy.dt.haber2017regions() with adata.obs['celllabel']. Download Cell Ontology JSON (cl.json) via ov.single.downloadcl(...) or manual links, and optionally Cell Taxonomy resources (CellTaxonomyresource.txt). Ensure access to a SentenceTransformer model (sentence-transformers/all-MiniLM-L6-v2, BAAI/bge-base-en-v1.5, etc.), downloading to localmodeldir if offline. - Preprocessing & model fit: Create the mapper with ov.single.CellOntologyMapper(clobofile='newontology/cl.json', modelname='sentence-transformers/all-MiniLM-L6-v2', localmodeldir='./mymodels'). Run mapper.mapadata(...) to assign ontology-derived labels/IDs, optionally enabling taxonomy matching (usetaxonomy=True after calling loadcelltaxonomyresource). - Inference & interpretation: Explore mapping summaries (mapper.printmappingsummarytaxonomy) and inspect embeddings coloured by cellontology, cellontologyclid, or enhancedcellontology. Use helper queries such as mapper.findsimilarcells('T helper cell'), mapper.getcell_info(...), and category browsing to validate ontology coverage.

1. GPTAnno LLM-powered annotation

- Data requirements: The same PBMC3k dataset (raw matrix or .h5ad) and cluster assignments. Access to an LLM endpoint—configure AGIAPIKEY for OpenAI-compatible providers (provider='openai', 'qwen', 'kimi', etc.), or supply a local model path for ov.single.gptcelltypelocal. - Preprocessing & model fit: Follow the QC, normalization, HVG, scaling, PCA, neighbor, Leiden, and marker discovery steps described above (reusing outputs from the SCSA workflow). Build the marker dictionary automatically with ov.single.getcelltypemarker(adata, clustertype='leiden', rank=True, key='rankgenesgroups', foldchange=2, topgenenumber=5). - Inference & interpretation: Invoke ov.single.gptcelltype(...) specifying tissue/species context and desired provider/model. Post-process responses to keep clean labels (result[key].split(': ')[-1]...) and write them to adata.obs['gptcelltype']. Compare embeddings (ov.pl.embedding(..., color=['leiden','gptcelltype'])) to verify cluster identities. If operating offline, call ov.single.gptcelltypelocal with a downloaded instruction-tuned checkpoint.

1. Weighted KNN annotation transfer

- Data requirements: Cross-modal GLUE outputs with aligned embeddings, e.g. data/analysislymph/rna-emb.h5ad (annotated RNA) and data/analysislymph/atac-emb.h5ad (query ATAC) where both contain obsm['Xglue']. - Preprocessing & model fit: Load both modalities, optionally concatenate for QC plots, and compute a shared low-dimensional embedding with ov.utils.mde. Train a neighbour model using ov.utils.weightedknntrainer(trainadata=rna, trainadataemb='Xglue', nneighbors=15). - Inference & interpretation: Transfer labels via labels, uncert = ov.utils.weightedknntransfer(queryadata=atac, queryadataemb='Xglue', labelkeys='majorcelltype', knnmodel=knntransformer, refadataobs=rna.obs). Store predictions in atac.obs['transfcelltype'] and uncertainties in atac.obs['transfcelltypeunc']; copy to majorcelltype if you want consistent naming. Visualise (ov.pl.embedding) and inspect uncertainty to flag ambiguous cells.

Defensive Validation Patterns

# Before SCSA: verify rank_genes_groups has been computed
assert 'rank_genes_groups' in adata.uns, \
    "Marker genes required. Run sc.tl.rank_genes_groups(adata, groupby='leiden') first."

# Before any annotation: verify clustering exists
assert 'leiden' in adata.obs.columns or 'louvain' in adata.obs.columns, \
    "Clustering required. Run ov.pp.leiden(adata) or sc.tl.leiden(adata) first."

# Before CellVote: verify multiple annotation columns exist
annotation_keys = ['scsa_annotation', 'gpt_celltype']  # adjust to actual keys
for key in annotation_keys:
    assert key in adata.obs.columns, f"Annotation column '{key}' not found — run annotators first"

Critical API Reference - EXACT Function Signatures

pySCSA - IMPORTANT: Parameter is clustertype, NOT cluster

CORRECT usage:

# Step 1: Initialize pySCSA
scsa = ov.single.pySCSA(
    adata,
    foldchange=1.5,
    pvalue=0.01,
    species='Human',
    tissue='All',
    target='cellmarker'  # or 'panglaodb'
)

# Step 2: Run annotation - NOTE: use clustertype='leiden', NOT cluster='leiden'!
anno_result = scsa.cell_anno(clustertype='leiden', cluster='all')

# Step 3: Add cell type labels to adata.obs
scsa.cell_auto_anno(adata, clustertype='leiden', key='scsa_celltype')
# Results are stored in adata.obs['scsa_celltype']

WRONG - DO NOT USE:

# WRONG! 'cluster' is NOT a valid parameter for cell_auto_anno!
# scsa.cell_auto_anno(adata, cluster='leiden')  # ERROR!

COSG Marker Genes - Results stored in adata.uns, NOT adata.obs

CORRECT usage:

# Step 1: Run COSG marker gene identification
ov.single.cosg(adata, groupby='leiden', n_genes_user=50)

# Step 2: Access results from adata.uns (NOT adata.obs!)
marker_names = adata.uns['rank_genes_groups']['names']  # DataFrame with cluster columns
marker_scores = adata.uns['rank_genes_groups']['scores']

# Step 3: Get top markers for specific cluster
cluster_0_markers = adata.uns['rank_genes_groups']['names']['0'][:10].tolist()

# Step 4: To create celltype column, manually map clusters to cell types
cluster_to_celltype = {
    '0': 'T cells',
    '1': 'B cells',
    '2': 'Monocytes',
}
adata.obs['cosg_celltype'] = adata.obs['leiden'].map(cluster_to_celltype)

WRONG - DO NOT USE:

# WRONG! COSG does NOT create adata.obs columns directly!
# adata.obs['cosg_celltype']  # This key does NOT exist after running COSG!
# adata.uns['cosg_celltype']  # This key also does NOT exist!

Common Pitfalls to Avoid

1. pySCSA parameter confusion:

- clustertype = which obs column contains cluster labels (e.g., 'leiden') - cluster = which specific clusters to annotate ('all' or specific cluster IDs) - These are DIFFERENT parameters!

1. COSG result access:

- COSG is a marker gene finder, NOT a cell type annotator - Results are per-cluster gene rankings stored in adata.uns['rankgenesgroups'] - To assign cell types, you must manually map clusters to cell types based on markers

1. Result storage patterns in OmicVerse:

- Cell type annotations → adata.obs['<key>'] - Marker gene results → adata.uns['<key>'] (includes 'names', 'scores', 'logfoldchanges') - Differential expression → adata.uns['rankgenesgroups']

Examples

• "Run SCSA with both CellMarker and PanglaoDB references on PBMC3k, then benchmark against manual marker assignments before feeding the results into CellVote."
• "Annotate tumour microenvironment states in the MetaTiME Figshare dataset, highlight Major_MetaTiME classes, and export the label distribution per patient."
• "Download Cell Ontology resources, map haber2017regions clusters to ontology terms, and enrich ambiguous clusters using Cell Taxonomy hints."
• "Propagate RNA-derived major_celltype labels onto GLUE-integrated ATAC cells and report clusters with high transfer uncertainty."

References

• Tutorials and notebooks: [tcellanno.ipynb](../../../omicverseguide/docs/Tutorials-single/tcellanno.ipynb), [tmetatime.ipynb](../../../omicverseguide/docs/Tutorials-single/tmetatime.ipynb), [tcellvote.md](../../../omicverseguide/docs/Tutorials-single/tcellvote.md), [tcellvotepbmc3k.ipynb](../../../omicverseguide/docs/Tutorials-single/tcellvotepbmc3k.ipynb), [tcellmatch.ipynb](../../../omicverseguide/docs/Tutorials-single/tcellmatch.ipynb), [tgptanno.ipynb](../../../omicverseguide/docs/Tutorials-single/tgptanno.ipynb), [tannotrans.ipynb](../../../omicverseguide/docs/Tutorials-single/tanno_trans.ipynb).
• Sample data & assets: PBMC3k matrix from 10x Genomics, MetaTiME TiMEadatascvi.h5ad (Figshare), SCSA database downloads, GLUE embeddings under data/analysis_lymph/, Cell Ontology cl.json, and Cell Taxonomy resource.
• Quick copy commands: [reference.md](reference.md).