Neuropixels-Analyse

Analyse von Neuropixels-Daten

Überblick

Toolkit zur Analyse hochdichter neuronaler Aufzeichnungen von Neuropixels-Sonden unter Verwendung aktueller Best Practices aus SpikeInterface, dem Allen Institute und dem International Brain Laboratory (IBL). Es deckt den gesamten Workflow von rohen Daten bis zu publikationsreifen kuratierten Einheiten (Units) ab.

Alle Beispiele verwenden die echte SpikeInterface-API (spikeinterface.full as si) sowie das begleitende Kurationsmodul (spikeinterface.curation as sc). Der Skill enthält ausführbare Skripte in scripts/ und eine kopier- und bearbeitbare Vorlage in assets/, die diesen Workflow direkt auf SpikeInterface implementieren. Es gibt kein separates Paket, das über die unter Installation aufgeführten Abhängigkeiten hinaus installiert werden müsste.

Wann dieser Skill verwendet werden sollte

Dieser Skill sollte verwendet werden, wenn:

• mit Neuropixels-Aufzeichnungen (.ap.bin, .lf.bin, .meta-Dateien) gearbeitet wird
• Daten aus den Formaten SpikeGLX, Open Ephys oder NWB geladen werden
• neuronale Aufzeichnungen vorverarbeitet werden (Filtern, gemeinsame Referenz, Erkennung fehlerhafter Kanäle)
• Bewegung/Drift erkannt und korrigiert wird
• Spike-Sorting durchgeführt wird (Kilosort4, SpykingCircus2, Mountainsort5, Tridesclous2)
• Qualitätsmetriken berechnet werden (SNR, ISI-Verletzungen, Anwesenheitsverhältnis, Amplitudengrenzwert)
• Units kuratiert werden (schwellenbasiert, modellbasiert oder KI-gestützt)
• Visualisierungen erstellt und nach Phy oder NWB exportiert werden

Unterstützte Hardware und Formate

Sonde	Elektroden	Kanäle	Hinweise
Neuropixels 1.0	960	384	phase_shift für ADC-Korrektur verwenden
Neuropixels 2.0 (einzeln)	1280	384	Dichteres Gitter
Neuropixels 2.0 (4-Schäfte)	5120	384	Mehrbereichsaufzeichnung

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

Schnellstart

Import und Konfiguration der Parallelverarbeitung

import spikeinterface.full as si

# Globale Job-Kwargs werden von allen parallelisierbaren Schritten wiederverwendet
si.set_global_job_kwargs(n_jobs=-1, chunk_duration="1s", progress_bar=True)

Daten laden

# Zuerst verfügbare Streams inspizieren
stream_names, stream_ids = si.get_neo_streams("spikeglx", "/pfad/zu/run_g0/")
print(stream_names)  # z.B. ['imec0.ap', 'imec0.lf', 'nidq']

# SpikeGLX (am häufigsten) — AP-Stream nach Namen auswählen
recording = si.read_spikeglx("/pfad/zu/run_g0/", stream_name="imec0.ap", load_sync_channel=False)

# Open Ephys
recording = si.read_openephys("/pfad/zu/Record_Node_101/")

# Für schnelle Iteration die ersten 60 s ausschneiden
fs = recording.get_sampling_frequency()
recording_sub = recording.frame_slice(0, int(60 * fs))

Vollständige Pipeline (gebündeltes Skript)

Das Repository enthält eine auf SpikeInterface basierende End-to-End-Pipeline:

python scripts/neuropixels_pipeline.py /pfad/zu/spikeglx/daten output/ --sorter kilosort4 --curation allen

Sie führt die Schritte Laden → Vorverarbeitung → Driftprüfung → optionale Bewegungskorrektur → Sorting → Nachverarbeitung → Qualitätsmetriken → Kuration → Export aus. Lesen Sie die folgenden Schritte, um sie interaktiv auszuführen oder die Pipeline anzupassen.

Standard-Analyse-Workflow

1. Vorverarbeitung

Empfohlene Kette, nach der SpikeInterface-Neuropixels-Anleitung (IBL-artige Destriping mit Kanalentfernung + gemeinsame Referenz):

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

Die vorverarbeitete Aufzeichnung speichern (Kilosort benötigt eine Binärdatei, und es beschleunigt die Wiederverwendung):

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

2. Drift prüfen und korrigieren

Vor dem Sorting immer den Drift inspizieren:

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

# Drift-Raster visualisieren
si.plot_drift_raster_map(peaks=peaks, peak_locations=peak_locations,
                         recording=rec, clim=(-50, 50))

Bei Bedarf Korrektur anwenden (Voreinstellungen: 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="bewegung/")

3. Spike-Sorting

# Kilosort4 (empfohlen, erfordert eine CUDA-GPU)
sorting = si.run_sorter("kilosort4", rec_corrected, folder="ks4_ausgabe")

# CPU-Alternativen (intern entwickelt, keine externe Installation)
sorting = si.run_sorter("spykingcircus2", rec_corrected, folder="sc2_ausgabe")
sorting = si.run_sorter("tridesclous2", rec_corrected, folder="tdc2_ausgabe")
sorting = si.run_sorter("mountainsort5", rec_corrected, folder="ms5_ausgabe")

# Externe Sorter können ohne lokale Installation in Containern ausgeführt werden
sorting = si.run_sorter("kilosort2_5", rec_corrected, folder="ks25_ausgabe", docker_image=True)

print(si.installed_sorters())

Hinweis: run_sorter verwendet das Argument folder=. Das ältere output_folder= ist veraltet.

4. Nachverarbeitung

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. Kuration mittels Metrikschwellenwerten

# Allen-artige Abfrage (Hinweis: Spalte heißt 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

Für wiederverwendbare, mehrschwellige Logik mit den Voreinstellungen allen / ibl / strict verwenden Sie das gebündelte scripts/compute_metrics.py. Einzelheiten und die Werkzeuge Bombcell / UnitMatch finden Sie in references/AUTOMATED_CURATION.md.

6. Modellbasierte Kuration (UnitRefine)

SpikeInterface kann vortrainierte maschinelle Lernklassifikatoren von Hugging Face über das Modul spikeinterface.curation anwenden. Die UnitRefine-Modelle wurden auf echten Neuropixels-Daten (V1, SC, ALM) trainiert:

import spikeinterface.curation as sc

# 1) Rauschen vs. neuronal
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) Single-Unit (sua) vs. Multi-Unit (mua) auf den verbleibenden Units
sua_mua_labels = sc.model_based_label_units(
    sorting_analyzer=neural,
    repo_id="SpikeInterface/UnitRefine_sua_mua_classifier",
    trust_model=True,
)

Jeder Aufruf gibt einen DataFrame mit prediction und probability (Konfidenz) pro Unit zurück. trust_model=True (oder eine explizite trusted=[...]-Liste) ist erforderlich, um das .skops-Modell zu laden – laden Sie nur Modelle aus Quellen, denen Sie vertrauen. Auf anderen Hirnregionen/Datensätzen trainierte Modelle übertragen sich möglicherweise nicht; validieren Sie gegen eine manuell beschriftete Teilmenge.

7. KI-gestützte Kuration (für unsichere Units)

Wenn der Skill in einem Agenten wie Cursor oder Claude Code ausgeführt wird, kann der Agent direkt Wellenform-/Korrelogramm-Plots inspizieren und eine Expertenbewertung abgeben – keine API-Einrichtung erforderlich. Erstellen Sie Plots und bitten Sie den Agenten, die Isolationsqualität zu bewerten.

Für programmatischen Zugriff auf visuelle Modelle: Lesen Sie API-Schlüssel aus der Umgebung – codieren Sie Anmeldeinformationen niemals fest in Analyses (sie gelangen in die Versionskontrolle und Protokolle):

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])  # setzen Sie dies in Ihrer Shell, nicht im Code

Das vollständige Muster (Rendern eines Unit-Übersichtsbildes, Erstellen des Prompts und Parsen der Antwort) finden Sie in references/AI_CURATION.md.

8. Ergebnisse exportieren

# Nur gute Units behalten, dann exportieren
analyzer_clean = analyzer.select_units(good_unit_ids, folder="analyzer_clean/", format="binary_folder")

# Phy für manuelle Überprüfung
si.export_to_phy(analyzer_clean, output_folder="phy_export/",
                 compute_pc_features=True, compute_amplitudes=True)

# Figurenbericht
si.export_report(analyzer_clean, "bericht/", format="png")

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

# Metriktabelle
metrics.to_csv("qualitaetsmetriken.csv")

Häufige Fallstricke und Best Practices

1. Drift immer vor dem Spike-Sorting überprüfen – Drift > ~10 μm verschlechtert die Qualität erheblich.
2. phase_shift für Neuropixels 1.0 verwenden, um ADC-Abtastabweichungen zu korrigieren.
3. Die vorverarbeitete Aufzeichnung mit rec.save(folder=...) speichern, um Neuberechnung zu vermeiden (Kilosort benötigt auch eine Binärdatei).
4. Eine GPU für Kilosort4 verwenden – es ist viel schneller als CPU-Sorter.
5. Unsichere Units überprüfen – automatisierte/modellbasierte Kuration ist ein Ausgangspunkt, kein Urteil.
6. Ansätze kombinieren – Schwellenwerte für klare Fälle, Modell/KI für Grenzfälle verwenden.
7. Schwellenwerte und Modell-Repository-IDs für die Reproduzierbarkeit dokumentieren.
8. Für kritische Experimente nach Phy exportieren – menschliche Aufsicht ist wertvoll.

Wichtige anzupassende Parameter

Vorverarbeitung

• freq_min: Hochpass-Grenzfrequenz (300–400 Hz typisch)
• detect_bad_channels: gibt (bad_channel_ids, channel_labels) zurück

Bewegungskorrektur

• preset: nonrigid_fast_and_accurate (ausgewogen), nonrigid_accurate (starker Drift), dredge (modernster Stand)

Spike-Sorting (Kilosort4)

• batch_size: Samples pro Batch (60000 Standard)
• nblocks: Drift-Blöcke (erhöhen für lange, driftende Aufzeichnungen)
• Th_universal / Th_learned: Erkennungsschwellen (niedriger = mehr Spikes)

Qualitätsmetriken

• snr: Signal-Rausch-Grenzwert (3–5 typisch)
• isi_violations_ratio: Refraktärverletzungen (0.01–0.5)
• presence_ratio: Aufzeichnungsabdeckung (0.5–0.95)

Gebündelte Ressourcen

scripts/explore_recording.py

Schnelle Inspektion einer Aufzeichnung (Streams, Kanäle, Dauer, fehlerhafte Kanäle):

python scripts/explore_recording.py /pfad/zu/daten

scripts/preprocess_recording.py

Automatisierte Vorverarbeitung:

python scripts/preprocess_recording.py /pfad/zu/daten --output vorverarbeitet/

scripts/run_sorting.py

Spike-Sorting ausführen:

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

scripts/compute_metrics.py

Qualitätsmetriken berechnen und Kuration anwenden:

python scripts/compute_metrics.py sorting/ vorverarbeitet/ --output metrik/ --curation allen

scripts/export_to_phy.py

Nach Phy für manuelle Kuration exportieren:

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

scripts/neuropixels_pipeline.py

Vollständige End-to-End-Pipeline (siehe Schnellstart).

assets/analysis_template.py

Vollständige, bearbeitbare Analysevorlage. Kopieren und anpassen:

cp assets/analysis_template.py meine_analyse.py
# Abschnitt PARAMETERS bearbeiten, dann ausführen
python meine_analyse.py

Detaillierte Referenzhandbücher

Thema	Referenz
Vollständiger Workflow	references/standard_workflow.md
API-Referenz (SpikeInterface)	references/api_reference.md
Plotting-Anleitung	references/plotting_guide.md
Vorverarbeitung	references/PREPROCESSING.md
Spike-Sorting	references/SPIKE_SORTING.md
Bewegungskorrektur	references/MOTION_CORRECTION.md
Qualitätsmetriken	references/QUALITY_METRICS.md
Automatisierte und modellbasierte Kuration	references/AUTOMATED_CURATION.md
KI-gestützte Kuration	references/AI_CURATION.md
Wellenformanalyse	references/ANALYSIS.md

Installation

Erfordert Python ≥ 3.10. Die Verwendung von uv wird empfohlen.

# Kernpakete (SpikeInterface bündelt die Kurations-/Modellwerkzeuge)
uv pip install "spikeinterface[full]" probeinterface neo

# Spike-Sorter
uv pip install kilosort          # Kilosort4 (CUDA GPU erforderlich)
uv pip install spykingcircus     # SpykingCircus (Legacy; SpykingCircus2 wird mit SpikeInterface mitgeliefert)
uv pip install mountainsort5     # Mountainsort5 (CPU)

# Modellbasierte Kuration (UnitRefine) lädt von Hugging Face herunter
uv pip install "huggingface_hub" skops

# Optional: KI-gestützte visuelle Kuration
uv pip install anthropic

# Optional: IBL-Werkzeuge und Bombcell
uv pip install ibl-neuropixel ibllib bombcell

Für reproduzierbare Umgebungen Versionen festlegen (aktueller Stand Juni 2026: spikeinterface==0.104.3, kilosort==4.1.7, probeinterface==0.3.2, neo==0.14.4). Nicht festgelegte Installationen sind für schnelle Experimente in Ordnung, sollten aber in Produktionspipelines festgelegt werden.

Projektstruktur

projekt/
├── rohdaten/
│   └── aufnahme_g0/
│       └── aufnahme_g0_imec0/
│           ├── aufnahme_g0_t0.imec0.ap.bin
│           └── aufnahme_g0_t0.imec0.lf.bin
├── vorverarbeitet/
│   ├── ap.bin
│   └── ap.json
├── bewegung/
├── ks4_ausgabe/
├── analyzer/
├── analyzer_clean/
├── phy_export/
├── bericht/
├── metrik/
├── scripts/
├── assets/
├── referenzen/
└── README.md

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.