scanpy

Scanpy: Análisis de Célula Única

Resumen

Scanpy es un toolkit escalable en Python para analizar datos de scRNA-seq, construido sobre AnnData. Aplica esta skill para flujos de trabajo completos de célula única, incluyendo control de calidad, normalización, reducción de dimensionalidad, agrupamiento, identificación de genes marcadores, visualización y análisis de trayectorias. Versión estable actual: scanpy 1.12.x (enero 2026).

Instalación

Requiere Python 3.12+ (scanpy 1.12 eliminó el soporte para Python ≤3.11) y anndata ≥0.10.

uv pip install "scanpy[leiden]"

El extra [leiden] instala python-igraph y leidenalg, necesarios para el agrupamiento Leiden. Para entornos reproducibles, fija una versión: uv pip install "scanpy[leiden]==1.12.1".

Para conjuntos de datos grandes o fuera del núcleo, muchas funciones admiten arrays de Dask (experimental):

uv pip install "scanpy[leiden]" dask

Consulta el tutorial Usando dask con Scanpy. Para operaciones similares a Scanpy aceleradas por GPU, usa rapids-singlecell como paquete independiente.

Si la entrada es un objeto nativo de R de célula única (.rds, .RData, Seurat o SingleCellExperiment), conviértelo primero a .h5ad con herramientas de R, luego cárgalo con Scanpy. Lee references/r_interop.md para instrucciones de instalación y conversión ejecutadas por agentes en macOS, Linux y Windows.

Para detalles sobre la estructura e I/O de AnnData, usa la skill anndata. Para modelos probabilísticos y corrección por lotes, usa scvi-tools.

Cuándo Usar Esta Skill

Esta skill debe usarse cuando:

• Se analizan datos de scRNA-seq (h5ad, 10X, formatos CSV)
• Se trabaja con conjuntos de datos de célula única de R (.rds, .RData, Seurat, SingleCellExperiment) que requieren conversión a .h5ad
• Se realiza control de calidad en conjuntos de datos scRNA-seq
• Se crean visualizaciones UMAP, t-SNE o PCA
• Se identifican grupos de células y se encuentran genes marcadores
• Se anotan tipos celulares basados en expresión génica
• Se realiza inferencia de trayectorias o análisis de pseudotiempo
• Se generan gráficos de célula única de calidad para publicación

Toolkit de Scripts (prefiere estos a escribir código desde cero)

Esta skill incluye scripts CLI listos para ejecutar en scripts/ para cada paso común. Ejecuta estos en lugar de escribir código scanpy a mano — manejan la carga de archivos por extensión, configuración de figuras, valores predeterminados sensatos, preservación de cuentas brutas y registro de progreso. Cada uno lee y escribe .h5ad, por lo que se encadenan, y cada uno tiene su propio --help. Solo recurre a escribir código scanpy cuando una tarea no esté cubierta por un script o necesite una personalización inusual.

Todos los scripts usan un helper compartido scripts/_common.py (carga, guardado, configuración de figuras) — mantenlo junto a los demás. Ejecuta desde el directorio de la skill o pasa rutas completas; las figuras por defecto van a ./figures/.

Script	Propósito	Llamada típica
run_pipeline.py	Flujo de trabajo completo en un comando: carga → QC → normaliza → HVG → PCA → (lote) → UMAP → Leiden → marcadores	python scripts/run_pipeline.py raw.h5ad -o processed.h5ad
inspect_data.py	Resume un conjunto de datos desconocido (forma, obs/var, capas, qué está ya calculado, bruto vs normalizado)	python scripts/inspect_data.py data.h5ad
convert.py	Carga cualquier formato (directorio 10x/.h5, csv, loom, mtx) y escribe .h5ad	python scripts/convert.py 10x_dir/ -o data.h5ad
qc_analysis.py	Métricas de QC, gráficos antes/después, filtrado, dobletes opcionales con Scrublet	python scripts/qc_analysis.py raw.h5ad -o qc.h5ad --scrublet
preprocess.py	Normaliza, log1p, HVG, escala/regresa opcional (mantiene la capa counts + raw)	python scripts/preprocess.py qc.h5ad -o norm.h5ad
reduce_dimensions.py	PCA + gráfico de varianza, vecinos, UMAP, t-SNE opcional	python scripts/reduce_dimensions.py norm.h5ad -o red.h5ad
batch_correct.py	Integración: harmony / bbknn / combat	python scripts/batch_correct.py red.h5ad -o int.h5ad --method harmony --batch-key sample
cluster.py	Leiden (o louvain) a una o varias resoluciones	python scripts/cluster.py red.h5ad -o clu.h5ad --resolution 0.3 0.6 1.0
find_markers.py	rank_genes_groups + CSV por grupo + gráficos de marcadores	python scripts/find_markers.py clu.h5ad --groupby leiden -o clu.h5ad
annotate.py	Mapa de grupos → tipos celulares desde JSON/CSV; dotplot de referencia de marcadores opcional	python scripts/annotate.py clu.h5ad -o ann.h5ad --mapping map.json
score_genes.py	Puntúa firmas génicas (JSON) y/o fase del ciclo celular	python scripts/score_genes.py ann.h5ad -o scored.h5ad --gene-sets sigs.json
pseudobulk.py	Agrega cuentas por muestra × tipo celular → matriz para pydeseq2	python scripts/pseudobulk.py ann.h5ad --by sample cell_type --out-prefix pb
subset.py	Subconjunto por valores de obs o lista de genes (opcionalmente limpia incrustaciones obsoletas)	python scripts/subset.py ann.h5ad -o tcells.h5ad --obs cell_type --keep "T cells"
plot.py	Genera umap/tsne/pca/violin/dotplot/heatmap/etc. a partir de un objeto procesado	python scripts/plot.py ann.h5ad --kind dotplot --genes CD3D CD14 --groupby cell_type

Ejecución completa de una sola vez

# Cuentas → objeto agrupado y anotado con marcadores + figuras + CSV de marcadores
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad \
    --resolution 0.5 --n-top-genes 2000 --scrublet
# Con integración de múltiples muestras:
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --batch-key sample --batch-method harmony
# Parámetros reproducibles vía JSON (las claves reflejan los nombres de las banderas con guiones bajos):
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --config params.json

Cadena paso a paso (cuando necesites inspeccionar/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
# inspecciona resultados/marcadores/*.csv, decide etiquetas, escribe un JSON de mapeo, luego:
python scripts/annotate.py           clu.h5ad  -o ann.h5ad  --mapping celltypes.json

Las secciones a continuación documentan las llamadas subyacentes a scanpy que cada script realiza — léelas cuando personalices más allá de las banderas del script.

Inicio Rápido

Importación y Configuración Básica

import scanpy as sc
import pandas as pd
import numpy as np

# Configurar ajustes
sc.settings.verbosity = 3
sc.settings.set_figure_params(dpi=80, facecolor='white')
sc.settings.figdir = './figures/'
sc.settings.autosave = True  # Preferido sobre save= por gráfico (obsoleto en scanpy 1.12)

Carga de Datos

# Desde 10X Genomics
adata = sc.read_10x_mtx('ruta/a/datos/')
adata = sc.read_10x_h5('ruta/a/datos.h5')

# Desde h5ad (formato AnnData)
adata = sc.read_h5ad('ruta/a/datos.h5ad')

# Desde CSV
adata = sc.read_csv('ruta/a/datos.csv')

Para archivos nativos de R, no intentes analizar archivos .rds de Seurat directamente en Python. Convierte primero:

# Consulta references/r_interop.md para instalar R y paquetes de conversión.
Rscript convert_rds_to_h5ad.R input.rds output.h5ad

adata = sc.read_h5ad('output.h5ad')

Entendiendo la Estructura de AnnData

El objeto AnnData es la estructura de datos central en scanpy:

adata.X          # Matriz de expresión (células × genes)
adata.obs        # Metadatos de células (DataFrame)
adata.var        # Metadatos de genes (DataFrame)
adata.uns        # Anotaciones no estructuradas (dict)
adata.obsm       # Datos celulares multidimensionales (PCA, UMAP)
adata.raw        # Copia de seguridad de datos brutos

# Acceder a nombres de células y genes
adata.obs_names  # Códigos de barras de células
adata.var_names  # Nombres de genes

Flujo de Trabajo de Análisis Estándar

Los siete pasos, con código y los parámetros que importan en cada uno, están en references/analysis_workflow.md:

1. Control de calidad — filtrar células y genes; inspeccionar la fracción mitocondrial y los recuentos antes de elegir umbrales en lugar de copiar valores predeterminados.
2. Normalización y preprocesamiento — normalizar, transformar log, seleccionar genes altamente variables y mantener .raw para gráficos posteriores.
3. Reducción de dimensionalidad — PCA, luego el gráfico de vecinos, luego UMAP.
4. Agrupamiento — Leiden con una resolución elegida para la pregunta, no la predeterminada.
5. Identificación de genes marcadores — genes clasificados por grupo.
6. Anotación de tipos celulares — mapeo de grupos a tipos a partir de marcadores.
7. Guardar resultados — escribir el AnnData anotado.

Las tareas comunes posteriores — gráficos para publicación, inferencia de trayectorias, expresión diferencial pseudobulk entre condiciones, puntuación de conjuntos de genes y corrección por lotes — están en el mismo archivo. Consulta también references/standard_workflow.md y references/plotting_guide.md.

Parámetros Clave a Ajustar

Control de Calidad

• min_genes: Genes mínimos por célula (típicamente 200-500)
• min_cells: Células mínimas por gen (típicamente 3-10)
• pct_counts_mt: Umbral mitocondrial (típicamente 5-20%)

Normalización

• target_sum: Recuentos objetivo por célula (por defecto 1e4)

Selección de Características

• n_top_genes: Número de HVGs (típicamente 2000-3000)
• min_mean, max_mean, min_disp: Parámetros de selección de HVG

Reducción de Dimensionalidad

• n_pcs: Número de componentes principales (revisa el gráfico de proporción de varianza)
• n_neighbors: Número de vecinos (típicamente 10-30)

Agrupamiento

• resolution: Granularidad del agrupamiento (0.4-1.2, mayor = más grupos)

Errores Comunes y Mejores Prácticas

1. Siempre guarda los recuentos brutos: adata.raw = adata antes de filtrar genes
2. Revisa cuidadosamente los gráficos de QC: Ajusta los umbrales según la calidad del conjunto de datos
3. Usa el agrupamiento Leiden: sc.tl.louvain está obsoleto en scanpy 1.12
4. Prueba múltiples resoluciones de agrupamiento: Encuentra la granularidad óptima
5. Valida las anotaciones de tipos celulares: Usa múltiples genes marcadores
6. Usa use_raw=True para gráficos de expresión génica: Muestra recuentos normalizados de .raw
7. Revisa el gráfico de proporción de varianza de PCA: Determina el número óptimo de PCs
8. Guarda resultados intermedios: Los flujos de trabajo largos pueden fallar a medio camino
9. Pseudobulk para DE: No trates los valores p de rank_genes_groups como DE rigurosa entre condiciones
10. Guarda gráficos a través de la configuración: Usa sc.settings.autosave en lugar del obsoleto save= en funciones de gráfico
11. Convierte objetos R antes de Scanpy: Usa paquetes de R para convertir archivos .rds de Seurat o SingleCellExperiment a .h5ad, preservando recuentos, metadatos e identificadores de genes

Recursos Incluidos

scripts/ (toolkit CLI)

Un conjunto componible de scripts de entrada/salida .h5ad que cubren todo el flujo de trabajo, además de un pipeline completo de un solo comando. Consulta la sección Toolkit de Scripts arriba para la tabla completa y ejemplos de encadenamiento. Cada script tiene --help. Archivos:

• _common.py — helpers compartidos de carga/guardado/figuras importados por los demás (no es un CLI)
• run_pipeline.py — pipeline completo en un comando (banderas o --config JSON)
• inspect_data.py, convert.py — explorar y cargar/convertir cualquier formato de entrada
• qc_analysis.py, preprocess.py, reduce_dimensions.py, batch_correct.py, cluster.py — pasos del pipeline
• find_markers.py, annotate.py, score_genes.py, pseudobulk.py — marcadores, anotación, puntuación, preparación DE
• subset.py, plot.py — subconjunto por metadatos/genes; generar cualquier gráfico estándar

Usa estos scripts por defecto antes de escribir código scanpy desde cero.

references/standard_workflow.md

Flujo de trabajo completo paso a paso con explicaciones detalladas y ejemplos de código para:

• Carga y configuración de datos
• Control de calidad con visualización
• Normalización y escalado
• Selección de características
• Reducción de dimensionalidad (PCA, UMAP, t-SNE)
• Agrupamiento (Leiden)
• Detección de dobletes (scrublet) y agregación pseudobulk
• Identificación de genes marcadores
• Anotación de tipos celulares
• Inferencia de trayectorias
• Expresión diferencial

Lee esta referencia cuando realices un análisis completo desde cero.

references/api_reference.md

Guía de referencia rápida para funciones de scanpy organizadas por módulo:

• Lectura/escritura de datos (sc.read_*, adata.write_*)
• Preprocesamiento (sc.pp.*)
• Herramientas (sc.tl.*)
• Trazado (sc.pl.*)
• Estructura y manipulación de AnnData
• Configuración y utilidades

Usa esta guía para una búsqueda rápida de firmas de funciones y parámetros comunes.

references/plotting_guide.md

Guía completa de visualización que incluye:

• Gráficos de control de calidad
• Visualizaciones de reducción de dimensionalidad
• Visualizaciones de agrupamiento
• Gráficos de genes marcadores (mapas de calor, gráficos de puntos, gráficos de violín)
• Gráficos de trayectoria y pseudotiempo
• Personalización para publicación
• Figuras de múltiples paneles
• Paletas de colores y estilo

Consulta esta guía al crear figuras listas para publicación.

references/r_interop.md

Manual de ejecución para agente sobre cómo instalar R en macOS, Linux y Windows, instalar paquetes de conversión de CRAN/Bioconductor, inspeccionar entradas .rds/.RData, convertir objetos Seurat o SingleCellExperiment a .h5ad y validar el resultado en Scanpy.

assets/analysis_template.py

Plantilla de análisis completa que proporciona un flujo de trabajo completo desde la carga de datos hasta la anotación de tipos celulares. Copia y personaliza esta plantilla para nuevos análisis:

cp assets/analysis_template.py my_analysis.py
# Edita parámetros y ejecuta
python my_analysis.py

La plantilla incluye todos los pasos estándar con parámetros configurables y comentarios útiles.

Plantillas JSON en assets/

Plantillas editables y listas para usar para que no tengas que crear configuraciones/mapeos desde cero:

• assets/pipeline_config.json — conjunto de parámetros para run_pipeline.py --config
• assets/celltype_mapping.json — mapa de grupo → tipo celular para annotate.py --mapping
• assets/gene_signatures.json — firmas de conjuntos de genes para score_genes.py --gene-sets

Recursos Adicionales

• Documentación oficial de scanpy: https://scanpy.scverse.org/en/stable/
• Tutoriales de Scanpy: https://

…[truncado para traducción]