Quick Start Guide¶
Dependencies¶
The program runs inside a Docker container and will run on any Docker-compatible operating system.
Docker
Installation¶
Make sure you have Linux and Docker installed: a Linux computer, or a Linux virtual machine (Hyper-V, VirtualBox, VMware). WSL 2 on Windows and Docker Desktop do not work: they don’t expose the hardware ID the license is tied to.
Copy the installer that you received from OSOP,
respgen-install.sh, to the machine where respGen will run.From a command line run:
$ chmod +x respgen-install.sh $ sudo ./respgen-install.sh
This creates
/opt/osop/respgen(configuration, data and results), with the example data in/opt/osop/respgen/EXAMPLE-DATA, and/opt/osop/license.To generate the license machine-ID OSOP needs to create your license key, start respGen on each machine where it is expected to run:
$ sudo respgen
The license machine-ID is printed to the screen (and the program quits). For example:
❌ respgen license: no license file found. Send this machine ID to OSOP to obtain a license: OSOP3-YMEQ-SC2H-MV9F-T87B-2J9X Save the license file you receive as /opt/osop/license/respgen.key
Send the machine-ID of each computer to OSOP. The machine-ID belongs to the computer: it stays the same when you reinstall or update respGen.
Note
Updating from an older respGen version? Its license key does not work with this version. Run
sudo respgenafter installing and send the newOSOP3-…machine-ID to OSOP for a new key.OSOP will generate a license key for each computer and send them to you. Save each key on the corresponding computer in the directory
/opt/osop/license/. Make sure it is namedrespgen.key.Configure respGen in
/opt/osop/respgen/setup.py(see Configuration parameters explained). Put your data files in/opt/osop/respgen/DATAand refer to them insetup.pyasDATA/<file name>.
Input/ Output¶
- Input:
RESP-formatted text files — the manufacturer’s responses of the known and unknown sensor. The RESP file of the unknown sensor is optional.
miniSEED-formatted binary files — the waveforms collected from side-by-side known and unknown sensors. Your data must be in miniSEED format. If your data is not in miniSEED format, there are converters available from ORFEUS: http://www.orfeus-eu.org/software/waveform_conversions.html
Settings from
/opt/osop/respgen/setup.py— created by the installer; edit it to set input files and parameters. For full details see: Configuration parameters explained
Note
Learn how to setup your experiment at Experimental Setup Guide
- Output:
Plots — each stage plots the result of its work
RESP-formatted text file —
/opt/osop/respgen/out4.response.restored— the final output of the processing chain, containing the instrument response (poles, zeros, and gain) of the unknown sensor.
Note
see also: Interpreting the results
How to execute the program¶
Edit
/opt/osop/respgen/setup.py(see: Configuration parameters explained)Run the full pipeline:
$ sudo respgen
This runs stage0, stage1e, stage2, stage3 and stage4 in order. Or run individual stages one at a time:
$ sudo respgen stage0 $ sudo respgen stage1e $ sudo respgen stage2 $ sudo respgen stage3 $ sudo respgen stage4
stage1e is the default transfer function estimator. To use the Pavlis robust averaging method instead, substitute
stage1forstage1e:$ sudo respgen stage0 stage1 stage2 stage3 stage4
Plot windows open when respGen runs in a desktop session. Without a display (e.g. over SSH) the stages still run and write their results, but no plots are shown. You can redraw a stage’s plots later with
sudo respgen view0…sudo respgen view4.
The final output of the processing chain is /opt/osop/respgen/out4.response.restored, produced by stage 4. This is the RESP formatted file containing the instrument response (poles, zeros, and gain) of the unknown sensor.
Note
Stage 0 also plots the coherence between the two input waveforms. Check it before continuing: coherence should be close to 1.0 across the frequency band of interest for reliable results.
For more details see Data flow & execution design & Recommended background reading
Note
Before you begin processing your own data, we recommend playing with the Example Data to familiarize yourself with respGen.