---

name: data-model description: "Construct, inspect, validate, slice, copy, and mutate in-memory AnnData objects and their aligned annotations." disable-model-invocation: true metadata: disco-role: operating license: BSD 3-Clause

AnnData Data Model

Use this sub-skill when a task asks how to build, inspect, validate, subset, copy, convert, or mutate an in-memory anndata.AnnData object. Typical prompts mention AnnData(...), X, obs, var, layers, obsm, varm, obsp, varp, uns, .raw, obs_names, var_names, views, copy-on-modify warnings, .to_df(), .copy(), .to_memory(), or shape/name validation.

Route First

• Continue here for single-object construction, aligned slot contracts, index/name checks, view semantics, .raw, to_df, copy, to_memory, and safe in-memory mutation patterns.
• Route .h5ad, Zarr, backed reads/writes, lazy reads, element I/O, compression, and file lifecycle to ../storage-io/SKILL.md.
• Route anndata.concat, experimental.concat_on_disk, AnnCollection, batch labels, joins, and multi-object merging to ../combining-data/SKILL.md.
• Route anndata.acc references and register_anndata_namespace extension namespaces to ../accessors-extensions/SKILL.md.

Use The Bundled Files

• references/api-reference.md lists verified public signatures, construction forms, and method/property notes.
• references/object-model.md explains axis alignment, slot shape contracts, slicing, copy-on-modify views, .raw, and mutation rules.
• references/troubleshooting.md maps common construction and mutation failures to concrete recovery steps.
• scripts/inspect_anndata_structure.py prints a deterministic shape/key/name summary for a demo object, an .h5ad, or a Zarr store.

Default Workflow

1. Establish the intended shape (n_obs, n_vars) from X, from shape=..., or from the aligned annotations being supplied.
2. Build obs with exactly n_obs rows and var with exactly n_vars rows; treat their indexes as obs_names and var_names.
3. Add aligned containers only after checking their axes: layers match (n_obs, n_vars), obsm rows match n_obs, varm rows match n_vars, obsp match (n_obs, n_obs), and varp match (n_vars, n_vars).
4. Keep free-form metadata in uns; do not put axis-aligned arrays in uns when an aligned slot exists.
5. When subsetting, assume adata[...] returns a view until copied or mutated; use .copy() before intentional independent edits.
6. For normalized/counts snapshots, set adata.raw = adata.copy() before replacing X or filtering variables; remember .raw follows observation slicing but keeps its own variable axis.
7. Validate final objects with .shape, .obs_names.is_unique, .var_names.is_unique, slot keys, and the inspection script before handing them to storage, concat, or downstream analysis.

Quick Checks

python sub-skills/data-model/scripts/inspect_anndata_structure.py
python sub-skills/data-model/scripts/inspect_anndata_structure.py --h5ad example.h5ad
python sub-skills/data-model/scripts/inspect_anndata_structure.py --zarr example.zarr

When running from outside the skill directory, use the script's full path. The script does not write outputs, access the network, or mutate inputs.