Conversion
==========


Case 1: FairField FCNT only
---------------------------

This is an example for a project to convert a series of FCNT files to SDS. The software is able to walk recursively in
the subfolders:

.. code-block:: text

   # This is a template config file
   UTM_zone = 34S

   ["data_folders"]

   [["data_folder1"]]
   folder = "/mnt/hard_drive/testdata"
   format = FAIRFIELD_FCNT
   recursive = False

   ["export_to_sds"]
   components = HHZ,HHN,HHE
   sds_root = SDS
   sampling_rates = raw, 50
   response_root = RESP

Step 1
~~~~~~

The next step is to run the ``largen index`` command that will list all files matching ``*.fcnt`` in the ``folder``.
Once files have been listed, they will be read and indexed. The index will be saved in a local ``LARGEN`` folder in the
h5 format. This indexation allows to rapidly access waveform data in the files.

Step 2
~~~~~~

One finished, the ``largen index`` process will output a new file in the project directory called ``metadata.csv``.
If ``UTM_zone`` was provided in the ``config.ini``, the ``X`` and ``Y`` UTM coordinates from the FCNT files are already
converted to Latitude and Longitude.

The next step for the user is to create a copy of the ``metadata_csv`` and call it ``metadata_UPDATED.csv``. In this
file, the user is expected to input the ``seed_id``. Seed IDs are compulsory to convert the FCNT files to SDS. The IDs
need to be provided in the NET.STA.LOC.CHAN format, e.g ``BE.TOM.00.HHZ``, even if the FCNT file contains three
channels (the HHZ will be replaced on the fly when converting or preparing the response files).

The Latitude/Longitude can also be changed in the ``metadata_UPDATED.csv`` files, as the X,Y coordinates in the FCNT
file could be the pre-planned locations, but not the final locations.

Step 3
~~~~~~

``largen convert`` will make use of ``metadata_UPDATED.csv`` to list the files to convert to SDS. This step will convert
the content of FCNT files to SDS, using the ``export_to_sds`` configuration parameters. The ``sampling_rates`` can be
unique (but followed by a comma, e.g. ``50,``) or a list (``raw, 50``). If decimation is required, the input streams
will be filtered using a lowpass Cheby2 filter with maxorder=12 (!not zero-phase!).

Done
~~~~
Once done, you should have three new subfolders: ``LARGEN`` containing the indexes, ``SDS`` containing the converted
data streams (1 subfolder per sampling_rate) and ``RESP`` containing the responses of the FF 5Hz in xseed format (1 file
per channel, thus 3 per station).