Storage Io

---
name: storage-io
description: "Read, write, choose, inspect, and troubleshoot AnnData H5AD/Zarr
  storage, backed mode, lazy reads, sparse datasets, element-level I/O, and Zarr
  v3 options."
disable-model-invocation: true
metadata:
  disco-role: operating
license: BSD 3-Clause
---

# Storage I/O

Use this sub-skill when a task mentions `.h5ad`, `.zarr`, HDF5, Zarr, storage formats, backed mode, lazy reads, `read_h5ad`, `read_zarr`, `write_h5ad`, `write_zarr`, `anndata.io.read_elem`, `anndata.io.write_elem`, `anndata.io.sparse_dataset`, encoding metadata, sparse on-disk arrays, compression, chunking, Zarr v3, metadata consolidation, or `concat_on_disk` storage prerequisites.

## Route First

- Continue here for whole-object H5AD/Zarr reads and writes, storage choice, backed/lazy access, element-level reads/writes, sparse on-disk datasets, encoding metadata, and storage-specific failures.
- Route object construction, aligned slot shape rules, views, `obs`/`var` semantics, `.raw`, and in-memory mutation to `../data-model/SKILL.md`.
- Route multi-object combination semantics to `../combining-data/SKILL.md`; use this sub-skill only to prepare readable input stores and validate writable output stores for `concat_on_disk`.
- Route accessors, references, and extension namespaces to `../accessors-extensions/SKILL.md`.

## Use The Bundled Files

- `references/api-reference.md` lists verified public I/O signatures, stable versus experimental APIs, and option notes.
- `references/file-format.md` distills the H5AD/Zarr hierarchy, required encoding metadata, and inspection checks.
- `references/io-workflows.md` gives decision workflows for H5AD versus Zarr, backed versus lazy access, element I/O, sparse datasets, Zarr v3 metadata, sharding, and compressor choices.
- `references/troubleshooting.md` maps storage symptoms to causes and recovery steps.
- `scripts/check_anndata_io_roundtrip.py` creates tiny deterministic H5AD and/or Zarr fixtures, reads them back, optionally checks backed/lazy access, and prints pass/fail without network access.

## Default Decisions

- Prefer `.h5ad` for single-file local exchange and HDF5 `backed` reads; close backed objects with `adata.file.close()`.
- Prefer Zarr for directory or cloud-style stores, chunk tuning, consolidated metadata, sharding, and codec configuration.
- Use full `read_h5ad`/`read_zarr` for small or final validation reads; use `read_h5ad(..., backed="r")` for low-memory H5AD inspection; use `anndata.experimental.read_lazy` for experimental dask/xarray-backed low-memory reads.
- Treat `anndata.experimental.read_lazy`, `read_dispatched`, and `write_dispatched` as experimental APIs; use stable high-level methods and `anndata.io.read_elem`/`write_elem` unless callback-based traversal or lazy materialization is required.
- After writing any store, re-read it and validate shape, names, expected keys, sparse/dense representation, and backing/lazy file lifecycle.

## Quick Checks

```bash
python sub-skills/storage-io/scripts/check_anndata_io_roundtrip.py
python sub-skills/storage-io/scripts/check_anndata_io_roundtrip.py --backed-lazy
python sub-skills/storage-io/scripts/check_anndata_io_roundtrip.py --output-dir ./tmp-anndata-io --keep
```

When running the script from outside the skill directory, use its full path. The script creates only local temporary fixtures unless `--output-dir` is provided.