Skip to content

TurtleWave hdEEG Documentation

Welcome to the TurtleWave hdEEG documentation! TurtleWave is a Python toolkit for high-density EEG event detection and analysis in sleep research.

What is TurtleWave?

TurtleWave provides tools for:

  • Automated event detection - Detect sleep spindles, slow waves, and phase-amplitude coupling
  • Manual review - Validate detected events with an efficient GUI
  • Batch processing - Process large datasets on HPC clusters
  • Visualization - Explore EEG data and detected events interactively

🎓 New to TurtleWave?

Start with our tutorials to learn by doing:

🔧 Need to Solve a Specific Problem?

Check our how-to guides for practical solutions:

📚 Looking for Technical Details?

Browse our reference documentation:

🧠 Want to Understand How It Works?

Read our explanations:

Features

Event Detection

  • Sleep Spindles - Wavelet-based and bandpass detection methods
  • Slow Waves - Amplitude and slope-based detection
  • Phase-Amplitude Coupling (PAC) - Cross-frequency coupling analysis

Review GUI

  • QC-driven triage - Spot outlier channels first, then drill into their epochs
  • Keyboard-driven workflow - Flag a channel for re-detection with F
  • Flexible filtering - Filter by event type, channel, sleep stage, method, frequency band
  • Performance optimized - Handle 100,000+ events smoothly

Data Formats

  • Input: EEGLAB (.set/.fdt), EDF, MNE-compatible formats
  • Output: a SQLite database (neural_events.db) by default — one row per event, no intermediate files. Pass write_db=False (or --legacy-json on the driver scripts) to opt back into per-channel JSON plus an aggregated CSV instead.

Installation

pip install turtlewave-hdEEG

For detailed installation instructions, see the Installation Guide.

Quick Start

Detect Sleep Spindles

from wonambi.dataset import Dataset as WonambiDataset
from turtlewave_hdEEG import ParalEvents, CustomAnnotations

# Load EEG data and annotations
data = WonambiDataset('subject001.set')
annot = CustomAnnotations('subject001_annotations.xml')

# Detect spindles — events go straight into wonambi/neural_events.db;
# no per-channel JSON or CSV is written.
event_processor = ParalEvents(dataset=data, annotations=annot)
spindles = event_processor.detect_spindles(
    method='Ferrarelli2007',
    chan=['Cz', 'Fz'],
    frequency=(11, 16),
    stage=['NREM2', 'NREM3'],
    json_dir='wonambi/spindle_results',
    db_path='wonambi/neural_events.db',
)

See examples/hdEEG_spindle_detector.py for the full script, including density reporting. Need a flat CSV for a downstream stats tool? See Where did my CSV go?. To keep the old per-channel JSON → CSV → import pipeline instead, pass write_db=False — see Write Detection Results Directly to the Database.

Review Detected Events

eeg_review_gui

Then load your database, EEG file, and annotations, triage channels on the Channels (QC) tab, drill into a channel's Epochs to inspect outliers, and press F to flag a channel for re-detection.

See the EEG Review GUI Tutorial for a complete walkthrough.

Documentation Structure

This documentation follows the Diátaxis framework, organizing content into four types:

Type Purpose When to Use
Tutorials Learning-oriented lessons You're new and want to learn by doing
How-to Guides Problem-solving recipes You have a specific task to accomplish
Reference Technical specifications You need to look up details
Explanation Understanding-oriented discussion You want to understand how/why it works

Support

Contributing

We welcome contributions! See our repository for details.

Citation

If you use TurtleWave in your research, please cite:

@software{turtlewave2024,
  title = {TurtleWave: High-density EEG Event Detection for Sleep Research},
  author = {TurtleWave Development Team},
  year = {2024},
  url = {https://github.com/TancyKao/TurtleWave-hdEEG}
}

License

TurtleWave is released under the MIT License. See LICENSE for details.