Quick Start Guide

Dependencies

The program runs inside a Docker container and will run on any Docker-compatible operating system.

  • Docker

Installation

  1. 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.

  2. Copy the installer that you received from OSOP, respgen-install.sh, to the machine where respGen will run.

  3. 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.

  4. 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
    
  5. 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 respgen after installing and send the new OSOP3-… machine-ID to OSOP for a new key.

  6. 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 named respgen.key.

  7. Configure respGen in /opt/osop/respgen/setup.py (see Configuration parameters explained). Put your data files in /opt/osop/respgen/DATA and refer to them in setup.py as DATA/<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

  1. Edit /opt/osop/respgen/setup.py (see: Configuration parameters explained)

  2. 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 stage1 for stage1e:

    $ 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.