Análisis de Datos de Neuropixels
Resumen
Conjunto de herramientas para analizar grabaciones neuronales de alta densidad de Neuropixels utilizando las mejores prácticas actuales de SpikeInterface, el Allen Institute y el International Brain Laboratory (IBL). Cubre el flujo de trabajo completo desde datos brutos hasta unidades curadas listas para publicación.
Todos los ejemplos usan la API real de SpikeInterface (spikeinterface.full as si) más el módulo de curación complementario (spikeinterface.curation as sc). La habilidad incluye scripts ejecutables en scripts/ y una plantilla editable en assets/ que implementan este flujo de trabajo directamente sobre SpikeInterface; no hay un paquete separado que instalar más allá de las dependencias listadas en Instalación.
Cuándo Usar Esta Habilidad
Esta habilidad debe usarse cuando:
- Se trabaja con grabaciones de Neuropixels (archivos
.ap.bin,.lf.bin,.meta) - Se cargan datos de SpikeGLX, Open Ephys o formatos NWB
- Se preprocesan grabaciones neuronales (filtrado, referencia común, detección de canales defectuosos)
- Se detecta y corrige movimiento/deriva
- Se ejecuta spike sorting (Kilosort4, SpykingCircus2, Mountainsort5, Tridesclous2)
- Se calculan métricas de calidad (SNR, violaciones ISI, ratio de presencia, corte de amplitud)
- Se curan unidades (basada en umbrales, basada en modelos o asistida por IA)
- Se crean visualizaciones y se exporta a Phy o NWB
Hardware y Formatos Soportados
| Sonda | Electrodos | Canales | Notas |
|---|---|---|---|
| Neuropixels 1.0 | 960 | 384 | Usar phase_shift para corrección ADC |
| Neuropixels 2.0 (individual) | 1280 | 384 | Geometría más densa |
| Neuropixels 2.0 (4 shanks) | 5120 | 384 | Grabación multi-región |
| Formato | Extensión | Lector |
|---|---|---|
| SpikeGLX | .ap.bin, .lf.bin, .meta | si.read_spikeglx() |
| Open Ephys | .continuous, .oebin | si.read_openephys() |
| NWB | .nwb | si.read_nwb() |
Inicio Rápido
Importar y configurar procesamiento paralelo
import spikeinterface.full as si
# Los kwargs globales de trabajo se reutilizan en todos los pasos paralelizables
si.set_global_job_kwargs(n_jobs=-1, chunk_duration="1s", progress_bar=True)
Cargar datos
# Inspeccionar los streams disponibles primero
stream_names, stream_ids = si.get_neo_streams("spikeglx", "/ruta/al/run_g0/")
print(stream_names) # ej. ['imec0.ap', 'imec0.lf', 'nidq']
# SpikeGLX (más común) — seleccionar el stream AP por nombre
recording = si.read_spikeglx("/ruta/al/run_g0/", stream_name="imec0.ap", load_sync_channel=False)
# Open Ephys
recording = si.read_openephys("/ruta/al/Record_Node_101/")
# Para iteración rápida, recortar los primeros 60 s
fs = recording.get_sampling_frequency()
recording_sub = recording.frame_slice(0, int(60 * fs))
Pipeline completo (script empaquetado)
El repositorio incluye un pipeline completo construido sobre SpikeInterface:
python scripts/neuropixels_pipeline.py /ruta/a/datos/spikeglx salida/ --sorter kilosort4 --curation allen
Realiza: carga → preprocesamiento → verificación de deriva → corrección de movimiento opcional → sorting → postprocesamiento → métricas de calidad → curación → exportación. Lea los pasos a continuación para ejecutarlos interactivamente o personalizar el pipeline.
Flujo de Trabajo de Análisis Estándar
1. Preprocesamiento
Cadena recomendada, siguiendo el cómo hacerlo de SpikeInterface para Neuropixels (eliminación de bandas estilo IBL con eliminación de canales + referencia común):
rec = si.highpass_filter(recording, freq_min=400.0)
bad_channel_ids, channel_labels = si.detect_bad_channels(rec)
rec = rec.remove_channels(bad_channel_ids)
rec = si.phase_shift(rec) # Corrección de fase ADC (Neuropixels 1.0)
rec = si.common_reference(rec, operator="median", reference="global")
Guardar la grabación preprocesada (Kilosort necesita un archivo binario, y acelera la reutilización):
rec = rec.save(folder="preprocessed/", format="binary")
2. Verificar y corregir deriva
Inspeccionar siempre la deriva antes del sorting:
from spikeinterface.sortingcomponents.peak_detection import detect_peaks
from spikeinterface.sortingcomponents.peak_localization import localize_peaks
noise_levels = si.get_noise_levels(rec, return_in_uV=False)
peaks = detect_peaks(rec, method="locally_exclusive", noise_levels=noise_levels,
detect_threshold=5, radius_um=50.0)
peak_locations = localize_peaks(rec, peaks, method="center_of_mass")
# Visualizar el raster de deriva
si.plot_drift_raster_map(peaks=peaks, peak_locations=peak_locations,
recording=rec, clim=(-50, 50))
Aplicar corrección si es necesario (preajustes: rigid_fast, kilosort_like,
nonrigid_accurate, nonrigid_fast_and_accurate, dredge, dredge_fast):
rec_corrected = si.correct_motion(rec, preset="nonrigid_fast_and_accurate", folder="motion/")
3. Spike sorting
# Kilosort4 (recomendado, requiere GPU CUDA)
sorting = si.run_sorter("kilosort4", rec_corrected, folder="ks4_output")
# Alternativas para CPU (desarrolladas internamente, sin instalación externa)
sorting = si.run_sorter("spykingcircus2", rec_corrected, folder="sc2_output")
sorting = si.run_sorter("tridesclous2", rec_corrected, folder="tdc2_output")
sorting = si.run_sorter("mountainsort5", rec_corrected, folder="ms5_output")
# Sorters externos pueden ejecutarse en contenedores sin instalación local
sorting = si.run_sorter("kilosort2_5", rec_corrected, folder="ks25_output", docker_image=True)
print(si.installed_sorters())
Nota:
run_sorterusa el argumentofolder=. El antiguooutput_folder=está obsoleto.
4. Postprocesamiento
analyzer = si.create_sorting_analyzer(sorting, rec_corrected, sparse=True,
format="binary_folder", folder="analyzer/")
analyzer.compute("random_spikes", method="uniform", max_spikes_per_unit=500)
analyzer.compute("waveforms", ms_before=1.0, ms_after=2.0)
analyzer.compute("templates", operators=["average", "std"])
analyzer.compute("noise_levels")
analyzer.compute("spike_amplitudes")
analyzer.compute("correlograms", window_ms=50.0, bin_ms=1.0)
analyzer.compute("unit_locations", method="monopolar_triangulation")
analyzer.compute("template_similarity")
metric_names = ["firing_rate", "presence_ratio", "snr", "isi_violation", "amplitude_cutoff"]
analyzer.compute("quality_metrics", metric_names=metric_names)
metrics = analyzer.get_extension("quality_metrics").get_data()
5. Curación por umbrales de métricas
# Consulta estilo Allen (nota: la columna es isi_violations_ratio)
query = "(amplitude_cutoff < 0.1) & (isi_violations_ratio < 0.5) & (presence_ratio > 0.9)"
good_unit_ids = metrics.query(query).index.values
Para lógica reutilizable de múltiples umbrales con preajustes allen / ibl / strict, use el
script scripts/compute_metrics.py incluido. Ver
references/AUTOMATED_CURATION.md para detalles y las
herramientas Bombcell / UnitMatch.
6. Curación basada en modelos (UnitRefine)
SpikeInterface puede aplicar clasificadores de machine learning preentrenados de Hugging Face a través del
módulo spikeinterface.curation. Los modelos UnitRefine fueron entrenados con datos reales de Neuropixels
(V1, SC, ALM):
import spikeinterface.curation as sc
# 1) ruido vs neural
noise_labels = sc.model_based_label_units(
sorting_analyzer=analyzer,
repo_id="SpikeInterface/UnitRefine_noise_neural_classifier",
trust_model=True,
)
neural = analyzer.remove_units(noise_labels[noise_labels["prediction"] == "noise"].index)
# 2) unidad única (sua) vs multiunidad (mua) en las unidades supervivientes
sua_mua_labels = sc.model_based_label_units(
sorting_analyzer=neural,
repo_id="SpikeInterface/UnitRefine_sua_mua_classifier",
trust_model=True,
)
Cada llamada devuelve un DataFrame con prediction y probability (confianza) por unidad.
trust_model=True (o una lista explícita trusted=[...]) es necesario para cargar el modelo .skops
— cargue solo modelos de fuentes de confianza. Los modelos entrenados en otras áreas
cerebrales/conjuntos de datos pueden no transferirse; valide contra un subconjunto etiquetado manualmente.
7. Curación asistida por IA (para unidades inciertas)
Cuando se ejecuta dentro de un agente como Cursor o Claude Code, el agente puede inspeccionar directamente los gráficos de forma de onda/correlograma y dar una lectura experta, sin necesidad de configuración de API. Genere gráficos y pida al agente que evalúe la calidad del aislamiento.
Para acceso programático a modelos de visión, lea las claves API del entorno — nunca codifique credenciales en scripts de análisis (se filtran al control de versiones y registros):
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"]) # configure esto en su shell, no en el código
Ver references/AI_CURATION.md para el patrón completo (renderizar una imagen resumen de la unidad, construir el prompt y analizar la respuesta).
8. Exportar resultados
# Mantener solo unidades buenas, luego exportar
analyzer_clean = analyzer.select_units(good_unit_ids, folder="analyzer_clean/", format="binary_folder")
# Phy para revisión manual
si.export_to_phy(analyzer_clean, output_folder="phy_export/",
compute_pc_features=True, compute_amplitudes=True)
# Informe de figuras
si.export_report(analyzer_clean, "report/", format="png")
# NWB
from spikeinterface.exporters import export_to_nwb
export_to_nwb(analyzer_clean, "output.nwb")
# Tabla de métricas
metrics.to_csv("quality_metrics.csv")
Errores Comunes y Buenas Prácticas
- Siempre verifique la deriva antes del spike sorting — una deriva > ~10 μm degrada significativamente la calidad.
- Use
phase_shiftpara Neuropixels 1.0 para corregir desviaciones de muestreo ADC. - Guarde la grabación preprocesada con
rec.save(folder=...)para evitar recálculos (Kilosort también necesita un archivo binario). - Use una GPU para Kilosort4 — es mucho más rápido que los sorters de CPU.
- Revise las unidades inciertas — la curación automatizada/basada en modelos es un punto de partida, no un veredicto.
- Combine enfoques — umbrales para casos claros, modelo/IA para unidades límite.
- Documente umbrales e IDs de repositorio de modelos para reproducibilidad.
- Exporte a Phy para experimentos críticos — la supervisión humana es valiosa.
Parámetros Clave a Ajustar
Preprocesamiento
freq_min: frecuencia de corte del filtro pasa altas (300–400 Hz típico)detect_bad_channels: devuelve(bad_channel_ids, channel_labels)
Corrección de Movimiento
preset:nonrigid_fast_and_accurate(equilibrado),nonrigid_accurate(deriva severa),dredge(estado del arte)
Spike Sorting (Kilosort4)
batch_size: muestras por lote (60000 por defecto)nblocks: bloques de deriva (aumentar para grabaciones largas y con deriva)Th_universal/Th_learned: umbrales de detección (más bajo = más spikes)
Métricas de Calidad
snr: umbral de relación señal-ruido (3–5 típico)isi_violations_ratio: violaciones refractarias (0.01–0.5)presence_ratio: cobertura de grabación (0.5–0.95)
Recursos Incluidos
scripts/explore_recording.py
Inspección rápida de una grabación (streams, canales, duración, canales defectuosos):
python scripts/explore_recording.py /ruta/a/datos
scripts/preprocess_recording.py
Preprocesamiento automatizado:
python scripts/preprocess_recording.py /ruta/a/datos --output preprocessed/
scripts/run_sorting.py
Ejecutar spike sorting:
python scripts/run_sorting.py preprocessed/ --sorter kilosort4 --output sorting/
scripts/compute_metrics.py
Calcular métricas de calidad y aplicar curación:
python scripts/compute_metrics.py sorting/ preprocessed/ --output metrics/ --curation allen
scripts/export_to_phy.py
Exportar a Phy para curación manual:
python scripts/export_to_phy.py metrics/analyzer --output phy_export/
scripts/neuropixels_pipeline.py
Pipeline completo de principio a fin (ver Inicio Rápido).
assets/analysis_template.py
Plantilla de análisis completa y editable. Copie y personalice:
cp assets/analysis_template.py my_analysis.py
# Edite la sección PARÁMETROS, luego ejecute
python my_analysis.py
Guías de Referencia Detalladas
| Tema | Referencia |
|---|---|
| Flujo de trabajo completo | references/standard_workflow.md |
| Referencia de API (SpikeInterface) | references/api_reference.md |
| Guía de gráficos | references/plotting_guide.md |
| Preprocesamiento | references/PREPROCESSING.md |
| Spike sorting | references/SPIKE_SORTING.md |
| Corrección de movimiento | references/MOTION_CORRECTION.md |
| Métricas de calidad | references/QUALITY_METRICS.md |
| Curación automatizada y basada en modelos | references/AUTOMATED_CURATION.md |
| Curación asistida por IA | references/AI_CURATION.md |
| Análisis de formas de onda | references/ANALYSIS.md |
Instalación
Requiere Python ≥ 3.10. Se recomienda usar uv.
# Paquetes principales (SpikeInterface incluye las herramientas de curación/modelos)
uv pip install "spikeinterface[full]" probeinterface neo
# Spike sorters
uv pip install kilosort # Kilosort4 (requiere GPU CUDA)
uv pip install spykingcircus # SpykingCircus (heredado; SpykingCircus2 viene con SpikeInterface)
uv pip install mountainsort5 # Mountainsort5 (CPU)
# Curación basada en modelos (UnitRefine) descarga desde Hugging Face
uv pip install "huggingface_hub" skops
# Opcional: curación visual asistida por IA
uv pip install anthropic
# Opcional: herramientas IBL y Bombcell
uv pip install ibl-neuropixel ibllib bombcell
Para entornos reproducibles, fije las versiones (actuales a fecha de 2026-06: spikeinterface==0.104.3,
kilosort==4.1.7, probeinterface==0.3.2, neo==0.14.4). Las instalaciones sin fijar están bien para
experimentación rápida pero deben fijarse en pipelines de producción.
Estructura del Proyecto
project/
├── raw_data/
│ └── recording_g0/
│ └── recording_g0_imec0/
│ ├── recording_g0_t0.imec0.ap.bin
│ └── recording_g0_t0.imec0.lf.bin
├── preprocessed/
├── motion/
├── ks4_output/
├── analyzer/
├── analyzer_clean/
├── phy_export/
├── report/
├── scripts/
│ ├── neuropixels_pipeline.py
│ ├── explore_recording.py
│ ├── preprocess_recording.py
│ ├── run_sorting.py
│ ├── compute_metrics.py
│ └── export_to_phy.py
├── assets/
│ └── analysis_template.py
├── references/
│ └── (archivos .md de referencia)
└── quality_metrics.csv