Event Processor

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

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

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

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

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

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

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