Merge pull request #51 from GiacomoValliPhD/Towards_v0.1.0

Towards v0.1.0

.gitignore

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

docs/about-us.md

@@ -72,7 +72,7 @@ Francesco Negro:
 
 - Contribution:   :fontawesome-solid-brain: Knowledge sharing   :fontawesome-solid-file-code: Code sharing   :octicons-codescan-checkmark-24: Accuracy check
 
-- Prof. 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.
+- 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.
 
 Andrea Casolo:
 
@@ -81,3 +81,12 @@ Andrea Casolo:
 - Contribution:   :fontawesome-solid-brain: Knowledge sharing   :octicons-codescan-checkmark-24: Accuracy check
 
 - Andrea Casolo is an Assistant Professor at the Department of Biomedical Sciences, University of Padova (IT). He obtained a MSc in Health and Physical Activity (2016) and a PhD in Human Movement and Sport Sciences (2020) from the University of Rome "Foro Italico". His research interests focus on the neural control of movement and the study of neuromuscular plasticity to physical exercise investigated with high-density surface electromyography.
+
+Giuseppe De Vito:
+
+- giuseppe.devito@unipd.it
+
+- 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_openfiles.md

@@ -1,58 +1,48 @@
 Description
 -----------
-This module contains all the functions that are necessary to open or save
-MATLAB (.mat), JSON (.json) or custom (.csv) files.<br>
-MATLAB files are used to store data from the DEMUSE and the OTBiolab+
-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.
+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>
+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
 ----------------
 - **emg_from_samplefile**:<br>
     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.
-- **refsig_from_otb**:<br>
-    Used to load files from the OTBiolab+ software that contain only
-    the REF_SIGNAL.
+    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_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.
 - **save_json_emgfile**, **emg_from_json**:<br>
-    Used to save the working file to a .json file or to load the .json
-    file.
+    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.
+    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>
 
-"SOURCE" : source of the file (i.e., "CUSTOM", "DEMUSE", "OTB")<br>
+"SOURCE" : source of the file (i.e., "CUSTOMCSV", "DEMUSE", "OTB")<br>
+"FILENAME" : the name of the opened file<br>
 "RAW_SIGNAL" : the raw EMG signal<br>
 "REF_SIGNAL" : the reference signal<br>
-"PNR" : pulse to noise ratio<br>
-"SIL" : silouette score<br>
+"ACCURACY" : accuracy score (depending on source file type)<br>
 "IPTS" : pulse train (decomposed source)<br>
 "MUPULSES" : instants of firing<br>
 "FSAMP" : sampling frequency<br>
 "IED" : interelectrode distance<br>
 "EMG_LENGTH" : length of the emg file (in samples)<br>
 "NUMBER_OF_MUS" : total number of MUs<br>
 "BINARY_MUS_FIRING" : binary representation of MUs firings<br>
+"EXTRAS" : additional custom values<br>
 
-The only exception is when OTB files are loaded with just the reference signal:
+The only exception is when files are loaded with just the reference signal:
 
-"SOURCE": source of the file (i.e., "OTB_REFSIG")<br>
-"FSAMP": sampling frequency<br>
-"REF_SIGNAL": the reference signal<br>
+"SOURCE" : source of the file (i.e., "CUSTOMCSV_REFSIG", "OTB_REFSIG")<br>
+"FILENAME" : the name of the opened file<br>
+"FSAMP" : sampling frequency<br>
+"REF_SIGNAL" : the reference signal<br>
+"EXTRAS" : additional custom values<br>
 
 Additional informations can be found in the
 [info module](api_info.md#openhdemg.library.info.info.data) and in the
@@ -97,6 +87,13 @@ Furthermore, all the users are encouraged to read the dedicated tutorial [Struct
 
 <br/>
 
+::: openhdemg.library.openfiles.refsig_from_customcsv
+    options:
+        show_root_full_path: False
+        show_root_heading: True
+
+<br/>
+
 ::: openhdemg.library.openfiles.save_json_emgfile
     options:
         show_root_full_path: False

docs/api_plotemg.md

@@ -1,7 +1,6 @@
 Description
 -----------
-This module contains all the functions used to visualise the emg file,
-the MUs properties or to save figures.
+This module contains all the functions used to visualise the content of the imported EMG file, the MUs properties or to save figures.
 
 <br/>
 

docs/api_tools.md

@@ -21,6 +21,13 @@ shortcuts necessary to operate with the HD-EMG recordings.
 
 <br/>
 
+::: openhdemg.library.tools.mupulses_from_binary
+    options:
+        show_root_full_path: False
+        show_root_heading: True
+
+<br/>
+
 ::: openhdemg.library.tools.resize_emgfile
     options:
         show_root_full_path: False
@@ -42,6 +49,13 @@ shortcuts necessary to operate with the HD-EMG recordings.
 
 <br/>
 
+::: openhdemg.library.tools.delete_empty_mus
+    options:
+        show_root_full_path: False
+        show_root_heading: True
+
+<br/>
+
 ::: openhdemg.library.tools.sort_mus
     options:
         show_root_full_path: False

docs/gui_advanced.md

@@ -8,23 +8,24 @@ So far, we have included three advanced analyses in the *openhdemg* GUI.
 
 - `Motor Unit Tracking`
 - `Duplicate Removal`
-- `Conduction Velocity Calculation`
+- `Conduction Velocity Estimation`
 
 For all of those, the specification of a `Matrix Orientation` and a `Matrix Code` is required. The `Matrix Orientaion` must match the one of your matrix during acquisition. You can find a reference image for the `Orientation` at the bottom in the right side of the `Plot Window` when using the `Plot EMG`function. The `Matrix Orientation` can be either **0** or **180** and must be chosen from the dropdown list.
+
 The `Matrix Code` must be specified according to the one you used during acquisition. So far, the codes
 
 - `GR08MM1305`
 - `GR04MM1305`
 - `GR10MM0808`
 - `None`
 
-are implemented. You must choose one from the respective dropdown list.
-In case you selected `None`, the entrybox `Rows, Columns` will appear. Please specify the number of rows and columns of your used matrix since you now bypass included matrix codes. In example, specifying
+are implemented. You must choose one from the respective dropdown list. In case you selected `None`, the entrybox `Rows, Columns` will appear. Please specify the number of rows and columns of your used matrix since you now bypass included matrix codes. `Orientation` is ignored when `Matrix Code` is `None`. In example, specifying
 
 ```Python
 Rows, Columns: 13, 5
 ```
 means that your File has 65 channels.
+
 Once you specified these parameter, you can click the `Advaned Analysis` button to start your analysis.
 
 -----------------------------------------
@@ -39,9 +40,9 @@ When you want to track MUs across two different files, you need to select the `M
     - `OTB` (.mat file exportable by OTBiolab+)
     - `DEMUSE` (.mat file used in DEMUSE)
     - `OPENHDEMG` (emgfile or reference signal stored in .json format)
-    - `CUSTOM` (custom data from a .csv file)
+    - `CUSTOMCSV` (custom data from a .csv file)
 
-    Each filetype corresponds to a distinct datatype that should match the file you want to analyse. So, select the **Type of file** corresponding to the type of your file. In case you selected `OTB` specify the `extension factor` in the dropdown.
+    Each filetype corresponds to a distinct datatype that should match the file you want to analyse. So, select the **Type of file** corresponding to the type of your file. In case you selected `OTB`, specify the `extension factor` in the dropdown.
 
 2. Load the files according to specified `Type of file`using the `Load File 1` and `Load File 2` buttons.
 
@@ -65,8 +66,7 @@ When you want to remove MUs duplicates across different files, you need to selec
 1. You should specify How to remove the duplicated MUs in the `Which` dropdown. You can choose between
 
     - munumber: Duplicated MUs are removed from the file with more MUs.
-    - PNR: The MU with the lowest PNR is removed.
-    - SIL: The MU with the lowest SIL is removed.
+    - accuracy: The MU with the lowest accuracy score is removed.
 
 2. By clicking the `Remove Duplicates` button, you start the removal process.
 

docs/gui_basics.md

@@ -181,6 +181,7 @@ Subsequently to specifying the MVC, you can calculate a number of basic MUs prop
 
 - The absolute/relative recruitment/derecruitment thresholds
 - The discharge rate at recruitment, derecruitment, during the steady-state phase and during the entire contraction
+- The individual and average accuracy
 - The coefficient of variation of interspike interval
 - The coefficient of variation of force signal
 
@@ -237,7 +238,7 @@ These three setting options are universally used in all plots. There are two mor
     ```
     means that your File has 65 channels.
 
-2. You need to specify the `Orientation` in row two and column four in the left side of the `Plot Window`. The `Orientaion` must match the one of your matrix during acquisition. You can find a reference image for the `Orientation` at the bottom in the right side of the `Plot Window`.
+2. You need to specify the `Orientation` in row two and column four in the left side of the `Plot Window`. The `Orientaion` must match the one of your matrix during acquisition. You can find a reference image for the `Orientation` at the bottom in the right side of the `Plot Window`. `Orientation` is ignored when `Matrix Code` is `None`.
 
 ### Plot Raw EMG Signal
 1. Click the `Plot EMGsig` button in row four and column one in the left side of the `Plot Window`, to plot the raw emg signal of your analysis file. 

docs/gui_intro.md

@@ -1,6 +1,7 @@
 # Graphical Interface
 
 Welcome, to the *openhdemg* Graphical User Interface (GUI) introduction! 
+
 The *openhdemg* GUI incorporates all relevant high-level functions of the *openhdemg* library. The GUI allows you to successfully perform High-Density Electromyography (HD-EMG) data anlysis **without any programming skills required**. Moreover, there is no downside to using the GUI even if you are an experienced programmer.
 
 The GUI can be simply accessed from the command line with:
@@ -27,9 +28,10 @@ This is your starting point for every analysis. On the left hand side you can fi
     - `DEMUSE` (.mat file used in DEMUSE)
     - `OTB_REFSIG` (Reference signal in the .mat file exportable by OTBiolab+)
     - `OPENHDEMG` (emgfile or reference signal stored in .json format)
-    - `CUSTOM` (custom data from a .csv file)
+    - `CUSTOMCSV` (custom data from a .csv file)
+    - `CUSTOMCSV_REFSIG` (Reference signal in a custom .csv file)
 
-    Each filetype corresponds to a distinct datatype that should match the file you want to analyse. So, select the `Type of file` corresponding to the type of your file. 
+    Each filetype corresponds to a distinct datatype that should match the file you want to analyse. So, select the `Type of file` corresponding to the type of your file. In case you selected `OTB`, specify the `extension factor` in the dropdown.
 
 2. To actually load the file, click the **Load File** button and select the file you want to analyse. In case of occurence, follow the error messages and repeat this and the previos step.
 
@@ -38,6 +40,7 @@ This is your starting point for every analysis. On the left hand side you can fi
 ## Viewing an analysis file
 
 It doesn't get any simpler than this! 
+
 Once a file is successfully loaded as described above, you can click the `View MUs` button to plot/view your file. In the middle section of the GUI, a plot containing your data should appear.
 
 ----------------------------------------

docs/quick-start.md

@@ -193,9 +193,9 @@ There might be cases in which we need to remove one or more MUs from our *emgfil
 
 From the visual inspection of our plots, we can see that the firings pattern of MU number 2 (remember, Python is in base 0!!!) is not really regular. We might therefore have doubts about its quality.
 
-A way to assess the quality of the MUs is to look at the separation between the signal and the noise. This is efficiently measured by the silouette (SIL) score.
+A way to assess the quality of the MUs is to look at the separation between the signal and the noise. This is efficiently measured by accuracy scores.
 
-This score is automatically calculated while importing the *emgfile* and can be easily accessed as `emgfile["SIL"]`.
+This score is automatically calculated while importing the *emgfile* and can be easily accessed as `emgfile["ACCURACY"]`. In our sample file, the accuracy is calculated by the Silhouette (SIL) score (Negro 2016).
 
 ```Python
 # Import the library with the short name 'emg'
@@ -205,7 +205,7 @@ import openhdemg.library as emg
 emgfile = emg.emg_from_samplefile()
 
 # Print the SIL score
-print(emgfile["SIL"])
+print(emgfile["ACCURACY"])
 
 """Output
           0
@@ -217,7 +217,7 @@ print(emgfile["SIL"])
 """
 ```
 
-Our suspicion was right, MU number 2 has the lowest SIL score.
+Our suspicion was right, MU number 2 has the lowest accuracy score.
 
 In order to remove this MU, we can use the function [delete_mus](api_tools.md#openhdemg.library.tools.delete_mus).
 
@@ -285,35 +285,29 @@ results = emg.basic_mus_properties(
 print(results)
 
 """
-     MVC  MU_number        PNR    avg_PNR       SIL   avg_SIL      abs_RT  \
-0  634.0          0  27.480307  29.877575  0.899082  0.922923   30.621759
-1    NaN          1  28.946493        NaN  0.919601       NaN   32.427026
-2    NaN          2  28.640680        NaN  0.917190       NaN   68.371911
-3    NaN          3  34.442821        NaN  0.955819       NaN  118.504004
-
-     abs_DERT     rel_RT   rel_DERT    DR_rec  DR_derec  DR_start_steady  \
-0   36.168135   4.829930   5.704753  7.548770  5.449581        11.788779
-1   31.167703   5.114673   4.916041  8.344515  5.333535        11.254445
-2   67.308703  10.784213  10.616515  5.699017  3.691367         9.007505
-3  102.761472  18.691483  16.208434  5.701081  4.662196         7.393645
-
-   DR_end_steady  DR_all_steady     DR_all  COVisi_steady  COVisi_all  \
-0      10.401857      11.154952  10.693076       6.833642   19.104306
-1       9.999033      10.751960  10.543011       8.364553   15.408739
-2       7.053079       8.168471   7.949294      10.097045   23.324503
-3       6.430807       6.908502   6.814687      11.211862   16.319474
-
-   COV_steady
-0    1.422424
-1         NaN
-2         NaN
-3         NaN
+     MVC  MU_number  ACCURACY  avg_ACCURACY      abs_RT    abs_DERT  \
+0  634.0          0  0.899082      0.922923   30.621759   36.168135  
+1    NaN          1  0.919601           NaN   32.427026   31.167703  
+2    NaN          2  0.917190           NaN   68.371911   67.308703  
+3    NaN          3  0.955819           NaN  118.504004  102.761472  
+
+       rel_RT   rel_DERT    DR_rec  DR_derec  DR_start_steady  DR_end_steady  \
+0    4.829930   5.704753  7.548770  5.449581        11.788779      10.401857  
+1    5.114673   4.916041  8.344515  5.333535        11.254445       9.999033  
+2   10.784213  10.616515  5.699017  3.691367         9.007505       7.053079  
+3   18.691483  16.208434  5.701081  4.662196         7.393645       6.430807  
+
+   DR_all_steady     DR_all  COVisi_steady  COVisi_all  COV_steady
+0      11.154952  10.693076       6.833642   19.104306    1.422424
+1      10.751960  10.543011       8.364553   15.408739         NaN
+2       8.168471   7.949294      10.097045   23.324503         NaN
+3       6.908502   6.814687      11.211862   16.319474         NaN
 """
 ```
 
 ## 7. Save the results and the edited file
 
-It looks like we got a lot of results, which makes it extremely inefficient to copy them manually.
+It looks like we got a lot of results, which makes of it extremely inefficient to copy them manually.
 
 Obviously, this can be automated using one attribute of the *results* object and we can conveniently save all the results in a .csv file.