AnnData Repo Skill

Use this repo skill when a task involves anndata, AnnData, annotated data matrices, .h5ad, .zarr, backed mode, lazy reads, anndata.concat, AnnCollection, anndata.acc, or AnnData extension namespaces. AnnData is a Python package for annotated data matrices with aligned observations, variables, multidimensional annotations, pairwise arrays, layers, unstructured metadata, and native HDF5/Zarr storage.

First Checks

• Install AnnData with pip install anndata or conda install -c conda-forge anndata when the project does not already provide it.
• For lazy reads or remote Zarr workflows, install the package extra that provides xarray, dask, requests, and aiohttp: pip install "anndata[lazy]".
• Prefer public imports such as import anndata as ad and from anndata import AnnData; avoid leading-underscore internals unless the task is explicitly repository maintenance.
• Confirm importability before deeper work:

python - <<'PY'
import anndata as ad
from anndata import AnnData
print(ad.__name__, AnnData)
PY

• Run scripts/smoke_anndata_core.py for a safe bundled smoke test covering construction, concat, H5AD, and optional Zarr round-trips.

Route Map

• Use sub-skills/data-model/SKILL.md for constructing, inspecting, mutating, validating, slicing, copying, or repairing in-memory AnnData objects and aligned containers such as X, obs, var, layers, obsm, varm, obsp, varp, uns, and raw.
• Use sub-skills/storage-io/SKILL.md for .h5ad, Zarr, backed mode, lazy reads, sparse on-disk datasets, element-level read_elem/write_elem, encoding metadata, compression, chunking, and I/O troubleshooting.
• Use sub-skills/combining-data/SKILL.md for anndata.concat, mapping-vs-sequence keys, merge and join decisions, batch labels, duplicate names, pairwise graph retention, AnnCollection, and experimental.concat_on_disk.
• Use sub-skills/accessors-extensions/SKILL.md for anndata.acc.A references, reusable validation or plotting helpers, JSON/string reference forms, register_anndata_namespace, and extension namespace debugging.

Common Workflows

1. For a new object, start with data-model: confirm X.shape == (len(obs), len(var)), choose stable obs_names and var_names, add aligned arrays only when their leading axes match, then run the bundled structure inspector when shape problems are likely.
2. For persistence, move to storage-io: choose .h5ad for single-file exchange or Zarr for directory/object-store workflows, validate round-trips with a tiny fixture, and use backed/lazy reads only when their access constraints fit the task.
3. For multi-dataset integration, use combining-data: decide axis, join, merge, uns_merge, label, keys, index_unique, fill_value, and whether memory pressure requires AnnCollection or concat_on_disk.
4. For reusable library code, use accessors-extensions: represent fields with A.obs[...], A.obsm[...][:, i], or A.layers[...], validate references before indexing, and keep extension namespaces small and explicitly typed.

Shared References And Scripts

• Read references/troubleshooting.md for cross-cutting install/import, optional dependency, data validation, API misuse, storage backend, and workflow-routing issues before diving into sub-skill-specific troubleshooting.
• Read references/repo-provenance.md when deciding whether this generated skill is stale against a newer AnnData checkout or release.
• references/repo-routing-metadata.json is structured metadata used by DisCo's managed repo-skills-router import.
• Run scripts/smoke_anndata_core.py to validate import, core object construction, concat behavior, and optional H5AD/Zarr round-trips with tiny temporary fixtures.

Decision Points

• Use sparse X and sparse layers when data is mostly zero; dense arrays are simpler for tiny examples but can hide memory pressure.
• Treat .raw as an intentional snapshot of original X, var, and varm; later .var mutations do not automatically update .raw.var.
• Use .copy() before mutating subsets when parent preservation or warning-free behavior matters.
• Use join="inner" for conservative concat across features and join="outer" only when downstream code can handle missing values or sparse zero fill.
• For anndata.concat, use mapping keys or sequence keys, not both, when creating batch labels.
• Use backed mode for limited H5AD inspection and reads; do not assume every in-memory mutation works without materializing.
• Treat experimental APIs as useful but less stable; mention optional dependencies and deprecations such as AnnLoader moving toward annbatch.Loader when relevant.

Troubleshooting Priority

1. Verify the import, installed version, and optional extras relevant to the task.
2. Reproduce with a tiny AnnData object before scaling to large files or many batches.
3. Check shapes and names on every aligned slot.
4. Isolate storage problems with a fresh tiny H5AD or Zarr round-trip.
5. For concat surprises, print shape, obs_names, var_names, label categories, .uns.keys(), and relevant .obsm/.varm/.obsp keys.
6. For accessor or extension errors, validate references and namespace signatures before optional plotting, storage, or downstream package imports.