Event Processor

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

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()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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')[source]

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)[source]

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