explorepy

Main API

class explore.Explore(n_device=1)

Bases: object

Mentalab Explore device

Parameters:n_device (int) – Number of devices to be connected

connect(device_name=None, device_addr=None, device_id=0)

Connects to the nearby device. If there are more than one device, the user is asked to choose one of them.

Parameters:

• device_name (str) – Device name in the format of “Explore_XXXX”
• device_addr (str) – The MAC address in format “XX:XX:XX:XX:XX:XX” Either Address or name should be in the input
• device_id (int) – device id (not needed in the current version)

disconnect(device_id=None)

Disconnects from the device

Parameters:device_id (int) – device id (not needed in the current version)

acquire(device_id=0, duration=None)

Start getting data from the device

Parameters:

• device_id (int) – device id (not needed in the current version)
• duration (float) – duration of acquiring data (if None it streams data endlessly)

record_data(file_name, do_overwrite=False, device_id=0, duration=None, file_type='csv')

Records the data in real-time

Parameters:

• file_name (str) – Output file name
• device_id (int) – Device id (not needed in the current version)
• do_overwrite (bool) – Overwrite if files exist already
• duration (float) – Duration of recording in seconds (if None records endlessly).
• file_type (str) – File type of the recorded file. Supported file types: ‘csv’, ‘edf’

push2lsl(device_id=0, duration=None)

Push samples to two lsl streams

Parameters:

• device_id (int) – device id (not needed in the current version)
• duration (float) – duration of data acquiring (if None it streams endlessly).

visualize(device_id=0, bp_freq=(1, 30), notch_freq=50, calibre_file=None)

Visualization of the signal in the dashboard :Parameters: * device_id (int) – Device ID (not needed in the current version)

• bp_freq (tuple) – Bandpass filter cut-off frequencies (low_cutoff_freq, high_cutoff_freq), No bandpass filter
• if it is None.
• notch_freq (int) – Line frequency for notch filter (50 or 60 Hz), No notch filter if it is None
• calibre_file (str) – Calibration data file name

_io_loop(device_id=0, mode='visualize')

signal_handler(signal, frame)

measure_imp(device_id=0, notch_freq=50)

Visualization of the electrode impedances

Parameters:

• device_id (int) – Device ID
• notch_freq (int) – Notch frequency for filtering the line noise (50 or 60 Hz)

set_marker(code)

Sets an event marker during the recording

Parameters:code (int) – Marker code. It must be an integer larger than 7 (codes from 0 to 7 are reserved for hardware markers).

change_settings(command, device_id=0)

sends a message to the device :Parameters: * device_id (int) – Device ID

• command (explorepy.command.Command) – Command object

Returns:

calibrate_orn(file_name, device_id=0, do_overwrite=False)

Calibrate the orientation module of the specified device

Parameters:

• device_id (int) – device id
• file_name (str) – filename to be used for calibration. If you pass this parameter, ORN module should be ACTIVE!
• do_overwrite (bool) – Overwrite if files exist already

Bluetooth API

class bt_client.BtClient

Bases: object

Responsible for Connecting and reconnecting explore devices via bluetooth

init_bt(device_name=None, device_addr=None)

Initialize Bluetooth connection

Parameters:

• device_name (str) – Name of the device (either device_name or device address should be given)
• device_addr (str) – Devices MAC address

bt_connect()

Creates the socket

reconnect()

tries to open the last bt socket, uses the last port and host. if after 1 minute the connection doesnt succeed, program will end

find_mac_addr(device_name)

find_explore_service()

static _check_mac_address(device_name, mac_address)

Parser

parser.generate_packet(pid, timestamp, bin_data)

Generates the packets according to the pid

Parameters:

• pid (int) – Packet ID
• timestamp (int) – Timestamp
• bin_data – Binary dat

Returns:

Packet

class parser.Parser(bp_freq=None, notch_freq=None, socket=None, fid=None)

Bases: object

Parser class for explore device

Parameters:

• socket (BluetoothSocket) – Bluetooth Socket (Should be None if fid is provided)
• fid (file object) – File object for reading data (Should be None if socket is provided)
• bp_freq (tuple) – Tuple of cut-off frequencies of bandpass filter (low cut-off frequency, high cut-off frequency)
• notch_freq (int) – Notch filter frequency (50 or 60 Hz)

filter

parse_packet(mode='print', recorders=None, outlets=None, dashboard=None)

Reads and parses a package from a file or socket

Parameters:

• mode (str) – Parsing mode {‘print’, ‘record’, ‘lsl’, ‘visualize’, ‘impedance’, None}
• recorders (tuple) – Tuple of recorder objects (ExG_recorder, ORN_recorder, Marker_recorder)
• outlets (tuple) – Tuple of lsl StreamOutlet (orientation_outlet, EEG_outlet, marker_outlet)
• dashboard (Dashboard) – Dashboard object for visualization

Returns:

packet object

read(n_bytes)

Read n_bytes from socket or file

Parameters:n_bytes (int) – number of bytes to be read Returns:list of bytes

set_marker(marker_code)

_init_filters()

_compute_NED(packet)

class packet.PACKET_ID

Bases: enum.IntEnum

An enumeration.

ORN = 13

ENV = 19

TS = 27

DISCONNECT = 111

INFO = 99

EEG94 = 144

EEG98 = 146

EEG99S = 30

EEG99 = 62

EEG94R = 208

EEG98R = 210

CMDRCV = 192

CMDSTAT = 193

MARKER = 194

CALIBINFO = 195

class packet.Packet(timestamp, payload)

Bases: object

An abstract base class for Explore packet

Gets the timestamp and payload and initializes the packet object

Parameters:payload (bytearray) – a byte array including binary data and fletcher

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

__str__()

Print the data/info

static int24to32(bin_data)

converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

push_to_dashboard(dashboard)

class packet.EEG(timestamp, payload)

Bases: packet.Packet

Gets the timestamp and payload and initializes the packet object

Parameters:payload (bytearray) – a byte array including binary data and fletcher

apply_bp_filter(exg_filter)

Bandpass filtering of ExG data

Args: exg_filter: Filter object

apply_bp_filter_noise(exg_filter)

Bandpass filtering of ExG data

Args: exg_filter: Filter object

apply_notch_filter(exg_filter)

Band_stop filtering of ExG data

Parameters:exg_filter – Filter object

push_to_lsl(outlet)

Push data to lsl socket

Parameters:outlet (lsl.StreamOutlet) – lsl stream outlet

calculate_impedance(imp_calib_info)

calculate impedance with the help of impedance calibration info

Parameters:imp_calib_info (dict) – dictionary of impedance calibration info including slope, offset and noise level

push_to_dashboard(dashboard)

push_to_imp_dashboard(dashboard, imp_calib_info)

write_to_file(recorder)

__str__()

Print the data/info

_check_fletcher(fletcher)

Checks if the fletcher is valid

_convert(bin_data)

Read the binary data and convert it to real values

static int24to32(bin_data)

converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.EEG94(timestamp, payload)

Bases: packet.EEG

EEG packet for 4 channel device

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

apply_bp_filter(exg_filter)

Bandpass filtering of ExG data

Args: exg_filter: Filter object

apply_bp_filter_noise(exg_filter)

Bandpass filtering of ExG data

Args: exg_filter: Filter object

apply_notch_filter(exg_filter)

Band_stop filtering of ExG data

Parameters:exg_filter – Filter object

calculate_impedance(imp_calib_info)

calculate impedance with the help of impedance calibration info

Parameters:imp_calib_info (dict) – dictionary of impedance calibration info including slope, offset and noise level

static int24to32(bin_data)

converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

push_to_dashboard(dashboard)

push_to_imp_dashboard(dashboard, imp_calib_info)

push_to_lsl(outlet)

Push data to lsl socket

Parameters:outlet (lsl.StreamOutlet) – lsl stream outlet

write_to_file(recorder)

class packet.EEG98(timestamp, payload)

Bases: packet.EEG

EEG packet for 8 channel device

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

apply_bp_filter(exg_filter)

Bandpass filtering of ExG data

Args: exg_filter: Filter object

apply_bp_filter_noise(exg_filter)

Bandpass filtering of ExG data

Args: exg_filter: Filter object

apply_notch_filter(exg_filter)

Band_stop filtering of ExG data

Parameters:exg_filter – Filter object

calculate_impedance(imp_calib_info)

calculate impedance with the help of impedance calibration info

Parameters:imp_calib_info (dict) – dictionary of impedance calibration info including slope, offset and noise level

static int24to32(bin_data)

converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

push_to_dashboard(dashboard)

push_to_imp_dashboard(dashboard, imp_calib_info)

push_to_lsl(outlet)

Push data to lsl socket

Parameters:outlet (lsl.StreamOutlet) – lsl stream outlet

write_to_file(recorder)

class packet.EEG99s(timestamp, payload)

Bases: packet.EEG

EEG packet for 8 channel device

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

apply_bp_filter(exg_filter)

Bandpass filtering of ExG data

Args: exg_filter: Filter object

apply_bp_filter_noise(exg_filter)

Bandpass filtering of ExG data

Args: exg_filter: Filter object

apply_notch_filter(exg_filter)

Band_stop filtering of ExG data

Parameters:exg_filter – Filter object

calculate_impedance(imp_calib_info)

calculate impedance with the help of impedance calibration info

Parameters:imp_calib_info (dict) – dictionary of impedance calibration info including slope, offset and noise level

static int24to32(bin_data)

converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

push_to_dashboard(dashboard)

push_to_imp_dashboard(dashboard, imp_calib_info)

push_to_lsl(outlet)

Push data to lsl socket

Parameters:outlet (lsl.StreamOutlet) – lsl stream outlet

write_to_file(recorder)

class packet.EEG99(timestamp, payload)

Bases: packet.EEG

EEG packet for 8 channel device

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

apply_bp_filter(exg_filter)

Bandpass filtering of ExG data

Args: exg_filter: Filter object

apply_bp_filter_noise(exg_filter)

Bandpass filtering of ExG data

Args: exg_filter: Filter object

apply_notch_filter(exg_filter)

Band_stop filtering of ExG data

Parameters:exg_filter – Filter object

calculate_impedance(imp_calib_info)

calculate impedance with the help of impedance calibration info

Parameters:imp_calib_info (dict) – dictionary of impedance calibration info including slope, offset and noise level

static int24to32(bin_data)

converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

push_to_dashboard(dashboard)

push_to_imp_dashboard(dashboard, imp_calib_info)

push_to_lsl(outlet)

Push data to lsl socket

Parameters:outlet (lsl.StreamOutlet) – lsl stream outlet

write_to_file(recorder)

class packet.Orientation(timestamp, payload)

Bases: packet.Packet

Orientation data packet

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

write_to_file(recorder)

push_to_lsl(outlet)

push_to_dashboard(dashboard)

compute_angle(matrix=None)

static int24to32(bin_data)

converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.Environment(timestamp, payload)

Bases: packet.Packet

Environment data packet

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

push_to_dashboard(dashboard)

static _volt_to_percent(voltage)

static int24to32(bin_data)

converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.TimeStamp(timestamp, payload)

Bases: packet.Packet

Time stamp data packet

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

translate()

push_to_lsl(outlet)

static int24to32(bin_data)

converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

push_to_dashboard(dashboard)

class packet.MarkerEvent(timestamp, payload)

Bases: packet.Packet

Marker packet

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

write_to_file(recorder)

push_to_lsl(outlet)

push_to_dashboard(dashboard)

static int24to32(bin_data)

converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.Disconnect(timestamp, payload)

Bases: packet.Packet

Disconnect packet

_convert(bin_data)

Disconnect packet has no data

_check_fletcher(fletcher)

Checks if the fletcher is valid

static int24to32(bin_data)

converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

push_to_dashboard(dashboard)

class packet.DeviceInfo(timestamp, payload)

Bases: packet.Packet

Device information packet

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

write_to_file(recorder)

push_to_dashboard(dashboard)

static int24to32(bin_data)

converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.CommandRCV(timestamp, payload)

Bases: packet.Packet

Command Status packet

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

static int24to32(bin_data)

converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

push_to_dashboard(dashboard)

class packet.CommandStatus(timestamp, payload)

Bases: packet.Packet

Command Status packet

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

static int24to32(bin_data)

converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

push_to_dashboard(dashboard)

class packet.CalibrationInfo(timestamp, payload)

Bases: packet.Packet

Calibration Info packet

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

static int24to32(bin_data)

converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

push_to_dashboard(dashboard)

Dashboard

class dashboard.dashboard.Dashboard(n_chan, exg_fs, mode='signal', firmware_version='NA')

Bases: object

Explorepy dashboard class

Parameters:

• n_chan (int) – Number of channels
• exg_fs (int) – Sampling rate of ExG signal
• mode (str) – Visualization mode {‘signal’, ‘impedance’}
• firmware_version

update_exg(self, time_vector, ExG)

update_exg() Update ExG data in the visualization

Parameters:

• time_vector (list) – time vector
• ExG (np.ndarray) – array of new data

start_server()

Start bokeh server

start_loop()

Start io loop and show the dashboard

update_exg()

Update ExG data in the visualization

Parameters:

• time_vector (list) – time vector
• ExG (np.ndarray) – array of new data

update_orn(timestamp, orn_data)

Update orientation data

Parameters:

• timestamp (float) – timestamp of the sample
• orn_data (float vector) – Vector of orientation data with shape of (9,)

update_info(new)

Update device information in the dashboard

Parameters:new (dict) – Dictionary of new values

_update_fft()

Update spectral frequency analysis plot

_update_heart_rate()

Detect R-peaks and update the plot and heart rate

_change_scale(attr, old, new)

Change y-scale of ExG plot

_change_t_range(attr, old, new)

Change time range

_change_mode(new)

Set EEG or ECG mode

_init_plots()

Initialize all plots in the dashboard

_init_controls()

Initialize all controls in the dashboard

_set_t_range(t_length)

Change time range of ExG and orientation plots

Additional tools

tools.bt_scan()

“Scan for bluetooth devices Scans for available explore devices. Prints out MAC address and name of each found device

Args:

Returns:

tools.bin2csv(bin_file, do_overwrite=False, out_dir='')

Binary to CSV file converter. This function converts the given binary file to ExG and ORN csv files.

Parameters:

• bin_file (str) – Binary file full address
• out_dir (str) – Relative output directory (if not given, it uses the current working directory.)
• do_overwrite (bool) – Overwrite if files exist already

tools.bin2edf(bin_file, do_overwrite=False, out_dir='')

Binary to EDF file converter. This function converts the given binary file to ExG and ORN csv files.

Parameters:

• bin_file (str) – Binary file full address
• out_dir (str) – Output directory (if None, uses the same directory as binary file)
• do_overwrite (bool) – Overwrite if files exist already

class tools.HeartRateEstimator(fs=250, smoothing_win=20)

Bases: object

Real-time heart Rate Estimator class This class provides the tools for heart rate estimation. It basically detects R-peaks in ECG signal using the method explained in Hamilton 2002 [2].

Parameters:

• fs (int) – Sampling frequency
• smoothing_win (int) – Length of smoothing window

References

[1] Hamilton, P. S. (2002). Open source ECG analysis software documentation. Computers in cardiology, 2002.

[2] Hamilton, P. S., & Tompkins, W. J. (1986). Quantitative investigation of QRS detection rules using the MIT/BIH arrhythmia database. IEEE transactions on biomedical engineering.

average_noise_peak

average_qrs_peak

decision_threshold

average_rr_interval

heart_rate

push_r_peak(val, time)

push_noise_peak(val, peak_idx, peak_time)

estimate(ecg_sig, time_vector)

Detection of R-peaks

Parameters:

• time_vector (np.array) – One-dimensional time vector
• ecg_sig (np.array) – One-dimensional ECG signal

Returns:

List of detected peaks indices

check_missing_peak(peak_time, peak_idx, detected_peaks_idx, ecg_sig, time_vector)

class tools.FileRecorder(file_name, ch_label, fs, ch_unit, ch_min=None, ch_max=None, device_name='Explore', file_type='edf', do_overwrite=False)

Bases: object

Explorepy file recorder class.

This class can write ExG, orientation and environment data into (separated) EDF+ files. It can write data while streaming from Explore device. The incoming data will be stored in a buffer and after it reached fs samples, it writes the buffer in EDF file.

Attributes:

Parameters:

• file_name (str) – File name
• ch_label (list) – List of channel labels.
• fs (int) – Sampling rate (must be identical for all channels)
• ch_unit (list) – List of channels unit (e.g. ‘V’, ‘mG’, ‘s’, etc.)
• ch_min (list) – List of minimum value of each channel. Only needed in edf mode (can be None in csv mode)
• ch_max (list) – List of maximum value of each channel. Only needed in edf mode (can be None in csv mode)
• device_name (str) – Recording device name
• file_type (str) – File type. current options: ‘edf’ and ‘csv’.
• do_overwrite (bool) – Overwrite file if a file with the same name exists already.

fs

_create_edf(do_overwrite)

_create_csv(do_overwrite)

stop()

Stop recording

_init_edf_channels()

write_data(data)

writes data to the file

Notes

If file type is set to EDF, this function writes each 1 seconds of data. If the input is less than 1 second, it will be buffered in the memory and it will be written in the file when enough data is in the buffer.

Parameters:data (np.array) – Array of data to be written in the file with dimension of n_chan x n_sample

set_marker(data)

Writes a marker event in the file

Parameters:data (np.array) – Array of marker data with size 2x1 ([[timestamp],[code]])