Merge pull request #68 from GiacomoValliPhD/Towards_v0.1.0

First stable release.

Release notes at: https://www.giacomovalli.com/openhdemg/what%27s-new/

CODEOWNERS

@@ -7,3 +7,8 @@
 # When there are changes in the GUI folder, @GiacomoValliPhD
 # and @PaulRitsche will be requested for review.
 /openhdemg/gui/ @GiacomoValliPhD @PaulRitsche
+
+# When there are changes in the pic module, @GiacomoValliPhD
+# and @JABeauchamp will be requested for review.
+/openhdemg/library/pic.py @GiacomoValliPhD @JABeauchamp
+/openhdemg/library/tools.py @GiacomoValliPhD @JABeauchamp

docs/api_analysis.md

@@ -1,6 +1,9 @@
 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 apart from those involving:
+
+- The MUs action potential shape => Available in the [muap module](api_muap.md)
+- DeltaF / PICs estimation => available in the [pic module](api_pic.md)
 
 <br/>
 

docs/api_muap.md

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

docs/api_pic.md

@@ -0,0 +1,14 @@
+Description
+-----------
+This module contains all the functions used to quantify and analyze MU persistent inward currents.
+
+Currently includes delta F.
+
+<br/>
+
+::: openhdemg.library.pic.compute_deltaf
+    options:
+        show_root_full_path: False
+        show_root_heading: True
+
+<br/>

docs/api_plotemg.md

@@ -53,6 +53,13 @@ This module contains all the functions used to visualise the content of the impo
 
 <br/>
 
+::: openhdemg.library.plotemg.plot_smoothed_dr
+    options:
+        show_root_full_path: False
+        show_root_heading: True
+
+<br/>
+
 ::: openhdemg.library.plotemg.plot_muaps
     options:
         show_root_full_path: False

docs/api_tools.md

@@ -104,3 +104,10 @@ shortcuts necessary to operate with the HD-EMG recordings.
         show_root_heading: True
 
 <br/>
+
+::: openhdemg.library.tools.compute_svr
+    options:
+        show_root_full_path: False
+        show_root_heading: True
+
+<br/>

docs/gui_advanced.md

@@ -8,13 +8,14 @@ Please note, the `Advanced Tools` might not be available for all the files, as s
 
 ## Start a Specific Tool
 
-So far, we have included three advanced analyses in the *openhdemg* GUI.
+So far, we have included four advanced analyses in the *openhdemg* GUI.
 
 - `Motor Unit Tracking`
 - `Duplicate Removal`
 - `Conduction Velocity Estimation`
+- `Persistent Inward Currents`
 
-For all of those, the specification of a `Matrix Code` and a `Matrix Orientation` is required.
+For some of these analyses, the specification of a `Matrix Code` and a `Matrix Orientation` is required.
 
 The `Matrix Code` must be specified according to the one you used during acquisition. So far, the implemented codes are:
 
@@ -33,6 +34,8 @@ Rows, Columns: 13, 5
 ```
 means that your File has 65 channels organised over 13 rows and 5 columns.
 
+The use of `None` is suggested anytime your loaded file contains already sorted EMG channels and you want to avoid further sorting.
+
 If you selected one of the built-in sorting orders (e.g., `GR08MM1305`, `GR04MM1305`, `GR10MM0808`), you need to specify also 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` or `Custom order`.
 
 Once you specified these parameter, you can click the `Advaned Analysis` button to start your analysis.
@@ -66,7 +69,7 @@ When you want to track MUs across two different files, you need to select the `M
 
 7. The `Show` checkbox indicates whether to plot the spike triggered average of pairs of MUs with cross-correlation above `Threshold`.
 
-8. By clicking the `Track` button, you can start the analysis. The tracking results will be displayed in the `MUs Tracking Resul` output in the right side of the `MUs Tracking Window`.
+8. By clicking the `Track` button, you can start the analysis. The tracking results will be displayed in the `MUs Tracking Result` output in the right side of the `MUs Tracking Window`.
 
 ## Duplicate Removal
 
@@ -111,6 +114,24 @@ Prior to calculation of the `Conduction Velocity` you need to load a file in the
 
 We are now at the end of describing the advanced functions included in the *openhdemg* GUI. If you want to take a look at more basic stuff, check out the [basic](gui_basics.md).
 
+## Persistent Inward Currents
+
+When you want to estimate Persistent Inward Currents, you need to select the `Persistent Inward Currents` option. In this case, `Matrix Code` and `Matrix Orentation` will be locked, as these are not needed for the analysis. Once you clicked the `Advanced Analysis` button, the `Persistent Inward Currents Window` will pop-up.
+
+![persistent_inward_currents](md_graphics/gui/pics_window.png)
+
+Please note that it is suggested to [sort the MUs](gui_basics.md/#motor-unit-sorting) based on recruitment order before performing the PICs estimation. This can be done in the main GUI window.
+
+1. In row 1 of this window you can select the smoothing tecnique to adopt (at the time of writing, only the `Support Vector Regression` is available, but more are under development).
+
+2. Select the `Average Method` to use for test MU deltaF value.
+
+3. Select the method for deltaF  `Normalisation`.
+
+4. Select the `Clean` option if you want to remove values that do not meet exclusion criteria.
+
+5. By clicking the `Compute PIC` button, you can start the analysis. The results will be displayed in the right side of the `Persistent Inward Currents Window`.
+
 ## More questions?
 
 We hope that this tutorial was useful. If you need any additional information, do not hesitate to read the answers or ask a question in the [*openhdemg* discussion section](https://github.com/GiacomoValliPhD/openhdemg/discussions){:target="_blank"}. If you are not familiar with GitHub discussions, please read this [post](https://github.com/GiacomoValliPhD/openhdemg/discussions/42){:target="_blank"}. This will allow the *openhdemg* community to answer your questions.

docs/gui_settings.md

@@ -8,6 +8,10 @@ Accessing these GUI settings is simple: just click on the Gear icon located at t
 
 Upon clicking the settings icon, a Python file will open in your default text editor. Here, you'll be able to modify the settings according to your requirements.
 
+Always remember to **save the Python settings file after changing the variables**, or the changes will not be effective.
+
+If the Python file does not open, please read the [Troubleshooting section](#troubleshooting).
+
 ## Modify GUI settings
 
 The GUI settings file (named *settings.py*) is organised into distinct topic sections.
@@ -18,7 +22,7 @@ All the variables that can be modified are labelled as:
 
 In this way, the values that each variable can assume can be discovered from the API section of this website by navigating into the topic, then into the Name of the function and then looking at the specific variable.
 
-The variables that can be modified from the GUI settings, as well as their values, can differ between different *openhdemg* releases. Therefore, the user is always encouraged to check the specifics APIs, and not to rely on this guide, which only serves didactical purposes.
+**The variables that can be modified from the GUI settings, as well as their values, can differ between different *openhdemg* releases. Therefore, the user is always encouraged to check the specifics APIs, and not to rely on this guide, which only serves didactical purposes.**
 
 ### openfiles
 
@@ -89,6 +93,22 @@ resize_emgfile__ignore_negative_ipts = False
 
 The corresponding APIs for the function *resize_emgfile* can be accessed [here](api_tools.md/#openhdemg.library.tools.resize_emgfile).
 
+### pic
+
+The section named *pic* controls the Persistent Inward Currents estimation.
+
+The API section for this topic is [here](api_pic.md).
+
+For example, in the following code snippet we can adjust how to estimate Delta F.
+
+```Python
+compute_deltaf__recruitment_difference_cutoff = 1.0
+compute_deltaf__corr_cutoff = 0.7
+compute_deltaf__controlunitmodulation_cutoff = 0.5
+```
+
+The corresponding APIs for the function *compute_deltaf* can be accessed [here](api_pic.md/#openhdemg.library.pic.compute_deltaf).
+
 ### muap
 
 The section named *muap* controls all the functionalities that require MU action potentials. Currently, it controls the behaviour of functionalities such as MU tracking, duplicate removal and conduction velocity estimation, among others.
@@ -189,6 +209,44 @@ Additionally, you cannot remove the unused variables from the settings file! You
 
 If you accidentally modify some variables and the GUI stops working properly, you can restore the original settings by copying and pasting the content of the *backup_settings.py* file. This will be visible in the file explorer of your editor next to the *settings.py* file.
 
+## Troubleshooting
+
+### The settings don't show up
+
+If clicking the Gear icon doesn't open the *settings.py* file, it might be because your operating system doesn't recognize the .py file extension. This can happen if you've never opened a Python file before. To solve this:
+
+1. Double-click on any Python file (do this from outside Visual Studio Code, or it will take care of the process and your operating system will not associate the Python file to a specific software).
+
+2. A window should prompt you to choose which software to use to open the file.
+
+3. Select Visual Studio Code and set it as the default application for .py files.
+
+4. After doing this, try restarting the *openhdemg* GUI and Visual Studio Code. The Gear icon should now function correctly.
+
+If the issue persists, please continue reading.
+
+### Locate the settings.py file
+
+If the *settings.py* file does not open after clicking on the Gear icon, you can still manually navigate to this file and change the settings. The *settings.py* file can be accessed navigating the file explorer of your editor (usually on the left side of Visual Studio Code).
+
+In your file explorer, navigate as follows:
+
+1. Click on your virtual environment folder
+
+2. Click on *Lib*
+
+3. Click on *openhdemg*
+
+4. Click on *gui*
+
+5. Here you will find the *settings.py* file. Double click it and edit the settings as needed.
+
+6. Save the file
+
+### Changes are not effective
+
+Always remember to save the Python settings file after changing the variables, or the changes will not be effective. It is not necessary to restart the GUI when changes are made to the settings.py file.
+
 ## More questions?
 
 We hope that this tutorial was useful. If you need any additional information, do not hesitate to read the answers or ask a question in the [*openhdemg* discussion section](https://github.com/GiacomoValliPhD/openhdemg/discussions){:target="_blank"}. If you are not familiar with GitHub discussions, please read this [post](https://github.com/GiacomoValliPhD/openhdemg/discussions/42){:target="_blank"}. This will allow the *openhdemg* community to answer your questions.

docs/isek_jek_tutorials.md

@@ -26,7 +26,7 @@ You can download the sample files and the sample scripts [here](https://drive.go
 
 <br> <!-- links in HTML should be full links-->
 
-## 2023 ISEK Workshop
+## 2024 ISEK Workshop
 
 **Workshop: Simplified analysis of motor unit properties with *openhdemg*.**
 

docs/overrides/main.html

@@ -7,13 +7,9 @@
 {% block announce %}
   <div class="announcement-banner">
     <div class="announcement-content">
-      <h2 style="display: block;">2 X 🎉 == Double News!</h2>
-      <p style="display: inline;">The 4th openhdemg beta release is now available! => </p>
-      <a href="https://www.giacomovalli.com/openhdemg/what%27s-new/" class="btn btn-secondary" style="display: inline;">See what's new</a>
+      <h2 style="display: block;">🚀 Release V0.1.0</h2>
+      <p style="display: inline;"> The first openhdemg stable version is here! => </p>
+      <a href="https://www.giacomovalli.com/openhdemg/what%27s-new/" class="btn btn-secondary" style="display: inline;"> See the new functionalities</a>
       <br> <!-- New line -->
-      <p style="display: inline;">We are thrilled to announce the publication of our Tutorial article! => </p>
-      <a href="https://www.giacomovalli.com/openhdemg/isek_jek_tutorials/" class="btn btn-primary" style="display: inline;">Read it Now</a>
-    </div>
-  </div>
 {% endblock %}
 <!-- links in HTML should be full links-->

docs/what's-new.md

@@ -1,3 +1,47 @@
+## :octicons-tag-24: 0.1.0
+:octicons-clock-24: June 2024
+
+This release is aimed at expanding the functionalities of the library with new and improved analysis tools. It also marks the exit from the beta phase!
+
+### Backward Compatibility
+
+This version is fully backward compatible with v0.1.0-beta.3 and 4.
+
+### Major Achievements
+- **More functionalities**
+
+### Major Changes
+
+- **New modules**:
+
+    - With this release, we introduce the module `pic`. A module dedicated to Persistent Inward Currents estimation. It now allows to estimate PICs via Delta F and will be enriched with new functionalities in the near future.
+
+- **New classes**:
+
+    - The class `Tracking_gui` provides a convenient interface for the visual inspection of the tracking results, improving the flexibility and accuracy of MUs tracking based on MUAPs shape.
+
+- **Updated classes**:
+
+    - The class `MUcv_gui` has been optimised to reduce RAM memory usage and can now be expanded to full-screen. Furthermore, it now accepts custom separators for copying the results and pasting them into Excel (or any other text/tabular document).
+
+- **New functions**:
+
+    - The function `compute_svr` allows to fit MU discharge rates with Support Vector Regression, nonlinear regression.
+    - The function `compute_deltaf` allows to quantify delta F via paired motor unit analysis.
+    - The function `plot_smoothed_dr` allows to visualise the smoothed discharge rate, with or without IDR and with or without stacking MUs.
+
+- **Updated functions**:
+
+    - The functions `tracking()` and `remove_duplicates_between()` now allow to directly show the `Tracking_gui` after completing the tracking procedure for additional inspection of the results. They also allow to select whether to use parallel processing to improve execution speed.
+    - The functions `plot_muaps` and `plot_muaps_for_cv` now allow to use a tight layout for the output figure.
+    - The functions `compute_dr`, `compute_drvariability`, `compute_covisi` and `basic_mus_properties` now allow to exclude firings outside a custom range of frequencies.
+
+- **GUI updates**:
+
+    - The openhdemg GUI allows access to the `Tracking_gui` during MUs tracking (not after duplicates removal) and to perform PICs estimation via the advanced tools window. It also allows tuning the behaviour of these functionalities through the settings window.
+
+<br>
+
 ## :octicons-tag-24: 0.1.0-beta.4
 :octicons-clock-24: April 2024 
 

mkdocs.yml

@@ -83,6 +83,7 @@ nav:
     - openfiles: api_openfiles.md
     - plotemg: api_plotemg.md
     - analysis: api_analysis.md
+    - pic: api_pic.md
     - tools: api_tools.md
     - mathtools: api_mathtools.md
     - muap: api_muap.md

openhdemg/__init__.py

@@ -1,3 +1,3 @@
 __all__ = ["__version__"]
 
-__version__ = "0.1.0-beta.4"
+__version__ = "0.1.0"