Updated ReadMe files for better documentation

Documentation/README.md

+# Documentation
+Here some general explanations are given and all pictures for the documentation
+are uploaded.
+
+# Technical comments
+## Measurements
+The shear experiments are done in a ring shear type shear cell rst.pc01
+manufactured by D. Schulze (Details in ASTM standard D-6773). It uses an easy
+and reproducible workflow to determine yield properties, cohesion and
+dilational properties of a granular bulk material, such as sand or glass beads.

README.md

 # RST Evaluation
 Scripts for analysing shear experiments from the Schulze RST.pc01 ring shear tester.
 
+# Quick Guide to rst-evaluation
+The software `rst-evaluation` is a series of scripts to semi-automatically
+evaluate shear experiments done at the Helmholtz Laboratory for Tectonic
+Modelling. In principle, it may be used for other measurements done in a
+similar setup, but it was build with our standardized workflow in mind.
+
 # Installation
-To use the scripts you need Python 3.x and the modules supplied in `requirements.txt`.
+This software is programmed in Python 3 using several external modules and
+therefore requires these to run. You can find the newest version of Python at
+[here (external link!)](https://python.org). At the time of writing this was
+Python 3.8.x, but because of the relatively simple nature of this software it
+should also work with most older versions. Furthermore it uses the additional
+modules summarized in
+[requirements.txt](https://gitext.gfz-potsdam.de/analab-code/rst-evaluation/blob/master/requirements.txt)
+which are installed using `pip` by calling `python3 -m pip install -r requirements.txt`.
+
+To install this software simply download and extract, or git clone, it into
+your destination folder.
 
 # How-To
-The main scripts are located in RSTpicking and to run the scripts you should use `python RST_main.py` (Windows) or `python3 RST_main.py` (Unix). That will open a GUI providing the necessary details to open data files and analyse full folders.
+The main scripts are located in RSTpicking and to run the scripts you should
+use `python RST_main.py` (Windows) or `python3 RST_main.py` (Unix). That will
+open a GUI providing the necessary details to open data files and analyse full
+folders.
+
+## RSTpicking
+The software features several independent components that can be used for file
+conversion, manual picking, analysis or a fully featured analysis.
+
+The main component of this software is `RSTpicking` which incorporates the
+functionality of all other components. There are two different scripts that run
+the picking and analysis. It is recommended to use `RST_pick_GUI.py` which
+makes use of a user interface and allows the user to easily change the
+parameters and projects. `RST_main.py` is an older version that is less
+flexible and requires the user to manually edit the settings in the script.
+
+## Other Components
+For a more detailed description of the other components see the
+[Documentation](https://gitext.gfz-potsdam.de/analab-code/rst-evaluation/blob/master/Documentation/)
+and the readme files in the individual folders.
+
 
 # Acknowledgements
 The original scripts for version 0.0.1 (4260ec45) in this repository have been provided by M. Warsitzka @warsitzka_at_ig.cas.cz and contain scripts that have been developed by M. Ritter.
@@ -15,4 +51,6 @@ Warsitzka, Michael; Ge, Zhiyuan; Schönebeck, Jan-Michael; Pohlenz, Andre; Kukow
 # Citation
 Please cite this repository as:
 
-Rudolf, M., & M. Warsitzka (2019): RST Evaluation - Scripts for analysing shear experiments from the Schulze RST.pc01 ring shear tester. https://gitext.gfz-potsdam.de/analab-code/rst-evaluation/
\ No newline at end of file
+Rudolf, M., & M. Warsitzka (2019): RST Evaluation - Scripts for analysing shear
+experiments from the Schulze RST.pc01 ring shear tester.
+https://gitext.gfz-potsdam.de/analab-code/rst-evaluation/

RSTpicking/README.md

+# RSTpicking
+Automatic picking procedure including the production of files and plots for a
+datapublication.
+
+## RST_pick_GUI (recommended)
+User interface based script that allows for quick and easy adjustment of
+picking parameters. Furthermore, it is possible to do a full manual picking or
+revise the automatically picked peaks with this script.
+
+### How To Run
+The evaluation is started by downloading the repository and then running the
+script in its folder in the console.
+#### For Windows:
+1. Press `Ctrl+R` and type `cmd`, this opens the command prompt.
+2. Navigate to the folder by using `cd` and the path to the script like so:
+  `cd C:\Users\username\git-repos\rst-evaluation\RSTpicking\`.
+3. Type `python RST_pick_GUI.py` and then the below interface should appear.
+   Leave the command prompt running for the whole duration of the evaluation,
+   otherwise it stops working.
+
+#### For Linux:
+1. Use a file browser to navigate to the folder `RSTpicking`, then right
+   click and select `open Terminal/Bash here`
+2. Type `python3 RST_pick_GUI.py` and then the below interface should appear.
+   Leave the command prompt running for the whole duration of the evaluation,
+   otherwise it stops working.
+
+See below for typical errors.
+
+### The Interface
+![RSTpickGUI.png](https://gitext.gfz-potsdam.de/analab-code/rst-evaluation/-/raw/master/Documentation/RSTpickGUI.png "The main interface")
+
+The above picture shows the main interface and the standard selections based on
+the standard procedure from `RST_main`. It is advised to enable `Review picking
+during run` because the standard options only work well for sand. The project
+name and output folder are automatically generated from the input folder name
+which in our case usually contains an measurement number (`XXX-01`) and a name.
+The user can change the project name and output folder as needed.
+
+The main options in the lower left define what kind of picking should be used
+(automatic/manual or manual with revision). If left in automatic mode, the
+script iterates over all `*.tdms` files in the selected folder and picks the
+yield points according to the procedure outlined in the
+[Documentation](https://gitext.gfz-potsdam.de/analab-code/rst-evaluation/blob/master/Documentation/).
+If `Automatic Picking` is unchecked, the manual picking dialog is shown for
+each measurement. The user has to select each point manually. If `Review
+picking during run` is selected. The user has the opportunity to check the
+automatic picks and repick a specific point before continuing. Furthermore, the
+other options in the leftmost column define which kind of reports should be
+generated. As a standard ASCII-encoded text files with the results and several
+plots are automatically generated and output to the `Output Folder`. Additional
+settings are found in the `More options...` dialog (see below).
+
+### Picking Interface
+![RSTpickGUImanualPick.png](https://gitext.gfz-potsdam.de/analab-code/rst-evaluation/-/raw/master/Documentation/RSTpickGUImanualPick.png "The picking and revision interface")
+
+This is the manual picking and revision dialog. It is based on a standard
+`matplotlib` plot and contains additional buttons to select the points to repick.
+In some cases the automatic picking fails to correctly identify the points,
+therefore a manual inspection is needed. In the example shown above, the filter
+window is too large and smooths the original data too much. As a result the
+user should either change the `smoothwindow` option in the `More options...`
+dialog, or manually repick the `peak` and `static` picks. When repicking a new
+window opens with a cursor for the user to select the approximate location of
+the point. The algorithm then uses the original data around the picked point to
+pick the value more precisely. The exact definition is explained in the
+[Documentation](https://gitext.gfz-potsdam.de/analab-code/rst-evaluation/blob/master/Documentation/).
+The user should also check, whether the value for normal stress fits with the
+values set during the experiment. Due to rounding errors, built-in
+correction factors in the RSTcontrol software or a non-standard normal stress
+interval, sometimes it is not possible to calculate the normal stress
+correctly. When this is the case the user should modify the `prec` option in
+the `More options...` dialog.
+
+### Other Options Dialog
+The additional options that the user can modify for correct evaluation of the
+parameters. The image below shows the default settings.
+![RSTpickGUIoptions.png](https://gitext.gfz-potsdam.de/analab-code/rst-evaluation/-/raw/master/Documentation/RSTpickGUIoptions.png
+"The Other Options Dialog.")
+The parameters annotated in blue are standard values that are mainly defined by
+the ring shear tester and should __not be changed__ by the user, if not advised
+to do so because a different shear cell has been used or a modified leverage
+system was in place. The properties marked in orange are properties that may
+require changing if the tests are either non-standard or the material behaves
+differently than the standard, e.g. when it shows stick-slip behavior.
+
+## RST_main (deprecated)
+Older version that does not support manual picking or revision. Parameters are
+hard-coded and need to be changed directly in the script. This is to maintain
+backwards compatibility with the original data publication and is not going to
+be developed further. Only if there are any major bugs in one of the files this
+is going to be updated. Most functionality is provided by the shared script
+`RST_func.py`.
+
+## Console Output
+During the run you may see several notifications in the Python console:
+
+```
+01_example.tdms read
+.
+.
+.
+xxx_example.tdms read
+```
+This shows which files have been found and read correctly during the import phase.
+
+```
+Automatic analysis successful
+
+```
+This is shown at the end of a successful automatic picking run. In rare cases
+this may fail, but can be circumvented by using manual revision during picking.
+```
+>>> Friction data plotted
+>>> Time series data plotted
+>>> Friction data saved
+```
+This shows that the data has been plot and saved.
+```
+>>> There is no prop file! Going on as usual.
+```
+In some cases one can use a file that contains properties for each measurement,
+such as material content, or density. This will allow a more in-depth material
+characterization using dilational data and density estimation.
+```
+>>> Time series data saved
+```
+This marks the end of the evaluation and shows that the complete dataset has
+been written into a single ASCII-text file for easier import into Excel or
+other spreadsheet software.
+
+## RST_Func
+This file only contains functions for the module to run properly. They may be
+incorporated into other projects easily by importing them, e.g.:
+```Python
+from RST_func import convert
+
+data = convert('~/home/user/somefolder', '008-15_someMeasurement.tdms', configvariables)
+```
+
+To get a simple conversion function that can read the different data formats we
+use at HelTec.
+
+# Troubleshooting
+Here some common problems are outlined and indications for solutions are given.
+
+- `'python' is not recognized as internal or external command, operable program
+or batch file.`
+
+Either Python is not installed on your system, or the folder with `python.exe`
+has not been added to PATH. Please google how to add Python to path in Windows.
+
+- `ModuleNotFoundError` followed by a module name.
+
+If the module name is not `RST_Func` then you probably need to install the
+requirements. This can be done using pip or conda. In some cases the scripts
+are not able to pick up the modules in this project. Please check whether it
+has been started in the correct folder.
+
+- `FileNotFoundError`
+
+If the folder path is given as a relative path, e.g. `'input/'` and
+`RST_pick_GUI` has been started from a different folder it might not be able to
+correctly resolve the path properly. To solve this, one should only use
+absolute paths, such as obtained by the `open file` dialog.