Software for recording and analysing microEMG recordings, developed for "Multi-channel jitter recordings in the diagnosis of myasthenia gravis and congenital myasthenic syndromes" project.
In clinical practice, electromyography (EMG) is performed using a single-channel electrode to capture motor unit and muscle fibre potentials. These recordings are subsequently analysed to detect abnormalities in motor unit function. Clinicians must currently obtain multiple single-channel recordings which is time-consuming and requires expertise. Additionally, a single-channel recording does not provide information about muscle fibre locations or motor unit sizes.
To address these limitations, the microEMG team has developed:
- A multichannel EMG (microEMG) electrode. Each electrode contains 32 or 64 channels, allowing clinicians to obtain a single, multivariate recording per muscle.
- An analytical pipeline that identifies motor units and localises muscle fibres.
These Python modules provide classes and a user interface for analysing microEMG recordings.
Dr Roger Whittaker, Newcastle University (roger.whittaker@newcastle.ac.uk)
Dr Stuart Maitland, Newcastle University (stu.maitland@newcastle.ac.uk)
Dr Gabrielle Schroeder, Newcastle University (gabrielle.schroeder@newcastle.ac.uk)
Dr Richard Howey, Newcastle University (richard.howey@newcastle.ac.uk)
Dr Frances Turner, Newcastle University (frances.hutchings@newcastle.ac.uk)
Gabrielle Schroeder
RSE Team
Newcastle University
(gabrielle.schroeder@newcastle.ac.uk)
The microEMG GUI uses
Bootstrap Icons
CartoColors (via the palettable Python package)
Developed and tested using Python 3.11
Dependencies are managed using Python package Poetry, version 1.4.0
See pyproject.toml file for list of Python package dependencies.
mypy as a static type checker
Flake8 (including the bugbear plugin) as a linter
pre-commit install to use the included pre-commit hooks)
Create a Python 3.11 environment and install poetry:
pip install poetry==1.4.0
Next, install the packages using poetry (run from within the project directory):
poetry install
poetry will install both the Python package dependencies and set up paths to the local modules, pymicroemg and microemggui.
See the Troubleshooting section for more help with poetry.
Example recording data needs to be manually added in a recordings folder at the root level (see the paths in helper_config.py). These paths are the same as in the provided data, with the exception that the 64 channel directory is replaced with 64-channel. The recording needed as a demo recording for the GUI is recordings/64-channel/Stuart_E2/raw.
From the root directory, run gui_dev/gui_dev_main.py from a command line to launch the full GUI:
python gui_dev/gui_dev_main.py
Subsections of the GUI can also be run using the other Python files in gui_dev.
GUI instructions are here.
The GUI has been developed on MacOS and may have some missing functionality or altered formats on other operating systems.
The GUI produces log messages in a file microemggui.log (located in the directory from which the GUI is run). This log file is overwritten each time the GUI is launched - if you experience issues, rename this file to save the logs.
Alternatively, you can develop your own analysis scripts using the pymicroemg module for additional control over analysis settings and steps. See data_analysis/example_pipeline.py for an example pipeline.
We developed two modules:
pymicroemgcontains functions and classes for analysing microEMG data.microemgguiis built on top ofpymicroemgto provide a graphical user interface (GUI) for performing the analysis, with the ability to modify some analysis settings.
The pymicroemg module is documented using pdoc here, and an overview of the methods is provided here. You can view this documentation by downloading the entire folder (or cloning the repository) and opening pymicroemg.html - it will open in web browser.
If you update the pymicroemg module, please update the documentation by running
pdoc --docformat numpy pymicroemg -o ./docs/pymicroemg
from a terminal from the root directory.
The widgets submodule contains the widgets for the GUI, organised by the "pages" in the GUI (one page per analysis step).
The full GUI is specified in widgets/main/main_window.py.
The models submodule contains "models", or interfaces, to some of the pymicroemg classes for settings and data.
This approach makes it easier to separate GUI functionality from the underlying analysis software. Note that many of the settings options (e.g., options for dropdown boxes) for the GUI are specified in models/settings.py.
The docs folder contains a PDF with GUI instructions, microemg_help_guide.pdf. This PDF can be manually updated using the associated Word Document. It is linked to a help icon in the GUI.
The styles submodule contains a style sheet for modifying the GUI's appearance and code for implementing the style sheet.
The icons submodule contains icons (mostly Bootstrap) used in the GUI.
These icons are set up using a Qt resource system to ensure they are not dependent on a specific directory structure or paths.
If you change the icons, you need to update the resource system by running this command from the root directory in a terminal:
pyside6-rcc analysis_software/microemggui/microemggui/icons/icons.qrc -o analysis_software/microemggui/microemggui/icons/icons.py
The microemggui has partial test coverage using pytest. These tests can be run from a terminal using
pytest analysis_software/microemggui/
-
If you ran the installation instructions outside of a virtual environment, poetry will have created one for you when you ran
poetry install, however it won't have activated it automatically. You can activate the virtual environment withpoetry shelland exit this with the commandexit. Outside of this virtual environment you will not have the required installed dependencies so this can be a cause of errors. -
For Linux users, an error has been noted when trying to run the GUI where the QT platform plugin fails to load. This thread proposes a solution that worked in our testing, to install libxcb-cursor-dev.
pymicroemgdocumentation (must download entire folder and open pymicroemg.html - will open in web browser)- GUI instructions
- MicroEMG analysis methods
- Intan recording format
- Initial Research
- Minimum viable product <-- You are Here
- Alpha Release
- Feature-Complete Release
- Extend test coverage of
microemgguiand add unit tests forpymicroemg - Modify
pymicroemgsettings classes to validate settings attributes when modified by the user and prevent direct access to settings attributes (e.g., using getters and setters) - Type hints have been implemented, but not fully validated using
mypy(a static type checker) - Package GUI
- Improve and test GUI implementation on Windows and Linux
- Update CI to 1) automatically update documentation (GUI PDF and
pymicroemgpdocdocumentation) and the Qt resource system when necessary and 2) include testing and static type checking in pull request checks.
Additional potential features are organised using the associate project board and issues (see not planned issues).
Protected and can only be pushed to via pull requests. It should be considered stable and a representation of production code.
Should be considered fragile; code should compile and run, but features may be prone to errors.
A branch per feature that is being worked on.
https://nvie.com/posts/a-successful-git-branching-model/
Adding new packages:
poetry add <package name>which adds a package to the pyproject.toml file (the list of requirements)
To add a package to a specific group, e.g. dev: poetry add <package name> -G dev
poetry lock --no-updateupdates the lock file (with all the packages needed and the exact versions, including dependencies of the packages in the pyproject.toml file), but does not change the version of the previously tracked dependencies
This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details.
Third-party components bundled with this project retain their original licenses; see NOTICE for attributions.
Please cite the associated paper if you use this code:
Stuart Maitland, Enrique Escobedo-Cousin, Ian Schofield, Anthony O'Neill, Stuart Baker, Roger Whittaker, Electrical cross-sectional imaging of human motor units in vivo, Clinical Neurophysiology, Volume 136, 2022, Pages 82-92, ISSN 1388-2457, https://doi.org/10.1016/j.clinph.2021.12.022 (ScienceDirect link)
@article{maitland2022electrical,
title = {Electrical cross-sectional imaging of human motor units in vivo},
author = {Maitland, Stuart and Escobedo-Cousin, Enrique and Schofield, Ian and O'Neill, Anthony and Baker, Stuart and Whittaker, Roger},
journal = {Clinical Neurophysiology},
volume = {136},
pages = {82--92},
year = {2022},
issn = {1388-2457},
doi = {10.1016/j.clinph.2021.12.022}
}