Scanpy: Análise de Célula Única
Visão Geral
Scanpy é um kit de ferramentas Python escalável para analisar dados de RNA-seq de célula única, construído sobre o AnnData. Aplique esta habilidade para workflows completos de célula única, incluindo controle de qualidade, normalização, redução de dimensionalidade, clusterização, identificação de genes marcadores, visualização e análise de trajetória. Versão estável atual: scanpy 1.12.x (Janeiro de 2026).
Instalação
Requer Python 3.12+ (scanpy 1.12 abandonou suporte a Python ≤3.11) e anndata ≥0.10.
uv pip install "scanpy[leiden]"
O extra [leiden] instala python-igraph e leidenalg, necessários para clusterização Leiden. Para ambientes reproduzíveis, fixe uma versão: uv pip install "scanpy[leiden]==1.12.1".
Para conjuntos de dados grandes ou fora do núcleo, muitas funções suportam arrays Dask (experimental):
uv pip install "scanpy[leiden]" dask
Veja o tutorial Usando Dask com Scanpy. Para operações aceleradas por GPU similares ao scanpy, use rapids-singlecell como um pacote separado.
Se a entrada for um objeto de célula única nativo do R (.rds, .RData, Seurat ou SingleCellExperiment), converta-o primeiro para .h5ad com ferramentas R e depois carregue-o com Scanpy. Leia references/r_interop.md para instruções de instalação e conversão executadas pelo agente em macOS, Linux e Windows.
Para detalhes sobre estrutura e I/O do AnnData, use a habilidade anndata. Para modelos probabilísticos e correção de lote, use scvi-tools.
Quando Usar Esta Habilidade
Esta habilidade deve ser usada quando:
- Analisando dados de RNA-seq de célula única (.h5ad, 10X, formatos CSV)
- Trabalhando com conjuntos de dados de célula única amigáveis ao R (
.rds,.RData, Seurat, SingleCellExperiment) que precisam de conversão para.h5ad - Realizando controle de qualidade em conjuntos de dados scRNA-seq
- Criando visualizações UMAP, t-SNE ou PCA
- Identificando clusters celulares e encontrando genes marcadores
- Anotando tipos celulares com base na expressão gênica
- Conduzindo inferência de trajetória ou análise de pseudotempo
- Gerando gráficos de célula única com qualidade de publicação
Kit de Scripts (Prefira Estes a Escrever Código do Zero)
Esta habilidade inclui scripts CLI prontos para execução em scripts/ para cada etapa comum. Execute estes scripts em vez de escrever código scanpy manualmente — eles lidam com carregamento de arquivos por extensão, configuração de figuras, padrões sensatos, preservação de contagens brutas e registro de progresso. Cada um lê e escreve .h5ad, então eles se encadeiam, e cada um tem seu próprio --help. Só recorra a escrever código scanpy quando uma tarefa não for coberta por um script ou precisar de customização incomum.
Todos os scripts usam um helper compartilhado scripts/_common.py (carregamento, salvamento, configuração de figuras) — mantenha-o junto com os outros. Execute a partir do diretório da habilidade ou forneça caminhos completos; as figuras padrão vão para ./figures/.
| Script | Propósito | Chamada Típica |
|---|---|---|
run_pipeline.py | Workflow completo em um comando: carregar → QC → normalizar → HVG → PCA → (lote) → UMAP → Leiden → marcadores | python scripts/run_pipeline.py raw.h5ad -o processed.h5ad |
inspect_data.py | Resumir um conjunto de dados desconhecido (forma, obs/var, camadas, o que já foi calculado, bruto vs normalizado) | python scripts/inspect_data.py data.h5ad |
convert.py | Carregar qualquer formato (dir 10x/.h5, csv, loom, mtx) e escrever .h5ad | python scripts/convert.py 10x_dir/ -o data.h5ad |
qc_analysis.py | Métricas de QC, gráficos antes/depois, filtragem, opcional Scrublet para doublets | python scripts/qc_analysis.py raw.h5ad -o qc.h5ad --scrublet |
preprocess.py | Normalizar, log1p, HVG, opcional escalar/regredir (mantém camada counts + raw) | python scripts/preprocess.py qc.h5ad -o norm.h5ad |
reduce_dimensions.py | PCA + gráfico de variância, vizinhos, UMAP, opcional t-SNE | python scripts/reduce_dimensions.py norm.h5ad -o red.h5ad |
batch_correct.py | Integração: harmony / bbknn / combat | python scripts/batch_correct.py red.h5ad -o int.h5ad --method harmony --batch-key sample |
cluster.py | Leiden (ou louvain) em uma ou várias resoluções | python scripts/cluster.py red.h5ad -o clu.h5ad --resolution 0.3 0.6 1.0 |
find_markers.py | rank_genes_groups + CSVs por grupo + gráficos de marcadores | python scripts/find_markers.py clu.h5ad --groupby leiden -o clu.h5ad |
annotate.py | Mapear clusters → tipos celulares a partir de JSON/CSV; gráfico dotplot de referência de marcadores opcional | python scripts/annotate.py clu.h5ad -o ann.h5ad --mapping map.json |
score_genes.py | Pontuar assinaturas gênicas (JSON) e/ou fase do ciclo celular | python scripts/score_genes.py ann.h5ad -o scored.h5ad --gene-sets sigs.json |
pseudobulk.py | Agregar contagens por amostra × tipo celular → matriz para pydeseq2 | python scripts/pseudobulk.py ann.h5ad --by sample cell_type --out-prefix pb |
subset.py | Subdividir por valores obs ou lista de genes (opcionalmente limpar embeddings obsoletos) | python scripts/subset.py ann.h5ad -o tcells.h5ad --obs cell_type --keep "T cells" |
plot.py | Gerar gráficos umap/tsne/pca/violin/dotplot/heatmap/etc. a partir de um objeto processado | python scripts/plot.py ann.h5ad --kind dotplot --genes CD3D CD14 --groupby cell_type |
Execução ponta a ponta em um comando
# Contagens → objeto clusterizado com marcadores anotados + figuras + CSVs de marcadores
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad \
--resolution 0.5 --n-top-genes 2000 --scrublet
# Com integração multi-amostra:
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --batch-key sample --batch-method harmony
# Parâmetros reproduzíveis via JSON (chaves espelham nomes de flags com underscores):
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --config params.json
Cadeia passo a passo (quando você precisa inspecionar/iterar entre etapas)
python scripts/qc_analysis.py raw.h5ad -o qc.h5ad --scrublet
python scripts/preprocess.py qc.h5ad -o norm.h5ad --n-top-genes 2000
python scripts/reduce_dimensions.py norm.h5ad -o red.h5ad --n-pcs 40
python scripts/cluster.py red.h5ad -o clu.h5ad --resolution 0.3 0.5 0.8
python scripts/find_markers.py clu.h5ad -o clu.h5ad --groupby leiden --use-raw
# inspecionar resultados/marcadores/*.csv, decidir rótulos, escrever um JSON de mapeamento, então:
python scripts/annotate.py clu.h5ad -o ann.h5ad --mapping celltypes.json
As seções abaixo documentam as chamadas scanpy subjacentes que cada script executa — leia-as ao customizar além das flags dos scripts.
Início Rápido
Importação e Configuração Básicas
import scanpy as sc
import pandas as pd
import numpy as np
# Configurar configurações
sc.settings.verbosity = 3
sc.settings.set_figure_params(dpi=80, facecolor='white')
sc.settings.figdir = './figures/'
sc.settings.autosave = True # Preferido em vez de salvar por gráfico (depreciado no scanpy 1.12)
Carregando Dados
# Do 10X Genomics
adata = sc.read_10x_mtx('caminho/para/dados/')
adata = sc.read_10x_h5('caminho/para/dados.h5')
# De h5ad (formato AnnData)
adata = sc.read_h5ad('caminho/para/dados.h5ad')
# De CSV
adata = sc.read_csv('caminho/para/dados.csv')
Para arquivos nativos do R, não tente analisar Seurat .rds diretamente em Python. Converta primeiro:
# Veja references/r_interop.md para instalar R e pacotes de conversão.
Rscript convert_rds_to_h5ad.R input.rds output.h5ad
adata = sc.read_h5ad('output.h5ad')
Entendendo a Estrutura AnnData
O objeto AnnData é a estrutura de dados central no scanpy:
adata.X # Matriz de expressão (células × genes)
adata.obs # Metadados das células (DataFrame)
adata.var # Metadados dos genes (DataFrame)
adata.uns # Anotações não estruturadas (dict)
adata.obsm # Dados celulares multidimensionais (PCA, UMAP)
adata.raw # Backup de dados brutos
# Acessar nomes de células e genes
adata.obs_names # Barcodes de células
adata.var_names # Nomes de genes
Workflow Padrão de Análise
As sete etapas, com código e os parâmetros importantes em cada uma, estão em references/analysis_workflow.md:
- Controle de qualidade — filtrar células e genes; inspecionar fração mitocondrial e contagens antes de escolher limites, em vez de copiar padrões.
- Normalização e pré-processamento — normalizar, transformar log, selecionar genes altamente
variáveis e manter
.rawpara plotagem posterior. - Redução de dimensionalidade — PCA, depois o grafo de vizinhos, depois UMAP.
- Clusterização — Leiden com uma resolução escolhida para a questão, não o padrão.
- Identificação de genes marcadores — genes ranqueados por cluster.
- Anotação de tipos celulares — mapear clusters para tipos a partir de marcadores.
- Salvar resultados — escrever o
AnnDataanotado.
Tarefas comuns de acompanhamento — gráficos para publicação, inferência de trajetória, expressão diferencial pseudobulk entre condições, pontuação de conjuntos de genes e correção de lote — estão no mesmo arquivo. Veja também references/standard_workflow.md e references/plotting_guide.md.
Principais Parâmetros para Ajustar
Controle de Qualidade
min_genes: Mínimo de genes por célula (tipicamente 200-500)min_cells: Mínimo de células por gene (tipicamente 3-10)pct_counts_mt: Limiar mitocondrial (tipicamente 5-20%)
Normalização
target_sum: Soma alvo por célula (padrão 1e4)
Seleção de Características
n_top_genes: Número de HVGs (tipicamente 2000-3000)min_mean,max_mean,min_disp: Parâmetros de seleção HVG
Redução de Dimensionalidade
n_pcs: Número de componentes principais (verifique o gráfico de razão de variância)n_neighbors: Número de vizinhos (tipicamente 10-30)
Clusterização
resolution: Granularidade da clusterização (0.4-1.2, maior = mais clusters)
Armadilhas Comuns e Melhores Práticas
- Sempre salve contagens brutas:
adata.raw = adataantes de filtrar genes - Verifique os gráficos de QC cuidadosamente: Ajuste limites com base na qualidade do conjunto de dados
- Use clusterização Leiden:
sc.tl.louvainestá depreciado no scanpy 1.12 - Tente múltiplas resoluções de clusterização: Encontre a granularidade ideal
- Valide as anotações de tipos celulares: Use múltiplos genes marcadores
- Use
use_raw=Truepara gráficos de expressão gênica: Mostra contagens normalizadas de.raw - Verifique a razão de variância do PCA: Determine o número ideal de PCs
- Salve resultados intermediários: Workflows longos podem falhar no meio do caminho
- Pseudobulk para DE: Não trate os valores-p de
rank_genes_groupscomo DE rigoroso entre condições - Salve gráficos via configurações: Use
sc.settings.autosaveem vez dosave=depreciado nas funções de plotagem - Converta objetos R antes do Scanpy: Use pacotes R para converter arquivos Seurat ou SingleCellExperiment
.rdspara.h5ad, preservando contagens, metadados e identificadores de genes
Recursos Inclusos
scripts/ (Kit de ferramentas CLI)
Um conjunto combinável de scripts de entrada/saída .h5ad cobrindo todo o workflow, além de um pipeline ponta a ponta em um comando. Veja a seção Kit de Scripts acima para a tabela completa e exemplos de encadeamento. Cada script tem --help. Arquivos:
_common.py— helpers compartilhados de carregamento/salvamento/figuras importados pelos outros (não é CLI)run_pipeline.py— pipeline completo em um comando (flags ou--configJSON)inspect_data.py,convert.py— explorar e carregar/converter qualquer formato de entradaqc_analysis.py,preprocess.py,reduce_dimensions.py,batch_correct.py,cluster.py— etapas do pipelinefind_markers.py,annotate.py,score_genes.py,pseudobulk.py— marcadores, anotação, pontuação, preparação DEsubset.py,plot.py— subdividir por metadados/genes; gerar qualquer gráfico padrão
Prefira estes scripts antes de escrever código scanpy do zero.
references/standard_workflow.md
Workflow passo a passo completo com explicações detalhadas e exemplos de código para:
- Carregamento e configuração de dados
- Controle de qualidade com visualização
- Normalização e escalonamento
- Seleção de características
- Redução de dimensionalidade (PCA, UMAP, t-SNE)
- Clusterização (Leiden)
- Detecção de doublets (scrublet) e agregação pseudobulk
- Identificação de genes marcadores
- Anotação de tipos celulares
- Inferência de trajetória
- Expressão diferencial
Leia esta referência ao realizar uma análise completa do zero.
references/api_reference.md
Guia de referência rápida para funções scanpy organizadas por módulo:
- Leitura/escrita de dados (
sc.read_*,adata.write_*) - Pré-processamento (
sc.pp.*) - Ferramentas (
sc.tl.*) - Plotagem (
sc.pl.*) - Estrutura e manipulação AnnData
- Configurações e utilitários
Use este guia para consulta rápida de assinaturas de funções e parâmetros comuns.
references/plotting_guide.md
Guia abrangente de visualização incluindo:
- Gráficos de controle de qualidade
- Visualizações de redução de dimensionalidade
- Visualizações de clusterização
- Gráficos de genes marcadores (heatmaps, dot plots, violin plots)
- Gráficos de trajetória e pseudotempo
- Customização para qualidade de publicação
- Figuras com múltiplos painéis
- Paletas de cores e estilização
Consulte este guia ao criar figuras prontas para publicação.
references/r_interop.md
Manual do agente para instalar R no macOS, Linux e Windows, instalar pacotes de conversão CRAN/Bioconductor, inspecionar entradas .rds/.RData, converter objetos Seurat ou SingleCellExperiment para .h5ad e validar o resultado no Scanpy.
assets/analysis_template.py
Modelo de análise completo fornecendo um workflow completo desde o carregamento de dados até a anotação de tipos celulares. Copie e customize este modelo para novas análises:
cp assets/analysis_template.py my_analysis.py
# Edite parâmetros e execute
python my_analysis.py
O modelo inclui todas as etapas padrão com parâmetros configuráveis e comentários úteis.
Modelos JSON em assets/
Modelos para editar e passar, para que você não precise criar configurações/mapeamentos do zero:
assets/pipeline_config.json— conjunto de parâmetros pararun_pipeline.py --configassets/celltype_mapping.json— mapa cluster → tipo celular paraannotate.py --mappingassets/gene_signatures.json— assinaturas de conjuntos de genes parascore_genes.py --gene-sets
Recursos Adicionais
- Documentação oficial do scanpy: https://scanpy.scverse.org/en/stable/
- Tutoriais do Scanpy: https://