Merge pull request #46 from GiacomoValliPhD/Towards_v0.1.0-beta

Towards v0.1.0 beta

README.md

@@ -37,7 +37,7 @@ or conda:
 conda install -c conda-forge openhdemg
 ```
 
-If you want an overview of what you can do with the *openhdemg* library, have a look at the [**Quick Start** section](https://www.giacomovalli.com/openhdemg/Quick-Start/).
+If you want an overview of what you can do with the *openhdemg* library, have a look at the [Quick Start section](https://www.giacomovalli.com/openhdemg/Quick-Start/).
 
 ## Good to know
 In addition to the rich set of modules and functions presented in the **API documentation**, *openhdemg* offers also a practical graphical user interface (GUI) from which many tasks can be performed without writing a single line of code!

docs/API_openfiles.md

@@ -35,12 +35,12 @@ Notes
 -----
 Once opened, the file is returned as a dictionary with keys:<br>
 
-"SOURCE" : source of the file (i.e., "DEMUSE", "OTB", "custom")<br>
+"SOURCE" : source of the file (e.g., "DEMUSE", "OTB", "custom")<br>
 "RAW_SIGNAL" : the raw EMG signal<br>
 "REF_SIGNAL" : the reference signal<br>
 "PNR" : pulse to noise ratio<br>
 "SIL" : silouette score<br>
-"IPTS" : pulse train<br>
+"IPTS" : pulse train (decomposed source)<br>
 "MUPULSES" : instants of firing<br>
 "FSAMP" : sampling frequency<br>
 "IED" : interelectrode distance<br>

docs/GUI_advanced.md

@@ -4,18 +4,28 @@ This is the toturial for the `Advanced Tools` in the *openhdemg* GUI. Great that
 
 ![advanced_analysis](md_graphics/GUI/Advanced_analysis_window.png)
 
-So far, we have included three advanced analyses in the *openhdemg* GUI. 
+So far, we have included three advanced analyses in the *openhdemg* GUI.
+
 - `Motor Unit Tracking`
 - `Duplicate Removal`
 - `Conduction Velocity Calculation`
 
 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 
+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.
-Once you specified these parameter, you can click the "Advaned Analysis" button to start your analysis.
+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
+
+```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.
 
 -----------------------------------------
 
@@ -25,6 +35,7 @@ When you want to track MUs across two different files, you need to select the `M
 ![mus_tracking](md_graphics/GUI/MU_Tracking_window.png)
 
 1. You need to specify the `Type of file` you want to track MUs across in the respective dropdown. The available filetypes are:
+
     - `OTB` (.mat file exportable by OTBiolab+)
     - `DEMUSE` (.mat file used in DEMUSE)
     - `OPENHDEMG` (emgfile or reference signal stored in .json format)
@@ -51,10 +62,11 @@ When you want to remove MUs duplicates across different files, you need to selec
 
 ![duplicate_removal](md_graphics/GUI/Duplicate_Removal_window.png)
 
-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.
+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.
 
 2. By clicking the `Remove Duplicates` button, you start the removal process.
 

docs/GUI_basics.md

@@ -38,7 +38,7 @@ The *openhdemg* GUI also allows you to edit and filter reference signals corresp
 
 1. View the MUs using the `View MUs` button prior to reference signal editing, so you can see what is happening.
 
-2. Click the `RefSig Editing` button located in row five and column one, a new pop-up window opens. In the `Reference Signal Editing Window`, you can low-pass filter the reference signal as well as remove any signal offset. 
+2. Click the `RefSig Editing` button located in row five and column one, a new pop-up window opens. In the `Reference Signal Editing Window`, you can low-pass filter the reference signal as well as remove any signal offset. Additionally, you can also convert your reference signal by a specific factor (amplification factor) or convert it from absolute to percentage (relative or normalised) values.
 
 3. When you click the `Filter RefSig` button, the reference signal is low-pass filtered (Zero-lag, Butterworth) according to values specified in the `Filter Order` and `Cutoff Freq` textboxes. In example, specifiying 
 
@@ -66,7 +66,21 @@ The *openhdemg* GUI also allows you to edit and filter reference signals corresp
     Offset Value : 0
     Automatic: 0
     ```
-    will allow you to manually correct the offset in a new pop-up plot. You just need to follow the instructions on the plot. 
+    will allow you to manually correct the offset in a new pop-up plot. You just need to follow the instructions on the plot.
+
+5. When you click the `Convert` button, the reference signal will be multiplied or divided (depending on `Operator`) by the `Factor`. In example, specifying
+
+    ```Python
+    Operator : "Multiply"
+    Factor: 2.5
+    ```
+    will amplify the reference signal 2.5 times.
+
+6. When you click the `To Percent` button, the reference signal in absolute values is converted to percentage (relative or normalised) values based on the provided `MVC Value`. **This step should be performed before any analysis, because *openhdemg* is designed to work with a normalised reference signal.** In example, a file with a reference signal in absolute values ranging from 0 to 100 will be normalised from 0 to 20 if
+
+    ```Python
+    MVC Value : 500
+    ```
 
 ## Resize EMG File
 Sometimes, resizing of your analysis file is unevitable. Luckily, *openhdemg* provides an easy solution. In row five and column two in the left side of the GUI, you can find the `Resize File` button. 
@@ -194,7 +208,7 @@ You can choose between the follwing plotting options:
 - Plot the raw emg signal. Single or multiple channels. (Plot EMGSig)
 - Plot the reference signal. (Plot RefSig)
 - Plot all the MUs pulses (binary representation of the firings time). (Plot MUPulses)
-- Plot the source of decomposition. (Plot Source)
+- Plot the decomposed source. (Plot Source)
 - Plot the instantaneous discharge rate (IDR). (Plot IDR)
 - Plot the differential derivation of the raw emg signal by matrix column. (Plot Derivation)
 - Plot motor unit action potentials (MUAPs) obtained from spike-triggered average from one or multiple MUs. (Plot MUAPs)
@@ -215,6 +229,13 @@ These three setting options are universally used in all plots. There are two mor
     - `GR08MM1305`
     - `GR04MM1305`
     - `GR10MM0808`
+    - `None`
+
+    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
+    ```Python
+    Rows, Columns: 13, 5
+    ```
+    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`.
 
@@ -232,9 +253,9 @@ These three setting options are universally used in all plots. There are two mor
 2. Enter/select a pulse `Linewidth` in/from the dropdown list. For example, if you want to use a `Linewidth` of one, enter *1* in the dropdown. 
 3. Once you have clicked the `Plot MUpulses` button, a pop-up plot will appear. 
 
-### Plot the Source of decomposition
-1. Click the `Plot Source` button in row seven and column one in the left side of the `Plot Window`, to plot the Source of the MUs decomposition in your analysis file. 
-2. Enter/select a `MU Number` in/from the dropdown list. For example, if you want to plot the source of `MU Number` one enter *0* in the dropdown. If you want to plot the sources of `MU Number` one, two and three enter *0,1,2,* in the dropdown. You can also set `MU Number` to "all" to plot the sources of all included MUs in the analysis file.
+### Plot the Decomposed Source
+1. Click the `Plot Source` button in row seven and column one in the left side of the `Plot Window`, to plot the Source of the decomposed MUs in your analysis file. 
+2. Enter/select a `MU Number` in/from the dropdown list. For example, if you want to plot the source for `MU Number` one enter *0* in the dropdown. If you want to plot the sources for `MU Number` one, two and three enter *0,1,2,* in the dropdown. You can also set `MU Number` to "all" to plot the sources for all included MUs in the analysis file.
 3. Once you have clicked the `Plot Source` button, a pop-up plot will appear. 
 
 ### Plot Instanteous Discharge rate
@@ -277,7 +298,7 @@ We all make mistakes! But, most likely, we are also able to correct them. In cas
 
 --------------------------------------------
 
-We hope you had fun! We are now at the end of describing the basic functions included in the *openhdemg* GUI. In case you need further clarification, don't hesitate to post a question in the Github discussion forum (LINK). Moreover, if you noticed an error that was not properly catched by the GUI, please file a bug report according to our guidelines (LINK).
+We hope you had fun! We are now at the end of describing the basic functions included in the *openhdemg* GUI. In case you need further clarification, don't hesitate to post a question in the [*openhdemg* discussion section](https://github.com/GiacomoValliPhD/openhdemg/discussions){:target="_blank"}. Moreover, if you noticed an error that was not properly catched by the GUI, please file a bug report according to our guidelines (LINK).
 If you want to proceed to the advanced stuff now, take a look at the [advanced](GUI_advanced.md) tab on the left side of the webpage.
 
 ## More questions?

docs/tutorials/Setup_working_env.md

@@ -87,10 +87,16 @@ The Virtual environments provide an isolated and controlled environment for your
 
 In order to create a virtual environment type in your terminal:
 
+For Windows users:
 ```shell
 python -m venv myvenv
 ```
 
+For Mac users:
+```shell
+python3 -m venv myvenv  
+```
+
 ![venv_command](Setup_working_env/venv_command.png)
 
 This command will create a Virtual environment named `myvenv`.

mkdocs.yml

@@ -43,9 +43,9 @@ nav:
     - For new users:
       - Setup working environment: tutorials/Setup_working_env.md
   - Graphical-Interface:
-    - Intro: GUI_intro.md
-    - Basics: GUI_basics.md
-    - Advanced: GUI_advanced.md
+    - intro: GUI_intro.md
+    - basics: GUI_basics.md
+    - advanced: GUI_advanced.md
   - What's-New.md
   - Contacts.md
   - Cite-Us.md
@@ -108,9 +108,9 @@ extra:
   generator: false # Remove 'Made with Material for MkDocs' in the footer.
   social:
     - icon: fontawesome/brands/github 
-      link: https://github.com/GiacomoValliPhD/openhdemg
+      link: https://github.com/GiacomoValliPhD
     - icon: fontawesome/brands/twitter 
-      link: https://twitter.com/openhdemg
+      link: https://
   version:
     provider: mike # TODO versioning