readmes here, readmes there, readmes everywhere

Code/Data Processing/README.md

@@ -1,32 +1,8 @@
-This folder collects MATLAB scripts commonly used for processing raw data.
-
-In `OpenSim4.3` you can find scripts that use OpenSim functionalities specifically. They described here, to view all of them on the same page
-
-When adding a new file, please edit the following list with the file name and a short description of how to use it (and why).
-
-- `EMGcrunch_example.m` : example of how to process EMG signals of specific (user defined muscles). Requires MVC experiments and generic motions to be analyzed (in format `MVC*.mat` and `motion*.mat`). The EMG data are filtered, rectified, and normalized.
-
-- `OpenSim4.3/c3dExport_markersOnly.m` : extracts marker trajectories (`.trc`) from motion capture results (`.c3d`). When run, prompts the user to navigate to the desired `.c3d` file, processes it and saves it with a user-defined name in the same folder.
-
-- `EMG_analysis.m`: processes EMG signals of specific (user defined muscles). Requires MVC experiments and generic motions to be analyzed (in format `MVC*.mat` and `motion*.mat`). The EMG data are filtered, rectified, and normalized.
-		    Uses: `butterworth_filter.m`, `extract_data.m`, `extract_mvc.m`, and `normalize_emg.m`
-
-- `butterworth_filter.m`: filters raw data by applying a bandpass filter, rectification and low pass filter to the EMG data. Output is filtered EMG prepped for analysis
-
-- `extract_data.m`: takes `.mat` files with analog data as input and extracts EMG channels. NB: EMG channel should be the first channel per muscle.
-
-- `extract_mvc.m` takes the maximum of the maximum of the filtered data, this results in one value per muscle: the highest measured activation over all trials.
-
-- `normalize_emg.m`: normalizes trial data with the use of the MVC data. Scales activation between 0 and 1.
-
-- `readTRC.m`: reads a `.trc` file (only input) and loads it into the workspace. It returns the x-y-z trajectories for each marker in form of a single 2D array. Timestamps, labels for the markers and units of measurement used can also be retrieved.
-
-- `writeMarkersToTRC.m`: saves a new `.trc` file. Takes as inputs the name of the files, the markers to be saved (3D markers trajectories as a single 2D array), marker labels, rate of acquisition, optionally the frames, the timestamps and the units of measurement used. A GUI will be prompted at the end to ask the directory for the `.trc' file to be saved in.
-
-- `read_motionFile.m`: reads a `.mot` file (only input) and returns a Matlab structure with fields corresponding to column labels, 2D matrix of data, dimensions of the matrix of data.
-
-- `CSV2TRC.m`: opens a `.CSV` file (or other ASCII text file that can be converted to a table) and transforms it to match the `.trc` format. Uses `writeMarkersToTRC.m`.
-
-
-- ... [add new script here]
-
+This folder collects scripts used for data processing. Many of them are general purpose scripts, whose use is documented in other functions or in the scripts themselves.
+
+In particular:
+- `SPM_robustness_analysis.m` allows to reproduce the robustness analysis performed in our paper. It requires 4 steps before running it:
+		1. installing the SP1D package for Matlab (instructions at https://spm1d.org/install/InstallationMatlab.html)
+		2. generating the perturbed models (using the scripts in `Code/Model Perturbation`)
+		3. getting the marker data from the open-access study from Seth et al (available at: https://simtk.org/projects/thoracoscapular). The marker data should be copied into the `ExperimentalData/Markers` folder of this repository
+		4. running the RMR solver on the models and markers retrieved above. The analysis can be performed through `Code/Compute Muscle Activity/RMR solver/analyse_perturbed_models.m`. Results should be stored in `Results/RMR analysis/robustness analysis`, following the indications provided there.

Code/Image Generation/README.md

@@ -0,0 +1 @@
+In order to generate the plots provided in our paper, simply run `PlotResults.m` and select the tasks you want to analyse.

Code/Model Perturbation/README.md

@@ -0,0 +1,5 @@
+In our paper we generated 200 different models to test for the robustness of our conclusions against intrinsic uncertainty of the study. We do not share the models, as this would clutter this repo, but we provide the scripts to generate them.
+
+In order to achieve similar results to ours:
+1. run the `perturb_models.m` to produce 100 different models, selecting as input the model in `OpenSim Models/for RMR solver/TSM_subject_noWeight.osim`. Copy-paste the resulting models into  `OpenSim Models/for RMR solver/perturbed models/noWeight`. 
+3. Run the script `add_2kgLoad_toModels.m`, selecting the results of the previous step, and copy-paste the resulting models in `OpenSim Models/for RMR solver/perturbed models/2kgWeight`.

Code/README.md

@@ -1,5 +1,6 @@
-The code collected here is divided in 3 folders:
+The code collected here is divided in 4 folders:
 
 - `Compute Muscle Activation`: stores the scripts required to perform both CMC and RMR analysis on the dataset
-- `Data Processing`: contains all the scripts necessary to process the data
-- `Image Generation`: stores the scripts used to analyze our results and generate the images included in the paper
+- `Data Processing`: contains all the scripts necessary to process the data (utilities, and scripts used to perform statistical analysis on our results)
+- `Image Generation`: stores the scripts used to analyze our results and generate the images included in the paper
+- `Model Perturbation`: stores the scripts used to perturb randomly our models, accounting for intrinsic uncertainty in marker-based biomechanical studies

ExperimentalData/EMG/README.md

@@ -0,0 +1,14 @@
+## EMG data
+This folder is used to collect the EMG data corresponding to the various tasks that are analyzed in our paper.
+The movements were performed by a single subject, and are:
+- unloaded abduction (ABD01, ABD02, ABD03)
+- loaded abduction (ABD21, ABD22, ABD23)
+- unloaded forward flexion (FLX01, FLX02, FLX03)
+- loaded forward flexion (FLX21, FLX22, FLX23)
+- unloaded shrugging (SHRUG01, SHRUG02, SHRUG03)
+- loaded shrugging (SHRUG21, SHRUG22, SHRUG23)
+
+You can get the data and populate your local version of the repository from the dataset available at https://simtk.org/projects/thoracoscapular.
+
+It could be annoying, but we do not provide the dataset directly on purpose.
+Why? We want to avoid duplicating it over and over, so that we can save memory and energy in the servers and appropriately credit the researchers who collected the data in the first place!

ExperimentalData/Markers/README.md

@@ -1,5 +1,5 @@
 ## Marker data
-In this folder, we collect the marker data corresponding to the various tasks that are analyzed in our paper.
+This folder is used to collect the marker data corresponding to the various tasks that are analyzed in our paper.
 The movements were performed by a single subject, and are:
 - unloaded abduction (ABD01, ABD02, ABD03)
 - loaded abduction (ABD21, ABD22, ABD23)
@@ -8,6 +8,7 @@ The movements were performed by a single subject, and are:
 - unloaded shrugging (SHRUG01, SHRUG02, SHRUG03)
 - loaded shrugging (SHRUG21, SHRUG22, SHRUG23)
 
-This data is part of the dataset available at https://simtk.org/projects/thoracoscapular, and we duplicate it here to facilitate reproducing of our results.
+You can get the data and populate your local version of the repository from the dataset available at https://simtk.org/projects/thoracoscapular.
 
-In the folder `noise_diversified` you can find the augmented version of this dataset, where Gaussian noise has been injected on the elbow markers (and only the relevant markers have been preserved). These files, grouped in 3 tasks (where the difference between loaded and unloaded conditions ceases to be relevant), are used in our paper to analyze statistically the effect of including the GH constraint in the estimation of the corresponding muscle activations.
+It could be annoying, but we do not provide the dataset directly on purpose.
+Why? We want to avoid duplicating it over and over, so that we can save memory and energy in the servers and appropriately credit the researchers who collected the data in the first place!

ExperimentalData/README.md

@@ -5,6 +5,4 @@ In particular, the data needed is:
 - marker data 3D trajectories (in `.trc` format)
 - filtered EMG values for superficial muscles (ground-truth for the muscle activations, in `.exp` format)
 
-Inside the `Markers\noise_diversified` folder you can find already the dataset augmented with white Gaussian noise, described in our paper.
-
 The folder `IK setup files` collects the setup files needed to perform the inverse kinematics on the basis of the experimental marker data, and the musculoskeletal model considered.

OpenSim Models/README.md

@@ -10,4 +10,4 @@ Lastly, to correctly consider the glenohumeral constraint, we add three extra ma
 - the center of the humeral head (`HumHead_Center`);
 - the width of the glenoid (`Glenoid_Edge`).
 
-When considering a new model, they should be added there as well.
+When considering your own model with the RMR solver, these markers should be added there as well.

OpenSim Models/for RMR solver/README.md

@@ -1 +1,2 @@
-The folder `perturbed_100` comes empty.
+The folder `perturbed` comes empty.
+Instructions on how to generate the models that can be used in the robustness analysis are contained in the two sub-folders above.

README.md

@@ -1,8 +1,8 @@
-# Rapid Muscle Redundancy Solver
+# RMR Solver
 
 ## What is it?
 
-**RMR solver** stands for Rapid Muscle Redundancy solver. It is an algorithm which solves the muscle redundancy problem, by selecting the muscles which are recruited by the human body to generate a given motion (leveraging a musculoskeletal model). The solver, tested on the dataset and model available freely at https://simtk.org/projects/thoracoscapular (Seth et al, 2019),  is presented in detail in our paper:
+**RMR solver** stands for _Rapid Muscle Redundancy_ solver. It is an algorithm which solves the muscle redundancy problem, by selecting the muscles which are recruited by the human body to generate a given motion (leveraging a musculoskeletal model). The solver, tested on the dataset and model available freely at https://simtk.org/projects/thoracoscapular (Seth et al, 2019),  is presented in detail in our paper:
 
 ```bib
 @article{todo,
@@ -68,7 +68,7 @@ In order to use the RMR solver, you will need:
     - **EMG and marker data**, available for free (licensed CC BY 4.0) at: https://simtk.org/projects/thoracoscapular# . Following the link, you will be redirected to the SimTK page of the paper where the data is published. Clicking on `Download Latest Releases` and providing a simple motivation for why you are interested in the data, you will be able to download the original study, that contains the dataset in `ThoracoscapularShoulderPaperMaterials\ExperimentalData`. Just copy-paste the content of `EMG` and `Markers` in the same sub-folders of our `ExperimentalData` folder and you are ready to go! 
 ## Structure
 The material is organized as follows:
-- `Code` contains the scripts used for general data (pre)processing (`Data Processing`) and for running the RMR solver simulations as well as CMC (`Compute Muscle Activity`)
+- `Code` contains the scripts used for general data (pre)processing and statistical analysis (`Data Processing`) and for running the RMR solver simulations as well as CMC (`Compute Muscle Activity`)
 - `OpenSim Models` stores the biomechanical models that are considered;
 - `ExperimentalData` will store the dataset considered in the paper (marker data and filtered EMG values), freely obtainable as described above;
 - `Results` stores our results, supporting the reproducibility of our findings.
@@ -78,21 +78,25 @@ Each of the folders also have a more specific `README`.
 ## Brief guide to our code
 
 1. In order to reproduce the figures and results commented in the paper, please run:
-    - `Code\Image Generation\main_plotMuscleResults.m` (returns figures comparing the RMR solver against the CMC algorithm and filtered EMG data, and mean absolute errors resulting from this comparison);
-    - `Code\Data Processing\spm_analysis.m` (performs a statistical analysis to determine the effect of the glenohumeral constraint on the muscle activations predicted by the RMR solver) 
+    - `Code\Image Generation\PlotResults.m` (produces figures comparing the RMR solver against the CMC algorithm and filtered EMG data, and mean absolute errors resulting from this comparison);
+    - `Code\Data Processing\SPM_robustness_analysis.m` (performs a statistical analysis to determine the effect of the glenohumeral constraint on the muscle activations predicted by the RMR solver) 
 
       [Note: in order to run, it requires installing the SPM1D package]
 
 2. In order to use the RMR solver on the dataset, and to estimate realistic muscle activations given user-chosen motions, please run:
     - `Code\Compute Muscle Activation\RMR solver\main_analyze_dataset.m`
+  This scripts produces our numerical results and can be used as a template to apply the RMR solver in other scenarios.
 
 
-3. To perform a similar CMC analysis on the dataset, to reach our same results, please run:
+3. To perform a similar CMC analysis on the dataset, please run:
     - `Code\Compute Muscle Activation\CMC analysis\batch_CMC_analysis.m` (by default considers the whole dataset)
 
 
 If you wish to make use of the RMR solver, you can either download the individual files the you need or (recommended) you can fork this repository into your own, and work freely there! We encourage you to try the method on your own data/model: in case you do, remember to cite our publication!
 
+### Trouble-shooting
+If you encounter any troubles or issues with running the code contained in this repository, feel free to open an issue and report it. We will do our best to help you!
+
 
 ## License
 Our code is licensed under the Apache 2.0 license (see the `LICENSE_code` file), while the data and models are licensed under CC BY 4.0 Use Agreement terms.

Results/README.md

@@ -0,0 +1,8 @@
+In this folder we store the results of our study. 
+
+- in `CMC analysis` you can find the results of analysing the various shoulder movements with the computed muscle control algorithm
+- in `RMR analysis`, we store the results of the same analysis, performed with our solver on the same marker data (with and without including the glenohumeral constraint)
+- in `IK solutions`, we share the results of our inverse kinematics analysis (which are the same both for the CMC and RMR tools)
+
+
+Note that in `RMR analysis/robustness analysis` we provide the structure that you should populate yourself with the results that the RMR solver delivers when considering different perturbed models (see our paper and the content of `OpenSim Models/for RMR solver/perturbed models`). We do not share our results here as they consist of over 3000 files, that would make this repository very heavy to clone and store. However, we hope to provide sufficient instructions so that our results can be reproduced fully.