.. highlight:: rst

.. _data2caps:

#########
data2caps
#########

**Send data in easy-to-change formats to CAPS.**


Description
===========

*data2caps* reads data from file and send them in :ref:`RAW format <sec-pt-raw>`
to a CAPS server. The list of supported file formats can be easily extended
allowing to import almost any custom data file containing time series. The data
samples are converted to integer values. A multiplier can be applied to reach
the desired precision. The multiplier can be passed by the command-line option
:option:`--multiplier`. During data processing the multiplier must be considered.
The best way to do so is to correct the gain in the :term:`inventory` by the
multiplier.

Supported file formats which can be given along with :option:`--format`:

* slist

  .. code-block:: properties

     TIMESERIES AM_ABCDE_00_SHZ_R, 8226 samples, 50 sps, 2020-01-01T10:20:03.862000, SLIST, FLOAT, M/S
     0.000134157
     0.000286938
     ...

  data2caps assumes files with exactly one block of data starting, e.g., with
  *TIMESERIES*. Files containing multiple blocks must be split into multiple
  one-block files before processing these files individually with data2caps. For
  splitting you may use external programs, e.g., csplit.

  Example for processing one file, *vz.data.raw*, containing multiple blocks:

  .. code-block:: sh

     csplit -z vz.data.raw /TIMESERIES/ '{*}'
     for i in xx*; do data2caps -i $i -f flist; done

* unavco

  The format supports tilt and pressure data on the data website of :cite:t:`unavco`
  in the versions

  * version 1.0: Requires to set the network code using :option:`--network` since the
    it is not provided within the data files.
  * version 1.1

  .. note::

    * The versions 1.0 and 1.1 are automatically recognized.
    * If no multiplier is speficied by :option:`--multiplier`, unit conversion is
      applied to the data for maintaining high resolution in :term:`miniSEED` format:

      * hPa : Pa
      * microradians :  nRad

If no input file is given, :program:`data2caps` creates a generic data series and sends
it to the CAPS server.

.. warning::

   The CAPS server to which data2caps should send data to must be up and running.


Examples
========

* Send data from a file in slist format to a CAPS server on *localhost:18003*:

  .. code-block:: sh

     data2caps -H localhost:18003 -i AM.ABCDE.00.SHZ-acc.slist -f slist

* Send tilt data from a file in unavco 1.1 format to a CAPS server on *localhost:18003*.
  The data is automatically converted from myRad (microradiant) to nRad (nanoradiant):

  .. code-block:: sh

     data2caps -H localhost:18003 -i  B2012327816TiltYuRad.txt -f unavco




Command-Line Options
====================

:program:`data2caps [options]`

Options
-------

.. option:: -H, --host arg

   Default: ``localhost``

   Data output host. Format: host:port. Port 18003 is assumed
   if not given explicitly. Default: localhost:18003.

.. option:: -h, --help

   Print help.

.. option:: -i, --input file

   Name of input data file.

.. option:: -f, --format arg

   Values: ``slist,unavco``

   Format of input data file. Supported: slist, unavco.

.. option:: -m, --multiplier arg

   Multiplier applied to data samples for generating integers.

.. option:: -n, --network arg

   Network code to be used for the data. Required for format unavco in
   version 1.0 since this format does not provide a network code.