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.

  2. Clone or download the respGen repository.

  3. Copy setup.py.example to setup.py:

    $ cp setup.py.example setup.py

  4. Edit setup.py to point to your data files and set your processing parameters (see Configuration parameters explained).

  5. Make the run script executable:

    $ chmod +x run.sh

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 setup.py — copy from setup.py.example and edit 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 — output/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 setup.py (see: Configuration parameters explained)

  2. Run the full pipeline:

    $ ./run.sh stage0.py stage1.py stage2.py stage3.py stage4.py

    Or run individual stages one at a time:

    $ ./run.sh stage0.py
$ ./run.sh stage1.py
$ ./run.sh stage2.py
$ ./run.sh stage3.py
$ ./run.sh stage4.py

    To use the simpler least-squares transfer function estimator instead of the robust Pavlis method, substitute stage1e.py for stage1.py.

    To suppress all GUI plot windows (e.g. in a headless or batch environment), add the --no-gui flag:

    $ ./run.sh --no-gui

    This forces the Matplotlib Agg backend, so plots are written to files only and no windows are opened.

The final output of the processing chain is output/out4.response.restored, produced by stage4.py. This is the RESP formatted file containing the instrument response (poles, zeros, and gain) of the unknown sensor.

Note

view_cohe.py is a diagnostic tool and can be run before stage1 to assess input data quality. It calculates and plots the coherence between the two input waveforms — 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.