scvi-scarches-reference-mapping

What problem does it solve?

Maps a query dataset onto an existing scvi-tools or scArches reference atlas using architectural surgery to project unseen cells without retraining from scratch.

Core Features & Use Cases

• Prepare_query_anndata for gene padding to ensure compatibility with the reference.
• load_query_data to attach the query to the reference workflow and enable transformation.
• Fine-tuning with a frozen encoder (weight_decay=0) to preserve reference structure.
• scANVI or weighted-KNN label transfer for efficient annotation transfer.
• Novel-cell-state detection from low confidence and hierarchical ontology transfer via treearches-hierarchy-learning.
• Supports both scvi-tools natives (scVI, scANVI, totalVI, MultiVI) and scarches models (trVAE, scGen, expiMap, treeArches, scPoli).
• Reference-training flags required: use_layer_norm=both, use_batch_norm=none, encode_covariates=True.
• For de novo integration without a reference: scvi-basic.

Quick Start

Run the end-to-end scArches workflow to map your query data to a pretrained reference.