analyse-neuropixels

Analyse des données Neuropixels

Aperçu

Boîte à outils pour analyser les enregistrements neuronaux haute densité Neuropixels en utilisant les meilleures pratiques actuelles de SpikeInterface, de l'Allen Institute et de l'International Brain Laboratory (IBL). Elle couvre l'ensemble du flux de travail, des données brutes aux unités curées prêtes pour publication.

Tous les exemples utilisent l'API réelle de SpikeInterface (spikeinterface.full as si) ainsi que le module de curation compagnon (spikeinterface.curation as sc). La compétence fournit des scripts exécutables dans scripts/ et un modèle copiable et modifiable dans assets/ qui implémentent ce flux de travail directement sur SpikeInterface — il n'y a pas de paquet séparé à installer au-delà des dépendances listées dans Installation.

Quand utiliser cette compétence

Cette compétence doit être utilisée lorsque :

• Vous travaillez avec des enregistrements Neuropixels (fichiers .ap.bin, .lf.bin, .meta)
• Vous chargez des données depuis SpikeGLX, Open Ephys ou des formats NWB
• Vous prétraitez des enregistrements neuronaux (filtrage, référence commune, détection des canaux défectueux)
• Vous détectez et corrigez le mouvement/la dérive
• Vous exécutez un tri de spikes (Kilosort4, SpykingCircus2, Mountainsort5, Tridesclous2)
• Vous calculez des métriques de qualité (SNR, violations ISI, ratio de présence, coupure d'amplitude)
• Vous curez des unités (par seuil, par modèle ou assisté par IA)
• Vous créez des visualisations et exportez vers Phy ou NWB

Matériel et formats pris en charge

Sonde	Électrodes	Canaux	Notes
Neuropixels 1.0	960	384	Utiliser phase_shift pour la correction ADC
Neuropixels 2.0 (simple)	1280	384	Géométrie plus dense
Neuropixels 2.0 (4-shank)	5120	384	Enregistrement multi-régions

Format	Extension	Lecteur
SpikeGLX	.ap.bin, .lf.bin, .meta	si.read_spikeglx()
Open Ephys	.continuous, .oebin	si.read_openephys()
NWB	.nwb	si.read_nwb()

Démarrage rapide

Importer et configurer le traitement parallèle

import spikeinterface.full as si

# Les kwargs de tâche globaux sont réutilisés par toutes les étapes parallélisables
si.set_global_job_kwargs(n_jobs=-1, chunk_duration="1s", progress_bar=True)

Chargement des données

# Inspecter d'abord les flux disponibles
stream_names, stream_ids = si.get_neo_streams("spikeglx", "/chemin/vers/run_g0/")
print(stream_names)  # ex. ['imec0.ap', 'imec0.lf', 'nidq']

# SpikeGLX (le plus courant) — sélectionner le flux AP par nom
recording = si.read_spikeglx("/chemin/vers/run_g0/", stream_name="imec0.ap", load_sync_channel=False)

# Open Ephys
recording = si.read_openephys("/chemin/vers/Record_Node_101/")

# Pour une itération rapide, trancher les 60 premières secondes
fs = recording.get_sampling_frequency()
recording_sub = recording.frame_slice(0, int(60 * fs))

Pipeline complet (script fourni)

Le dépôt fournit un pipeline de bout en bout construit sur SpikeInterface :

python scripts/neuropixels_pipeline.py /chemin/vers/donnees/spikeglx sortie/ --sorter kilosort4 --curation allen

Il effectue le chargement → prétraitement → vérification de la dérive → correction de mouvement optionnelle → tri → post-traitement → métriques de qualité → curation → exportation. Lisez les étapes ci-dessous pour les exécuter de manière interactive ou personnaliser le pipeline.

Flux de travail standard

1. Prétraitement

Chaîne recommandée, suivant le tutoriel SpikeInterface Neuropixels (destripage de type IBL avec suppression des canaux + référence commune) :

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)  # Correction de phase ADC (Neuropixels 1.0)
rec = si.common_reference(rec, operator="median", reference="global")

Enregistrer l'enregistrement prétraité (Kilosort a besoin d'un fichier binaire, et cela accélère la réutilisation) :

rec = rec.save(folder="preprocessed/", format="binary")

2. Vérifier et corriger la dérive

Toujours inspecter la dérive avant le tri :

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")

# Visualiser la carte de dérive
si.plot_drift_raster_map(peaks=peaks, peak_locations=peak_locations,
                         recording=rec, clim=(-50, 50))

Appliquer la correction si nécessaire (presets : 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. Tri de spikes

# Kilosort4 (recommandé, nécessite un GPU CUDA)
sorting = si.run_sorter("kilosort4", rec_corrected, folder="ks4_output")

# Alternatives CPU (développées en interne, aucune installation externe)
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")

# Les trieurs externes peuvent s'exécuter dans des conteneurs sans installation locale
sorting = si.run_sorter("kilosort2_5", rec_corrected, folder="ks25_output", docker_image=True)

print(si.installed_sorters())

Remarque : run_sorter utilise l'argument folder=. L'ancien output_folder= est déprécié.

4. Post-traitement

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. Curation par seuils de métriques

# Requête de style Allen (noter : la colonne est 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

Pour une logique multi-seuils réutilisable avec les presets allen / ibl / strict, utilisez le scripts/compute_metrics.py fourni. Voir references/AUTOMATED_CURATION.md pour les détails et les outils Bombcell / UnitMatch.

6. Curation basée sur modèle (UnitRefine)

SpikeInterface peut appliquer des classifieurs d'apprentissage automatique pré-entraînés depuis Hugging Face via le module spikeinterface.curation. Les modèles UnitRefine ont été entraînés sur des données Neuropixels réelles (V1, SC, ALM) :

import spikeinterface.curation as sc

# 1) bruit 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) unité simple (sua) vs multi-unité (mua) sur les unités survivantes
sua_mua_labels = sc.model_based_label_units(
    sorting_analyzer=neural,
    repo_id="SpikeInterface/UnitRefine_sua_mua_classifier",
    trust_model=True,
)

Chaque appel renvoie un DataFrame avec prediction et probability (confiance) par unité. trust_model=True (ou une liste explicite trusted=[...]) est nécessaire pour charger le modèle .skops — ne chargez que des modèles provenant de sources de confiance. Les modèles entraînés sur d'autres régions cérébrales/ensembles de données peuvent ne pas se transférer ; validez contre un sous-ensemble étiqueté manuellement.

7. Curation assistée par IA (pour les unités incertaines)

Lorsque vous travaillez avec un agent comme Cursor ou Claude Code, l'agent peut inspecter directement les tracés de formes d'onde/corrélogrammes et donner un avis d'expert — aucune configuration d'API nécessaire. Générez les tracés et demandez à l'agent d'évaluer la qualité de l'isolement.

Pour un accès programmatique aux modèles de vision, lisez les clés API depuis l'environnement — ne codez jamais en dur les identifiants dans les scripts d'analyse (ils fuient dans le contrôle de version et les logs) :

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])  # définissez ceci dans votre shell, pas dans le code

Voir references/AI_CURATION.md pour le modèle complet (rendu d'une image résumé d'unité, construction du prompt et analyse de la réponse).

8. Exportation des résultats

# Ne garder que les bonnes unités, puis exporter
analyzer_clean = analyzer.select_units(good_unit_ids, folder="analyzer_clean/", format="binary_folder")

# Phy pour révision manuelle
si.export_to_phy(analyzer_clean, output_folder="phy_export/",
                 compute_pc_features=True, compute_amplitudes=True)

# Rapport de figures
si.export_report(analyzer_clean, "report/", format="png")

# NWB
from spikeinterface.exporters import export_to_nwb
export_to_nwb(analyzer_clean, "output.nwb")

# Tableau des métriques
metrics.to_csv("quality_metrics.csv")

Pièges courants et meilleures pratiques

1. Toujours vérifier la dérive avant le tri de spikes — une dérive > ~10 μm dégrade la qualité de manière significative.
2. Utiliser phase_shift pour Neuropixels 1.0 pour corriger les décalages d'échantillonnage ADC.
3. Enregistrer l'enregistrement prétraité avec rec.save(folder=...) pour éviter de recalculer (Kilosort a aussi besoin d'un fichier binaire).
4. Utiliser un GPU pour Kilosort4 — il est beaucoup plus rapide que les trieurs CPU.
5. Réviser les unités incertaines — la curation automatisée/basée sur modèle est un point de départ, pas un verdict.
6. Combiner les approches — des seuils pour les cas clairs, un modèle/IA pour les unités limites.
7. Documenter les seuils et les ID de dépôt de modèles pour la reproductibilité.
8. Exporter vers Phy pour les expériences critiques — la supervision humaine est précieuse.

Paramètres clés à ajuster

Prétraitement

• freq_min: coupure passe-haut (300–400 Hz typique)
• detect_bad_channels: retourne (bad_channel_ids, channel_labels)

Correction de mouvement

• preset: nonrigid_fast_and_accurate (équilibré), nonrigid_accurate (dérive sévère), dredge (état de l'art)

Tri de spikes (Kilosort4)

• batch_size: échantillons par lot (60000 par défaut)
• nblocks: blocs de dérive (augmenter pour les enregistrements longs et instables)
• Th_universal / Th_learned: seuils de détection (plus bas = plus de spikes)

Métriques de qualité

• snr: seuil rapport signal/bruit (3–5 typique)
• isi_violations_ratio: violations réfractaires (0.01–0.5)
• presence_ratio: couverture d'enregistrement (0.5–0.95)

Ressources fournies

scripts/explore_recording.py

Inspection rapide d'un enregistrement (flux, canaux, durée, canaux défectueux) :

python scripts/explore_recording.py /chemin/vers/donnees

scripts/preprocess_recording.py

Prétraitement automatisé :

python scripts/preprocess_recording.py /chemin/vers/donnees --output preprocessed/

scripts/run_sorting.py

Exécuter le tri de spikes :

python scripts/run_sorting.py preprocessed/ --sorter kilosort4 --output sorting/

scripts/compute_metrics.py

Calculer les métriques de qualité et appliquer la curation :

python scripts/compute_metrics.py sorting/ preprocessed/ --output metrics/ --curation allen

scripts/export_to_phy.py

Exporter vers Phy pour curation manuelle :

python scripts/export_to_phy.py metrics/analyzer --output phy_export/

scripts/neuropixels_pipeline.py

Pipeline complet de bout en bout (voir Démarrage rapide).

assets/analysis_template.py

Modèle d'analyse complet et modifiable. Copier et personnaliser :

cp assets/analysis_template.py mon_analyse.py
# Modifier la section PARAMETERS, puis exécuter
python mon_analyse.py

Guides de référence détaillés

Sujet	Référence
Flux de travail complet	references/standard_workflow.md
Référence API (SpikeInterface)	references/api_reference.md
Guide de traçage	references/plotting_guide.md
Prétraitement	references/PREPROCESSING.md
Tri de spikes	references/SPIKE_SORTING.md
Correction de mouvement	references/MOTION_CORRECTION.md
Métriques de qualité	references/QUALITY_METRICS.md
Curation automatisée et par modèle	references/AUTOMATED_CURATION.md
Curation assistée par IA	references/AI_CURATION.md
Analyse des formes d'onde	references/ANALYSIS.md

Installation

Nécessite Python ≥ 3.10. L'utilisation d'uv est recommandée.

# Paquets principaux (SpikeInterface intègre les outils de curation/modèle)
uv pip install "spikeinterface[full]" probeinterface neo

# Trieurs de spikes
uv pip install kilosort          # Kilosort4 (GPU CUDA requis)
uv pip install spykingcircus     # SpykingCircus (legacy ; SpykingCircus2 est fourni avec SpikeInterface)
uv pip install mountainsort5     # Mountainsort5 (CPU)

# Curation par modèle (UnitRefine) téléchargement depuis Hugging Face
uv pip install "huggingface_hub" skops

# Optionnel : curation visuelle assistée par IA
uv pip install anthropic

# Optionnel : outils IBL et Bombcell
uv pip install ibl-neuropixel ibllib bombcell

Pour des environnements reproductibles, fixez les versions (actuelles au 2026-06 : spikeinterface==0.104.3, kilosort==4.1.7, probeinterface==0.3.2, neo==0.14.4). Les installations sans versions fixées sont acceptables pour une expérimentation rapide mais doivent être fixées dans les pipelines de production.

Structure du projet

projet/
├── donnees_brutes/
│   └── enregistrement_g0/
│       └── enregistrement_g0_imec0/
│           ├── enregistrement_g0_t0.imec0.ap.bin
│           └── enregistrement_g0_t0.imec0.lf.bin
├── preprocessed/
├── motion/
├── ks4_output/
├── analyseur/
├── analyseur_propre/
├── phy_export/
├── 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/
    └── ...

Remarque : La racine du projet, donnees_brutes/, preprocessed/ et sortie/ ne sont pas suivis par git. Les taille des données Neuropixels dépasse largement les limites de stockage git ; utilisez un stockage externe (NAS, cloud ou Dandiset).