.. _quickStartGuide:

Quick Start Guide
================== 

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

- Docker

.. _installation:

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 :ref:`configuration`).

5. Make the run script executable: ::

	$ chmod +x run.sh


.. _io:

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: :ref:`configuration`

	.. note:: Learn how to setup your experiment at :ref:`experimentalSetupGuide`

**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: :ref:`interpretation`


.. _execution:

How to execute the program
----------------------------

1. Edit ``setup.py`` (see: :ref:`configuration`)

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 :ref:`dataFlow` & :ref:`backgroundReading`


.. note:: Before you begin processing your own data, we recommend playing with the :ref:`exampleData` to familiarize yourself with respGen.