Event Processor

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