alterlab-anndata

Files (7)

• SKILL.md
• evals.json · evals/
• best_practices.md · references/
• concatenation.md · references/
• data_structure.md · references/
• io_operations.md · references/
• manipulation.md · references/

SKILL.md (first lines)

# 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

### Does NOT Trigger

| Scenario | Use Instead |
|----------|-------------|
| QC, normalization, HVG, clustering, UMAP, or marker genes | `alterlab-scanpy` |
| RNA velocity from spliced/unspliced layers | `alterlab-scvelo` |
| Deep generative models / batch integration (scVI, scANVI) | `alterlab-scvi-tools` |
| Querying the public CELLxGENE Census for reference cells | `alterlab-cellxgene` |
| Chunked n-dimensional arrays outside the AnnData model | `alterlab-zarr` |

## Installation

```bash
uv pip install anndata          # 0.13.x as of 2026-09; needs Python >= 3.12

# Lazy/backed reads (ad.experimental.read_lazy) need dask + xarray:
uv pip install 'anndata[lazy]'   # or 'anndata[dask]' for dask-backed arrays only
```

### What changed in 0.13 (breaking)

These bite existing scripts, so check them before running older code:

- **`AnnData.concatenate()` is gone** — use the module-level `ad.concat([...])`.
- **`.X` is copy-on-write** like `layers`/`obsm`: writing into a subset (`view.X = 0`) no
  longer propagates to the parent object. `.X` is now stored as `layers[None]`, so it shows
  up in the repr and in `.layers.keys()`.
- **The `dtype=` argument to the `AnnData` constructor was removed** — cast `X` yourself.
- **zarr v3 only** (`zarr >= 3.1`); writing the v2 format is deprecated as of 0.13.4 and
  goes away in 0.14. Stores are written sharded by default.
- **`anndata.__version__` and the `adata.*_keys()` methods are deprecated** — use
  `importlib.metadata.version("anndata")` and `sorted(adata.obs)` / `k in adata.uns`.
- **Loom I/O is deprecated** (`ad.io.read_loom`, `adata.write_loom`) in favour of h5ad/zarr.

## 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
import scanpy as sc  # 10x readers live in scanpy, not anndata

# Read h5ad file
adata = ad.read_h5ad('data.h5ad')

# Read with backed mode (for large files)
adata = ad.read_h5ad('large_data.h5ad', backed='r')

# Read other formats (these live under ad.io as of anndata 0.11)
adata = ad.io.read_csv('data.csv')
adata = ad.io.read_mtx('matrix.mtx')
adata = sc.read_10x_h5('filtered_feature_bc_matrix.h5')
```

> **API namespaces (anndata >= 0.11)**: all format readers/writers live in the
> `anndata.io` module (`ad.io.read_csv`, `ad.io.read_mtx`, `ad.io.read_loom`,
> `ad.io.read_elem`, ...). The top-level `ad.read_csv`-style aliases still resolve
> but emit a `FutureWarning` (upgraded from `DeprecationWarning` in 0.12), and
> `anndata.read` was removed in 0.12. **Exceptions**: `ad.read_h5ad`, `ad.read_zarr`,
> `adata.write_h5ad`, and `adata.write_zarr` stay top-level with no warning.
>
> **10x readers** (`read_10x_h5`, `read_10x_mtx`) live in **scanpy**
> (`sc.read_10x_h5`), not anndata — this skill defers analysis-specific I/O to scanpy.

### Writing data
```python
# 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')                  # zarr v3, sharded by default
adata.write_csvs('output_dir/', skip_data=False)  # skip_data defaults to True (obs/var only)
```

### Basic operations
```python
# Subset by conditions
t_cells = adata[adata.obs['cell_type'] == 'T cell']

From AlterLab-IEU/AlterLab-Academic-Skills, MIT.

More from AlterLab-IEU/AlterLab-Academic-Skills