<p align="center">
<img style="width: 35%; height: 35%" src="https://github.com/resurfemg-org/ReSurfEMG/blob/main/Logo_rond_tekst.svg">
</p>
[](https://doi.org/10.5281/zenodo.6811553)
[](https://pypi.python.org/pypi/resurfemg/)
[](https://github.com/resurfemg-org/ReSurfEMG/actions/workflows/on-commit.yml)
[](https://github.com/resurfemg-org/ReSurfEMG/actions/workflows/on-tag.yml)
[](https://opensource.org/licenses/Apache-2.0)
[](https://bestpractices.coreinfrastructure.org/projects/6487)
[](https://fair-software.eu)
[](https://joss.theoj.org/papers/5f08d1f2bb717b7d05762296e37ded3d)
**ReSurfEMG** is an open source collaborative python library for analysis
of respiratory electromyography (EMG). On the same site as
the repository for this library we keep [related resources](https://github.com/ReSurfEMG?tab=repositories).
ReSurfEMG includes a [main code library](https://github.com/resurfemg-org/ReSurfEMG) where the user can access the code to change various filter and analysis settings directly and/or in our [researcher interface notebooks](https://github.com/resurfemg-org/ReSurfEMG/tree/main/notebooks/researcher_interface).
In addition, ReSurfEMG has a [dashboard interface](https://github.com/resurfemg-org/ReSurfEMG-dashboard) which contains default settings for preprocessing and analysis which can be changed through a graphical (no code) interface. We have some functionality available through a [command line interface](#command-line-interface) as well.
The library was initially built for surface EMG, however many functions will also work for
invasively measured respiratory EMG. This library supports the ongoing research at University of Twente on respiratory EMG.
### Program files
The core functions of ReSurfEMG are in the folder [resurfemg](https://github.com/resurfemg-org/ReSurfEMG/tree/main/resurfemg):
- **cli:** Scripts for the command line interface
- **data_connector:** Converter functions for discovering, loading, simulating and handling data.
- **helper_functions:** General functions to support the functions in this repository
- **preprocessing:** Process the raw respiratory EMG signal
- filtering: low-, high- and bandpass filters, notch filter, computer power loss
- ecg-removal: gating and wavelet denoising
- envelope: root-mean-square (RMS), average rectified (ARV)
- **postprocessing:** Aspects of pre-processed the respiratory EMG data:
- moving baselines
- event detection: find pneumatic and EMG breaths, on- and offset detection
- features: amplitude, area under the curve, slope, area under the baseline, respiratory rate
- quality assessment: signal-to-noise ratio, end-expiratory occlussion manoeuvre quality, interpeak distance, area under the baseline, consecutive manoeuvres, bell-curve error, relative peak timing, relative area under the baseline, relative ETP
### Folders and Notebooks
Our [guide to notebooks](https://github.com/resurfemg-org/ReSurfEMG/blob/main/notebooks_guide.md) is under construction. To look around keep in mind the following distinction on folders:
dev:
- These notebooks are used in feature development and debugging by core members of the ReSurfEMG team. They can provide a basic example how to use some of the functionality.
open_work:
- This folder contains experimental work by core members of the ReSurfEMG
team that is not deployed yet.
researcher_interface:
- These are a growing series of interactive notebooks that allow
researchers to investigate questions about their own EMG data
### Data sets
The notebooks are configured to run on various datasets. Contact
Dr. Eline Mos-Oppersma( 📫 e.mos-oppersma@utwente.nl) to discuss any
questions on data configuration for your datasets.
If you want to use a standardized dataset for any purpose we recommend
the data in the [ReSurfEMG/test_data](https://github.com/resurfemg-org/ReSurfEMG/blob/main/test_data), which is also used in testing the ReSurfEMG functions.
Data there can be used with any respiratory EMG algorithms in any program. Thus that data can function as a benchmarking set to compare algorithms across different programs.
Alternatively, the data in the ReSurfEMG/synthetic_data repository:
[](https://zenodo.org/badge/latestdoi/635680008)
### Configuring (to work with your data)
In order to preprocess and/or to train models the code needs to be
able to locate the raw data you want it to find.
There are several ways to specify the location of the following
directories:
- **root_data:** Special directory. The rest of the directory layout can be derived from its location.
- **preprocessed_data:** The directory that will be used by preprocessing
code to output to.
- **test_data:** The directory for running sanity tests.
You can store this information persistently in several locations.
1. In the same directory where you run the script (or the notebook).
e.g. `./config.json`.
2. In home directory, e.g. `~/.resurfemg/config.json`.
3. In global directory, e.g. `/etc/resurfemg/config.json`.
However, we highly recommend using the home directory.
This file can have this or similar contents:
```
{
"root_data": "/mnt/data",
"patient_data": "/mnt/patient_data",
"simulated_data": "/mnt/simulated_data",
"preprocessed_data": "/mnt/data/preprocessed",
"output_data": "/mnt/data/output",
}
```
The file is read as follows: if the files specifies `root_data`
directory, then the missing entries are assumed to be relative to
the root. You do not need to specify all entries.
### Test data
Test data is provided in the repository in the test_data folder.
### Supported Platforms
ReSurfEMG is a pure Python package. Below is the list of
platforms that should work. Other platforms may work, but have had less extensive testing.
Please note that where python.org Python stated as supported, it means
that versions 3.9 - 3.12 are supported.
#### AMD64 (x86)
| | Linux | Win | OSX |
|:---------------------------:|:---------:|:---------:|:---------:|
|  | Supported | Supported | Supported |
|  | Discontinued | Discontinued | Discontinued |
### Installation for all supported platforms
Installation with Anaconda/conda and/or mamba are the preffered methods.
They are covered in [the "Getting Started" section](#Getting-Started).
If you wish to install with pip:
1. Create and activate a virtual environment (see developer setup section for more details)
2. Install ResurfEMG package by running `pip install resurfemg`.
## Getting Started
### With the recommended Python venv setup
How to get the notebooks running? Assuming the raw data set and
metadata is available.
### 0a. Create a virtual environment using Python
#### On Linux/OSX:
``` sh
python3 -m venv .venv
```
This might **require** the python3-venv.
#### On Windows:
``` sh
python -m venv .venv
```
### 0b. Activate the virtual environment and install ReSurfEMG
#### On Linux/OSX:
``` sh
source .venv/bin/activate
pip install resurfemg[dev]
```
#### On Windows:
``` sh
.venv\Scripts\activate.bat
pip install resurfemg[dev]
```
### 1. Open a notebook
Start a local Jupyter Notebook server by running the `jupyter notebook`
command in your terminal. This opens a browser window where you can browse,
open and run the notebooks. (We use [Jupyter notebooks](https://jupyter.org/try-jupyter/retro/notebooks/?path=notebooks/Intro.ipynb))
The ReSurfEMG notebooks are located in the notebooks folder. Navigate there
and open a notebook of interest. The [basic_emg_analysis](https://github.com/resurfemg-org/ReSurfEMG/blob/main/researcher_interface/basic_emg_analysis.ipynb)
notebook can be used to understand how to use the package.
## Advanced contributor's setup / "Developer's setup"
We distinguish between people who want to use this library in their own code
and/or analysis, and people who also want to develop this library who we call
developers, be it as members of our team or independent contributors. People
who simply want to use our library need to install the packaged version from
one of the package indexes to which we publish released versions (eg. PyPI).
This section of the readme is for advanced developers who want to modify the
library code (and possibly contribute their changes back or eventually publish
thier own modified fork). NB: You can accomplish modifications of the code,
submit pull-requests (PRs) and soforth without a 'developer's setup' but we
feel this setup will make advanced contributions easier.
We have transitioned to a fully Python 3.9+ environment.
(For older instructions with `venv` please see versions below 0.2.0, and
adapt them if using Windows and/or a different Python version than
Python.org Python. e.g. you may need to use `.venv\Scripts\activate.bat` in
place of `.venv/bin/activate`)
The instructions below are for our newer versions above 1.0.0. This will create
a distributable package from the source code, then install it in the currently
active environment. This will also install development tools we use
s.a. `pytest` and `codestyle` and will also install tools we use for
working with the library, such as `jupyter`.
### On Linux/OSX:
``` sh
python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
```
### On Windows:
``` sh
python -m venv .venv
.venv\Scripts\activate.bat
pip install -e .[dev]
```
These installs differ in two ways from the regular install: 1) The `.[dev]` (as compared to `resurfemg[dev]`)
installs the library as it currently is including all your local changes,
instead of pulling it from the PyPI repository. 2) The `-e` flag ensures an
editable install, such that any changes to the library are automatically
applied to your environment.
Now you should have everything necessary to start working on the
source code.
## Generating documentation
Online documentation can be found at https://resurfemg.github.io/ReSurfEMG/
or on https://readthedocs.org/ by searching for ReSurfEMG. Up-to-date
documentation can be generated in command-line as follows in terminal:
### On Linux/OSX:
``` sh
python3 -m venv .venv
source .venv/bin/activate
pip install -e .[docs]
python setup.py apidoc
python setup.py build_sphinx
```
### On Windows:
``` sh
python -m venv .venv
.venv\Scripts\activate.bat
pip install -e .[docs]
python setup.py apidoc
python setup.py build_sphinx
```
## Automation
The project comes with several modifications to the typical default `setup.py`.
The project has a sub-project of a related dashboard. Dashboard is a GUI that
exposes some of the project's functionality. In the past, we kept a a legacy
dashboard in the same repository with ReSurfEMG code but we have deleted it.
The current version of the dashboard into it's own repository:
https://github.com/resurfemg-org/ReSurfEMG-dashboard
### New commands
* `isort resurfemg --check --diff` checks that the imports are properly
formatted and sorted.
* `python setup.py apidoc` generates RST outlines necessary to generate
documentation.
### Testing
The project includes testing data. This test data is synthetic and generated by the ReSurfEMG `data_connector.synthetic_data` methods.
### On Linux/OSX:
``` sh
python3 -m venv .venv
source .venv/bin/activate
pip install -e .[tests]
pytest
```
### On Windows:
``` sh
python -m venv .venv
.venv\Scripts\activate.bat
pip install -e .[tests]
pytest
```
## Command-Line Interface
You will be able to preprocess data using command-line interface. You can also,
in some cases, create files in the correct format for our Dashboard in a per
folder batch process.
You can make synthetic data. To explore this start with
`python -m resurfemg simulate_emg --help`
`python -m resurfemg simulate_ventilator --help`
✨Copyright 2022 Netherlands eScience Center and U. Twente
Licensed under the Apache License, version 2.0. See LICENSE for details.✨
Raw data
{
"_id": null,
"home_page": null,
"name": "resurfemg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Eline Mos-Oppersma <e.oppersma@utwente.nl>, Rob Warnaar <r.s.p.warnaar@utwente.nl>",
"keywords": "electromyography, EMG, respiratory, Python, surface EMG",
"author": null,
"author_email": null,
"download_url": null,
"platform": null,
"description": "<p align=\"center\">\n <img style=\"width: 35%; height: 35%\" src=\"https://github.com/resurfemg-org/ReSurfEMG/blob/main/Logo_rond_tekst.svg\">\n</p>\n\n[](https://doi.org/10.5281/zenodo.6811553)\n[](https://pypi.python.org/pypi/resurfemg/)\n[](https://github.com/resurfemg-org/ReSurfEMG/actions/workflows/on-commit.yml)\n[](https://github.com/resurfemg-org/ReSurfEMG/actions/workflows/on-tag.yml)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://bestpractices.coreinfrastructure.org/projects/6487)\n[](https://fair-software.eu)\n[](https://joss.theoj.org/papers/5f08d1f2bb717b7d05762296e37ded3d)\n\n**ReSurfEMG** is an open source collaborative python library for analysis\nof respiratory electromyography (EMG). On the same site as \nthe repository for this library we keep [related resources](https://github.com/ReSurfEMG?tab=repositories). \n\nReSurfEMG includes a [main code library](https://github.com/resurfemg-org/ReSurfEMG) where the user can access the code to change various filter and analysis settings directly and/or in our [researcher interface notebooks](https://github.com/resurfemg-org/ReSurfEMG/tree/main/notebooks/researcher_interface).\nIn addition, ReSurfEMG has a [dashboard interface](https://github.com/resurfemg-org/ReSurfEMG-dashboard) which contains default settings for preprocessing and analysis which can be changed through a graphical (no code) interface. We have some functionality available through a [command line interface](#command-line-interface) as well.\n\nThe library was initially built for surface EMG, however many functions will also work for\ninvasively measured respiratory EMG. This library supports the ongoing research at University of Twente on respiratory EMG.\n\n\n### Program files\n\nThe core functions of ReSurfEMG are in the folder [resurfemg](https://github.com/resurfemg-org/ReSurfEMG/tree/main/resurfemg):\n\n- **cli:** Scripts for the command line interface\n- **data_connector:** Converter functions for discovering, loading, simulating and handling data.\n- **helper_functions:** General functions to support the functions in this repository\n- **preprocessing:** Process the raw respiratory EMG signal\n - filtering: low-, high- and bandpass filters, notch filter, computer power loss\n - ecg-removal: gating and wavelet denoising\n - envelope: root-mean-square (RMS), average rectified (ARV)\n- **postprocessing:** Aspects of pre-processed the respiratory EMG data:\n - moving baselines\n - event detection: find pneumatic and EMG breaths, on- and offset detection\n - features: amplitude, area under the curve, slope, area under the baseline, respiratory rate\n - quality assessment: signal-to-noise ratio, end-expiratory occlussion manoeuvre quality, interpeak distance, area under the baseline, consecutive manoeuvres, bell-curve error, relative peak timing, relative area under the baseline, relative ETP\n\n\n### Folders and Notebooks\n\nOur [guide to notebooks](https://github.com/resurfemg-org/ReSurfEMG/blob/main/notebooks_guide.md) is under construction. To look around keep in mind the following distinction on folders:\n\ndev:\n- These notebooks are used in feature development and debugging by core members of the ReSurfEMG team. They can provide a basic example how to use some of the functionality.\n\nopen_work:\n- This folder contains experimental work by core members of the ReSurfEMG\n team that is not deployed yet.\n\nresearcher_interface:\n- These are a growing series of interactive notebooks that allow\n researchers to investigate questions about their own EMG data\n\n### Data sets\n\nThe notebooks are configured to run on various datasets. Contact\nDr. Eline Mos-Oppersma( \ud83d\udceb e.mos-oppersma@utwente.nl) to discuss any\nquestions on data configuration for your datasets.\n\nIf you want to use a standardized dataset for any purpose we recommend\nthe data in the [ReSurfEMG/test_data](https://github.com/resurfemg-org/ReSurfEMG/blob/main/test_data), which is also used in testing the ReSurfEMG functions. \nData there can be used with any respiratory EMG algorithms in any program. Thus that data can function as a benchmarking set to compare algorithms across different programs.\n\nAlternatively, the data in the ReSurfEMG/synthetic_data repository:\n\n[](https://zenodo.org/badge/latestdoi/635680008)\n\n\n### Configuring (to work with your data)\n\nIn order to preprocess and/or to train models the code needs to be\nable to locate the raw data you want it to find.\n\nThere are several ways to specify the location of the following\ndirectories:\n\n- **root_data:** Special directory. The rest of the directory layout can be derived from its location.\n- **preprocessed_data:** The directory that will be used by preprocessing\n code to output to.\n- **test_data:** The directory for running sanity tests.\n\nYou can store this information persistently in several locations.\n\n1. In the same directory where you run the script (or the notebook).\n e.g. `./config.json`.\n2. In home directory, e.g. `~/.resurfemg/config.json`.\n3. In global directory, e.g. `/etc/resurfemg/config.json`.\n\nHowever, we highly recommend using the home directory.\nThis file can have this or similar contents:\n```\n{\n \"root_data\": \"/mnt/data\",\n \"patient_data\": \"/mnt/patient_data\",\n \"simulated_data\": \"/mnt/simulated_data\",\n \"preprocessed_data\": \"/mnt/data/preprocessed\",\n \"output_data\": \"/mnt/data/output\",\n}\n```\nThe file is read as follows: if the files specifies `root_data`\ndirectory, then the missing entries are assumed to be relative to\nthe root. You do not need to specify all entries.\n\n### Test data\n\nTest data is provided in the repository in the test_data folder.\n\n### Supported Platforms\n\nReSurfEMG is a pure Python package. Below is the list of\nplatforms that should work. Other platforms may work, but have had less extensive testing.\nPlease note that where python.org Python stated as supported, it means\nthat versions 3.9 - 3.12 are supported.\n\n#### AMD64 (x86)\n\n| | Linux | Win | OSX |\n|:---------------------------:|:---------:|:---------:|:---------:|\n|  | Supported | Supported | Supported |\n|  | Discontinued | Discontinued | Discontinued |\n\n### Installation for all supported platforms\n\nInstallation with Anaconda/conda and/or mamba are the preffered methods.\nThey are covered in [the \"Getting Started\" section](#Getting-Started). \nIf you wish to install with pip:\n\n1. Create and activate a virtual environment (see developer setup section for more details) \n2. Install ResurfEMG package by running `pip install resurfemg`.\n\n\n## Getting Started\n### With the recommended Python venv setup\n\nHow to get the notebooks running? Assuming the raw data set and\nmetadata is available.\n\n### 0a. Create a virtual environment using Python\n\n #### On Linux/OSX:\n``` sh\npython3 -m venv .venv\n```\n\n This might **require** the python3-venv.\n \n #### On Windows:\n ``` sh\n python -m venv .venv\n ```\n\n### 0b. Activate the virtual environment and install ReSurfEMG\n\n #### On Linux/OSX:\n``` sh\nsource .venv/bin/activate\npip install resurfemg[dev]\n```\n \n #### On Windows:\n ``` sh\n .venv\\Scripts\\activate.bat\n pip install resurfemg[dev]\n ```\n\n### 1. Open a notebook\n Start a local Jupyter Notebook server by running the `jupyter notebook` \n command in your terminal. This opens a browser window where you can browse, \n open and run the notebooks. (We use [Jupyter notebooks](https://jupyter.org/try-jupyter/retro/notebooks/?path=notebooks/Intro.ipynb))\n The ReSurfEMG notebooks are located in the notebooks folder. Navigate there \n and open a notebook of interest. The [basic_emg_analysis](https://github.com/resurfemg-org/ReSurfEMG/blob/main/researcher_interface/basic_emg_analysis.ipynb) \n notebook can be used to understand how to use the package.\n\n\n## Advanced contributor's setup / \"Developer's setup\"\n\nWe distinguish between people who want to use this library in their own code \nand/or analysis, and people who also want to develop this library who we call \ndevelopers, be it as members of our team or independent contributors. People \nwho simply want to use our library need to install the packaged version from \none of the package indexes to which we publish released versions (eg. PyPI). \nThis section of the readme is for advanced developers who want to modify the \nlibrary code (and possibly contribute their changes back or eventually publish \nthier own modified fork). NB: You can accomplish modifications of the code, \nsubmit pull-requests (PRs) and soforth without a 'developer's setup' but we \nfeel this setup will make advanced contributions easier.\n\nWe have transitioned to a fully Python 3.9+ environment. \n(For older instructions with `venv` please see versions below 0.2.0, and\nadapt them if using Windows and/or a different Python version than\nPython.org Python. e.g. you may need to use `.venv\\Scripts\\activate.bat` in\nplace of `.venv/bin/activate`) \nThe instructions below are for our newer versions above 1.0.0. This will create \na distributable package from the source code, then install it in the currently\nactive environment. This will also install development tools we use\ns.a. `pytest` and `codestyle` and will also install tools we use for\nworking with the library, such as `jupyter`.\n\n### On Linux/OSX:\n``` sh\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e .[dev]\n``` \n \n### On Windows:\n``` sh\npython -m venv .venv\n.venv\\Scripts\\activate.bat\npip install -e .[dev]\n```\n\nThese installs differ in two ways from the regular install: 1) The `.[dev]` (as compared to `resurfemg[dev]`) \ninstalls the library as it currently is including all your local changes, \ninstead of pulling it from the PyPI repository. 2) The `-e` flag ensures an \neditable install, such that any changes to the library are automatically \napplied to your environment.\n\nNow you should have everything necessary to start working on the\nsource code.\n\n\n## Generating documentation\n\nOnline documentation can be found at https://resurfemg.github.io/ReSurfEMG/\nor on https://readthedocs.org/ by searching for ReSurfEMG. Up-to-date \ndocumentation can be generated in command-line as follows in terminal:\n\n### On Linux/OSX:\n``` sh\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e .[docs]\npython setup.py apidoc\npython setup.py build_sphinx\n``` \n \n### On Windows:\n``` sh\npython -m venv .venv\n.venv\\Scripts\\activate.bat\npip install -e .[docs]\npython setup.py apidoc\npython setup.py build_sphinx\n```\n\n\n## Automation\n\nThe project comes with several modifications to the typical default `setup.py`.\n\nThe project has a sub-project of a related dashboard. Dashboard is a GUI that\nexposes some of the project's functionality. In the past, we kept a a legacy \ndashboard in the same repository with ReSurfEMG code but we have deleted it. \nThe current version of the dashboard into it's own repository:\nhttps://github.com/resurfemg-org/ReSurfEMG-dashboard\n\n\n### New commands\n\n* `isort resurfemg --check --diff` checks that the imports are properly \n formatted and sorted.\n* `python setup.py apidoc` generates RST outlines necessary to generate\n documentation.\n\n### Testing\n\nThe project includes testing data. This test data is synthetic and generated by the ReSurfEMG `data_connector.synthetic_data` methods.\n\n### On Linux/OSX:\n``` sh\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e .[tests]\npytest\n``` \n \n### On Windows:\n``` sh\npython -m venv .venv\n.venv\\Scripts\\activate.bat\npip install -e .[tests]\npytest\n```\n\n\n## Command-Line Interface\n\nYou will be able to preprocess data using command-line interface. You can also,\nin some cases, create files in the correct format for our Dashboard in a per \nfolder batch process.\n\nYou can make synthetic data. To explore this start with\n\n `python -m resurfemg simulate_emg --help`\n\n `python -m resurfemg simulate_ventilator --help`\n\n\n\u2728Copyright 2022 Netherlands eScience Center and U. Twente\nLicensed under the Apache License, version 2.0. See LICENSE for details.\u2728\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A package for analysis of respiratory EMG data",
"version": "1.0.2",
"project_urls": {
"Changelog": "https://github.com/resurfemg-org/ReSurfEMG/blob/main/CHANGELOG.md",
"Documentation": "https://resurfemg.github.io/ReSurfEMG/",
"Homepage": "https://github.com/ReSurfEMG",
"Issues": "https://github.com/resurfemg-org/ReSurfEMG/issues",
"Repository": "https://github.com/resurfemg-org/ReSurfEMG"
},
"split_keywords": [
"electromyography",
" emg",
" respiratory",
" python",
" surface emg"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d6cda49ee0d2813809ae309984e0d985aa3dd0504fde11b32e694b6b368bc8a0",
"md5": "44b1f6d2984ce5c38f9ca2dc3b787b5b",
"sha256": "f399625b3837b6d9deead551a818db515e11244620c3ed1ee9e3225d072312a9"
},
"downloads": -1,
"filename": "resurfemg-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "44b1f6d2984ce5c38f9ca2dc3b787b5b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 74308,
"upload_time": "2024-12-12T11:07:21",
"upload_time_iso_8601": "2024-12-12T11:07:21.601346Z",
"url": "https://files.pythonhosted.org/packages/d6/cd/a49ee0d2813809ae309984e0d985aa3dd0504fde11b32e694b6b368bc8a0/resurfemg-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-12 11:07:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "resurfemg-org",
"github_project": "ReSurfEMG",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "resurfemg"
}
JSON
