---

name: data-setup description: "Prepare AnnData and MuData inputs, readers, fixtures, preprocessing, setup_anndata/setup_mudata calls, and registry validation for scvi-tools models." disable-model-invocation: true metadata: disco-role: operating license: BSD 3-Clause

data-setup

Use this sub-skill when the task is about getting data into scvi-tools before model construction: AnnData/MuData shape, layers, obs/obsm/varm/uns keys, scvi.data readers, synthetic fixtures, preprocessing, setup_anndata, setup_mudata, or AnnDataManager validation.

Do not use this sub-skill for model choice, architecture parameters, training loops, callbacks, inference, differential expression, or spatial interpretation. Route those to the core model, multimodal/spatial, and training/inference sub-skills.

Fast Path

1. Load or construct an AnnData/MuData object with raw non-negative integer counts in adata.X, adata.layers[layer], or modality-specific .X/layers.
2. Confirm key existence before setup: batch_key, labels_key, covariate keys, protein obsm/uns keys, MuData modality names, and requested layers.
3. Call the model class setup method exactly once for the data object and model family, then instantiate the model with that same object.
4. Inspect model.adata_manager.registry, model.adata_manager.data_registry, and model.adata_manager.summary_stats when troubleshooting setup failures.

Core Setup Patterns

• scvi.model.SCVI.setup_anndata(adata, layer=None, batch_key=None, labels_key=None, size_factor_key=None, categorical_covariate_keys=None, continuous_covariate_keys=None) for RNA counts in X or a count layer.
• scvi.model.SCANVI.setup_anndata(adata, labels_key="cell_type", unlabeled_category="Unknown", layer=None, batch_key=None, size_factor_key=None, categorical_covariate_keys=None, continuous_covariate_keys=None) for semi-supervised labels.
• scvi.model.TOTALVI.setup_anndata(adata, protein_expression_obsm_key="protein_expression", protein_names_uns_key="protein_names", batch_key=None, panel_key=None, layer=None, size_factor_key=None, categorical_covariate_keys=None, continuous_covariate_keys=None) for CITE-seq-style AnnData.
• Prefer scvi.model.TOTALVI.setup_mudata(mdata, rna_layer=None, protein_layer=None, batch_key=None, panel_key=None, modalities={"rna_layer": "rna", "protein_layer": "protein_expression", "batch_key": "rna"}) for RNA + protein MuData.
• scvi.model.PEAKVI.setup_anndata(adata, batch_key=None, labels_key=None, categorical_covariate_keys=None, continuous_covariate_keys=None, layer=None) for chromatin accessibility counts.
• Prefer scvi.model.MULTIVI.setup_mudata(mdata, rna_layer=None, atac_layer=None, protein_layer=None, batch_key=None, size_factor_key=None, idx_layer=None, modalities={"rna_layer": "rna", "atac_layer": "accessibility", "protein_layer": "protein_expression", "batch_key": "rna"}) for multiome or tri-modal data.

Internal References

• Read data formats for accepted matrix locations, reader outputs, and AnnData/MuData key conventions.
• Read API reference for concrete scvi-tools setup, preprocessing, synthetic fixture, and registry APIs.
• Read troubleshooting for missing keys, non-count warnings, MuData pairing errors, protein masks, and registry validation fixes.
• Use scripts/create_tiny_anndata.py --help to generate small local AnnData/MuData fixtures for setup smoke tests.