Communitygithub.com

scanpy

Pipeline padrão de análise de RNA-seq de célula única. Use para QC, normalização, redução de dimensionalidade (PCA/UMAP/t-SNE), clusterização, expressão diferencial, visualização e conversão de formatos amigáveis ao R, como arquivos Seurat ou SingleCellExperiment RDS, para h5ad para o Scanpy. Ideal para análises exploratórias de scRNA-seq com workflows estabelecidos. Para modelos de deep learning, use o scvi-tools; para dúvidas sobre formato de dados, use o anndata.

O que é scanpy?

O Scanpy é um kit de ferramentas Python escalável para análise de dados de RNA-seq de célula única, construído sobre o AnnData. Esta habilidade fornece um pipeline completo e modular, ideal para análises exploratórias padrão, abrangendo desde controle de qualidade, normalização, redução de dimensionalidade (PCA, UMAP, t-SNE), clusterização (Leiden), identificação de genes marcadores, anotação de tipos celulares, até análise de trajetória e expressão diferencial pseudobulk. O que torna esta habilidade especialmente produtiva é seu conjunto de scripts CLI prontos para uso (em `scripts/`), que encapsulam cada etapa do workflow — o usuário pode executar o pipeline completo com um único comando ou encadear etapas individuais, evitando a necessidade de escrever código Scanpy do zero para tarefas comuns. A habilidade também inclui referências detalhadas e modelos de arquivos JSON para configuração de parâmetros e mapeamento de tipos celulares, agilizando a customização. O Scanpy é a melhor escolha para workflows estabelecidos e reprodutíveis de scRNA-seq; para modelos probabilísticos e correção de lote avançada, recomenda-se o scvi-tools, e para manipulação da estrutura AnnData, a habilidade anndata.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/skills/scanpy

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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/.

ScriptPropósitoChamada Típica
run_pipeline.pyWorkflow completo em um comando: carregar → QC → normalizar → HVG → PCA → (lote) → UMAP → Leiden → marcadorespython scripts/run_pipeline.py raw.h5ad -o processed.h5ad
inspect_data.pyResumir 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.pyCarregar qualquer formato (dir 10x/.h5, csv, loom, mtx) e escrever .h5adpython scripts/convert.py 10x_dir/ -o data.h5ad
qc_analysis.pyMétricas de QC, gráficos antes/depois, filtragem, opcional Scrublet para doubletspython scripts/qc_analysis.py raw.h5ad -o qc.h5ad --scrublet
preprocess.pyNormalizar, log1p, HVG, opcional escalar/regredir (mantém camada counts + raw)python scripts/preprocess.py qc.h5ad -o norm.h5ad
reduce_dimensions.pyPCA + gráfico de variância, vizinhos, UMAP, opcional t-SNEpython scripts/reduce_dimensions.py norm.h5ad -o red.h5ad
batch_correct.pyIntegração: harmony / bbknn / combatpython scripts/batch_correct.py red.h5ad -o int.h5ad --method harmony --batch-key sample
cluster.pyLeiden (ou louvain) em uma ou várias resoluçõespython scripts/cluster.py red.h5ad -o clu.h5ad --resolution 0.3 0.6 1.0
find_markers.pyrank_genes_groups + CSVs por grupo + gráficos de marcadorespython scripts/find_markers.py clu.h5ad --groupby leiden -o clu.h5ad
annotate.pyMapear clusters → tipos celulares a partir de JSON/CSV; gráfico dotplot de referência de marcadores opcionalpython scripts/annotate.py clu.h5ad -o ann.h5ad --mapping map.json
score_genes.pyPontuar assinaturas gênicas (JSON) e/ou fase do ciclo celularpython scripts/score_genes.py ann.h5ad -o scored.h5ad --gene-sets sigs.json
pseudobulk.pyAgregar contagens por amostra × tipo celular → matriz para pydeseq2python scripts/pseudobulk.py ann.h5ad --by sample cell_type --out-prefix pb
subset.pySubdividir 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.pyGerar gráficos umap/tsne/pca/violin/dotplot/heatmap/etc. a partir de um objeto processadopython 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:

  1. Controle de qualidade — filtrar células e genes; inspecionar fração mitocondrial e contagens antes de escolher limites, em vez de copiar padrões.
  2. Normalização e pré-processamento — normalizar, transformar log, selecionar genes altamente variáveis e manter .raw para plotagem posterior.
  3. Redução de dimensionalidade — PCA, depois o grafo de vizinhos, depois UMAP.
  4. Clusterização — Leiden com uma resolução escolhida para a questão, não o padrão.
  5. Identificação de genes marcadores — genes ranqueados por cluster.
  6. Anotação de tipos celulares — mapear clusters para tipos a partir de marcadores.
  7. Salvar resultados — escrever o AnnData anotado.

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

  1. Sempre salve contagens brutas: adata.raw = adata antes de filtrar genes
  2. Verifique os gráficos de QC cuidadosamente: Ajuste limites com base na qualidade do conjunto de dados
  3. Use clusterização Leiden: sc.tl.louvain está depreciado no scanpy 1.12
  4. Tente múltiplas resoluções de clusterização: Encontre a granularidade ideal
  5. Valide as anotações de tipos celulares: Use múltiplos genes marcadores
  6. Use use_raw=True para gráficos de expressão gênica: Mostra contagens normalizadas de .raw
  7. Verifique a razão de variância do PCA: Determine o número ideal de PCs
  8. Salve resultados intermediários: Workflows longos podem falhar no meio do caminho
  9. Pseudobulk para DE: Não trate os valores-p de rank_genes_groups como DE rigoroso entre condições
  10. Salve gráficos via configurações: Use sc.settings.autosave em vez do save= depreciado nas funções de plotagem
  11. Converta objetos R antes do Scanpy: Use pacotes R para converter arquivos Seurat ou SingleCellExperiment .rds para .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 --config JSON)
  • inspect_data.py, convert.py — explorar e carregar/converter qualquer formato de entrada
  • qc_analysis.py, preprocess.py, reduce_dimensions.py, batch_correct.py, cluster.py — etapas do pipeline
  • find_markers.py, annotate.py, score_genes.py, pseudobulk.py — marcadores, anotação, pontuação, preparação DE
  • subset.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 para run_pipeline.py --config
  • assets/celltype_mapping.json — mapa cluster → tipo celular para annotate.py --mapping
  • assets/gene_signatures.json — assinaturas de conjuntos de genes para score_genes.py --gene-sets

Recursos Adicionais

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

adaptyv

How to use the Adaptyv Bio Foundry API and Python SDK for protein experiment design, submission, and results retrieval. Use this skill whenever the user mentions Adaptyv, Foundry API, protein binding assays, protein screening experiments, BLI/SPR assays, thermostability assays, or wants to submit protein sequences for experimental characterization. Also trigger when code imports `adaptyv`, `adaptyv_sdk`, or `FoundryClient`, or references `foundry-api-public.adaptyvbio.com`.

aeon

This skill should be used for time series machine learning tasks including classification, regression, clustering, forecasting, anomaly detection, segmentation, and similarity search. Use when working with temporal data, sequential patterns, or time-indexed observations requiring specialized algorithms beyond standard ML approaches. Particularly suited for univariate and multivariate time series analysis with scikit-learn compatible APIs.

alphagenome

Look up precomputed AlphaGenome Atlas effects for any GRCh38 single-nucleotide variant (AVI score with Phred and 18 SHAP feature attributions, plus raw and quantile scores for RNA-seq, DNase, ATAC, ChIP-TF, ChIP-histone, CAGE, PRO-cap, splicing, polyadenylation and contact-map tracks), score variants or scan windows on demand with the AlphaGenome model for human and mouse (variant scoring, in silico mutagenesis, REF-versus-ALT track prediction), and build Atlas website deep links. Use when the user mentions AlphaGenome, AlphaGenome Atlas, AVI or AlphaGenome Variant Impact, DeepMind variant effect prediction, or wants to prioritise or mechanistically interpret non-coding, regulatory, splicing, enhancer, promoter, or chromatin-accessibility effects of SNVs from a VCF, credible set, or region. Research use only; not a clinical tool.

analytical-method-validation

Plan, execute, and document validation, verification, and transfer of analytical procedures under the governing framework - ICH Q2(R2) and Q14, USP <1220>/<1225>/<1226>, ICH M10 bioanalytical, CLSI EP, or ISO/IEC 17025. Use for HPLC, LC-MS/MS, GC, CE, ICP-MS, dissolution, qNMR, qPCR, NIR, and ligand binding or cell-based assays whenever the question is whether a procedure is fit for its intended purpose. Triggers include

anndata

Data structure for annotated matrices in single-cell analysis. Use when working with .h5ad files or integrating with the scverse ecosystem. This is the data format skill—for analysis workflows use scanpy; for probabilistic models use scvi-tools; for population-scale queries use cellxgene-census.

arbor

Autonomously improve a real artifact (code, training recipe, agent harness, data pipeline, prompt) against an objective and an evaluator, using Hypothesis Tree Refinement (HTR) from the Arbor paper. Use this whenever someone wants to iteratively optimize something over many experiments without overfitting — e.g.

arboreto

Infer gene regulatory networks (GRNs) from gene expression data using scalable algorithms (GRNBoost2, GENIE3). Use when analyzing transcriptomics data (bulk RNA-seq, single-cell RNA-seq) to identify transcription factor-target gene relationships and regulatory interactions. Supports distributed computation for large-scale datasets.

astropy

Core Python library for astronomy and astrophysics workflows that need Astropy APIs, including units/quantities, coordinates, FITS I/O, tables, time systems, WCS, and cosmology. Use when implementing or debugging astronomical data analysis code with Astropy.

autoskill

Observe the user

benchling-integration

Benchling Python SDK and REST API integration for registry entities, inventory, ELN entries, workflows, Benchling Apps, and Data Warehouse queries. Use when automating lab data with benchling-sdk or the v2 API.

bgpt-paper-search

Search scientific papers and retrieve structured experimental data extracted from full-text studies via the BGPT MCP server. Returns 25+ fields per paper including methods, results, sample sizes, quality scores, and conclusions. Use for literature reviews, evidence synthesis, and finding experimental details not available in abstracts alone.

bids

>

biopython

Comprehensive molecular biology toolkit. Use for sequence manipulation, file parsing (FASTA/GenBank/PDB), phylogenetics, and programmatic NCBI/PubMed access (Bio.Entrez). Best for batch processing, custom bioinformatics pipelines, BLAST automation. For quick lookups use gget; for multi-service integration use bioservices.

bioservices

Unified Python interface to 40+ bioinformatics services. Use when querying multiple databases (UniProt, KEGG, ChEMBL, Reactome) in a single workflow with consistent API. Best for cross-database analysis, ID mapping across services. For quick single-database lookups use gget; for sequence/file manipulation use biopython.

bulk-rnaseq

End-to-end bulk RNA-seq orchestrator — takes raw FASTQ reads through QC and trimming (FastQC, fastp/Trim Galore), alignment and quantification (STAR, Salmon, featureCounts), assembles a gene-level counts matrix, then hands off to differential expression (pydeseq2), pathway/GSEA enrichment (pathway-enrichment), and publication figures (scientific-visualization). Use whenever the user has bulk RNA-seq reads or quant output and wants a complete, reproducible differential-expression workflow — e.g.

cellxgene-census

Query the CZ CELLxGENE Census programmatically for versioned public single-cell and spatial transcriptomics data. Use when you need population-scale cell metadata, gene expression slices, Census summary counts, source H5AD URIs/downloads, embeddings, spatial Census data, or reference atlas comparisons across organisms, tissues, diseases, assays, and cell types. For analyzing your own local single-cell data use scanpy, anndata, or scvi-tools.

cirq

Google quantum computing framework. Use when targeting Google Quantum AI hardware, designing noise-aware circuits, or running quantum characterization experiments. Best for Google hardware, noise modeling, and low-level circuit design. For IBM hardware use qiskit; for quantum ML with autodiff use pennylane; for physics simulations use qutip.

citation-management

Comprehensive citation management for academic research. Search OpenAlex, PubMed, and Google Scholar for papers, extract accurate metadata, validate citations, and generate properly formatted BibTeX entries. This skill should be used when you need to find papers, verify citation information, convert DOIs to BibTeX, or ensure reference accuracy in scientific writing.

clinical-decision-support

Prepare and validate research-only clinical decision-support evaluation, evidence-profile, cohort, survival, biomarker/model, privacy, and governance artifacts. Use for aggregate or synthetic research documentation and traceability—not patient care or live clinical operation.

clinical-reports

Create safety-bounded draft structures and run local deterministic checks for clinical case, diagnostic, trial, safety, and aggregate research reports. Use only with synthetic, de-identified, or aggregate inputs and verified source-fact manifests; every output requires qualified review.

Habilidades Relacionadas