Skip to content

usage.md

Latest commit

 

History

History
119 lines (84 loc) · 5.47 KB

usage.md

File metadata and controls

119 lines (84 loc) · 5.47 KB

RecordMuse - Usage Guide

Installation

1. Prerequisite Software

You must be running one of these Lab Streaming Layer (LSL) applications. This process assumes that you are running Bluemuse, but two alternatives are also suggested:

App OS Download LSL Recording Paywall Notes
BluseMuse Windows Github ☑️ ❌ ❌ No in-built recording
Petal Metrics Windows, OS X, Linux Website, Free Ver.$^1$ (Windows, Linux only) ☑️ ☑️ 💵 Stops recording when signals are interrupted
Mind Monitor iOS, Android Website 🤷$^2$ ☑️ 💵 Timestamps are packaged and lossy

1: Version 1.8.0 of the software has been cached prior to the developers paywalling their application. I've only managed to cache the Windows and Linux versions; I unfortunately no longer have access to the OS X version. 2: I haven't explored this possibility yet. The Mind Monitor application implies to allow streaming to a specific IP address and port, but preliminary exploration did not give me a chance to access this IP from another device on the same network.

2. Cloning the Repo

The easiest way to download this repo is to download the source code of our latest release.

Alternatively, you can simply clone the repository via Git commands. This allows you to pull updates when needed. Just be sure to keep an eye out when we update new releases.

# HTTPS
https://github.com/SimpleDevs-Tools/RecordMuse.git
# SSH
git clone git@github.com:SimpleDevs-Tools/RecordMuse.git

3. Virtual Environment Setup

All dependencies are provided in requirements.txt. It's safest to set up a virtual Python environment first. This has been tested in Python 3.11.

# Virtual environment `.venv` setup (Windows)
py -m venv .venv
.venv/Scripts/activate
# Virtual environment `.venv` setup (Mac / Linux)
python -m venv .venv
source .venv/bin/activate

# Installing dependencies via pip
pip install -r requirements.txt

# Do your thing
# <run commands here>
# Or run the Streamlit app to have a visual interface
streamlit run app.py

# Closing the virtual environment
deactivate

WARNING: Execution Policy and Permissions

If you attempt to activate your virtual environment and you get an error, then you need to double-check that you have execution policy permissions allowed.

Firstly, open up a PowerShell window in Administrator Mode. Then, double-check the output of this command. You are likely to see the following:

# Run this Command
Get-ExecutionPolicy -List

# Likely Output
Scope ExecutionPolicy
----- ---------------
MachinePolicy       Undefined
   UserPolicy       Undefined
      Process       Undefined
  CurrentUser       Undefined   # <-- This should be "RemoteSigned", but it isn't...
 LocalMachine    RemoteSigned

To change this, run the following command:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

You can double-check once more if the permission has been applied to "CurrentUser" - if so, then you're golden.

Usage

All scripts are split between different directories:

  • record/: contains all scripts related to demo-ing and recording EEG data.
  • processing/: contains all scripts related to converting from Mind Monitor to BlueMuse formatting, filtering, and data normalization.
  • analysis/: contains all scripts related to analysis, such as data validation and power spectral density (PSD) calculation.

Option 1: Running with a User Interface

If you prefer a user interface for easy operation, you can run this repo as a Streamlit application:

streamlit run app.py

This interface gives you some basic controls for demo-ing, recording, converting, and processing EEG data. However, not all functions are provided. For more specific coverage, move onto Option 2.

Option 2: Command-Line Interface

A quick run-through of operations may look something like this:

  1. Record your Data
    1. Start your LSL streaming softare (BlueMuse or Petal Metrics)
    2. Check if RecordMuse properly detects which streaming presets are needed (record/stream_info.py and record/stream_presets.yaml)
    3. Demo your EEG data streams to ensure proper alignment with the user's scalp (record/demo.py)
    4. Record your EEG data (record/record.py)
  2. Processing your Data
    1. (If needed) Convert your EEG data from Mind Monitor's formatting to BlueMuse's formatting (processing/convert.py)
    2. Filter your EEG data via a notch filter of 60Hz to remove noise from electrical components; apply an additional butterworth filter to further restrict high-frequency noise data (processing/filter.py)
    3. (0If you recorded rest-state EEG) Normalize your EEG samples (processing/normalize.py)
  3. Analyze your Data
    1. Perform a Power Spectral Density calculation to identify key frequencies in your data (analysis/psd.py)
    2. Validate your samples (analysis/validate.py)

For more details on implementation specifics (e.g. command line flags, implementation details and methods), please refer to methodology.md.