How braingeneers/braindance works
Project type and purpose
• BrainDance is an open‐source Python toolkit for running neural stimulation experiments, doing real‐time spike detection/sorting, and post‐hoc analysis.
• It bundles drivers for two hardware backends (Maxwell stimulation hardware and Open Ephys acquisition) plus machine‐learning–based spikedetection and optional integration with Kilosort2.
File structure and core modules
• Top‐level package: braindance/
• analysis/: post‐hoc data‐loading and analysis utilities
• core/: heart of the system
– base_env.py + maxwell_env.py + open_ephys_env.py: hardware abstractions
– artifact_removal.py, phases.py, params.py: signal‐processing primitives
– spikedetector/: ML models (PyTorch) for real‐time detection
– spikesorter/: wrappers for Kilosort2 and RT‐Sort flows
– trainer.py: orchestrates training of detection models
• experiments/: user scripts to define and run stimulation protocols
• gui/: user interface layer and static resources
• Other files:
• requirements.txt / setup.py (package config)
• gen_docs.py (docs generator)
README insights
• Emphasizes conda/PIP installation, optional RT‐Sort (Torch‐TensorRT), and Kilosort2 integration.
• Notes optional dependency on open-ephys-python-tools.
Main components
A. Hardware & Data Sources
1. Maxwell stimulation hardware (via maxwell_env)
2. Open Ephys acquisition (via open_ephys_env)
B. Core Library Layers
1. Base Environment API (base_env)
2. Signal Processing
– Artifact Removal
– Phase & Parameter Management
3. Spikedetector (ML inference)
4. Spikesorter (external algorithm wrappers)
5. Trainer (model training pipeline)
C. User‐Facing Layers
1. Experiments scripts (CLI or Python API)
2. GUI application
D. Analysis Subsystem
– analysis/data_loader for post‐hoc processing
E. External Dependencies
– PyTorch (+ Torch‐TensorRT)
– Kilosort2 repository
– open‐ephys‐python‐tools
Relationships and data flows
• Experiments and GUI bootstrap and control the Core Library; they feed parameters and receive real‐time data/plots.
• Analysis module reads data files produced by Core Library for offline analysis.
• External libraries plugged into specific layers (e.g. PyTorch under Spikedetector, Kilosort2 under Spikesorter).
Architectural patterns and principles
• Layered architecture: hardware‐abstraction → processing → user orchestration.
• Modular plugin style for environment backends and sorting algorithms.
• Clear separation of real‐time (spikedetector) vs. offline (analysis) concerns.