edfio.Edf

class edfio.Edf(signals, *, patient=None, recording=None, starttime=None, data_record_duration=None, annotations=None)

Python representation of an EDF file.

EDF header fields are exposed as properties with appropriate data types (i.e., string, numeric, date, or time objects). Fields that might break the file on modification (i.e., version, bytes_in_header_record, reserved, num_data_records, data_record_duration, and num_signals) can not be set after instantiation.

Note that the startdate has to be set via the parameter recording.

For writing an EDF file with a non-integer seconds duration, currently an appropriate value for data_record_duration has to be provided manually.

Parameters:

signalsSequence[EdfSignal]

The (non-annotation) signals to be contained in the EDF file.

patientPatient | None, default: None

The “local patient identification”, containing patient code, sex, birthdate, name, and optional additional fields. If None, the field is set to X X X X in accordance with EDF+ specs.

recordingRecording | None, default: None

The “local recording identification”, containing recording startdate, hospital administration code, investigator/technical code, equipment code, and optional additional fields. If None, the field is set to Startdate X X X X in accordance with EDF+ specs.

starttimedatetime.time | None, default: None

The starttime of the recording. If None, 00.00.00 is used. If starttime contains microseconds, an EDF+C file is created.

data_record_durationfloat | None, default: None

The duration of each data record in seconds. If None, an appropriate value is chosen automatically.

annotationsIterable[EdfAnnotation] | None, default: None

The annotations, consisting of onset, duration (optional), and text. If not None, an EDF+C file is created.

Attributes

annotations	All annotations contained in the Edf, sorted chronologically.
bytes_in_header_record	Number of bytes in the header record.
data_record_duration	Duration of each data record in seconds.
duration	Recording duration in seconds.
labels	The labels of all signals contained in the Edf.
local_patient_identification	Unparsed string representation of the legacy local patient identification.
local_recording_identification	Unparsed string representation of the legacy local recording identification.
num_data_records	Number of data records in the recording.
num_signals	Return the number of signals, excluding annotation signals for EDF+.
patient	Parsed object representation of the local patient identification.
recording	Parsed object representation of the local recording identification.
reserved	"EDF+C" for an EDF+C file, else "".
signals	Ordinary signals contained in the recording.
startdate	Recording startdate.
starttime	Recording starttime.
version	EDF version, always 0.

Methods

__init__
add_annotations	Add annotations to the Edf.
anonymize	Anonymize a recording.
append_signals	Append one or more signal(s) to the Edf recording.
copy	Create a deep copy of the Edf.
drop_annotations	Drop annotations with a given text.
drop_signals	Drop signals by index or label.
get_annotations	All annotations defined (starting) in a specified time region of the Edf, sorted chronologically.
get_signal	Retrieve a single signal by its label.
set_annotations	Overwrite all annotations with new ones.
slice_between_annotations	Slice to the interval between two EDF+ annotations.
slice_between_seconds	Slice to the interval between two times.
to_bytes	Convert an Edf to a bytes object.
update_data_record_duration	Update the data record duration.
write	Write an Edf to a file or file-like object.

add_annotations(annotations)

Add annotations to the Edf.

This removes all existing annotation signals and adds a new one containing the old and new annotations as the last signal in the file.

Parameters:

annotationsIterable[EdfAnnotation]

The annotations to add.

property annotations

All annotations contained in the Edf, sorted chronologically.

Does not include timekeeping annotations.

anonymize(*, keep_age=False, keep_sex=False, keep_starttime=False)

Anonymize a recording.

By default, header fields are modified as follows:

• local patient identification is set to X X X X

• local recording identification is set to Startdate X X X X

• startdate is set to 01.01.85

• starttime is set to 00.00.00

For EDF+ files, subsecond starttimes specified via an annotations signal are removed.

Optionally, parts of the original information can be preserved by setting the corresponding parameters to True (see below).

Parameters:

keep_agebool, default: False

Whether to keep age information relative to the anonymized start date in the local patient identification. If True, the birthdate is set to January 1st of the year that preserves the age relative to 01.01.85. This implies that the local patient identification is set to X X 01-JAN-YYYY X, where YYYY is the age-preserving year.

keep_sexbool, default: False

Whether to keep the sex field in the local patient identification.

keep_starttimebool, default: False

Whether to keep the original start time.

append_signals(new_signals)

Append one or more signal(s) to the Edf recording.

Every signal must be compatible with the current data_record_duration and all signal durations must match the overall recording duration. For recordings containing EDF+ annotation signals, the new signals are inserted after the last ordinary (i.e. non-annotation) signal.

Parameters:

new_signalsEdfSignal | Iterable[EdfSignal]

The signal(s) to add.

property bytes_in_header_record

Number of bytes in the header record.

copy()

Create a deep copy of the Edf.

Returns:

Edf

The copied Edf object.

property data_record_duration

Duration of each data record in seconds.

drop_annotations(text)

Drop annotations with a given text.

Parameters:

textstr

All annotations whose text exactly matches this parameter are removed.

drop_signals(drop)

Drop signals by index or label.

_Signal indices (int) and labels (str) can be provided in the same iterable. For ambiguous labels, all corresponding signals are dropped. Raises a ValueError if at least one of the provided identifiers does not correspond to a signal.

Parameters:

dropIterable[int | str]

The signals to drop, identified by index or label.

property duration

Recording duration in seconds.

get_annotations(start_second=None, stop_second=None)

All annotations defined (starting) in a specified time region of the Edf, sorted chronologically.

Does not include timekeeping annotations. Will not include annotations that start within the specified time region but are defined in data records outside of that window.

Parameters:

start_secondfloat, optional

The start of the time region in seconds from recording start. If not provided, the start of the recording is used.

stop_secondfloat, optional

The end of the time region in seconds. If not provided, the end of the recording is used.

get_signal(label)

Retrieve a single signal by its label.

The label has to be unique - a ValueError is raised if it is ambiguous or does not exist.

Parameters:

labelstr

A label identifying a single signal

Returns:

EdfSignal

The signal corresponding to the given label.

property labels

The labels of all signals contained in the Edf.

Returns:

tuple[str, …]

The labels, in order of the signals.

property local_patient_identification

Unparsed string representation of the legacy local patient identification.

See also

patient

Parsed representation, as a Patient object.

property local_recording_identification

Unparsed string representation of the legacy local recording identification.

See also

recording

Parsed representation, as a Recording object.

property num_data_records

Number of data records in the recording.

property num_signals

Return the number of signals, excluding annotation signals for EDF+.

property patient

Parsed object representation of the local patient identification.

See Patient for information on its attributes.

property recording

Parsed object representation of the local recording identification.

See Recording for information on its attributes.

property reserved

"EDF+C" for an EDF+C file, else "".

set_annotations(annotations)

Overwrite all annotations with new ones.

This removes all existing annotation signals and adds a new one as the last signal in the file.

Parameters:

annotationsIterable[EdfAnnotation]

The annotations to set.

property signals

Ordinary signals contained in the recording.

Annotation signals are excluded. Individual signals can not be removed, added, or replaced by modifying this property. Use Edf.append_signals(), Edf.drop_signals(), or EdfSignal.data, respectively.

slice_between_annotations(start_text, stop_text, *, keep_all_annotations=False)

Slice to the interval between two EDF+ annotations.

The sample point corresponding to the onset of the annotation identified by stop_text is excluded. start_text and stop_text each have to uniquely identify a single annotation, whose onset corresponds exactly to a sample time in all non-annotation signals.

Parameters:

start_textstr

Text identifying the start annotation.

stop_textstr

Text identifying the stop annotation.

keep_all_annotationsbool, default: False

If set to True, annotations outside the selected time interval are kept.

slice_between_seconds(start, stop, *, keep_all_annotations=False)

Slice to the interval between two times.

The sample point corresponding to stop is excluded. start and stop are given in seconds from recording start and have to correspond exactly to a sample time in all non-annotation signals.

Parameters:

startfloat

Start time in seconds from recording start.

stopfloat

Stop time in seconds from recording start.

keep_all_annotationsbool, default: False

If set to True, annotations outside the selected time interval are kept.

property startdate

Recording startdate.

If the local_recording_identification conforms to the EDF+ standard, the startdate provided there is used. If not, this falls back to the legacy startdate field. If both differ, a warning is issued and the EDF+ field is preferred. Raises an AnonymizedDateError if the EDF+ field is anonymized (i.e., begins with Startdate X).

property starttime

Recording starttime.

In EDF+ files, microsecond accuracy is supported.

to_bytes()

Convert an Edf to a bytes object.

Returns:

bytes

The binary representation of the Edf object (i.e., what a file created with Edf.write would contain).

update_data_record_duration(data_record_duration, method='strict')

Update the data record duration.

This operation will fail if the new duration is incompatible with the current sampling frequencies.

Parameters:

data_record_durationfloat

The new data record duration in seconds.

method{"strict", "pad", "truncate"}, default: "strict"

How to handle the case where the new duration does not divide the Edf duration evenly

• “strict”: Raise a ValueError

• “pad”: Pad the data with zeros to the next compatible duration. If zero is outside the physical range, data is padded with the physical minimum.

• “truncate”: Truncate the data to the previous compatible duration (might lead to loss of data)

property version

EDF version, always 0.

write(target)

Write an Edf to a file or file-like object.

Parameters:

targetPath | str | io.BufferedWriter | io.BytesIO

The file location (path object or string) or file-like object to write to.