Package: emgdecompy
EMGdecomPyA package for decomposing multi-channel intramuscular and surface EMG signals into individual motor unit activity based off the blind source algorithm described inNegro et al. (2016).Table of ContentsOverviewProject DirectoryProposal and Final ReportInstallationUsageContributingLicenseCreditsOverviewWhat's Been AccomplishedAn open-source Python package,EMGdecomPycontaining two elements, a blind source separation algorithm based on the work ofNegro et al. (2016)and a visualization element, has been created to decompose raw EMG signals into its constituent motor unit activity. Experimental durations of any length can be run usingEMGdecomPy.The blind source separation algorithm has been modified slightly fromNegro et al. (2016). The initialization process of the separation vectors has been changed so that instead of initializing every separation vector with the same time instance of highest activity in the pre-processed data, each subsequent vector is initialized with the next highest activity time instance in the pre-processed data.More customization of the decomposition process is also allowed through different arguments to thedecompositionfunction. For example, the separation vectors can be orthogonalized against each other using either the 'source deflation' process described inNegro et al. (2016)or the Gram-Schmidt method.We have not had the chance to thoroughly validate our algorithm but preliminary results look promising, as 3 out of 5 of the MUAP shapes identified byEMGdecomPywere also identified byHug et al. (2021)for theGastrocnemius lateralismuscle with 10% contraction intensity.  Refer to thedocumentationand thefinal reportfor more information.The visualization element allows the user to interactively visualize the results of the blind source separation algorithm. The user can visualize one motor unit at a time from the motor units that were extracted from the EMG data using the algorithm. The visualization includes four plots, the instantaneous firing rate vs time, the signal vs time, an overlayed version of both the previous plots, and the average motor unit action potential shapes per channel. For a better idea of the interactivity of the plot, refer to theEMGdecomPyworkflow notebook.What's Not WorkingCurrently, the blind source separation algorithm accepts multiple motor units of the same shape. Upon inspection, it can be seen that many of these motor units have the exact same firing times or are time lagged from each other. Solutions to these problems are still in development, and include adding an orthogonalization step to therefinementfunction to stop the refinement process from converging on previous motor units and not accepting motor units whose firing times are within a certain time frame as another motor unit.There is also a bug in the visualization component that does not allow the user to visualize the results of a decomposition if only one motor unit is accepted. This bug is due to how the peak shapes are created and a fix is currently in development.Future WorkFuture work includes fixing the aforementioned problems, increasing code efficiency, improving the accuracy of the algorithm using domain knowledge, and further quantitative/qualitative validation of the results of the algorithm using the data fromHug et al. (2021)and other EMG data sources.A further improvement to the algorithm would be a re-learning feature. The user would run the algorithm on a sample of the data, and then identify inaccurate firing times (false positives) based on physiological limits of motor unit firing rates. Then the algorithm would use this information to no longer make similar mistakes in the rest of the decomposition. Implementing this feature would be quite complex because it is algorithmically unclear how this would be done.One idea is to somehow change the initialization of the separation vectors so that they no longer identify the false firing times when applied to the pre-processed data. However, since the separation vector changes throughout the LCA and refinement processes, it would be hard to control the effect that this would have on the estimated firing times. Another approach would be to influence the KMeans algorithm so that the threshold for the small peaks cluster includes the false positive peaks, in the hopes that future peaks of similar size are also false positives. The downside to this approach would be that we may increase the number of incorrect identifications of large peaks as small peaks, which are discarded.An improvement to the visualization related to the above improvement would be the ability to remove peaks with a click of a button. This improvement is already in progress and if the re-learning feature is implemented then these two features can be connected.Project Directory.githubworkflowsContains file for automated testing and publishing of package.dataContains a "raw" subdirectory with the EMG data corresponding to theGastrocnemius lateralismuscle with 10% contraction intensity EMG data fromHug et al. (2021).In the future can contain subdirectories pertaining to results from the blind source separation algorithm.docsContains files related to the final report, the proposal, and theReadtheDocsdocumentation.notebooksContains a Jupyter notebook with the well-documented reproducible workflow that can be used to applyEMGdecomPyon EMG data and/or as a guide on how to use the package.srcContains the.pyscripts containingEMGdecomPysource code.testsContains the tests for the functions withinsrc.Proposal and Final ReportTo generate the proposal and final report locally, ensure that you have R version 4.1.2 or above installed, as well as the RStudio IDE. Then install the necessary dependencies with the following commands:Rscript -e 'install.packages("rmarkdown", repos="http://cran.us.r-project.org")'
Rscript -e 'install.packages("tinytex", repos="http://cran.us.r-project.org")'
Rscript -e 'tinytex::install_tinytex()'
Rscript -e 'install.packages("bookdown", repos="http://cran.us.r-project.org")'ProposalOur project proposal can be foundhere.To generate the proposal locally, run the following command from the root directory after cloningEMGdecomPy:Rscript -e "rmarkdown::render('docs/proposal/proposal.Rmd')"Alternatively, if the above doesn't work, install Docker. While Docker is running, run the following command from the root directory after cloningEMGdecomPy:docker run --platform linux/amd64 --rm -v /$(pwd):/home/emgdecompy danfke/pandoc-r-bookdown Rscript -e "rmarkdown::render('home/emgdecompy/docs/proposal/proposal.Rmd')"Final ReportOur final report can be foundhere.To generate the final report locally, run the following command from the root directory after cloningEMGdecomPy:Rscript -e "rmarkdown::render('docs/final-report/final-report.Rmd')"Alternatively, if the above doesn't work, install Docker. While Docker is running, run the following command from the root directory after cloningEMGdecomPy:docker run --platform linux/amd64 --rm -v /$(pwd):/home/emgdecompy danfke/pandoc-r-bookdown Rscript -e "rmarkdown::render('home/emgdecompy/docs/final-report/final-report.Rmd')"InstallationEMGdecomPyis compatible with Python versions 3.9 to 3.11.pipinstallemgdecompyUsageAfter installing emgdecompy, refer to theEMGdecomPyworkflow notebookfor an example on how to use the package, from loading in the data to visualizing the decomposition results. Clone and run the notebook locally to view and interact with the visualization.ContributingInterested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.LicenseEMGdecomPywas created byDaniel King,Jasmine Ortega,Rada Rudyak, andRowan Sivanandam. It is licensed under the terms of theGPLv3 license.CreditsEMGdecomPywas created withcookiecutterand thepy-pkgs-cookiecuttertemplate.The blind source separation algorithm in this package was based off ofNegro et al. (2016).The data used for validation was obtained fromHug et al. (2021).Guilherme Ricioliwas consulted for his work onsemg-decomposition.