Package for decomposing EMG signals into motor unit firings, as used in Formento et al 2021.

Last update: Nov 01, 2022

Related tags

Overview

EMGDecomp

Package for decomposing EMG signals into motor unit firings, created for Formento et al 2021. Based heavily on Negro et al, 2016. Supports GPU via CUDA and distributed computation via Dask.

Installation

pip install emgdecomp

For those that want to either use Dask and/or CUDA, you can alternatively run:

pip install emgdecomp[dask]
pip install emgdecomp[cuda]

Usage

Basic

# data should be a numpy array of n_channels x n_samples
sampling_rate, data = fetch_data(...)

decomp = EmgDecomposition(
  params=EmgDecompositionParams(
    sampling_rate=sampling_rate
  ))

firings = decomp.decompose(data)
print(firings)

The resulting firings object is a NumPy structured array containing the columns source_idx, discharge_samples, and discharge_seconds. source_idx is a 0-indexed ID for each "source" learned from the data; each source is a putative motor unit. discharge_samples indicates the sample at which the source was detected as "firing"; note that the algorithm can only detect sources up to a delay. discharge_seconds is the conversion of discharge_samples into seconds via the passed-in sampling rate.

As a structured NumPy array, the resulting firings object is suitable for conversion into a Pandas DataFrame:

import pandas as pd
print(pd.DataFrame(firings))

And the "sources" (i.e. components corresponding to motor units) can be interrogated as needed via the decomp.model property:

model = decomp.model
print(model.components)

Advanced

Given an already-fit EmgDecomposition object, you can then decompose a new batch of EMG data with its existing sources via transform:

# Assumes decomp is already fit
new_data = fetch_more_data(...)
new_firings = decomp.transform(new_data)
print(new_firings)

Alternatively, you can add new sources (i.e. new putative motor units) while retaining the existing sources with decompose_batch:

# Assumes decomp is already fit

more_data = fetch_even_more_data(...)
# Firings corresponding to sources that were both existing and newly added
firings2 = decomp.decompose_batch(more_data)
# Should have at least as many components as before decompose_batch()
print(decomp.model.components)

Finally, basic plotting capabilities are included as well:

from emgdecomp.plots import plot_firings, plot_muaps
plot_muaps(decomp, data, firings)
plot_firings(decomp, data, firings)

File I/O

The EmgDecomposition class is equipped with load and save methods that can save/load parameters to disk as needed; for example:

with open('/path/to/decomp.pkl', 'wb') as f:
  decomp.save(f)

with open('/path/to/decomp.pkl', 'rb') as f:
  decomp_reloaded = EmgDecomposition.load(f)

Dask and/or CUDA

Both Dask and CUDA are supported within EmgDecomposition for support for distributed computation across workers and/or use of GPU acceleration. Each are controlled via the use_dask and use_cuda boolean flags in the EmgDecomposition constructor.

Parameter Tuning

See the list of parameters in EmgDecompositionParameters. The defaults on master are set as they were used for Formento et. al, 2021 and should be reasonable defaults for others.

Documentation

See documentation on classes EmgDecomposition and EmgDecompositionParameters for more details.

Acknowledgements

If you enjoy this package and use it for your research, you can:

cite the Journal of Neural Engineering paper, Formento et. al 2021, for which this package was developed: TODO
cite this github repo using its DOI: 10.5281/zenodo.5641426
star this repo using the top-right star button.

Contributing / Questions

Feel free to open issues in this project if there are questions or feature requests. Pull requests for feature requests are very much encouraged, but feel free to create an issue first before implementation to ensure the desired change sounds appropriate.

Useful tool for inserting DataFrames into the Excel sheet.

PyCellFrame Insert Pandas DataFrames into the Excel sheet with a bunch of conditions Install pip install pycellframe Usage Examples Let's suppose that

1 Feb 16, 2022

Import, connect and transform data into Excel

xlwings_query Import, connect and transform data into Excel. Description The concept is to apply data transformations to a main query object. When the

1 Jan 19, 2022

Used for data processing in machine learning, and help us to construct ML model more easily from scratch

Used for data processing in machine learning, and help us to construct ML model more easily from scratch. Can be used in linear model, logistic regression model, and decision tree.

0 Jul 5, 2022

A Python package for Bayesian forecasting with object-oriented design and probabilistic models under the hood.

Disclaimer This project is stable and being incubated for long-term support. It may contain new experimental code, for which APIs are subject to chang

1.6k Dec 29, 2022

Statistical package in Python based on Pandas

Pingouin is an open-source statistical package written in Python 3 and based mostly on Pandas and NumPy. Some of its main features are listed below. F

1.2k Dec 31, 2022

A Python package for the mathematical modeling of infectious diseases via compartmental models

A Python package for the mathematical modeling of infectious diseases via compartmental models. Originally designed for epidemiologists, epispot can be adapted for almost any type of modeling scenario.

12 Dec 28, 2022

GWpy is a collaboration-driven Python package providing tools for studying data from ground-based gravitational-wave detectors

GWpy is a collaboration-driven Python package providing tools for studying data from ground-based gravitational-wave detectors. GWpy provides a user-f

342 Jan 7, 2023

A powerful data analysis package based on mathematical step functions. Strongly aligned with pandas.

The leading use-case for the staircase package is for the creation and analysis of step functions. Pretty exciting huh. But don't hit the close button

48 Dec 21, 2022

Python Package for DataHerb: create, search, and load datasets.

The Python Package for DataHerb A DataHerb Core Service to Create and Load Datasets.

4 Feb 11, 2022

Comments

Expose functions for validation

From https://github.com/carmenalab/emgdecomp/issues/3:

Another question is that could you please provide some interface like '_assert_decomp_successful' at https://github.com/carmenalab/emgdecomp/blob/master/emgdecomp/tests/test_decomposition.py#L140 for validation?

cc @shihan-ma

opened by pbotros 1
Server restart error

Hi, Thanks for your repository!

I used the scripts in the readme and tried to decompose a 10-s simulated signal (64 channels * 20480 samples). It works at most times, producing around 10 MUs against 18 real ones. However, sometimes our server restarted after running the scripts three or four times. We found that the program stuck at https://github.com/carmenalab/emgdecomp/blob/master/emgdecomp/decomposition.py#L405. After converting 'whitening_matrix' and 'normalized_data' to np.float32, the error decreases but still happens sometimes. Could you please give me some advice on the reason that induced the restart of the server? The memory seems okay and we did not use CUDA at this point.

Another question is that could you please provide some interface like '_assert_decomp_successful' at https://github.com/carmenalab/emgdecomp/blob/master/emgdecomp/tests/test_decomposition.py#L140 for validation?

Thanks!

opened by shihan-ma 3

Releases(v0.1.0)

v0.1.0(Nov 3, 2021)

v0.1.0: initial release as used for Formento et. al, 2021.
Source code(tar.gz)
Source code(zip)

Package for decomposing EMG signals into motor unit firings, as used in Formento et al 2021.

Related tags

Overview

EMGDecomp

Installation

Usage

Basic

Advanced

File I/O

Dask and/or CUDA

Parameter Tuning

Documentation

Acknowledgements

Contributing / Questions

You might also like...

Useful tool for inserting DataFrames into the Excel sheet.

Import, connect and transform data into Excel

Used for data processing in machine learning, and help us to construct ML model more easily from scratch

A Python package for Bayesian forecasting with object-oriented design and probabilistic models under the hood.

Statistical package in Python based on Pandas

A Python package for the mathematical modeling of infectious diseases via compartmental models

GWpy is a collaboration-driven Python package providing tools for studying data from ground-based gravitational-wave detectors

A powerful data analysis package based on mathematical step functions. Strongly aligned with pandas.

Python Package for DataHerb: create, search, and load datasets.

Comments

Expose functions for validation

Server restart error

Releases(v0.1.0)

v0.1.0(Nov 3, 2021)

Owner

Integrate bus data from a variety of sources (batch processing and real time processing).

Processo de ETL (extração, transformação, carregamento) realizado pela equipe no projeto final do curso da Soul Code Academy.

MotorcycleParts DataAnalysis python

This creates a ohlc timeseries from downloaded CSV files from NSE India website and makes a SQLite database for your research.

TextDescriptives - A Python library for calculating a large variety of statistics from text

Data processing with Pandas.

This repo contains a simple but effective tool made using python which can be used for quality control in statistical approach.

A powerful data analysis package based on mathematical step functions. Strongly aligned with pandas.

General Assembly's 2015 Data Science course in Washington, DC

Sensitivity Analysis Library in Python (Numpy). Contains Sobol, Morris, Fractional Factorial and FAST methods.

Demonstrate the breadth and depth of your data science skills by earning all of the Databricks Data Scientist credentials

A Streamlit web-app for a data-science project that aims to evaluate if the answer to a question is helpful.

An interactive grid for sorting, filtering, and editing DataFrames in Jupyter notebooks

MDAnalysis is a Python library to analyze molecular dynamics simulations.

Python Practicum - prepare for your Data Science interview or get a refresher.

Utilize data analytics skills to solve real-world business problems using Humana’s big data

Intake is a lightweight package for finding, investigating, loading and disseminating data.

Churn prediction with PySpark

Validation and inference over LinkML instance data using souffle

PyPSA: Python for Power System Analysis