Home

Welcome to the WizardHat wiki!

Merlin Neurotech - Wizard Hat Documentation Introduction

Purpose

The Overall Description

Program Perspective Hardware Interfaces Software Interfaces Communications Interfaces

Philosophy

Quick Start with Wizard Hat! Connecting to the Muse Streaming data Frequent Issues

Software Design and Architecture

Overview Class Objects and Variables Types of errors

Version Control Flow Diagram of Git Repository Scheme Rules on handling the Git Repository
Beta testing repositories

Supporting information

Table of contents and index Definitions, Acronyms, and Abbreviations References and recommended readings

1 Introduction Wizard Hat was built by Merlin Neurotech at Queen’s University. Merlin Neurotech is a student club affiliated with NeuroTechX, an international not-for-profit organization with a purpose to bring hackers, neuroscientists, and the community together to develop a world wide neurotechnology community. Our club is comprised of graduate and undergraduate students who are passionate about neurotechnology and eager to develop brain-computer interfaces. We built Wizard Hat to make this job a little easier. 1.1 Purpose Wizard Hat is a modular framework for the streaming, manipulating, visualizing, and recording of EEG data from consumer-grade devices. This framework enables users and especially first timers to easily set up a stream and handle EEG data with little effort. Wizard Hat is modular, giving users flexibility to configure settings and add their own analysis pipelines. Use Wizard Hat to develop and test your brain-computer-interfaces and run EEG experiments.

2 Program Overview 2.1 Interfaces 2.1.1 Hardware Interfaces Wizard Hat 0.1 is configured to work with Muse-2016 brain-sensing headband. If you are working on macOS or Windows, you will need a BLED112 (Bluetooth Low Energy) dongle to connect to the Muse. Future iterations will include support for OpenBCI. 2.1.2 Software Interfaces This version of Wizard Hat is compatible with Python 3. All required dependencies can be found in the requirements file in the github repository. It is highly advised to run Wizard Hat in a python virtual environment (see Setup for instructions) in order to run the program without dependency errors. 2.1.3 Communication Interfaces 2.2 Philosophy <insert matt’s spiel about being pythonic and what not>

3 Quick Start with Wizard Hat! 3.1 Connecting to the Muse To connect to the muse, first ensure you are in your virtual environment and are in a directory that includes Wizard Hat. To establish a connection with your Muse, you will need to create a streaming outlet. This is a Lab Streaming Layer (LSL) protocol terminology for an established directional data flow between the device and your computer. In Python: import wizardhat as wiz outlet = wiz.acquire.LSLOutletStreamer() If your muse is turned on, you should see the LED light turn solid and a “Connected” message written on your console. Wizard Hat also provides an option to create a “dummy” outlet to generate random data for debugging your program without waiting for the muse to connect and when you don’t have the Muse with you. outlet_dummy = wiz.ble2lsl.LSLDummyOutlet() 3.2 Streaming data Once a stream has been established, you need to create a variable to capture the incoming data into a data structure. We call this a streaming inlet, where data is coming in. stream_inlet = wiz.acquire.LSLStreamer() This function automatically looks for a streaming outlet. This stream variable stores incoming EEG data in a structured array with a size that is determined by a time window (defaults to 10 seconds). After each window passes, the data is saved to your directory under a folder called ‘data’ as a csv (comma separated values) file. 3.3 Frequent Issues No BGAPI Compatible Device Found Make sure a BLE dongle is connected and that the Muse is turned on and within reach. The pygatt library may require a manual code fix, please refer to our beginner’s guide for how to implement this. Syntax Error Ensure you are in a virtual environment with all the correct packages installed **Other errors we commonly encounter If the error persists Please submit an issue on github or email mnc@clubs.queensu.ca with as much detail as possible about your problem and we will fix it as soon as we can.

4 Software Architecture 4.1 Overview Wizard Hat is built around the Lab Streaming Layer (LSL) Protocol and is designed to interface with bluetooth low energy (BLE) devices. Once a connection is established with the device, incoming data is fed through the LSL protocol first and foremost. Once an LSL outlet stream is established, the stream is captured into a structured array where metadata and data are sorted appropriately. From here, separate instances of data can be invoked for filtering and plotting purposes. See figure below

4.2 Classes <Spiel about the threading, permissions of each class, maybe a lil bit of philosophy> See figures below for class dependencies

4.2.1 OutletStreamer

Sets up a streaming of GATT data through LSL. OutletStreamer prepares ‘pylsl.StreamInfo’ and ‘pylsl.StreamOutlet’ objects as well as data buffers. Subclasses must implement ‘start’ and ‘stop’ methods for stream control. Attributes: info (pylsl.StreamInfo): Contains information about the stream outlet (pylsl.StreamOutlet):LSL Outlet to which data is pushed. 4.2.2 BLEStreamer Streams data to an LSL outlet from a BLE device Attributes: address (str): Device specific (MAC) address. start_time (float): Time of timestamp initialization by ‘initialize’ 4.2.3 DummyStreamer Can generate random data using a combination of sin waves or stream locally saved data from csv file. The purpose of this class is to allow individuals to build and debug code without using the muse. This is very useful if you have a limited number of devices. This class prepares an LSL outlet stream. Attributes: sfreq (int): Sampling frequency for generated data. n_chan (int): Number of channels of generated data. csv_file (str):Filename of ‘.csv’ containing local data 4.2.4 LSLStreamer Automatically finds an LSL outlet stream and passes data to a ‘data.TimeSeries object. Attributes: inlet (pylsl.StreamInlet):The LSL inlet from which to stream data. data (data.TimeSeries): Object in which the incoming data is stored, and which manages writing of that data to disk. sfreq (int) : The nominal sampling frequency of the stream. n_chan (int):The number of channels in the stream. ch_names(List[str]):The names of the channels in the stream. 4.2.4 Data Provides management of instance-related filenames and pipeline metadata for subclasses. Pipeline metadata consists of a field in the ‘metadata’ attribute which tracks the ‘Data’ and ‘transform.Transformer’ subclasses through which the data has flowed. As an abstract class, ‘Data’ should not be instantiated directly, but must be subclassed. Subclasses should conform to expected behaviour by overriding methods or properties that raise ‘NotImplementedError’ Args: metadata (dict) : Arbitrary information added to instance’s ‘json’ filename (str): User-defined for saving instance (meta)data. data_dir (str): Directory for saving instance (meta)data. label (str): User-defined addition to standard filename. Attributes: updated (Threading.event): Flag for threads waiting for data updates filename (str): Final (generated or specified) filename for writing metadata (dict): All metadata included in instance’s ‘.json’. 4.2.5 TimeSeries Stores data in a NumPy structured array where ‘time’ is the first field and the remaining fields correspond to the channel names passed during instantiation. Only the last ‘n_samples’ are stored in memory this way, but all samples are written to disk when ‘record=True’ Args: ch_names(List[str]): List of channel names. n_samples (int): Number of samples to store in memory. record (bool) : Whether to record samples to disk. channel_fmt (str or type or List[str]) or List[type]): Data type of channels. Attributes: 4.2.6 Lines(Plotter) Generates a visual representation of the data passed to it. Depends on VisPy library and requires an app.run() method be called outside the main loop in a script. Generates interactive keys for the user to manipulate the window and size of the data and toggle between filtered, raw, and PSD plots. Args: data Attributes: plot_params: 4.2.7 Transformer Provides management of all data transformation classes. Responsible to acquire the data to be transformed. Other transformer classes inherit this class and its objects. Args:

Attributes: 4.2.8 MNETransformer Responsible for the conversion of TimeSeries NumPy structured arrays to an compatible MNE data format for filtering purposes. Once data is filtered, this class converts it back to a structured NumPy Array. Args: Attributes: 4.2.9 MNEFilter Class for applying MNE filters to TimeSeries data objects. Expects a TimeSeries data object, a low frequency value, a high frequency value, and a filer buffer length.

4.2.10 ICAClean

Detects and removes blinks and other noise from EEG data and returns a cleaned array of data. Args: Attributes: 4.2.11 FFT Fourier Transforms the data into the frequency domain and sorts data into power spectrum frequency bands for plotting and feature analysis. Args: Attributes: 4.3 Objects and variables 4.3.1 TimeSeries Objects 4.3.1.1 Metadata 4.3.1.2 Timestamps 4.3.1.3 Channel Names 4.3.1.4 Raw Data 4.3.1.5 Window 4.3.2 Transformer 4.3.2.1 MNE Filter 4.3.2.2 Incoming data 4.3.2.3 FFT Feature Matrix 4.4 Methods 4.4.1 TimeSeries Methods 4.4.2 Transformer Methods 4.4.3 Plot Methods 4.5 Types of Errors 4.5.1 Class Errors NotImplementedError Thread 4.5.2 Method Errors 4.5.3 Others 5 Version Control 5.1 Git Repository Scheme Master branch, development branch etc 5.2 GitHub Repository Rules Pull requests, push requests, branch and fork etiqutte 6 Supporting Information 6.2 Definitions, Acronyms, and Abbreviations LSL - Lab Streaming Layer BLE - Bluetooth Low Energy FFT - Fourier Transform MNE - EEG Analysis and Visualization Library PIP -Python package installer and manager GATT - Generic Attribute, data structure for BLE 6.4 References and Readings Alexander Barachant’s muse-lsl : https://github.com/alexandrebarachant/muse-lsl NeuroTechX: http://neurotechx.com/ Merlin Neurotech: http://www.queensneurotech.ca/ BCI Workshop: https://github.com/NeuroTechX/bci-workshop Neuralink Article: https://waitbutwhy.com/2017/04/neuralink.html