anndata

# 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 Requires Python 3.11+. Current stable release: 0.12.16 (released 2026-05-18). ```bash uv pip install "anndata==0.12.16" # Lazy I/O and dask-backed operations uv pip install "anndata[dask,lazy]==0.12.16" # Development / docs (contributors) uv pip install "anndata[dev,test,doc]==0.12.16" ``` 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. - Avoid deprecated APIs: `ad.read`, `AnnData.concatenate()`, `AnnData.*_keys()`, and `anndata.__version__`. Prefer `ad.read_h5ad`, `ad.concat`, mapping `.keys()`, and `importlib.metadata.version("anndata")`. - Treat `anndata.experimental` APIs as useful but unstable. Prefer them for large-data workflows only when their current caveats are acceptable. ## Quick Start ### Creating an AnnData object ```python 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 ```python # Native formats (read_h5ad/read_zarr remain at top-level) adata = ad.read_h5ad('data.h5ad') adata = ad.read_h5ad('large_data.h5ad', backed='r') # lazy load for large files 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 ```python # Write h5ad file