domains / data / anndata-io-manipulation / anndata

anndata

Skill card

combined

The K-Dense copy is the most current and technically precise, containing specific 0.13.4 API changes (e.g., `anndata.io` module, removal of `AnnData.concatenate`, Zarr v3 defaults) that the other two lack. However, the aipoch and FreedomIntelligence copies provide a more complete 'runnable' example workflow (including `ad.concat` and `strings_to_categoricals`) and a clearer 'When to Use' section that the K-Dense copy truncates or omits in its quick start. Because the K-Dense copy is the only one with the critical version-specific API constraints, but the others have better pedagogical examples, crowning one would hide either the version safety or the workflow completeness.

Repositories

Other copies

Combined skill

---
name: anndata
description: Handles annotated matrices in single-cell analysis, .h5ad and Zarr files, and integration with the scverse ecosystem.
license: MIT
---

# AnnData

## When to Use
Use this skill when:
- Creating, reading, or writing AnnData objects.
- Working with h5ad, zarr, or other genomics data formats.
- Managing large datasets with sparse matrices or backed mode.
- Concatenating multiple datasets or experimental batches.
- Integrating with scanpy, scvi-tools, or other scverse ecosystem tools.

## Installation
Targets AnnData 0.13.4+ (Python 3.12+).

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

## API Notes (0.13+)
- 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.
- In 0.13, `.X` is also `layers[None]`. Use `key is not None` when selecting named layers.
- Zarr v3 is the default.

## Quick Start

### Creating an AnnData object
```python
import anndata as ad
import numpy as np
import pandas as pd
from scipy.sparse import csr_matrix

X = np.random.rand(100, 2000)
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)
adata.strings_to_categoricals()
```

### Reading and Writing
```python
# Native formats
adata = ad.read_h5ad('data.h5ad')
adata.write_h5ad('output.h5ad', compression='gzip')

# Other formats (prefer anndata.io)
from anndata.io import read_csv, read_loom
adata = read_csv('data.csv')
```

### Backed Mode
```python
source = ad.read_h5ad('large_data.h5ad', backed='r')
try:
    subset = source[:100, :].to_memory()
finally:
    source.file.close()
```

### Concatenation
```python
combined = ad.concat(
    [adata1, adata2],
    axis=0,
    join='inner',
    label='batch',
    keys=['A', 'B']
)
```

## Core Capabilities
1. **Data Structure**: X, obs, var, layers, obsm, varm, obsp, varp, uns, raw.
2. **I/O Operations**: h5ad, zarr, CSV, MTX, Loom, 10X (via scanpy).
3. **Concatenation**: `ad.concat` with join/merge strategies.
4. **Manipulation**: Subsetting, transposition, copying, type conversions.
5. **Best Practices**: Sparse matrices, categoricals, backed mode for large data.