AnnData

Visão Geral

AnnData é um pacote Python para lidar com matrizes de dados anotadas, armazenando medições experimentais (X) juntamente com metadados de observação (obs), metadados de variável (var) e anotações multidimensionais (obsm, varm, obsp, varp, uns). Originalmente projetado para genômica de célula única através do Scanpy, agora serve como um framework de propósito geral para qualquer dado anotado que exija armazenamento, manipulação e análise eficientes.

Quando Usar Esta Habilidade

Use esta habilidade quando:

• Criar, ler ou escrever objetos AnnData
• Trabalhar com formatos de dados genômicos h5ad, zarr ou outros
• Realizar análise de RNA-seq de célula única
• Gerenciar grandes conjuntos de dados com matrizes esparsas ou modo "backed"
• Concatenar múltiplos conjuntos de dados ou lotes experimentais
• Subconjuntar, filtrar ou transformar dados anotados
• Integrar com scanpy, scvi-tools ou outras ferramentas do ecossistema scverse

Instalação

Visa AnnData 0.13.4 (último lançamento do PyPI revisado em 2026-09-30), requerendo Python 3.12+. Pequenas verificações sintéticas cobrem matrizes densas/esparsas, I/O nativo, metadados, concatenação e leituras preguiçosas. Caminhos de arquivo, análise biológica, armazenamentos remotos e exemplos de integração de terceiros são ilustrativos, a menos que declarado de outra forma.

uv pip install "anndata==0.13.4"

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

Use instalações sem "pin" apenas quando estiver rastreando intencionalmente o último lançamento compatível.

Notas da API atual:

• Use anndata.io para helpers não nativos de read_* e write_*. anndata.read_h5ad e anndata.read_zarr de nível superior permanecem suportados.
• Use ad.concat; AnnData.concatenate() foi removido em 0.13. Evite helpers antigos de ad.read, obsoletos AnnData.*_keys() e anndata.__version__; prefira leitores explícitos, mapeamento .keys() e importlib.metadata.version("anndata").
• Em 0.13, .X também é layers[None]; a iteração de camadas inclui None. Use key is not None ao selecionar camadas nomeadas. Gravações de visualização .X agora usam cópia em gravação.
• Zarr v3 e sharding automático são os padrões; a dependência Python é Zarr >=3. H5AD denso X continua gravável com backed="r+", mas atribuição de item esparso "backed" não é suportada em 0.13.
• Leitura/escrita de AnnLoader e Loom estão obsoletas. AnnCollection e outras APIs experimentais precisam das ressalvas nas referências.

Essas mudanças são documentadas nas notas oficiais de lançamento. O cabeçalho da documentação ao vivo ainda exibia 0.13.3.post0 na revisão; o comportamento abaixo também foi verificado contra o código fonte instalado 0.13.4.

Início Rápido

Criando um objeto AnnData

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)

Lendo dados

# 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/')

Escrevendo dados

# 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

Operações básicas

# Subconjunto por condições
t_cells = adata[adata.obs['cell_type'] == 'T cell']

# Subconjunto por índices
subset = adata[0:50, 0:100]

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

# Acessar dimensões
print(f"{adata.n_obs} observações × {adata.n_vars} variáveis")

…