Headers

`edfrw.headers`

Manage EDF file headers.

`EdfHeader(subject_code='', subject_sex='', subject_dob='', subject_name='', experiment_id='', investigator_id='', equipment_code='', duration_of_data_record=0, date_time=None, reserved='', signals=[])`

The header in a EDF file.

Attributes:

Name	Type	Description
`duration_of_data_record`	`number`
`number_of_bytes_in_header`	`int`
`number_of_data_records`	`int`
`number_of_signals`	`int`
`recording_id`	`object of class EdfRecordingId`
`reserved`	`str`
`signals`	`list of EdfSignal`
`startdate`	`datetime.date`
`starttime`	`datetime.time`
`subject_id`	`object of class EdfSubjectId`
`version`	`str, always '0'`

Initialises an EDF header.

Parameters:

Name	Type	Description	Default
`subject_code`	`str, default`		`''`
`subject_sex`	`str, default`		`''`
`subject_dob`	`str, default`		`''`
`subject_name`		The parameters `subject_*` are used to construct an object of `class::EdfSubjectId`. See that class for details.	`''`
`experiment_id`	`str, default`		`''`
`investigator_id`	`str, default`		`''`
`equipment_code`	`str, default`		`''`
`date_time`	`str or datetime or None, default`	The parameters `experiment_id`, `investigator_id`, `equipment_code` and `date_time` are used to construct and object of `class::EdfRecordingId`. See that class for details.	`None`
`duration_of_data_record`	`number, default`	This can be a float, but is is recommended to be an integer value	`0`
`reserved`	`str, default`	Must be an empty string if the file conforms to the EDF format, or ‘EDF+C’ or ‘EDF+D’ if the file includes an annotations signal (EDF+ format).	`''`
`signals`	`list of EdfSignal objects, default`	A list of objects of `class::Signal`	`[]`

`str()`

Display the contents of the header.

`duration_of_data_record()` `writable` `property`

Get or set the duration (in seconds) of the data record.

This value is recommended (but not required) to be an integer.

`number_of_bytes_in_header()` `writable` `property`

Get or set the number of bytes in the data header.

This value depends on the number of signals, so it should be updated whenever the number of signals changes.

`number_of_signals()` `property`

Get the number of signals in the EDF file.

`pack()`

Return the header as a bytes object.

The header record, which includes the subject, recording, and signal(s) attributes, are concatenated into a single bytes (ascii string) object, as required by the EDF specification. This object can be then used to e.g. write the header record in an opened EDF file.

Returns:

Name	Type	Description
`main_hdr`	`str(ascii)`	The record header, formatted as per the EDF requirements.

`recording_id()` `writable` `property`

Get or set the recording identification.

The recording ID can be a single string with values [start_str, startdate, experiment_id, investigator_id, equipment_code] separated by spaces (as is the case when reading the recording ID from the header of and EDF file), or an object of class EdfRecordingId.

Examples:

Using one, space-separated string of values:

>>> rec_id = ("start_str startdate experiment_id " +
        "investigator_id  equipment_code")
>>> header.recording_id = rec_id

Using EdfRecordingId:

>>> rec_id = EdfRecordingId(startdate, experiment_id,
...     investigator_id, equipment_code)
>>> header.recording_id = rec_id

`signals()` `writable` `property`

Get or set the list of signals in an EDF file.

This attribute is a list of EdfSignal signal objects.

`startdate()` `writable` `property`

Set or get the recording start date.

Parameters:

Name	Type	Description	Default
`value`	`str or datetime`	It must be either (a) a string ‘yyyy-mm-dd’, e.g. ‘2016-10-25’, or (b) a string ‘d.m.y’ as required by EDF, e.g. ‘16.10.25’, or (c) a datetime object	required

Returns:

Name	Type	Description
`startdate`	`datetime object`

`starttime()` `writable` `property`

Get or set the recording start time.

Parameters:

Name	Type	Description	Default
`value`	`str or datetime`	It must be either (a) a string ‘H.M.S’ as required by EDF, e.g. ‘12.15.05’, or (b) a string in standard format ‘H:M:S’, e.g. ‘12:15:05’, or (b) a datetime object.	required

`subject_id()` `writable` `property`

Get or set the subject (patient) ID record.

The subject ID can be a single string with values [code, sex, dob, name] separated by spaces (as is the case when reading the patient ID from the header of and EDF file), or an object of class EdfSubjectId.

Examples:

Use a single string, values are space-separated.

>>> header.subject_id = "the_code X 1990-01-01 the_name"

or use EdfSubjectID

>>> id = EdfSubjectID(code, sex, dob, name)
>>> header.subject_id = id

`EdfRecordingId(startdate=None, experiment_id='', investigator_id='', equipment_code='')`

Recording identification.

The ‘local recording identification field’ is a string of 80 characters in the header of a EDF file. It contains information about the start date, experiment ID, investigator ID, and equipment code, each of these separated by a space.

This class handles that information. It is seldom useful on its own but rather as an attribute of class::Header.

Attributes:

Name	Type	Description
`equipment_code`	`str`
`experiment_id`	`str`
`investigator_id`	`str`
`startdate`	`datetime.date`

The ‘local recording identification field’.

The recording identification field forms part of the EDF header. All these subfields together will be concatenated (separated by spaces) to form one string which must not exceed 80 characters. Note that the text ‘Startdate’ is always prepended to this string, and this must betaken into account for the character count.

Fields that are unknown (empty strings) will be replaced by an ‘X’ as per the EDF specification.

Parameters:

Name	Type	Description	Default
`startdate`	`str or datetime or None, default`	The start date. Expected to be: (a) a string in isoformat (‘yyyy-mm-dd’), or (b) a `datetime` instance, as in e.g. datetime.now(), or (c) a date string with format ‘%d-%b-%Y’, as in e.g. ‘02-AUG-1951’, which is the format required by EDF for this field, or (d) None, in which case the current date will be used	`None`
`experiment_id`	`str, default`	“The hospital administration code of the investigation, i.e. EEG number” (Kemp, 2003)	`''`
`investigator_id`	`str, default`	“A code identifying the responsible investigator” (Kemp, 2003)	`''`
`equipment_code`	`str, default`	“A code specifying the used equipment” (Kemp, 2003)	`''`

`equipment_code()` `writable` `property`

Get or set the equipment code.

Any spaces will be replaced by underscores.

`experiment_id()` `writable` `property`

Get or set the experiment ID.

Any spaces will be replaced by underscores, as required by EDF.

`investigator_id()` `writable` `property`

Get or set the investigator ID.

Any spaces will be replaced by underscores, as required by EDF.

`startdate()` `writable` `property`

Get or set the recording start date.

To set the date, any of these values are acceptable: (a) a string in isoformat (‘yyyy-mm-dd’), or (b) a datetime instance, as in e.g. datetime.now(), or (c) a date string with format ‘%d-%b-%Y’, which is the format required by EDF for this field. (d) None, in which case the current date will be used.

In all cases startdate will be saved internally as a datetime object.

`to_str()`

Return the recording identification as a single string.

The local recording identification in an EDF file must be a string no longer than 80 characters. This function concatenates the recording attributes to create such a string. This is useful for making the full EDF header record.

Returns:

Name	Type	Description
`rec_id`	`str`	A string containing the recording identification in the format specified by EDF.

`EdfSignal(label='', transducer_type='', physical_dim='', physical_min=-32768, physical_max=32767, digital_min=-32768, digital_max=32767, prefiltering='', number_of_samples_in_data_record=0, sampling_freq=0)`

Properties of a signal.

These properties are stored in the header of an EDF file (after the first 256 bytes which contain the ‘main’ header). Each signal header is 256 bytes long.

Attributes:

Name	Type	Description
`digital_max`	`int`
`digital_min`	`int`
`gain`	`number`
`label`	`str`
`number_of_samples_in_data_record`	`int`
`physical_dim`	`str`
`physical_max`	`number`
`physical_min`	`number`
`prefiltering`	`str`
`reserved`	`str`
`sampling_freq`	`number`
`transducer_type`	`str`

Examples:

Example 1: A voltage signal digitised with a 12-bit ADC, single-ended, input range 0 to 5 V. Sampling rate (fs) is 30 Hz. saving_period_s is how often (in seconds) the data are saved to disk.

>>> fs = 30
>>> signal = edfrw.EdfSignal(label='ADC', sampling_freq=fs,
...     physical_dim="V",
...     number_of_samples_in_data_record=saving_period_s*fs,
...     physical_min=0, physical_max=5,
...     digital_min=0, digital_max=4095)

Example 2: A voltage signal, digitised with a 16-bit ADC with input range -10 to 10 V. Sampling rate (fs) is 1000 Hz.

>>> fs = 1000
>>> signal = edfrw.EdfSignal(label='ADC', sampling_freq=fs,
...     number_of_samples_in_data_record=saving_period_s*fs,
...     physical_dim="V", physical_min=-10, physical_max=10,
...     digital_min=-0x8000, digital_max=0x7fff)

Example 3: A digital signal as a boolean (off = 0, on = 1)

>>> signal = edfrw.EdfSignal(label='ON-OFF', sampling_freq=fs,
...     number_of_samples_in_data_record=saving_period_s*fs,
...     physical_min=0, physical_max=1, digital_min=0,
...     digital_max=1)

Properties of a signal in an EDF file.

Parameters:

Name	Type	Description	Default
`label`	`str, max.length`		`''`
`transducer_type`	`str of size 80, default`	The type of sensor used, e.g. ‘thermistor’ or ‘Ag-AgCl electrode’.	`''`
`physical_dim`	`str, max.length`	The physical dimension. A string that must start with a prefix (e.g. ‘u’ for ‘micro’) followed by the basic dimension (e.g. ‘V’ for volts). Other examples of basic dimensions are ‘K’, ‘degC’ or ‘degF’ for temperature, and ‘%’ for SaO2. Powers are denoted by ‘^’, as in ‘V^2/Hz’. An empty string represents an uncalibrated signal. For standards on labels and units, see http://www.edfplus.info/specs/edftexts.html	`''`
`physical_min`	`number, default`		`-32768`
`physical_max`	`number, default`	The physical minimum and maximum should correspond to the digital extremes `digital_min` and `digital_max` and be expressed in the physical dimension `physical_dim`. The values of `physical_min` and `physical_max` must be different.	`32767`
`digital_min`	`number, default`		`-32768`
`digital_max`	`number, default`	“The digital minimum and maximum of each signal should specify the extreme values that can occur in the data records. These often are the extreme output values of the A/D converter.” (Kemp et al. 1992). `digital_max` must be larger than `digital_min`. Together, the two `digital_` and the two `physical_` values specify the offset and the amplification of the signal.	`32767`
`prefiltering`	`str, max.length`	Specifies if this signal was filtered; e.g. for high-pass, low-pass, or notch filtering, ‘HP:0.1Hz’, ‘LP:75Hz’, ‘N:50Hz’	`''`
`number_of_samples_in_data_record`	`integer, default`	The number of 16-bit integers that this signal occupies	`0`
`sampling_freq`	`number, default`	The sampling frequency. This subfield is not part of the EDF specification. It is added for convenience.	`0`

Notes

Use only ascii characters.

The data in EDF files are saved as two’s complement, 16-bit integers. Thus, the range between digital_min and digital_max must not exceed 2**16 - 1 = 65535.

`dig_to_phys(value)`

Convert a digital value to a physical value.

Parameters:

Name	Type	Description	Default
`value`	`uint16 or array of uint16_t`	A digital value to convert. EDF digital values are always unsigned, 16-bit integers.	required

Returns:

Name	Type	Description
`phys`	`float or array of float`	The corresponding physical value.

Notes

These equations follow those used in EDFBrowser to convert from EDF to ascii (ascii_export.cpp)

`digital_max()` `writable` `property`

Get or set the signal’s digital maximum value.

`digital_min()` `writable` `property`

Get or set the signal’s digital minimum value.

`gain()` `property`

Get the signal gain.

The gain maps physical to digital dimensions. This property is calculated automatically whenever the digital or physical min/max values are set.

`label()` `writable` `property`

Get or set the signal label.

`number_of_samples_in_data_record()` `writable` `property`

Get or set the number of samples in each data record.

`phys_to_dig(value)`

Convert a physical value to a digital value.

Parameters:

Name	Type	Description	Default
`value`	`float or array of floats`	The physical value(s) to convert	required

Returns:

Name	Type	Description
`dig`	`uint16_t or array of uint16_t`	The digital value

Notes

Follows the equation of a straight line (point-slope form):

y = m * (x - x1) + y1

x = (y - y1)/m + x1

`physical_dim()` `writable` `property`

Get or set the signal’s physical dimension.

`physical_max()` `writable` `property`

Get or set the signal’s physical maximum.

`physical_min()` `writable` `property`

Get or set the signal’s physical minimum.

`prefiltering()` `writable` `property`

Get or set the signal’s prefiltering information.

Examples:

If the signal was low-pass filtered with a 10 Hz cut-off,

>>> signal.prefiltering = "LP:10Hz"

`transducer_type()` `writable` `property`

Get or set the transducer type.

`EdfSubjectId(code='', sex='', dob='', name='')`

Subject (patient) identification.

The subject (patient) identification is a string (80 characters long) in the header of a EDF file than contains information about the patient’s code, name, sex, and date of birth.

This class handles that information. It is seldom useful on its own but rather as an attribute of class::Header.

Attributes:

Name	Type	Description
`code`	`str`	Patient code
`sex`	`str`	Patient sex
`dob`	`datetime.date`	Patient date of birth
`name`	`str`	Patient name

Properties that identify the subject.

Parameters:

Name	Type	Description	Default
`code`	`str, default`	Patient code	`''`
`sex`	`str`		`''`
`dob`	`str or datetime, default`	Date of birth. It must be entered as: (a) a string in EDF format ‘dd-MMM-yy’, as in ‘30-DEC-1999’; (b) a string in iso format ‘yyyy-mm-dd’, as in ‘1999-12-30’; or (c) a datetime object.	`''`
`name`	`str, default`	The patient’s name	`''`

Any field that is not known can be entered as ‘X’ (as per the EDF standard) or as an empty string ‘’.

`code()` `writable` `property`

Get or set the patient’s code.

`dob()` `writable` `property`

Get or set the date of birth (DOB).

If DOB is not known it must be an empty string ‘’ or ‘X’. If it is known, it must be entered as

(a) a string in EDF format ‘dd-MMM-yy’, as in ‘30-DEC-1999’; (b) a string in iso format ‘yyyy-mm-dd’, as in ‘1999-12-30’; or (c) a datetime object.

In any case the date will be stored as a datetime.date object.

`name()` `writable` `property`

Get or set the patient’s name.

`sex()` `writable` `property`

Get or set the patient’s sex.

`to_str()`

Return patient ID record as a single string.

The patient identification record in an EDF file must be a string no longer than 80 characters. This function concatenates the patient attributes to create such a string. This is useful for making the full EDF header record.

Returns:

Name	Type	Description
`patient_id`	`str`	A string containing patient ID in the format specified by EDF.

edfrw.headers

EdfHeader(subject_code='', subject_sex='', subject_dob='', subject_name='', experiment_id='', investigator_id='', equipment_code='', duration_of_data_record=0, date_time=None, reserved='', signals=[])

__str__()

duration_of_data_record() writable property

number_of_bytes_in_header() writable property

number_of_signals() property

pack()

recording_id() writable property

signals() writable property

startdate() writable property

starttime() writable property

subject_id() writable property

EdfRecordingId(startdate=None, experiment_id='', investigator_id='', equipment_code='')

equipment_code() writable property

experiment_id() writable property

investigator_id() writable property

startdate() writable property

to_str()

EdfSignal(label='', transducer_type='', physical_dim='', physical_min=-32768, physical_max=32767, digital_min=-32768, digital_max=32767, prefiltering='', number_of_samples_in_data_record=0, sampling_freq=0)

Notes

dig_to_phys(value)

Notes

digital_max() writable property

digital_min() writable property

gain() property

label() writable property

number_of_samples_in_data_record() writable property

phys_to_dig(value)

Notes

physical_dim() writable property

physical_max() writable property

physical_min() writable property

prefiltering() writable property

transducer_type() writable property

EdfSubjectId(code='', sex='', dob='', name='')

code() writable property

dob() writable property

name() writable property

sex() writable property

to_str()

`edfrw.headers`

`EdfHeader(subject_code='', subject_sex='', subject_dob='', subject_name='', experiment_id='', investigator_id='', equipment_code='', duration_of_data_record=0, date_time=None, reserved='', signals=[])`

`str()`

`duration_of_data_record()` `writable` `property`

`number_of_bytes_in_header()` `writable` `property`

`number_of_signals()` `property`

`pack()`

`recording_id()` `writable` `property`

`signals()` `writable` `property`

`startdate()` `writable` `property`

`starttime()` `writable` `property`

`subject_id()` `writable` `property`

`EdfRecordingId(startdate=None, experiment_id='', investigator_id='', equipment_code='')`

`equipment_code()` `writable` `property`

`experiment_id()` `writable` `property`

`investigator_id()` `writable` `property`

`startdate()` `writable` `property`

`to_str()`

`EdfSignal(label='', transducer_type='', physical_dim='', physical_min=-32768, physical_max=32767, digital_min=-32768, digital_max=32767, prefiltering='', number_of_samples_in_data_record=0, sampling_freq=0)`

`dig_to_phys(value)`

`digital_max()` `writable` `property`

`digital_min()` `writable` `property`

`gain()` `property`

`label()` `writable` `property`

`number_of_samples_in_data_record()` `writable` `property`

`phys_to_dig(value)`

`physical_dim()` `writable` `property`

`physical_max()` `writable` `property`

`physical_min()` `writable` `property`

`prefiltering()` `writable` `property`

`transducer_type()` `writable` `property`

`EdfSubjectId(code='', sex='', dob='', name='')`

`code()` `writable` `property`

`dob()` `writable` `property`

`name()` `writable` `property`

`sex()` `writable` `property`

`to_str()`