Basic concepts

Data structures

The main entity in neurokit is the Recording class. A Recording can contain patient information, multiple timeseries, event annotations and other metadata.

Timeseries

Timeseries objects are extensions of the pandas.DataFrame class with some extra properties for easier management. Timeseries usually represent fixed-frequency signals such as the signal from EEG electrodes, but can also contain irregularly sampled timeseries such as readings from various monitors (ventilator, TCI, etc.). Fixed-frequency timeseries are implemented with the TimeSeries class, while irregularly sampled timeseries are implemented with the UnevenTimeSeries. Both extend the BaseTimeSeries class. The index of the frame is always of the type pandas.TimeDelta, which makes it possible to operate

Here is an example of the properties of a fixed-frequency timeseries:

import numpy as np
import neurokit as nk

# Generate a demo signal
signal = np.cos(np.linspace(0, 10, 10 * 100))

# Create a 100 Hz timeseries, with one channel named "EEG Fp1"
timeseries = nk.TimeSeries(signal, columns=['EEG Fp1'], frequency=100, name='EEG')

# Bandpass filter between 8 and 16 Hz
filtered = timeseries.filter(8, 16)

Events

Series of events are implemented with the class EventSeries. Each event is defined by a start and end time offsets and optionally a description, code, and channel it refers to.

import neurokit as nk

events = nk.EventSeries(name='annotations')

# Add a general event between 10 s and 20 s
events.add('10s', '20s', description='Patient talks')

# Add an event for a specific channel
events.add('25s', '26s', channel='EEG Fp2', description='Electrode popping artifact')

print(event.data)

Recordings

Recordings can be easily created by passing timeseries and events arrays.

import neurokit as nk

# Create demo timeseries
signal = np.random.normal(size=(1000, 2))  # two channel white noise
eeg = nk.TimeSeries(signal, columns=['EEG Fp1', 'EEG Fp2'], frequency=100, name='eeg')

signal = np.ones(size=(100, 2))
sevo = nk.TimeSeries(, columns=['Sevo IN', 'Sevo EXP'], frequency=10, name='sevoflurane')

# Create demo events
annots = nk.EventSeries(name='annotations')
annots.add('342s', '410s', description='Intubation')

# Create demo patient
patient = nk.Patient(code='TEST01', age=32, weight=73.2)

# Create the recording
recording = nk.Recording(timeseries=[eeg, sevo], events=[annots], patient=patient, meta={'type': 'anesthesia'})

# Show timeseries
print(recording.ts)

Input/output

Neurokit can read and write Recording objects in various formats.

Supported formats

Format	Extension	Notes	Example
HDF5 (Hierarchical Data Format)	.h5, .hdf	Reading and writing only (recommended format)	neurokit.io.read_hdf('file.h5')
EDF/EDF+ (European Data Format)	.edf	Reading and limited writing	neurokit.io.read_edf('file.edf')
FIF (MNE data Format)	.fif	Reading only	neurokit.io.read_fif('file_raw.fif')
Messagepack (neurokit)	.msgpack	Reading and writing	neurokit.io.read_msgpack('file.msgpack')

Reading and writing

We recommend using the hdf format whenever possible (usually with file extension .h5), as it provides the best compression and compatibility with other softwares such as Matlab.

EDF/EDF+ files are fully supported when reading, but only a limited support is available when writing due to technical limitations of the EDF specification. EDF does not support multiple timeseries and event series, so when writing to an edf file only the main timeseries be preserved. Most metadata and patient information will also be lost. We recommend writing to 'hdf' files instead.

Functions for reading are exposed through the neurokit.io module. Writing function are instead directly accessible from the Recording object (to_edf, to_hdf, to_msgpack).

import neurokit as nk

# Read an EDF file
rec = nk.io.read_edf('demo.edf')


# Write to HDF
rec.to_hdf('demo.h5')
rec.to_msgpack('demo.msgpack')