.. highlight:: rst

.. _rifftool:

########
rifftool
########

**CAPS data file analysis tool**


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

The CAPS server uses the RIFF file format for data archiving. :program:`rifftool`
may be used to analyse the RIFF container, check data integrity, print record
statistics and meta data, and to extract raw data stored in the files. The
output depends on the selected operational mode and is written to stdout.

:program:`rifftool` addresses files directly without a request to the
:ref:`CAPS server <sec-caps-server>`. This is in contrast to :ref:`capstool`
which makes server requests. Hence, rifftool can be used to extract data
files to, e.g., in miniSEED format, even if the CAPS server is not operational.


.. csv-table::
   :header: "Mode", "Description"
   :widths: 10,90
   :delim: ;

   chunks;       Dump individual RIFF chunks including size, position and meta information specific to individual chunk type.
   index;        Dump the CAPS record index organized in a B+ tree (BPT).
   data;         Dump the raw data stored in the CAPS records. The format is specific to the record type and different record types may be mixed in one file. E.g., if all records are of type miniSEED then the result will be a miniSEED conform file with the records sorted by sampling time.
   check;        Check data integrity by validating the record order. Additional check assertions may be enabled through parameters.
   records;      Dump meta data of all records.
   gaps;         Dump data gaps found in a file.
   overlaps;     Dump data overlaps found in a file.



Examples
========

* Dump list of record meta data to stdout

  .. code-block:: sh

     rifftool records NET.STA.LOC.CHA.2022.000.data

* Write the raw data stored in the CAPS records to new file

  .. code-block:: sh

     rifftool data NET.STA.LOC.CHA.2022.000.data > data.mseed

* Print gaps to stdout

  .. code-block:: sh

     rifftool gaps NET.STA.LOC.CHA.2022.000.data

* Check data integrity by validating the record order

  .. code-block:: sh

     rifftool check NET.STA.LOC.CHA.2022.000.data




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

:program:`rifftool [options] mode file`

Mode is one of: check, chunks, data, index, gaps, overlaps, records


Check Assertions
----------------

.. option:: --no-gaps

   Assert data file contains no gaps.

.. option:: --no-overlaps

   Assert no overlaps in data file.

.. option:: --no-data-type-change

   Assert no data type changes among records of same data file.

.. option:: --no-sampling-rate-change

   Assert no sampling rate change among records of same data file.