anndata – Data & Science skill for AI agents

AnnData

Overview

AnnData is a Python package for handling annotated data matrices, storing experimental measurements (X) alongside observation metadata (obs), variable metadata (var), and multi-dimensional annotations (obsm, varm, obsp, varp, uns). Originally designed for single-cell genomics through Scanpy, it now serves as a general-purpose framework for any annotated data requiring efficient storage, manipulation, and analysis.

When to Use This Skill

Use this skill when:

• Creating, reading, or writing AnnData objects
• Working with h5ad, zarr, or other genomics data formats
• Performing single-cell RNA-seq analysis
• Managing large datasets with sparse matrices or backed mode
• Concatenating multiple datasets or experimental batches
• Subsetting, filtering, or transforming annotated data
• Integrating with scanpy, scvi-tools, or other scverse ecosystem tools

Installation

Targets AnnData 0.13.4 (current PyPI release reviewed 2026-09-30), requiring Python

3.12+. Small synthetic checks cover dense/sparse matrices, native I/O, metadata,

concatenation, and lazy reads. File paths, biological analysis, remote stores, and

third-party integration examples are illustrative unless stated otherwise.

uv pip install "anndata==0.13.4"

# Lazy I/O and dask-backed operations
uv pip install "anndata[dask,lazy]==0.13.4"

Use unpinned installs only when intentionally tracking the latest compatible release.

Current API notes:

• Use anndata.io for non-native read_* and write_* helpers. Top-level anndata.read_h5ad and anndata.read_zarr remain supported.
• Use ad.concat; AnnData.concatenate() was removed in 0.13. Avoid old ad.read, deprecated AnnData.*_keys() helpers and anndata.__version__; prefer explicit readers, mapping .keys(), and importlib.metadata.version("anndata").
• In 0.13, .X is also layers[None]; layer iteration includes None. Use key is not None when selecting named layers. View .X writes now use copy-on-write.
• Zarr v3 and automatic sharding are the defaults; the Python dependency is Zarr >=3. Dense H5AD X remains writable with backed="r+", but backed sparse item assignment is unsupported in 0.13.
• AnnLoader and Loom reading/writing are deprecated. AnnCollection and other experimental APIs need the caveats in the references.

These changes are documented in the [official release notes](https://anndata.readthedocs.io/en/stable/release-notes/). The live docs header still displayed 0.13.3.post0 at review; behavior below was also checked against installed 0.13.4 source.

Quick Start

Creating an AnnData object

import anndata as ad
import numpy as np
import pandas as pd

# Minimal creation
X = np.random.rand(100, 2000)  # 100 cells × 2000 genes
adata = ad.AnnData(X)

# With metadata
obs = pd.DataFrame({
    'cell_type': ['T cell', 'B cell'] * 50,
    'sample': ['A', 'B'] * 50
}, index=[f'cell_{i}' for i in range(100)])

var = pd.DataFrame({
    'gene_name': [f'Gene_{i}' for i in range(2000)]
}, index=[f'ENSG{i:05d}' for i in range(2000)])

adata = ad.AnnData(X=X, obs=obs, var=var)

Reading data

# Native formats (read_h5ad/read_zarr remain at top-level)
adata = ad.read_h5ad('data.h5ad')
source = ad.read_h5ad('large_data.h5ad', backed='r')  # X backed; metadata/layers can load
try:
    subset = source[:100, :].to_memory()
finally:
    source.file.close()
adata = ad.read_zarr('data.zarr')

# Other formats: prefer anndata.io (top-level imports are deprecated)
from anndata.io import read_csv, read_loom, read_mtx

adata = read_csv('data.csv')
adata = read_loom('data.loom')

# 10X Genomics: use scanpy (not anndata) — see scanpy skill
import scanpy as sc
adata = sc.read_10x_h5('filtered_feature_bc_matrix.h5')
adata = sc.read_10x_mtx('filtered_feature_bc_matrix/')

Writing data

# Write h5ad file
adata.write_h5ad('output.h5ad')

# Write with compression
adata.write_h5ad('output.h5ad', compression='gzip')

# Write other formats
adata.write_zarr('output.zarr')
adata.write_csvs('output_dir/', skip_data=False)  # Lossy; may densify X

Basic operations

# Subset by conditions
t_cells = adata[adata.obs['cell_type'] == 'T cell']

# Subset by indices
subset = adata[0:50, 0:100]

# Add metadata
adata.obs['quality_score'] = np.random.rand(adata.n_obs)
adata.var['highly_variable'] = np.random.rand(adata.n_vars) > 0.8

# Access dimensions
print(f"{adata.n_obs} observations × {adata.n_vars} variables")

Core Capabilities

1. Data Structure

Understand the AnnData object structure including X, obs, var, layers, obsm, varm, obsp, varp, uns, and raw components.

See: references/data_structure.md for comprehensive information on:

• Core components (X, obs, var, layers, obsm, varm, obsp, varp, uns, raw)
• Creating AnnData objects from various sources
• Accessing and manipulating data components
• Memory-efficient practices

2. Input/Output Operations

Read and write data in various formats with support for compression, backed mode, and cloud storage.

See: references/io_operations.md for details on:

• Native formats (h5ad, zarr)
• Alternative formats (CSV, MTX, Loom, 10X, Excel)
• Backed mode for large datasets
• Remote data access
• Format conversion
• Performance optimization

Common commands:

from anndata.io import read_mtx

# Read/write h5ad
source = ad.read_h5ad('data.h5ad', backed='r')
try:
    source.write_h5ad('output.h5ad', compression='gzip')
finally:
    source.file.close()

# 10X Genomics (via scanpy)
import scanpy as sc
adata = sc.read_10x_h5('filtered_feature_bc_matrix.h5')

# Read MTX format
adata = read_mtx('matrix.mtx').T

3. Concatenation

Combine multiple AnnData objects along observations or variables with flexible join strategies.

See: references/concatenation.md for comprehensive coverage of:

• Basic concatenation (axis=0 for observations, axis=1 for variables)
• Join types (inner, outer)
• Merge strategies (same, unique, first, only)
• Tracking data sources with labels
• Lazy concatenation (AnnCollection)
• On-disk concatenation for large datasets

Common commands:

# Concatenate observations (combine samples)
adata = ad.concat(
    [adata1, adata2, adata3],
    axis=0,
    join='inner',
    label='batch',
    keys=['batch1', 'batch2', 'batch3']
)

# Concatenate variables (combine modalities)
adata = ad.concat([adata_rna, adata_protein], axis=1)

# Lazy collection over backed AnnData objects (experimental)
from anndata.experimental import AnnCollection

backed_adatas = [
    ad.read_h5ad(path, backed='r')
    for path in ['data1.h5ad', 'data2.h5ad']
]
collection = AnnCollection(
    backed_adatas,
    join_obs='outer',
    join_vars='inner',
    label='dataset'
)

4. Data Manipulation

Transform, subset, filter, and reorganize data efficiently.

See: references/manipulation.md for detailed guidance on:

• Subsetting (by indices, names, boolean masks, metadata conditions)
• Transposition
• Copying (full copies vs views)
• Renaming (observations, variables, categories)
• Type conversions (strings to categoricals, sparse/dense)
• Adding/removing data components
• Reordering
• Quality control filtering

Common commands:

# Subset by metadata
filtered = adata[adata.obs['quality_score'] > 0.8]
hv_genes = adata[:, adata.var['highly_variable']]

# Transpose an independent in-memory object; .raw is not retained
adata_T = adata.copy().T

# Copy vs view
view = adata[0:100, :]  # View (lightweight reference)
copy = adata[0:100, :].copy()  # Independent copy

# Convert strings to categoricals
adata.strings_to_categoricals()

5. Best Practices

Follow recommended patterns for memory efficiency, performance, and reproducibility.

See: references/best_practices.md for guidelines on:

• Memory management (sparse matrices, categoricals, backed mode)
• Views vs copies
• Data storage optimization
• Performance optimization
• Working with raw data
• Metadata management
• Reproducibility
• Error handling
• Integration with other tools
• Common pitfalls and solutions

Key recommendations:

# Use sparse matrices for sparse data
from scipy.sparse import csr_matrix
adata.X = csr_matrix(adata.X)

# Convert strings to categoricals
adata.strings_to_categoricals()

# Materialize a manageable backed subset before modifying it
source = ad.read_h5ad('large.h5ad', backed='r')
try:
    adata = source[:1000, :].to_memory()
finally:
    source.file.close()

# Snapshot current X/var before feature filtering (not automatically raw counts)
adata.raw = adata.copy()
adata = adata[:, adata.var['highly_variable']]

Integration with Scverse Ecosystem

AnnData serves as the foundational data structure for the scverse ecosystem:

Scanpy (Single-cell analysis)

Illustrative analysis; requires Scanpy and its selected clustering backend.

Choose QC thresholds and representations for the assay, and keep count provenance.

impor

… (full content is in the download package)