Commit 116f452d authored by Michael Rudolf's avatar Michael Rudolf
Browse files

Updated ReadMe files for better documentation

parent 20f71429
# 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.
# RST Evaluation # RST Evaluation
Scripts for analysing shear experiments from the Schulze RST.pc01 ring shear tester. 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 # 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 # 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 # 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. 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 ...@@ -15,4 +51,6 @@ Warsitzka, Michael; Ge, Zhiyuan; Schönebeck, Jan-Michael; Pohlenz, Andre; Kukow
# Citation # Citation
Please cite this repository as: 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/ Rudolf, M., & M. Warsitzka (2019): RST Evaluation - Scripts for analysing shear
\ No newline at end of file experiments from the Schulze RST.pc01 ring shear tester.
https://gitext.gfz-potsdam.de/analab-code/rst-evaluation/
# 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.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment