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 AnnData. Aplique essa habilidade para fluxos de trabalho 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. Destina-se ao Scanpy 1.12.4 (lançado em 27/08/2026), revisado em 01/10/2026. Testes sintéticos nativos estabelecem contratos de dados/API, não validade biológica.

Instalação

Requer Python 3.12+ (scanpy 1.12 removeu suporte a Python ≤3.11) e anndata ≥0.10.

uv pip install "scanpy[leiden]"

O extra [leiden] instala igraph e leidenalg; os scripts selecionam explicitamente flavor="igraph". Para ambientes reproduzíveis, fixe uma versão: uv pip install "scanpy[leiden]==1.12.4".

Para conjuntos de dados grandes ou fora da memória (out-of-core), muitas funções suportam arrays Dask (experimental):

uv pip install "scanpy[leiden]" dask

Veja o tutorial Usando dask com Scanpy. Para operações semelhantes ao scanpy aceleradas por GPU, 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), primeiro converta-o para .h5ad com ferramentas R, depois carregue-o com Scanpy. Leia references/r_interop.md para instruções de instalação e conversão executadas por agente em macOS, Linux e Windows.

Para detalhes sobre a estrutura e I/O do AnnData, use a habilidade anndata. Para modelos probabilísticos e correção de lotes (batch correction), use scvi-tools.

Contratos de Representação e Inferência

• A entrada para QC/pré-processamento deve ser contagens brutas identificadas. Os scripts rejeitam células negativas, fracionárias, não finitas ou com total zero. Use --counts-layer counts quando X já estiver normalizado; nunca infira a proveniência apenas de valores que parecem inteiros.
• layers["counts"] permanece não normalizado; .raw é um snapshot independente de log-normalização completa de genes. A subseleção de genes também subseleciona todas as camadas, mas não subseleciona genes .raw. Mantenha um objeto de genes completos para pseudobulk; o pipeline completo faz isso.
• HVGs seurat/cell_ranger usam valores log-normalizados; seurat_v3 e seurat_v3_paper usam contagens e requerem scanpy[skmisc]. Escalonamento/regressão são opcionais, podem densificar dados esparsos e podem remover biologia junto com covariáveis.
• A classificação de marcadores usa .raw por padrão quando presente; --no-use-raw seleciona X e --layer seleciona uma camada explícita log-normalizada. --groups/--reference controlam os contrastes. P-valores ajustados de Wilcoxon/t-test usam BH dentro de cada comparação; logreg retorna pontuações de classificação sem p-valores. Clusters escolhidos dos mesmos dados geram marcadores exploratórios.
• A DE de condição requer somas de contagens brutas por amostra e tipo celular, réplicas biológicas independentes, metadados de condição/doador alinhados e um design de posto completo (full-rank). Analise cada tipo celular separadamente; amostras de doadores repetidas requerem um design pareado adequado. A agregação não pode corrigir confundimento, falta de replicação, doublets ou anotações incorretas.
• Harmony (harmonypy) altera as coordenadas PCA; BBKNN (bbknn) altera o grafo; ComBat altera X. Mantenha a expressão/contagens originais para DE e avalie a conservação biológica e a mistura de lotes juntas. Falhas solicitadas de integração/doublet param.
• O kit de ferramentas carrega arquivos na memória. Para dados com backup (backed data), chame explicitamente .to_memory() em uma subseleção escolhida e feche o arquivo; o modo com backup não é um pipeline geral fora da memória. Copie visualizações antes da mutação. O suporte Dask varia por função/layout de array.
• .rds precisa de uma fase explícita de conversão R. IDs de cluster não determinam tipos celulares: todos os mapeamentos/ativos de assinatura são exemplos ilustrativos de marcadores humanos, exigindo revisão.

Harmony 2 retorna células x PCs; o kit de ferramentas chama sua API nativa porque o wrapper Scanpy 1.12.4 ainda transpõe essa saída e falha com o Harmony atual.

Pacotes opcionais: scikit-image para limiarização automática do Scrublet, loompy para Loom, scikit-misc para HVGs v3, harmonypy==2.0.2/bbknn==1.6.0 para seus branches de integração e louvain para a opção Louvain depreciada (ambiente separado: louvain 0.8.2 requer igraph <0.12, conflitando com o igraph 1.0 testado). Instale apenas os branches necessários. Os limites de execução de R e de integração opcional são registrados em references/upstream-review.md.

…