| name | neuropixels-analysis |
| description | Neuropixels neural recording analysis. Load SpikeGLX/OpenEphys data, preprocess, motion correction, Kilosort4 spike sorting, quality metrics, Allen/IBL curation, AI-assisted visual analysis, for Neuropixels 1.0/2.0 extracellular electrophysiology. Use when working with neural recordings, spike sorting, extracellular electrophysiology, or when the user mentions Neuropixels, SpikeGLX, Open Ephys, Kilosort, quality metrics, or unit curation. |
| license | MIT license |
| metadata | version: "1.0" skill-author: K-Dense Inc. |
Neuropixels Data Analysis
Overview
Comprehensive toolkit for analyzing Neuropixels high-density neural recordings using current best practices from SpikeInterface, Allen Institute, and International Brain Laboratory (IBL). Supports the full workflow from raw data to publication-ready curated units.
When to Use This Skill
This skill should be used when:
- Working with Neuropixels recordings (.ap.bin, .lf.bin, .meta files)
- Loading data from SpikeGLX, Open Ephys, or NWB formats
- Preprocessing neural recordings (filtering, CAR, bad channel detection)
- Detecting and correcting motion/drift in recordings
- Running spike sorting (Kilosort4, SpykingCircus2, Mountainsort5)
- Computing quality metrics (SNR, ISI violations, presence ratio)
- Curating units using Allen/IBL criteria
- Creating visualizations of neural data
- Exporting results to Phy or NWB
Supported Hardware & Formats
| Probe | Electrodes | Channels | Notes |
|---|
| Neuropixels 1.0 | 960 | 384 | Requires phase_shift correction |
| Neuropixels 2.0 (single) | 1280 | 384 | Denser geometry |
| Neuropixels 2.0 (4-shank) | 5120 | 384 | Multi-region recording |
| Format | Extension | Reader |
|---|
| SpikeGLX | .ap.bin, .lf.bin, .meta | si.read_spikeglx() |
| Open Ephys | .continuous, .oebin | si.read_openephys() |
| NWB | .nwb | si.read_nwb() |
Quick Start
Basic Import and Setup
import spikeinterface.full as si
import neuropixels_analysis as npa
job_kwargs = dict(n_jobs=-1, chunk_duration='1s', progress_bar=True)
Loading Data
recording = si.read_spikeglx('/path/to/data', stream_id='imec0.ap')
recording = si.read_openephys('/path/to/Record_Node_101/')
streams, ids = si.get_neo_streams('spikeglx', '/path/to/data')
print(streams)
recording = recording.frame_slice(0, int(60 * recording.get_sampling_frequency()))
Complete Pipeline (One Command)
results = npa.run_pipeline(
recording,
output_dir='output/',
sorter='kilosort4',
curation_method='allen',
)
sorting = results['sorting']
metrics = results['metrics']
labels = results['labels']
Standard Analysis Workflow
1. Preprocessing
rec = si.highpass_filter(recording, freq_min=400)
rec = si.phase_shift(rec)
bad_ids, _ = si.detect_bad_channels(rec)
rec = rec.remove_channels(bad_ids)
rec = si.common_reference(rec, operator='median')
rec = npa.preprocess(recording)
2. Check and Correct Drift
motion_info = npa.estimate_motion(rec, preset='kilosort_like')
npa.plot_drift(rec, motion_info, output='drift_map.png')
if motion_info['motion'].max() > 10:
rec = npa.correct_motion(rec, preset='nonrigid_accurate')
3. Spike Sorting
sorting = si.run_sorter('kilosort4', rec, folder='ks4_output')
sorting = si.run_sorter('tridesclous2', rec, folder='tdc2_output')
sorting = si.run_sorter('spykingcircus2', rec, folder='sc2_output')
sorting = si.run_sorter('mountainsort5', rec, folder='ms5_output')
print(si.installed_sorters())
4. Postprocessing
analyzer = si.create_sorting_analyzer(sorting, rec, sparse=True)
analyzer.compute('random_spikes', max_spikes_per_unit=500)
analyzer.compute('waveforms', ms_before=1.0, ms_after=2.0)
analyzer.compute('templates', operators=['average', 'std'])
analyzer.compute('spike_amplitudes')
analyzer.compute('correlograms', window_ms=50.0, bin_ms=1.0)
analyzer.compute('unit_locations', method='monopolar_triangulation')
analyzer.compute('quality_metrics')
metrics = analyzer.get_extension('quality_metrics').get_data()
5. Curation
good_units = metrics.query("""
presence_ratio > 0.9 and
isi_violations_ratio < 0.5 and
amplitude_cutoff < 0.1
""").index.tolist()
labels = npa.curate(metrics, method='allen')
6. AI-Assisted Curation (For Uncertain Units)
When using this skill with Claude Code, Claude can directly analyze waveform plots and provide expert curation decisions. For programmatic API access:
from anthropic import Anthropic
client = Anthropic()
uncertain = metrics.query('snr > 3 and snr < 8').index.tolist()
for unit_id in uncertain:
result = npa.analyze_unit_visually(analyzer, unit_id, api_client=client)
print(f"Unit {unit_id}: {result['classification']}")
print(f" Reasoning: {result['reasoning'][:100]}...")
Claude Code Integration: When running within Claude Code, ask Claude to examine waveform/correlogram plots directly - no API setup required.
7. Generate Analysis Report
report_dir = npa.generate_analysis_report(results, 'output/')
npa.print_analysis_summary(results)
8. Export Results
si.export_to_phy(analyzer, output_folder='phy_export/',
compute_pc_features=True, compute_amplitudes=True)
from spikeinterface.exporters import export_to_nwb
export_to_nwb(rec, sorting, 'output.nwb')
metrics.to_csv('quality_metrics.csv')
Common Pitfalls and Best Practices
- Always check drift before spike sorting - drift > 10ฮผm significantly impacts quality
- Use phase_shift for Neuropixels 1.0 probes (not needed for 2.0)
- Save preprocessed data to avoid recomputing - use
rec.save(folder='preprocessed/')
- Use GPU for Kilosort4 - it's 10-50x faster than CPU alternatives
- Review uncertain units manually - automated curation is a starting point
- Combine metrics with AI - use metrics for clear cases, AI for borderline units
- Document your thresholds - different analyses may need different criteria
- Export to Phy for critical experiments - human oversight is valuable
Key Parameters to Adjust
Preprocessing
freq_min: Highpass cutoff (300-400 Hz typical)detect_threshold: Bad channel detection sensitivity
Motion Correction
preset: 'kilosort_like' (fast) or 'nonrigid_accurate' (better for severe drift)
Spike Sorting (Kilosort4)
batch_size: Samples per batch (30000 default)nblocks: Number of drift blocks (increase for long recordings)Th_learned: Detection threshold (lower = more spikes)
Quality Metrics
snr_threshold: Signal-to-noise cutoff (3-5 typical)isi_violations_ratio: Refractory violations (0.01-0.5)presence_ratio: Recording coverage (0.5-0.95)
Bundled Resources
scripts/preprocess_recording.py
Automated preprocessing script:
python scripts/preprocess_recording.py /path/to/data --output preprocessed/
scripts/run_sorting.py
Run spike sorting:
python scripts/run_sorting.py preprocessed/ --sorter kilosort4 --output sorting/
scripts/compute_metrics.py
Compute quality metrics and apply curation:
python scripts/compute_metrics.py sorting/ preprocessed/ --output metrics/ --curation allen
scripts/export_to_phy.py
Export to Phy for manual curation:
python scripts/export_to_phy.py metrics/analyzer --output phy_export/
assets/analysis_template.py
Complete analysis template. Copy and customize:
cp assets/analysis_template.py my_analysis.py
python my_analysis.py
references/standard_workflow.md
Detailed step-by-step workflow with explanations for each stage.
references/api_reference.md
Quick function reference organized by module.
references/plotting_guide.md
Comprehensive visualization guide for publication-quality figures.
Detailed Reference Guides
Installation
pip install spikeinterface[full] probeinterface neo
pip install kilosort
pip install spykingcircus
pip install mountainsort5
pip install neuropixels-analysis
pip install anthropic
pip install ibl-neuropixel ibllib
Project Structure
project/
โโโ raw_data/
โ โโโ recording_g0/
โ โโโ recording_g0_imec0/
โ โโโ recording_g0_t0.imec0.ap.bin
โ โโโ recording_g0_t0.imec0.ap.meta
โโโ preprocessed/ # Saved preprocessed recording
โโโ motion/ # Motion estimation results
โโโ sorting_output/ # Spike sorter output
โโโ analyzer/ # SortingAnalyzer (waveforms, metrics)
โโโ phy_export/ # For manual curation
โโโ ai_curation/ # AI analysis reports
โโโ results/
โโโ quality_metrics.csv
โโโ curation_labels.json
โโโ output.nwb
Additional Resources
