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

SNV calling pipeline developed explicitly to process individual or trio vcf files obtained from Illumina based pipeline (grch37/grch38).

Sentiment analysis on streaming twitter data using Spark Structured Streaming & Python

A collection of robust and fast processing tools for parsing and analyzing web archive data.

Stochastic Gradient Trees implementation in Python

Time ranges with python

Visions provides an extensible suite of tools to support common data analysis operations

A set of functions and analysis classes for solvation structure analysis

Snakemake workflow for converting FASTQ files to self-contained CRAM files with maximum lossless compression.

Shot notebooks resuming the main functions of GeoPandas

Amundsen is a metadata driven application for improving the productivity of data analysts, data scientists and engineers when interacting with data.

NumPy aware dynamic Python compiler using LLVM

Uses MIT/MEDSL, New York Times, and US Census datasources to analyze per-county COVID-19 deaths.

Data cleaning tools for Business analysis

Statistical & Probabilistic Analysis of Store Sales, University Survey, & Manufacturing data

Data Analysis for First Year Laboratory at Imperial College, London.

simple way to build the declarative and destributed data pipelines with python

BinTuner is a cost-efficient auto-tuning framework, which can deliver a near-optimal binary code that reveals much more differences than -Ox settings.

Using approximate bayesian posteriors in deep nets for active learning

Full automated data pipeline using docker images

PostQF is a user-friendly Postfix queue data filter which operates on data produced by postqueue -j.