Event Processor

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

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

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

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

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

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