turtlewave_hdEEG package

Submodules

turtlewave_hdEEG.addjson2xml module

turtlewave_hdEEG.addjson2xml.convert_json_to_xml(json_files, output_dir='.', existing_xml=None, event_type='slowwave')

Convert multiple JSON files containing events (slow waves or spindles) into a single XML file. Can append to an existing XML file if provided.

Parameters: json_files (list): List of paths to JSON files output_dir (str): Directory to save the output XML file existing_xml (str): Path to existing XML file to append to (optional) event_type (str): Type of event to create (‘slowwave’ or ‘spindle’)

turtlewave_hdEEG.addjson2xml.create_new_wonambi_xml()

Create a new Wonambi-compatible XML structure

turtlewave_hdEEG.annotation module

Annotations module for turtlewave_hdEEG Provides tools to create and save annotations using event information from EEGLAB

class turtlewave_hdEEG.annotation.XLAnnotations(dataset, annot_file, rater_name='Anon')

Bases: object

Simplified annotations for large datasets

Initialize annotations object.

Parameters:

• dataset (LargeDataset) – Dataset to associate with annotations.

• annot_file (str) – Path to the annotation file.

add_artefacts_from_events()

Add artefact and arousal annotations from the dataset’s event information.

Uses the ‘isreject’ flag in events to identify artefacts. Also identifies arousal events if ‘arousal’ is in the event type (case-insensitive).

Highly optimized for large datasets by pre-filtering relevant events.

add_stages_from_header()

Import stages from header array into annotations using Wonambi’s import_staging with Compumedics format.

Parameters:

rater_name (str) – Name of the rater to use for staging (default: “Automatic_Staging”)

Returns:

True if successful, False otherwise

Return type:

bool

add_annotations_batch(label, start_times, end_times, channels=None)

Add multiple annotations at once.

add_annotation(label, start_time, end_time, channel=None)

Add a single annotation to the annotations object.

Parameters:

• label (str) – Label for the annotation

• start_time (float) – Start time in seconds

• end_time (float) – End time in seconds

• channel (str, list, or None) – Channel(s) associated with the annotation. If None, uses ‘(all)’ to indicate all channels.

Returns:

True if successful, False otherwise

Return type:

bool

process_all()

Process all annotations - add artefacts and stages.

save(filename=None)

Save annotations to the XML file in Wonambi format.

Parameters:

filename (str or None) – Path to save the file. If None, uses the annot_file from initialization.

class turtlewave_hdEEG.annotation.CustomAnnotations(annot_file)

Bases: object

Helper class for reading and working with Wonambi annotations

property last_second

Return the last second in the recording

property first_second

Return the first second in the recording

property dataset

Return the dataset associated with the annotations

property rater

Return the current rater

property raters

Return all raters in the annotation file

property epochs

Get all epochs from the annotation file

get_epochs(*args, **kwargs)

Get epochs that match the specified criteria. This method matches the Wonambi API for compatibility.

Returns:

list of epochs, which are dict with ‘start’ and ‘end’ times, plus additional parameters

Return type:

list of dict

get_rater(rater)

Select one rater.

Parameters:

rater (str) – name of the rater

add_rater(rater)

Add one rater.

Parameters:

rater (str) – name of the rater

get_stages()

Extract just the stages from the epochs

get_hypnogram()

Convert stages to numeric values for hypnogram plotting

save(filename=None)

Save annotations to the XML file in Wonambi format.

Parameters:

filename (str or None) – Path to save the file. If None, uses the annot_file from initialization.

create_epochs(times, epoch_length=30)

Create epochs from a sequence of time points.

Parameters:

• times (list or ndarray) – List of time points (in seconds)

• epoch_length (float, optional) – Length of each epoch in seconds

get_times(stage=None, cycle=None, exclude=None)

Return the times (start and end) for all epochs that match the parameters.

Parameters:

• stage (str or None) – Stage to match with

• cycle (str or None) – Cycle to match with

• exclude (str or None) – Stage to exclude

Returns:

Each tuple contains the start and end time of an epoch

Return type:

list of tuple

__getattr__(name)

Delegate any other method calls to the original WonambiAnnotations object

turtlewave_hdEEG.dataset module

class turtlewave_hdEEG.dataset.LargeDataset(filename, create_memmap=False, memmap_dir=None, extract_eeglab_metadata=True)

Bases: object

Dataset class optimized for large EEG recordings

Initialize a large dataset handler

Parameters:

• filename (str) – Path to the original EEG file

• create_memmap (bool) – Whether to create a memory-mapped version of the data

• memmap_dir (str or None) – Directory to store memory-mapped files, if None use same directory as input

create_memmap(memmap_dir=None)

Create a memory-mapped version of the data for faster access

read_data(begtime=None, endtime=None, chan=None)

Read data from the dataset, using memory map if available

Parameters:

• begtime (float or None) – Start time in seconds

• endtime (float or None) – End time in seconds

• chan (list or None) – List of channels to load

Returns:

data – Array containing the requested data

Return type:

ndarray

turtlewave_hdEEG.eventprocessor module

class turtlewave_hdEEG.eventprocessor.ParalEvents(dataset, annotations=None, log_level=20, log_file=None)

Bases: object

A class for parallel detection and analysis of EEG events such as spindles, and other neural events across multiple channels.

Initialize the ParalEvents object.

Parameters:

• dataset (Dataset) – Dataset object containing EEG data

• annotations (XLAnnotations) – Annotations object for storing and retrieving events

• log_level (int) – Logging level (e.g., logging.DEBUG, logging.INFO)

• log_file (str or None) – Path to log file. If None, logs to console only.

clean_memory()

Perform thorough memory cleanup to release resources

detect_spindles(method='Ferrarelli2007', chan=None, ref_chan=[], grp_name='eeg', frequency=(11, 16), duration=(0.5, 3), polar='normal', reject_artifacts=True, reject_arousals=True, stage=None, cat=None, save_to_annotations=False, json_dir=None, create_empty_json=True, **detector_params)

Detect spindles in the dataset while considering artifacts and arousals.

Parameters:

• method (str or list) – Detection method(s) to use (‘Ferrarelli2007’, ‘Wamsley2012’, etc.)

• chan (list or str) – Channels to analyze

• ref_chan (list or str) – Reference channel(s) for re-referencing, or None to use original reference

• grp_name (str) – Group name for channel selection

• frequency (tuple) – Frequency range for spindle detection (min, max)

• duration (tuple) – Duration range for spindle detection in seconds (min, max)

• polar (str) – ‘normal’ or ‘opposite’ for handling signal polarity

• reject_artifacts (bool) – Whether to exclude segments marked with artifact annotations

• reject_arousals (bool) – Whether to exclude segments marked with arousal annotations

• json_dir (str or None) – Directory to save individual channel JSON files (one per channel)

• create_empty_json (bool) – Whether to create empty JSON files when no spindles are found

• **detector_params (dict)

• method-specific (Additional parameters to pass to the detector. These are)

• det_thresh (and can include parameters like)

• sel_thresh

• etc.

Returns:

List of all detected spindles

Return type:

list

export_spindle_parameters_to_csv(json_input, csv_file, export_params='all', frequency=None, ref_chan=None, grp_name='eeg', n_fft_sec=4, file_pattern=None, skip_empty_files=True)

Calculate spindle parameters from JSON files and export to CSV.

Parameters:

• json_input (str or list) – Path to JSON file, directory of JSON files, or list of JSON files

• csv_file (str) – Path to output CSV file

• export_params (dict or str) – Parameters to export. If ‘all’, exports all available parameters

• frequency (tuple or None) – Frequency range for power calculations (default: None, uses original range from JSON)

• ref_chan (list or None) – Reference channel(s) to use for parameter calculation

• n_fft_sec (int) – FFT window size in seconds for spectral analysis

• file_pattern (str or None) – Pattern to filter JSON files if json_input is a directory

• grp_name (str) – Group name for channel selection

• skip_empty_files (bool) – Whether to skip empty JSON files or include them in the report

Returns:

Dictionary of calculated parameters

Return type:

dict

export_spindle_density_to_csv(json_input, csv_file, stage=None, file_pattern=None)

Export spindle statistics to CSV with both whole night and stage-specific densities.

Parameters:

• json_input (str or list) – Path to JSON file, directory of JSON files, or list of JSON files

• csv_file (str) – Path to output CSV file

• stage (str or list) – Sleep stage(s) to include (e.g., ‘NREM2’, [‘NREM2’, ‘NREM3’]) if None, will extract stages from spindles

• file_pattern (str or None)

Returns:

Dictionary with spindle statistics by channel

Return type:

dict

save_detection_summary(output_dir, method, parameters, results_summary)

Save a comprehensive summary of detection parameters and results.

Parameters:

• output_dir (str) – Directory to save the summary

• method (str) – Detection method used

• parameters (dict) – All parameters used for detection

• results_summary (dict) – Summary of detection results

initialize_sqlite_database(db_path='neural_events.db')

Create SQLite database optimized for storing calculated event parameters from event_params() function.

Parameters:

db_path (str) – Path to SQLite database file

Returns:

Path to created database

Return type:

str

import_parameters_csv_to_database(csv_file, db_path, append=True)

Import event parameters from an existing CSV file into SQLite database. Supports multiple event types and incremental updates.

Parameters:

• csv_file (str) – Path to existing parameters CSV file

• db_path (str) – Path to SQLite database

• append (bool) – If True, adds to existing database without replacing existing entries If False, replaces any existing entries with the same UUID

Returns:

Summary of the operation with counts of added, updated, and skipped rows

Return type:

dict

turtlewave_hdEEG.extensions module

Custom extensions to Wonambi spindle detection

class turtlewave_hdEEG.extensions.ImprovedDetectSpindle(method='Moelle2011', frequency=None, duration=None, det_thresh=None, sel_thresh=None, moving_rms=None, smooth_dur=None, tolerance=None, min_interval=None, merge=False, polar='normal', **kwargs)

Bases: DetectSpindle

Initialize improved spindle detection.

Parameters:

• method (str) – Detection method. Supported methods include: ‘Ferrarelli2007’, ‘Moelle2011’, ‘Nir2011’, ‘Wamsley2012’, ‘Martin2013’, ‘Ray2015’, ‘Lacourse2018’

• frequency (tuple of float) – Frequency range for spindle detection (low and high)

• duration (tuple of float) – Duration range for spindles in seconds (min and max)

• det_thresh (float or None) – Detection threshold (method-specific units)

• sel_thresh (float or None) – Selection threshold (method-specific units)

• moving_rms (dict or float or None) – Parameters for moving RMS, format: {‘dur’: float, ‘step’: float or None} or just duration as float

• smooth_dur (float or None) – Duration for smoothing window in seconds

• tolerance (float or None) – Tolerance for merging events in seconds

• min_interval (float or None) – Minimum interval between events in seconds

• merge (bool) – If True, merge events across channels

• polar (str) – Signal polarity - ‘normal’ or ‘opposite’

• **kwargs (dict) – Additional method-specific parameters

__call__(data, parent=None)

Detect spindles in the data with optional signal inversion.

Parameters:

• data (instance of Data) – The data to analyze

• parent (QWidget) – For use with GUI, as parent widget for the progress bar

• timeout (int) – Maximum time in seconds to allow for detection before timing out

Returns:

Detected spindles

Return type:

instance of graphoelement.Spindles

class turtlewave_hdEEG.extensions.ImprovedDetectSlowWave(method='Massimini2004', frequency=None, duration=None, neg_peak_thresh=40, p2p_thresh=75, min_dur=None, max_dur=None, polar='normal')

Bases: DetectSlowWave

Initialize improved slow wave detection.

Parameters:

• method (str) – Detection method. Supported methods: - ‘Massimini2004’: Traditional threshold-based detection - ‘AASM/Massimini2004’: AASM criteria with Massimini method - ‘Ngo2015’: Detection based on Ngo et al. 2015 - ‘Staresina2015’: Detection based on Staresina et al. 2015

• frequency (tuple of float) – Frequency range for slow wave detection

• duration (tuple of float) – Duration range for slow waves in seconds (used for trough_duration in Massimini methods)

• neg_peak_thresh (float) – Minimum negative peak amplitude in μV

• p2p_thresh (float) – Minimum peak-to-peak amplitude in μV

• min_dur (float or None) – Minimum duration of a slow wave in seconds (used for Ngo2015 and Staresina2015)

• max_dur (float or None) – Maximum duration of a slow wave in seconds (used for Ngo2015 and Staresina2015)

• polar (str) – Signal polarity - ‘normal’ or ‘opposite’

__call__(data)

Detect slow waves in the data.

Parameters:

data (instance of Data) – The data to analyze

Returns:

Detected slow waves

Return type:

instance of graphoelement.SlowWaves

turtlewave_hdEEG.json_to_annotations module

turtlewave_hdEEG.pacprocessor module

pac_processor.py A class for phase-amplitude coupling (PAC) analysis for high-density EEG data. Based on the OCTOPUS method from the seapipe package.

class turtlewave_hdEEG.pacprocessor.ParalPAC(dataset, annotations=None, rootpath=None, log_level=20, log_file=None)

Bases: object

A class for parallel detection and analysis of phase-amplitude coupling (PAC) across multiple channels of high-density EEG data.

Initialize the ParalPAC object.

Parameters:

• dataset (Dataset) – Dataset object containing EEG data

• annotations (Annotations) – Annotations object for storing and retrieving events

• rootpath (str) – Root path for input/output operations

• log_level (int) – Logging level (e.g., logging.DEBUG, logging.INFO)

• log_file (str or None) – Path to log file. If None, logs to console only.

pac_method(method, surrogate, correction, list_methods=False)

Format the method and corrections to be applied through Tensorpac. Adapted from OCTOPUS module.

Parameters:

• method (int) – PAC method number

• surrogate (int) – Surrogate method number

• correction (int) – Correction method number

• list_methods (bool) – If True, return a list of method descriptions

Returns:

Either a tuple of (method, surrogate, correction) or a list of descriptions

Return type:

tuple or list

analyze_pac(chan=None, ref_chan=None, grp_name='eeg', stage=None, rater=None, reject_artf=['Artefact', 'Arousal'], cycle_idx=None, cat=(1, 1, 1, 0), nbins=18, phase_freq=(0.5, 1.25), amp_freq=(11, 16), idpac=(2, 3, 4), min_dur=1, adap_bands_phase='Fixed', adap_bands_amplitude='Fixed', filter_opts=None, event_opts=None, invert=False, use_detected_events=True, event_type='slow_wave', pair_with_spindles=False, time_window=0.5, db_path=None, out_dir=None, progress=False)

Analyze phase-amplitude coupling (PAC) in the dataset.

Parameters:

• chan (list or str) – Channels to analyze

• ref_chan (list or str) – Reference channel(s) for re-referencing

• grp_name (str) – Group name for channel selection

• stage (list or str) – Sleep stage(s) to analyze

• rater (str) – Rater name for annotations

• reject_artf (list) – Event types to reject

• cycle_idx (list or None) – Sleep cycle indices to include

• cat (tuple) – Category specification for data selection

• nbins (int) – Number of phase bins

• phase_freq (tuple) – Frequency range for phase signal

• amp_freq (tuple) – Frequency range for amplitude signal

• idpac (tuple) – PAC method settings (method, surrogate, correction)

• min_dur (float) – Minimum event duration in seconds

• adap_bands_phase (str) – Type of frequency band adaptation for phase

• adap_bands_amplitude (str) – Type of frequency band adaptation for amplitude

• filter_opts (dict) – Signal filtering options

• event_opts (dict) – Event processing options

• invert (bool) – Whether to invert signal polarity

• use_detected_events (bool) – Whether to use detected events for PAC analysis

• event_type (str) – Type of events to use (‘slow_wave’ or ‘spindle’)

• pair_with_spindles (bool) – If True and event_type is ‘slow_wave’, will pair slow waves with spindles

• time_window (float) – Time window (in seconds) to search for spindles around slow waves

• db_path (str) – Path to the SQLite database containing events

• out_dir (str) – Output directory for results

• progress (bool) – Whether to show progress bar

Returns:

Dictionary containing PAC results

Return type:

dict

generate_comodulogram(chan=None, stage=None, phase_freqs=None, amp_freqs=None, idpac=(2, 3, 4), buffer=1.0, out_dir=None, reject_artf=['Artefact', 'Arousal'])

Generate a comodulogram for the given channel and parameters.

Parameters:

• chan (str) – Channel to analyze

• stage (list or str) – Sleep stage(s) to analyze

• phase_freqs (list of tuples) – List of phase frequency bands to analyze

• amp_freqs (list of tuples) – List of amplitude frequency bands to analyze

• idpac (tuple) – PAC method settings (method, surrogate, correction)

• buffer (float) – Buffer in seconds

• out_dir (str) – Output directory for results

• reject_artf (list) – Event types to reject

Returns:

Dictionary containing comodulogram results

Return type:

dict

compare_conditions(condition1, condition2, test_type='watson_williams', alpha=0.05, out_dir=None)

Compare PAC between two conditions.

Parameters:

• condition1 (dict) – First condition with keys ‘amp_file’, ‘stage’, etc.

• condition2 (dict) – Second condition with keys ‘amp_file’, ‘stage’, etc.

• test_type (str) – Type of statistical test (‘watson_williams’ or ‘permutation’)

• alpha (float) – Significance level

• out_dir (str) – Output directory for results

Returns:

Dictionary containing comparison results

Return type:

dict

export_pac_parameters_to_csv(json_dir=None, csv_file=None, channels=None, stages=None, phase_freq=None, amp_freq=None, append=True, method_info=None, out_dir=None)

Export PAC parameters from tracking to a CSV file.

Parameters:

• json_dir (str) – Directory containing JSON files or individual channel CSV files

• csv_file (str) – Output CSV file

• channels (list) – List of channels to include

• stages (list) – List of sleep stages to include

• phase_freq (tuple) – Phase frequency range

• amp_freq (tuple) – Amplitude frequency range

• append (bool) – If True, append to existing CSV file by channel rather than overwrite

• method_info (dict) – Dictionary containing method information (sw_method, spindle_method)

• out_dir (str) – Base output directory to use

Returns:

Dictionary containing export results

Return type:

dict

turtlewave_hdEEG.swprocessor module

class turtlewave_hdEEG.swprocessor.ParalSWA(dataset, annotations=None, log_level=20, log_file=None)

Bases: object

A class for parallel detection and analysis of slow wave activity (SWA) across multiple channels.

Initialize the ParalSWA object.

Parameters:

• dataset (Dataset) – Dataset object containing EEG data

• annotations (XLAnnotations) – Annotations object for storing and retrieving events

• log_level (int) – Logging level (e.g., logging.DEBUG, logging.INFO)

• log_file (str or None) – Path to log file. If None, logs to console only.

clean_memory()

Perform thorough memory cleanup to release resources

detect_slow_waves(method='Massimini2004', chan=None, ref_chan=[], grp_name='eeg', frequency=(0.1, 4), trough_duration=(0.3, 1.5), neg_peak_thresh=-80.0, p2p_thresh=140.0, min_dur=None, max_dur=None, detrend=False, polar='normal', reject_artifacts=True, reject_arousals=True, stage=None, cat=None, peak_thresh_sigma=None, ptp_thresh_sigma=None, save_to_annotations=False, json_dir=None, create_empty_json=True)

Detect slow waves in the dataset while considering artifacts and arousals.

Parameters:

• method (str or list) – Detection method(s) to use (‘Massimini2004’, ‘AASM/Massimini2004’, ‘Ngo2015’, ‘Staresina2015’)

• chan (list or str) – Channels to analyze

• ref_chan (list or str) – Reference channel(s) for re-referencing

• grp_name (str) – Group name for channel selection

• frequency (tuple) – Frequency range for slow wave detection (min, max)

• trough_duration (tuple) – Duration range for slow wave trough in seconds (min, max)

• neg_peak_thresh (float) – Minimum negative peak threshold in μV

• p2p_thresh (float) – Minimum peak-to-peak amplitude threshold in μV

• peak_thresh_sigma (float or None) – Peak threshold in standard deviations (for Ngo2015 method)

• ptp_thresh_sigma (float or None) – Peak-to-peak threshold in standard deviations (for Ngo2015 method)

• invert (bool) – Whether to invert the signal polarity

• reject_artifacts (bool) – Whether to exclude segments marked with artifact annotations

• reject_arousals (bool) – Whether to exclude segments marked with arousal annotations

• stage (list or str) – Sleep stage(s) to analyze

• cat (tuple) – Category specification for data selection

• save_to_annotations (bool) – Whether to save detected slow waves to annotations

• json_dir (str or None) – Directory to save individual channel JSON files

Returns:

List of all detected slow waves

Return type:

list

export_slow_wave_parameters_to_csv(json_input, csv_file, export_params='all', frequency=None, ref_chan=None, grp_name='eeg', n_fft_sec=4, file_pattern=None, skip_empty_files=True)

Calculate slow wave parameters from JSON files and export to CSV.

Parameters:

• json_input (str or list) – Path to JSON file, directory of JSON files, or list of JSON files

• csv_file (str) – Path to output CSV file

• export_params (dict or str) – Parameters to export. If ‘all’, exports all available parameters

• frequency (tuple or None) – Frequency range for power calculations

• ref_chan (list or None) – Reference channel(s) for parameter calculation

• n_fft_sec (int) – FFT window size in seconds for spectral analysis

• file_pattern (str or None) – Pattern to filter JSON files if json_input is a directory

export_slow_wave_density_to_csv(json_input, csv_file, stage=None, file_pattern=None)

Export slow wave statistics to CSV with both whole night and stage-specific densities.

Parameters:

• json_input (str or list) – Path to JSON file, directory of JSON files, or list of JSON files

• csv_file (str) – Path to output CSV file

• stage (str or list) – Sleep stage(s) to include

• file_pattern (str or None) – Pattern to filter JSON files

save_detection_summary(output_dir, method, parameters, results_summary)

Save a comprehensive summary of detection parameters and results.

Parameters:

• output_dir (str) – Directory to save the summary

• method (str) – Detection method used

• parameters (dict) – All parameters used for detection

• results_summary (dict) – Summary of detection results

initialize_sqlite_database(db_path='neural_events.db')

Create SQLite database optimized for storing calculated event parameters from event_params() function.

Parameters:

db_path (str) – Path to SQLite database file

Returns:

Path to created database

Return type:

str

import_parameters_csv_to_database(csv_file, db_path, append=True)

Import event parameters from an existing CSV file into SQLite database. Supports multiple event types and incremental updates.

Parameters:

• csv_file (str) – Path to existing parameters CSV file

• db_path (str) – Path to SQLite database

• append (bool) – If True, adds to existing database without replacing existing entries If False, replaces any existing entries with the same UUID

Returns:

Summary of the operation with counts of added, updated, and skipped rows

Return type:

dict

turtlewave_hdEEG.utils module

turtlewave_hdEEG.utils.process_events_parallel(events, data_source, window_size=5, n_workers=4, func=None)

Process EEG events in parallel

Parameters:

• events (list of dict) – List of events with at least ‘start_time’ key

• data_source (LargeDataset or str) – Large dataset object or path to data file

• window_size (float) – Window size around event in seconds

• n_workers (int) – Number of parallel workers

• func (callable or None) – Function to apply to each event data, if None just return the data

Returns:

results – List of processed event data

Return type:

list

turtlewave_hdEEG.utils.explore_eeglab_structure(filename)

Utility to explore the structure of an EEGLAB file

Parameters:

filename (str) – Path to EEGLAB .set file

Returns:

structure – Dictionary representation of EEGLAB file structure

Return type:

dict

turtlewave_hdEEG.utils.read_channels_from_csv(csv_file_path)

turtlewave_hdEEG.visualization module

class turtlewave_hdEEG.visualization.EventViewer(data_source, annotation_file, window_size=5)

Bases: object

Interactive viewer for EEG events in large datasets

Parameters:

• data_source (LargeDataset or str) – Large dataset object or path to data file

• annotation_file (str) – Path to annotation file with events

• window_size (float) – Initial window size in seconds

update_event(val)

Update when event slider changes

update_display(val)

Update the EEG display

next_event(event)

Go to next event

prev_event(event)

Go to previous event

show()

Display the viewer

Module contents

turtlewave_hdEEG - Extended Wonambi for large EEG datasets