scpdac.tl.extend_atlas

scpdac.tl.extend_atlas(query, atlas, species, *, layer='counts', max_epochs=10, batch_key='Sample_ID', freeze_dropout=True)

Map a query dataset onto the reference atlas via scArches surgery.

The pretrained SCANVI model is adapted to the query with load_query_data() (scArches architectural surgery), which tolerates batches not present in the reference registry. The query and reference are then embedded in a shared latent space and concatenated into an expanded reference object, retaining all user-supplied query metadata.

Parameters:

• query (AnnData) – Query data with raw counts in adata.layers[layer] and batch_key in obs. All of its obs columns are preserved in the returned object.

• atlas (AnnData) – Reference atlas AnnData (raw counts in the same layer).

• species (str) – "human" or "mouse".

• layer (str (default: 'counts')) – Layer holding raw counts to bin.

• max_epochs (int (default: 10)) – Epochs to fine-tune the surgery (query) model.

• batch_key (str (default: 'Sample_ID')) – Column in adata.obs identifying the batch covariate.

• freeze_dropout (bool (default: True)) – Passed to scArches surgery; freezes dropout in transferred layers.

Return type:

AnnData

Returns:

An expanded reference AnnData containing both atlas and query cells in a shared obsm["X_scANVI_emb"] space, with a "source" column (“atlas”/”query”), a joint UMAP, and predicted labels for the query in obs["predicted_celltype"].

Raises:

ValueError – If batch_key is absent from query.obs.