Merge pull request #54 from GiacomoValliPhD/Towards_v0.1.0

Release 0.1.0-b.3

.gitignore

@@ -6,6 +6,6 @@ __pycache__*
 docs/.DS_Store
 dist/
 openhdemg.egg-info/
-
+openhdemg/.DS_Store
 prove.py
 prove_storage.py

CODE_OF_CONDUCT.md

@@ -2,17 +2,11 @@
 
 ## Our Pledge
 
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to make participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, sex characteristics, gender identity and expression,
-level of experience, education, socio-economic status, nationality, personal
-appearance, race, religion, or sexual identity and orientation.
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
 
 ## Our Standards
 
-Examples of behavior that contributes to creating a positive environment
-include:
+Examples of behavior that contributes to creating a positive environment include:
 
 * Using welcoming and inclusive language
 * Being respectful of differing viewpoints and experiences
@@ -22,55 +16,32 @@ include:
 
 Examples of unacceptable behavior by participants include:
 
-* The use of sexualized language or imagery and unwelcome sexual attention or
-  advances
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
 * Trolling, insulting/derogatory comments, and personal or political attacks
 * Public or private harassment
-* Publishing others' private information, such as a physical or electronic
-  address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
 
 ## Our Responsibilities
 
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
 
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
 
 ## Scope
 
-This Code of Conduct applies within all project spaces, and it also applies when
-an individual is representing the project or its community in public spaces.
-Examples of representing a project or community include using an official
-project e-mail address, posting via an official social media account, or acting
-as an appointed representative at an online or offline event. Representation of
-a project may be further defined and clarified by project maintainers.
+This Code of Conduct applies within all project spaces, and it also applies when an individual is representing the project or its community in public spaces. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at giacomo.valli@phd.unipd.it. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at openhdemg@gmail.com. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
 
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+This Code of Conduct is adapted from the Contributor Covenant homepage, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
 
 [homepage]: https://www.contributor-covenant.org
 
-For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq
+For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq

README.md

@@ -1,4 +1,15 @@
 # Welcome to openhdemg
+<p align="left">
+    <a href="https://pypi.python.org/pypi/openhdemg/" alt="openhdemg version" target="_blank">
+        <img alt="PyPI" src="https://img.shields.io/pypi/v/openhdemg?label=pip&logo=PyPI&logoColor=gold&color=blue"></a>
+    <a href="https://pypi.org/project/openhdemg" alt="Python version" target="_blank">
+        <img alt="PyPI" src="https://img.shields.io/pypi/pyversions/openhdemg?logo=Python&logoColor=gold&color=blue"></a>
+    <a href="https://www.youtube.com/@openhdemg" alt="YouTube" target="_blank">
+        <img src="https://img.shields.io/badge/youtube-Watch_videos-red.svg?color=blue&logoColor=gold&logo=youtube" /></a>
+    <a href="https://twitter.com/openhdemg" alt="Twitter" target="_blank">
+        <img src="https://img.shields.io/badge/twitter-Follow_us-red.svg?color=blue&logoColor=gold&logo=twitter" /></a>
+</p>
+
 <br/>
 
 <p align="center">
@@ -14,7 +25,7 @@
 *openhdemg* is an open-source framework written in Python 3 with many functionalities specifically designed for the analysis of High-Density
 Electromyography (HD-EMG) recordings. Some of its main features are listed below, but there is much more to discover! For a full list of available functions, please refer to the **API reference** section at [www.giacomovalli.com/openhdemg](https://www.giacomovalli.com/openhdemg/).
 
-1. **Load** decomposed HD-EMG files from various sources, such as .mat and .csv files. This allows to interface *openhdemg* with the commonly used softwares like OTBioLab+ or DEMUSE and potentially with any other software.
+1. **Load** decomposed HD-EMG files from various sources, such as .mat and .csv files. This allows to interface *openhdemg* with the commonly used softwares like OTBioLab+, DEMUSE, Delsys NeuroMap and potentially with any other software.
 2. **Visualise** your EMG or force/reference signal, as well as the motor units' firing times and their action potentials shape.
 3. **Edit** your file changing the reference signal offset, filtering noise, calculating differential derivations and removing unwanted motor units.
 4. **Analyse** motor units' recruitment/derecruitment thresholds, discharge rate, conduction velocity, action potentials amplitude and more...

docs/about-us.md

@@ -50,11 +50,11 @@ graph TB;
 
 Giacomo Valli:
 
-- giacomo.valli@phd.unipd.it
+- giacomo.valli@unibs.it
 
-- The creator of the project and the developer of the library.
+- The creator/maintainer of the project and developer of the library.
 
-- Giacomo Valli obtained a master degree in Sports Science and a research fellowship in molecular biology of exercise at the University of Urbino (IT). He is currently a PhD student at the University of Padova (IT) in neuromuscular physiology. He is investigating the electrophysiological modifications happening during disuse, disease and aging and linking this information to the molecular alterations of the muscle.
+- Giacomo Valli obtained a master degree in Sports Science and a research fellowship in molecular biology of exercise. He completed the PhD in neuromuscular physiology at the University of Padova (IT) and he is currently a PostDoc fellow at the University of Brescia (IT). His main focus is on investigating electrophysiological modifications that occur during periods of disuse, disease, and aging, and in linking this information to the molecular alterations of the muscle.
 
 Paul Ritsche:
 
@@ -64,6 +64,15 @@ Paul Ritsche:
 
 - Paul Ritsche obtained a master degree in Sports Science at the University of Basel (CH). He is currently a research associate at the University of Basel (CH) focusing on muscle ultrasonography. He is investigating automatic ultrasonography image analysis methods to evaluate muscle morphological as well architectural parameters.
 
+
+Drew-James Beauchamp:
+
+- jbeaucha@andrew.cmu.edu
+
+- Developer of the library.
+
+- James (Drew) Beauchamp completed his doctoral studies in Engineering at Northwestern University, where his work focused on characterizing the deficits in human motor function that are introduced by neuromodulatory inputs to spinal motoneurons. He is interested in providing creative ways to decouple the structure of descending motor commands and is currently a post-doctoral researcher at Carnegie Mellon University. 
+
 ## Meet the contributors
 
 Francesco Negro:
@@ -74,6 +83,14 @@ Francesco Negro:
 
 - Francesco Negro is a Full Professor at the Department of Clinical and Experimental Sciences at Universita’ degli Studi di Brescia (IT). His research interests include applied physiology of the human motor system, signal processing of intramuscular and surface electromyography, and modeling of spinal neural networks.
 
+Gregory EP Pearcey:
+
+- gpearcey@northwestern.edu
+
+- Contribution:   :fontawesome-solid-brain: Knowledge sharing   :fontawesome-solid-file-code: Code sharing   :octicons-codescan-checkmark-24: Accuracy check
+
+- Gregory Pearcey is an Assistant Professor in the School of Human Kinetics and Recreation at Memorial University of Newfoundland and holds a cross-appointment in BioMedical Sciences (Faculty of Medicine, Memorial), as well as an Adjunct Faculty position in Physical Therapy & Human Movement Sciences (Northwestern University). He is interested in decoding the neural control of human movement via recording myoelectric signals from the surface and within human muscle with a goal of understanding and enhancing neuroplasticity and the recovery of motor function after neurological impairment.
+
 Andrea Casolo:
 
 - andrea.casolo@unipd.it
@@ -89,4 +106,3 @@ Giuseppe De Vito:
 - Contribution:   :fontawesome-solid-brain: Knowledge sharing
 
 - Giuseppe De Vito is a full Professor of Human Physiology in the Department of Biomedical Sciences at University of Padova (IT). He was, from 2007 until 2019, Professor and Dean in the School of Public Health, Physiotherapy & Sports Science at University College Dublin (IE) (Head of School between 2014 and 2019). Giuseppe does research in Human and Exercise Physiology.
-

docs/api_analysis.md

@@ -1,7 +1,6 @@
 Description
 -----------
-This module contains all the functions used to analyse the MUs properties when
-not involving the MUs action potential shape.
+This module contains all the functions used to analyse the MUs properties when not involving the MUs action potential shape.
 
 <br/>
 

docs/api_compatibility.md

@@ -0,0 +1,14 @@
+Description
+-----------
+This module contains the functions used to ensure the compatibility of file formats saved with previous versions of *openhdemg* with the most recent versions of the library.
+
+<br/>
+
+::: openhdemg.compatibility.conversions.convert_json_output
+    options:
+        show_root_full_path: False
+        show_root_heading: True
+        merge_init_into_class: True 
+        show_if_no_docstring: False 
+
+<br/>

docs/api_muap.md

@@ -19,6 +19,13 @@ This module contains functions to produce and analyse MUs anction potentials
 
 <br/>
 
+::: openhdemg.library.muap.extract_delsys_muaps
+    options:
+        show_root_full_path: False
+        show_root_heading: True
+
+<br/>
+
 ::: openhdemg.library.muap.sta
     options:
         show_root_full_path: False

docs/api_openfiles.md

@@ -1,6 +1,6 @@
 Description
 -----------
-This module contains all the functions that are necessary to open or save MATLAB (.mat), JSON (.json) or custom (.csv) files. .mat files are currently used to store data from the DEMUSE and the OTBiolab+ software, while .csv files are used to store custom data. Instead, .json files are used to save and load files from this library.<br>
+This module contains all the functions that are necessary to open or save MATLAB (.mat), text (.txt), JSON (.json) or custom (.csv) files. MATLAB files are used to store data from the DEMUSE, OTBiolab+ and Delsys software while JSON files are used to save and load files from this library.<br>
 The choice of saving files in the open standard JSON file format was preferred over the MATLAB file format since it has a better integration with Python and has a very high cross-platform compatibility.
 
 Function's scope
@@ -9,25 +9,27 @@ Function's scope
     Used to load the sample file provided with the library.
 - **emg_from_otb** and **emg_from_demuse**:<br>
     Used to load .mat files coming from the DEMUSE or the OTBiolab+ software. Demuse has a fixed file structure while the OTB file, in order to be compatible with this library should be exported with a strict structure as described in the function emg_from_otb. In both cases, the input file is a .mat file.
+- **emg_from_delsys**:<br>
+    Used to load a combination of .mat and .txt files exported by the Delsys Neuromap and Neuromap explorer software containing the raw EMG signal and the decomposition outcome.
 - **emg_from_customcsv**:<br>
     Used to load custom file formats contained in .csv files.
-- **refsig_from_otb** and **refsig_from_customcsv**:<br>
-    Used to load files from the OTBiolab+ software or from a custom .csv file that contain only the REF_SIGNAL.
+- **refsig_from_otb**, **refsig_from_delsys** and **refsig_from_customcsv**:<br>
+    Used to load files from the OTBiolab+ (.mat) and the Delsys Neuromap software (.mat) or from a custom .csv file that contain only the reference signal.
 - **save_json_emgfile**, **emg_from_json**:<br>
     Used to save the working file to a .json file or to load the .json file.
 - **askopenfile**, **asksavefile**:<br>
     A quick GUI implementation that allows users to select the file to open or save.
 
 Notes
 -----
-Once opened, the file is returned as a dictionary with keys:<br>
+Once opened, the file is returned as a dictionary with key-value pairs:<br>
 
-"SOURCE" : source of the file (i.e., "CUSTOMCSV", "DEMUSE", "OTB")<br>
+"SOURCE" : source of the file (i.e., "CUSTOMCSV", "DEMUSE", "OTB", "DELSYS")<br>
 "FILENAME" : the name of the opened file<br>
 "RAW_SIGNAL" : the raw EMG signal<br>
 "REF_SIGNAL" : the reference signal<br>
 "ACCURACY" : accuracy score (depending on source file type)<br>
-"IPTS" : pulse train (decomposed source)<br>
+"IPTS" : pulse train (decomposed source, depending on source file type)<br>
 "MUPULSES" : instants of firing<br>
 "FSAMP" : sampling frequency<br>
 "IED" : interelectrode distance<br>
@@ -38,7 +40,7 @@ Once opened, the file is returned as a dictionary with keys:<br>
 
 The only exception is when files are loaded with just the reference signal:
 
-"SOURCE" : source of the file (i.e., "CUSTOMCSV_REFSIG", "OTB_REFSIG")<br>
+"SOURCE" : source of the file (i.e., "CUSTOMCSV_REFSIG", "OTB_REFSIG", "DELSYS_REFSIG")<br>
 "FILENAME" : the name of the opened file<br>
 "FSAMP" : sampling frequency<br>
 "REF_SIGNAL" : the reference signal<br>
@@ -66,14 +68,14 @@ Furthermore, all the users are encouraged to read the dedicated tutorial [Struct
 
 <br/>
 
-::: openhdemg.library.openfiles.refsig_from_otb
+::: openhdemg.library.openfiles.emg_from_demuse
     options:
         show_root_full_path: False
         show_root_heading: True
 
 <br/>
 
-::: openhdemg.library.openfiles.emg_from_demuse
+::: openhdemg.library.openfiles.emg_from_delsys
     options:
         show_root_full_path: False
         show_root_heading: True
@@ -87,6 +89,20 @@ Furthermore, all the users are encouraged to read the dedicated tutorial [Struct
 
 <br/>
 
+::: openhdemg.library.openfiles.refsig_from_otb
+    options:
+        show_root_full_path: False
+        show_root_heading: True
+
+<br/>
+
+::: openhdemg.library.openfiles.refsig_from_delsys
+    options:
+        show_root_full_path: False
+        show_root_heading: True
+
+<br/>
+
 ::: openhdemg.library.openfiles.refsig_from_customcsv
     options:
         show_root_full_path: False

docs/cite-us.md

@@ -1,3 +1,5 @@
-If you use *openhdemg* for your reaserch, please cite the project as:
+If you use *openhdemg* for your reaserch, please cite our [tutorial article](/isek_jek_tutorials#jek-tutorial-article). Any citation will help us to continue our work.
 
-*We are working to publish soon..*
+Cite us as:
+
+*Valli G, Ritsche P, Casolo A, Negro F, De Vito G.* **Tutorial: analysis of central and peripheral motor unit properties from decomposed High-Density surface EMG signals with openhdemg.** Journal of Electromyography and Kinesiology, 2023, 102850, ISSN 1050-6411, [https://doi.org/10.1016/j.jelekin.2023.102850](https://doi.org/10.1016/j.jelekin.2023.102850){:target="_blank"}.

docs/gui_advanced.md

@@ -2,6 +2,8 @@
 
 This is the toturial for the `Advanced Tools` in the *openhdemg* GUI. Great that you made it this far! In the next few sections we will take a look at the more advanced functions implemented in the GUI. But first of all, you need to click the `Advanced Tools`button in the main window of the GUI to get to the respective adavanced analysis. The `Advanced Tools Window` will open.
 
+Please note, the `Advanced Tools` might not be available for all the files, as some of them might not have a sufficient number of electrodes to directly perform the advanced analyses. If you want to use the advanced tools anyway, you can still do so from the library.
+
 ![advanced_analysis](md_graphics/gui/advanced_analysis_window.png)
 
 So far, we have included three advanced analyses in the *openhdemg* GUI.

docs/gui_basics.md

@@ -29,7 +29,9 @@ To remove MUs included in your analysis file, you can click the `Remove MUs` but
     ```
     will result in the second MU to be deleted (Python is base 0).
 
-4. Click the `Remove MU` button to remove the MU. 
+4. Click the `Remove MU` button to remove the MU.
+
+Alternatively, you can click the `Remove empty MUs` button to delete all the MUs without discharge times. These can be present in the emgfile as the result of decomposed duplicates that have not been fully removed.
 
 ## Reference Signal Editing
 The *openhdemg* GUI also allows you to edit and filter reference signals corresponding to your analysis file (this can be either a file containing both the MUs and the reference signal or a file containing only the reference signal).