Metadata-Version: 2.4
Name: python-mindrove-emg
Version: 0.1.0
Summary: Tools for recording, streaming, and analyzing MindRove EMG and IMU data.
Author-email: Jonathan Shulgach <jshulgac@andrew.cmu.edu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Neuro-Mechatronics-Interfaces/python-mindrove-emg
Project-URL: Repository, https://github.com/Neuro-Mechatronics-Interfaces/python-mindrove-emg
Project-URL: Issues, https://github.com/Neuro-Mechatronics-Interfaces/python-mindrove-emg/issues
Keywords: mindrove,emg,imu,lsl,xdf,biosignals
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mindrove
Requires-Dist: numpy>=1.23
Requires-Dist: pylsl==1.17.6
Provides-Extra: gui
Requires-Dist: PyQt5; extra == "gui"
Provides-Extra: playback
Requires-Dist: pyxdf>=1.17; extra == "playback"
Provides-Extra: analysis
Requires-Dist: matplotlib>=3.8; extra == "analysis"
Requires-Dist: pyxdf>=1.17; extra == "analysis"
Requires-Dist: scikit-learn>=1.4; extra == "analysis"
Requires-Dist: scipy>=1.11; extra == "analysis"
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: all
Requires-Dist: PyQt5; extra == "all"
Requires-Dist: matplotlib>=3.8; extra == "all"
Requires-Dist: pyxdf>=1.17; extra == "all"
Requires-Dist: scikit-learn>=1.4; extra == "all"
Requires-Dist: scipy>=1.11; extra == "all"
Dynamic: license-file

# python-mindrove-emg

Tools for recording, streaming, replaying, and analyzing MindRove EMG + IMU data.

This project is currently alpha software. It is intended for research workflows around
MindRove Wi-Fi EMG devices, Lab Streaming Layer (LSL), XDF recordings, and quick
gesture/state separability checks.

## Features

- Stream one MindRove device to LSL as EMG and IMU streams.
- Record MindRove EMG + IMU data to compressed `.npz` files.
- Stream either or both of two MindRove Wi-Fi devices from one GUI.
- Apply optional EMG DC removal and bandpass filtering in the dual-device streamer.
- Replay `.npz` or `.xdf` recordings to LSL.
- Analyze event-labeled XDF recordings for state separability.

## Installation

For GUI acquisition and streaming:

```powershell
pip install "python-mindrove-emg[gui]"
```

For XDF replay support:

```powershell
pip install "python-mindrove-emg[gui,playback]"
```

For offline separability analysis:

```powershell
pip install "python-mindrove-emg[analysis]"
```

For development from a local checkout:

```powershell
pip install -e ".[all,dev]"
```

## Command-Line Tools

Single-device LSL streamer:

```powershell
mindrove-lsl
```

Single-device recorder:

```powershell
mindrove-recorder --output-dir recordings --session-name mindrove_session
```

Dual-device LSL streamer:

```powershell
mindrove-dual-lsl
```

Dual-device streamer with custom LSL prefixes:

```powershell
mindrove-dual-lsl --device-a-prefix MindRove_Left --device-b-prefix MindRove_Right
```

Dual-device streamer with explicit device IPs:

```powershell
mindrove-dual-lsl --device-a-ip 192.168.4.1 --device-b-ip 192.168.5.1
```

Separability analysis for event-labeled XDF recordings:

```powershell
mindrove-separability C:\path\to\xdf_folder --output-dir analysis_outputs\session001
```

## Data Streams

The LSL tools expose:

- EMG: 8 channels, float32, nominally 500 Hz.
- Combined IMU: 9 channels, accelerometer + gyroscope + magnetometer.
- Optional IMU breakout streams in the dual-device GUI: accelerometer, gyroscope, magnetometer.

## Recording And Analysis Notes

The separability analyzer expects XDF files with:

- A continuous MindRove signal stream.
- A marker stream with `prompt_onset` events.
- Gesture markers encoded like `prompt_onset|phase=gesture|trial=001|gesture=hand_open|duration_s=5.000`.

It extracts gesture windows, computes time-domain EMG features, and reports
leave-one-recording-out accuracy, trial majority-vote accuracy, confusion matrices,
pairwise accuracy, centroid distances, and a PCA plot.

## Repository Hygiene

Do not commit local recordings, generated analysis outputs, virtual environments,
`__pycache__`, or `*.egg-info` directories. These are ignored by `.gitignore`.

## License

MIT. See [LICENSE](LICENSE).
