Análise de Dados Neuropixels
Visão Geral
Kit de ferramentas para analisar gravações neurais de alta densidade Neuropixels usando as melhores práticas atuais do SpikeInterface, Allen Institute e International Brain Laboratory (IBL). Ele cobre todo o fluxo de trabalho, desde dados brutos até unidades curadas prontas para publicação.
Todos os exemplos usam a API real do SpikeInterface (spikeinterface.full as si) além do módulo de curadoria acompanhante (spikeinterface.curation as sc). A skill fornece scripts executáveis em scripts/ e um modelo copiável e editável em assets/ que implementam este fluxo de trabalho diretamente sobre o SpikeInterface — não há pacote separado para instalar além das dependências listadas em Instalação.
Quando Usar Esta Skill
Esta skill deve ser usada quando:
- Trabalhando com gravações Neuropixels (arquivos
.ap.bin,.lf.bin,.meta) - Carregando dados de SpikeGLX, Open Ephys ou formatos NWB
- Pré-processando gravações neurais (filtragem, referência comum, detecção de canais ruins)
- Detectando e corrigindo movimento/drift
- Executando spike sorting (Kilosort4, SpykingCircus2, Mountainsort5, Tridesclous2)
- Computando métricas de qualidade (SNR, violações ISI, taxa de presença, corte de amplitude)
- Curando unidades (baseada em limiares, baseada em modelo ou assistida por IA)
- Criando visualizações e exportando para Phy ou NWB
Hardware e Formatos Suportados
| Sonda | Eletrodos | Canais | Notas |
|---|---|---|---|
| Neuropixels 1.0 | 960 | 384 | Use phase_shift para correção ADC |
| Neuropixels 2.0 (única) | 1280 | 384 | Geometria mais densa |
| Neuropixels 2.0 (4-shank) | 5120 | 384 | Gravação multi-região |
| Formato | Extensão | Leitor |
|---|---|---|
| SpikeGLX | .ap.bin, .lf.bin, .meta | si.read_spikeglx() |
| Open Ephys | .continuous, .oebin | si.read_openephys() |
| NWB | .nwb | si.read_nwb() |
Início Rápido
Importar e configurar processamento paralelo
import spikeinterface.full as si
# Os kwargs globais de job são reutilizados por todas as etapas paralelizáveis
si.set_global_job_kwargs(n_jobs=-1, chunk_duration="1s", progress_bar=True)
Carregando dados
# Inspecione os streams disponíveis primeiro
stream_names, stream_ids = si.get_neo_streams("spikeglx", "/caminho/para/run_g0/")
print(stream_names) # ex.: ['imec0.ap', 'imec0.lf', 'nidq']
# SpikeGLX (mais comum) — selecione o stream AP pelo nome
recording = si.read_spikeglx("/caminho/para/run_g0/", stream_name="imec0.ap", load_sync_channel=False)
# Open Ephys
recording = si.read_openephys("/caminho/para/Record_Node_101/")
# Para iteração rápida, fatie os primeiros 60 s
fs = recording.get_sampling_frequency()
recording_sub = recording.frame_slice(0, int(60 * fs))
Pipeline completo (script incluso)
O repositório fornece um pipeline de ponta a ponta construído sobre o SpikeInterface:
python scripts/neuropixels_pipeline.py /caminho/para/dados/spikeglx output/ --sorter kilosort4 --curation allen
Ele executa carregar → pré-processar → verificar drift → correção de movimento opcional → sorting → pós-processamento → métricas de qualidade → curadoria → exportar. Leia os passos abaixo para executá-los interativamente ou personalizar o pipeline.
Fluxo de Trabalho Padrão de Análise
1. Pré-processamento
Cadeia recomendada, seguindo o guia de como fazer Neuropixels do SpikeInterface (destriping estilo IBL com remoção de canais + referência comum):
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) # Correção de fase ADC (Neuropixels 1.0)
rec = si.common_reference(rec, operator="median", reference="global")
Salve a gravação pré-processada (Kilosort precisa de um arquivo binário e acelera a reutilização):
rec = rec.save(folder="preprocessed/", format="binary")
2. Verificar e corrigir drift
Sempre inspecione o drift antes do 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")
# Visualize o raster de drift
si.plot_drift_raster_map(peaks=peaks, peak_locations=peak_locations,
recording=rec, clim=(-50, 50))
Aplique correção se necessário (predefinições: 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, requer uma GPU CUDA)
sorting = si.run_sorter("kilosort4", rec_corrected, folder="ks4_output")
# Alternativas de CPU (desenvolvidas internamente, sem instalação 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 podem ser executados em contêineres sem instalação local
sorting = si.run_sorter("kilosort2_5", rec_corrected, folder="ks25_output", docker_image=True)
print(si.installed_sorters())
Nota:
run_sorterusa o argumentofolder=. O argumento mais antigooutput_folder=está obsoleto.
4. Pós-processamento
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. Curadoria por limiares de métricas
# Consulta estilo Allen (nota: a coluna é 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 reutilizável de múltiplos limiares com predefinições allen / ibl / strict, use o script incluso scripts/compute_metrics.py. Veja references/AUTOMATED_CURATION.md para detalhes e as ferramentas Bombcell / UnitMatch.
6. Curadoria baseada em modelo (UnitRefine)
O SpikeInterface pode aplicar classificadores de aprendizado de máquina pré-treinados do Hugging Face através do módulo spikeinterface.curation. Os modelos UnitRefine foram treinados em dados reais de Neuropixels (V1, SC, ALM):
import spikeinterface.curation as sc
# 1) ruído 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) unidade única (sua) vs multi-unidade (mua) nas unidades sobreviventes
sua_mua_labels = sc.model_based_label_units(
sorting_analyzer=neural,
repo_id="SpikeInterface/UnitRefine_sua_mua_classifier",
trust_model=True,
)
Cada chamada retorna um DataFrame com prediction e probability (confiança) por unidade. trust_model=True (ou uma lista explícita trusted=[...]) é necessário para carregar o modelo .skops — carregue apenas modelos de fontes confiáveis. Modelos treinados em outras áreas cerebrais/conjuntos de dados podem não transferir; valide contra um subconjunto rotulado manualmente.
7. Curadoria assistida por IA (para unidades incertas)
Ao executar dentro de um agente como Cursor ou Claude Code, o agente pode inspecionar diretamente gráficos de waveform/correlograma e fornecer uma leitura especializada — sem necessidade de configuração de API. Gere gráficos e peça ao agente para avaliar a qualidade do isolamento.
Para acesso programático a modelos de visão, leia chaves de API do ambiente — nunca codifique credenciais em scripts de análise (elas vazam para controle de versão e logs):
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"]) # defina isso no seu shell, não no código
Veja references/AI_CURATION.md para o padrão completo (renderizar uma imagem de resumo da unidade, construir o prompt e analisar a resposta).
8. Exportar resultados
# Mantenha apenas as unidades boas, depois exporte
analyzer_clean = analyzer.select_units(good_unit_ids, folder="analyzer_clean/", format="binary_folder")
# Phy para revisão manual
si.export_to_phy(analyzer_clean, output_folder="phy_export/",
compute_pc_features=True, compute_amplitudes=True)
# Relatório 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")
# Tabela de métricas
metrics.to_csv("quality_metrics.csv")
Armadilhas Comuns e Melhores Práticas
- Sempre verifique o drift antes do spike sorting — drift > ~10 μm degrada significativamente a qualidade.
- Use
phase_shiftpara Neuropixels 1.0 para corrigir offsets de amostragem ADC. - Salve a gravação pré-processada com
rec.save(folder=...)para evitar recomputação (Kilosort também precisa de um arquivo binário). - Use uma GPU para Kilosort4 — é muito mais rápido que sorters de CPU.
- Revise unidades incertas — a curadoria automatizada/baseada em modelo é um ponto de partida, não um veredito.
- Combine abordagens — limiares para casos claros, modelo/IA para unidades limítrofes.
- Documente limiares e IDs de repositório de modelos para reprodutibilidade.
- Exporte para Phy para experimentos críticos — a supervisão humana é valiosa.
Principais Parâmetros para Ajustar
Pré-processamento
freq_min: corte highpass (300–400 Hz típico)detect_bad_channels: retorna(bad_channel_ids, channel_labels)
Correção de Movimento
preset:nonrigid_fast_and_accurate(equilibrado),nonrigid_accurate(drift severo),dredge(estado da arte)
Spike Sorting (Kilosort4)
batch_size: amostras por lote (60000 padrão)nblocks: blocos de drift (aumente para gravações longas e com drift)Th_universal/Th_learned: limiares de detecção (menor = mais spikes)
Métricas de Qualidade
snr: corte de relação sinal-ruído (3–5 típico)isi_violations_ratio: violações refratárias (0.01–0.5)presence_ratio: cobertura da gravação (0.5–0.95)
Recursos Inclusos
scripts/explore_recording.py
Inspeção rápida de uma gravação (streams, canais, duração, canais ruins):
python scripts/explore_recording.py /caminho/para/dados
scripts/preprocess_recording.py
Pré-processamento automatizado:
python scripts/preprocess_recording.py /caminho/para/dados --output preprocessed/
scripts/run_sorting.py
Executar spike sorting:
python scripts/run_sorting.py preprocessed/ --sorter kilosort4 --output sorting/
scripts/compute_metrics.py
Calcular métricas de qualidade e aplicar curadoria:
python scripts/compute_metrics.py sorting/ preprocessed/ --output metrics/ --curation allen
scripts/export_to_phy.py
Exportar para Phy para curadoria manual:
python scripts/export_to_phy.py metrics/analyzer --output phy_export/
scripts/neuropixels_pipeline.py
Pipeline completo de ponta a ponta (veja Início Rápido).
assets/analysis_template.py
Modelo de análise completo e editável. Copie e personalize:
cp assets/analysis_template.py my_analysis.py
# Edite a seção PARAMETERS, depois execute
python my_analysis.py
Guias de Referência Detalhados
| Tópico | Referência |
|---|---|
| Fluxo de trabalho completo | references/standard_workflow.md |
| Referência da API (SpikeInterface) | references/api_reference.md |
| Guia de plotagem | references/plotting_guide.md |
| Pré-processamento | references/PREPROCESSING.md |
| Spike sorting | references/SPIKE_SORTING.md |
| Correção de movimento | references/MOTION_CORRECTION.md |
| Métricas de qualidade | references/QUALITY_METRICS.md |
| Curadoria automatizada e baseada em modelo | references/AUTOMATED_CURATION.md |
| Curadoria assistida por IA | references/AI_CURATION.md |
| Análise de waveform | references/ANALYSIS.md |
Instalação
Requer Python ≥ 3.10. O uso de uv é recomendado.
# Pacotes principais (SpikeInterface inclui as ferramentas de curadoria/modelo)
uv pip install "spikeinterface[full]" probeinterface neo
# Spike sorters
uv pip install kilosort # Kilosort4 (requer GPU CUDA)
uv pip install spykingcircus # SpykingCircus (legado; SpykingCircus2 acompanha SpikeInterface)
uv pip install mountainsort5 # Mountainsort5 (CPU)
# Curadoria baseada em modelo (UnitRefine) baixa do Hugging Face
uv pip install "huggingface_hub" skops
# Opcional: curadoria visual assistida por IA
uv pip install anthropic
# Opcional: ferramentas IBL e Bombcell
uv pip install ibl-neuropixel ibllib bombcell
Para ambientes reproduzíveis, fixe as versões (atuais em 2026-06: spikeinterface==0.104.3,
kilosort==4.1.7, probeinterface==0.3.2, neo==0.14.4). Instalações sem versões fixas são
adequadas para experimentação rápida, mas devem ser fixadas em pipelines de produção.
Estrutura do Projeto
project/
├── raw_data/
│ └── recording_g0/
│ └── recording_g0_imec0/
│ ├── recording_g0_t0.imec0.ap.bin
│ └── recording_g0_t0.imec0.lf.bin
├── preprocessed/
│ └── ... (dados pré-processados)
├── motion/
│ └── ... (resultados da correção de movimento)
├── ks4_output/
│ └── ... (resultados do Kilosort4)
├── analyzer/
│ └── ... (sorting analyzer)
├── phy_export/
│ └── ... (exportação Phy)
├── report/
│ └── ... (relatório de figuras)
├── quality_metrics.csv
├── output.nwb
├── 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/
├── standard_workflow.md
├── api_reference.md
├── plotting_guide.md
├── PREPROCESSING.md
├── SPIKE_SORTING.md
├── MOTION_CORRECTION.md
├── QUALITY_METRICS.md
├── AUTOMATED_CURATION.md
├── AI_CURATION.md
└── ANALYSIS.md