explorepy

Main API

class explore.Explore(n_device=1)[source]

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)[source]

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)[source]

Disconnects from the device

Parameters:device_id (int) – device id (not needed in the current version)
acquire(device_id=0, duration=None)[source]

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)[source]

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).
push2lsl(n_chan, device_id=0, duration=None)[source]

Push samples to two lsl streams

Parameters:
  • device_id (int) – device id (not needed in the current version)
  • n_chan (int) – Number of channels (4 or 8)
  • duration (float) – duration of data acquiring (if None it streams endlessly).
visualize(n_chan, device_id=0, bp_freq=(1, 30), notch_freq=50)[source]

Visualization of the signal in the dashboard :Parameters: * n_chan (int) – Number of channels device_id (int): Device ID (in case of multiple device connection)

  • 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
_io_loop(device_id=0, mode='visualize')[source]
measure_imp(n_chan, device_id=0, notch_freq=50)[source]

Visualization of the electrode impedances

Parameters:
  • n_chan (int) – Number of channels
  • device_id (int) – Device ID
  • notch_freq (int) – Notch frequency for filtering the line noise (50 or 60 Hz)

Returns:

change_settings(command, device_id=0)[source]

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

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

Returns:

Bluetooth API

class bt_client.BtClient[source]

Bases: object

Responsible for Connecting and reconnecting explore devices via bluetooth

init_bt(device_name=None, device_addr=None)[source]

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()[source]

Creates the socket

reconnect()[source]

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)[source]
find_explore_service()[source]

Parser

parser.generate_packet(pid, timestamp, bin_data)[source]

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=50, socket=None, fid=None)[source]

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)
parse_packet(mode='print', csv_files=None, outlets=None, dashboard=None)[source]

Reads and parses a package from a file or socket

Parameters:
  • mode (str) – logging mode {‘print’, ‘record’, ‘lsl’, ‘visualize’, None}
  • csv_files (tuple) – Tuple of csv file objects (EEG_csv_file, ORN_csv_file, Marker_csv_file)
  • outlets (tuple) – Tuple of lsl StreamOutlet (orientation_outlet, EEG_outlet, marker_outlet)
  • dashboard (Dashboard) – Dashboard object for visualization
Returns:

packet object

read(n_bytes)[source]

Read n_bytes from socket or file

Parameters:n_bytes (int) – number of bytes to be read
Returns:list of bytes
send_msg(msg)[source]

tries to send a message through socket.

class packet.PACKET_ID[source]

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)[source]

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)[source]

Read the binary data and convert it to real values

_check_fletcher(fletcher)[source]

Checks if the fletcher is valid

__str__()[source]

Print the data/info

static int24to32(bin_data)[source]

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)[source]
class packet.EEG(timestamp, payload)[source]

Bases: packet.Packet

Gets the timestamp and payload and initializes the packet object

Parameters:payload (bytearray) – a byte array including binary data and fletcher
write_to_csv(csv_writer)[source]

Write EEG data to csv file

Parameters:csv_writer (csv_writer) – csv writer object
apply_bp_filter(exg_filter)[source]

Bandpass filtering of ExG data

Args: exg_filter: Filter object

apply_bp_filter_noise(exg_filter)[source]

Bandpass filtering of ExG data

Args: exg_filter: Filter object

apply_notch_filter(exg_filter)[source]

Band_stop filtering of ExG data

Parameters:exg_filter – Filter object
push_to_lsl(outlet)[source]

Push data to lsl socket

Parameters:outlet (lsl.StreamOutlet) – lsl stream outlet
calculate_impedance(imp_calib_info)[source]

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)[source]
push_to_imp_dashboard(dashboard, imp_calib_info)[source]
__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)[source]

Bases: packet.EEG

EEG packet for 4 channel device

_convert(bin_data)[source]

Read the binary data and convert it to real values

_check_fletcher(fletcher)[source]

Checks if the fletcher is valid

write_to_csv(csv_writer)[source]

Write EEG data to csv file

Parameters:csv_writer (csv_writer) – csv writer object
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
class packet.EEG98(timestamp, payload)[source]

Bases: packet.EEG

EEG packet for 8 channel device

_convert(bin_data)[source]

Read the binary data and convert it to real values

_check_fletcher(fletcher)[source]

Checks if the fletcher is valid

write_to_csv(csv_writer)[source]

Write EEG data to csv file

Parameters:csv_writer (csv_writer) – csv writer object
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
class packet.EEG99s(timestamp, payload)[source]

Bases: packet.EEG

EEG packet for 8 channel device

_convert(bin_data)[source]

Read the binary data and convert it to real values

_check_fletcher(fletcher)[source]

Checks if the fletcher is valid

write_to_csv(csv_writer)[source]

Write EEG data to csv file

Parameters:csv_writer (csv_writer) – csv writer object
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
class packet.EEG99(timestamp, payload)[source]

Bases: packet.EEG

EEG packet for 8 channel device

_convert(bin_data)[source]

Read the binary data and convert it to real values

_check_fletcher(fletcher)[source]

Checks if the fletcher is valid

write_to_csv(csv_writer)[source]

Write EEG data to csv file

Parameters:csv_writer (csv_writer) – csv writer object
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
class packet.Orientation(timestamp, payload)[source]

Bases: packet.Packet

Orientation data packet

_convert(bin_data)[source]

Read the binary data and convert it to real values

_check_fletcher(fletcher)[source]

Checks if the fletcher is valid

write_to_csv(csv_writer)[source]
push_to_lsl(outlet)[source]
push_to_dashboard(dashboard)[source]
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)[source]

Bases: packet.Packet

Environment data packet

_convert(bin_data)[source]

Read the binary data and convert it to real values

_check_fletcher(fletcher)[source]

Checks if the fletcher is valid

push_to_dashboard(dashboard)[source]
static _volt_to_percent(voltage)[source]
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)[source]

Bases: packet.Packet

Time stamp data packet

_convert(bin_data)[source]

Read the binary data and convert it to real values

_check_fletcher(fletcher)[source]

Checks if the fletcher is valid

translate()[source]
write_to_csv(csv_writer)[source]
push_to_lsl(outlet)[source]
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)[source]

Bases: packet.Packet

Marker packet

_convert(bin_data)[source]

Read the binary data and convert it to real values

_check_fletcher(fletcher)[source]

Checks if the fletcher is valid

write_to_csv(csv_writer)[source]
push_to_lsl(outlet)[source]
push_to_dashboard(dashboard)[source]
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)[source]

Bases: packet.Packet

Disconnect packet

_convert(bin_data)[source]

Disconnect packet has no data

_check_fletcher(fletcher)[source]

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)[source]

Bases: packet.Packet

Device information packet

_convert(bin_data)[source]

Read the binary data and convert it to real values

_check_fletcher(fletcher)[source]

Checks if the fletcher is valid

push_to_dashboard(dashboard)[source]
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)[source]

Bases: packet.Packet

Command Status packet

_convert(bin_data)[source]

Read the binary data and convert it to real values

_check_fletcher(fletcher)[source]

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)[source]

Bases: packet.Packet

Command Status packet

_convert(bin_data)[source]

Read the binary data and convert it to real values

_check_fletcher(fletcher)[source]

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)[source]

Bases: packet.Packet

Calibration Info packet

_convert(bin_data)[source]

Read the binary data and convert it to real values

_check_fletcher(fletcher)[source]

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, mode='signal')[source]

Bases: object

Explorepy dashboard class

update_exg(self, time_vector, ExG)[source]

update_exg() Update ExG data in the visualization

Parameters:
  • time_vector (list) – time vector
  • ExG (np.ndarray) – array of new data
start_server()[source]

Start bokeh server

start_loop()[source]

Start io loop and show the dashboard

update_exg()[source]

Update ExG data in the visualization

Parameters:
  • time_vector (list) – time vector
  • ExG (np.ndarray) – array of new data
update_orn(timestamp, orn_data)[source]

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)[source]

Update device information in the dashboard

Parameters:new (dict) – Dictionary of new values
_update_fft()[source]

Update spectral frequency analysis plot

_update_heart_rate()[source]

Detect R-peaks and update the plot and heart rate

_change_scale(attr, old, new)[source]

Change y-scale of ExG plot

_change_t_range(attr, old, new)[source]

Change time range

_change_mode(new)[source]

Set EEG or ECG mode

_init_plots()[source]

Initialize all plots in the dashboard

_init_controls()[source]

Initialize all controls in the dashboard

_set_t_range(t_length)[source]

Change time range of ExG and orientation plots

Additional tools

tools.bt_scan()[source]

“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=None)[source]

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) – Output directory (if None, uses the same directory as binary file)
  • do_overwrite (bool) – Overwrite if files exist already

Returns:

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

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)[source]
push_noise_peak(val, peak_idx, peak_time)[source]
estimate(ecg_sig, time_vector)[source]

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)[source]