Annotation And Query

---
name: annotation-and-query
description: "Use for scvi-tools label transfer, query/reference mapping,
  semi-supervised annotation, doublet detection, and marker-based cell
  assignment with SCANVI, SOLO, and CellAssign."
disable-model-invocation: true
metadata:
  disco-role: operating
license: BSD 3-Clause
---

# annotation-and-query

Use this sub-skill when the task is to annotate cells, transfer labels from a reference, map query data into a trained reference, detect doublets, or assign cell types from marker genes.

## Route here for

- Semi-supervised annotation with `scvi.model.SCANVI`, including `labels_key`, `unlabeled_category`, `SCANVI.from_scvi_model(...)`, and `model.predict(...)`.
- Query/reference workflows that start from a trained `SCVI` reference and then initialize `SCANVI` for label transfer.
- Doublet detection with `scvi.external.SOLO.from_scvi_model(...)`, `SOLO.train(...)`, and `SOLO.predict(...)`.
- Marker-based cell assignment with `scvi.external.CellAssign`, binary marker matrices, and soft assignment probabilities.
- Annotation validation, including prediction confidence, ambiguous cells, unseen labels, and marker-gene alignment checks.

## Do not route here for

- Generic `train(...)`, checkpointing, accelerators, early stopping, or dataloader tuning unless annotation-specific behavior is the core issue; route to training-and-inference coverage when available.
- General model selection among `SCVI`, `SCANVI`, `TOTALVI`, or other model families; route to core-models coverage when available.
- Spatial or multimodal specialized annotation workflows; route to multimodal-and-spatial coverage when available.

## Start points

- For SCANVI label transfer and query/reference patterns, read `references/workflows.md`.
- For exact constructors, setup methods, prediction outputs, and validation checks, read `references/api-reference.md`.
- For common label, marker, and SOLO failures, read `references/troubleshooting.md`.

## Quick decision guide

- If labels exist for some cells and one category marks unknown cells, use `SCANVI.setup_anndata(..., labels_key=..., unlabeled_category=...)` or bootstrap from a trained `SCVI` with `SCANVI.from_scvi_model(...)`.
- If a trained `SCVI` reference exists and the goal is doublet calls, use `SOLO.from_scvi_model(scvi_model, restrict_to_batch=...)` and inspect soft doublet probabilities.
- If curated marker genes define expected cell types, use `CellAssign` after subsetting `adata` to marker genes and validating that marker matrix rows exactly cover `adata.var_names`.
- Always store both hard labels and uncertainty scores in `adata.obs`; avoid trusting only the argmax label when probabilities are diffuse.