$Id: Readme.txt 2353 2017-02-07 15:08:58Z lendl $

This directory contains Cube examples useful for (unit-) testing the
'cube2mseed' GIPPtools utility.

Note: The programs 'cube2mseed' and 'cube2ascii' share a lot of source code.
      The following test cases may be relevant for the 'cube2ascii' utility 
      as well!


Test 001 -- Single channel Cube data
------------------------------------

  Plain and simple 100Hz, one channel Cube file as recorded by Cube #005.
  No special cases, no silly surprises.

  Note: About 90% of the original recording were removed (and the header as
        well as the trailer block were adjusted accordingly) to speed up
        testing.

  Cube input file:

    001-input.cube

  The output files are named after the command line options used to generate
  them. The first string gives the resampler used (NONE, LINEAR, SINC), which 
  is followed by the fringe sample treatment (SKIP, NOMINAL, CONSTANT). 
  Finally the last string informs about the used timing quality control 
  algorithm. File extension '*.mseed' is used for the "data" in miniSEED 
  format, while '*.error' contains output written to standard error.

  "Rule" based quality control:

    001-none-nominal-rule.mseed
    001-none-constant-rule.mseed
    001-linear-nominal-rule.mseed
    001-linear-constant-rule.mseed 
    001-sinc25-nominal-rule.mseed
    001-sinc25-constant-rule.mseed

  "Fake" time algorithm:

    001-none-nominal-fake.mseed
    001-none-nominal-fake.error


Test 002 -- Backward compatibility & cutting out events
-------------------------------------------------------

  During the field work (project CyprusArc) the Cube #18 lost the GPS signal 
  for several hours and the internal clock drifted. Later, GPS reception 
  returned.

  Although the input data is missing some GPS fixes it does not really test 
  "anything different" that wasn't already tested in Test #001 (see above). 
  However, it remains here as it proofs backward compatibility! (The output 
  file "002-none-nominal-rule.mseed", although renamed, hasn't changed since 
  February 2011.)

  Background: In 2014 the 'cube2mseed' utility was completely rewritten and 
              a "resampler" processing step was added. Unfortunately, the much 
              improved utility is not longer backward compatible! To partly 
              overcome the deficit, an additional "fake" resampler was 
              implemented that more or less "simulates" the behavior of the 
              older GIPPtool releases.

              To obtain this "historic" behavior the changed command line 
              options of the rewritten utility must be used. Specifically, to 
              simulate the old (pre 2014) "NONE" time correction mode 

                    --time-correction=NONE

              the following new (i.e. post 2014) combination of command line 
              options is necessary:

                    --timing-control=RULE_BASED
                    --fringe-samples=NOMINAL
                    --resample=NONE

  The second aspect that is tested using the input file ('002-input.cube')
  is the correct behavior when converting time windows ("events").

  Files: 

    002-input.cube ............... Cube input file.

    002-none-nominal-rule.mseed .. MiniSEED output when running 'cube2mseed' in 
                                   "--resampler=NONE", "--fringe-samples=NOMINAL",
                                   and "--timing-control=RULE_BASED" mode.

    002-cutout.event ............. Event file containing the description of some 
                                   time windows to cut-out.

    002-cutout.error ............. Standard error output. Contains two warnings 
                                   that time windows could not be converted 
                                   because of lack of Cube input data. 

    002-cutout-1.mseed ........... First time window to cut-out.
    002-cutout-2.mseed .......... Second time window to cut-out.
    002-cutout-3.mseed ........... Third time window to cut-out.
    002-cutout-4.mseed ........... Fourth time window to cut-out.
    002-cutout-5.mseed ........... Fifth time window to cut-out.

  Note: As in the previous test case, a large chunk of the original recording
        was removed (of course without compromising the file integrity) to
        speed up testing.


Test 003 -- Two time tags in a row
----------------------------------

  The Cube file in this test case erroneously contains several cases where
  two complete time tag sequences (PPS-SAMPLE, GPS, and DELAY block) follow
  directly after each other! (Usually, one full second of sample data lies
  in between two time tags.) To make things even worse, the two time tags use
  the same time for two different samples.

  Fortunately, the overall number of sample values is actually correct and
  the Cube file can successfully be converted to miniSEED format. (After
  discarding the suspicious time tag information, which is tested here.)

  The creation of this badly formed Cube file was caused by a bad/illegal
  combination of configuration settings (probably 'F_TIME=60', allowed are
  values up to 59 minutes). Nevertheless, the GIPPtools should be able to
  handle this!

  Note: As usual, a large part of the original recording was removed to speed 
        up testing. So, looking at the 'dump' of the Cube file, it seems at 
        first glance that there are three locations (around Cube block #9, 
        #947, and #1001) where two time tags directly follow each other. 
        However, there are actually only two as the first time tag is 
        incomplete (the leading PPS-SAMPLE block is missing)!

    003-double-timetag.cube ... Problematic Cube input file.
    003-double-timetag.dump ... A textual dump of all blocks in the Cube input 
                                for illustration.

    003-channel-0.mseed ....... Converted miniSEED output (channel #0).
    003-channel-1.mseed ....... Converted miniSEED output (channel #1).
    003-channel-2.mseed ....... Converted miniSEED output (channel #2).

  This problem was reported by the friendly people at the Black Forest 
  Observatory (BFO). Thanks!


Test 004 -- Continuous recording over several files
---------------------------------------------------

  The main point of this example is to simulate "day files", i.e. a continuous 
  recording that spans several files. At the same time this is also the simplest
  possible case of a multi-file recording as every file contains enough "good"
  time tags.

  The ten Cube input files contain about one minute of data each. The GPS 
  hardware was continuously powered on during the recording so there is no 
  lack of timing information. None of the recorded (GPS) time tags is "bad",
  everything is straight forward and "easy".

    004-continuous.0.cube
    004-continuous.1.cube
    004-continuous.2.cube
    004-continuous.3.cube
    004-continuous.4.cube
    004-continuous.5.cube
    004-continuous.6.cube
    004-continuous.7.cube
    004-continuous.8.cube
    004-continuous.9.cube

  Resulting miniSEED files (generated using options '--timing-control=LLS', 
  '--resample=NONE', and '--fringe-samples=SKIP')

    004-channel-0.mseed
    004-channel-1.mseed
    004-channel-2.mseed

  Note: No resampling is done in this example to make things easier in case 
        debugging will become necessary. (Input sample values correspond to 
        output file sample values.)


Test 005 -- Underground recording
---------------------------------

  Like in the previous test case, each file contains about one minute of data. 
  However, this time the GPS hardware is configured to run in cycled mode. 
  Consequently, some files do only contain a few or no time tags at all. 

  This test case "simulates" the deployment of Cubes in an underground mine or 
  under water. The instrument picks up some final GPS fixes while being readied 
  in the parking lot. It then is deployed in a location without GPS reception.
  There it records until it is taken back into the range of GPS reception at 
  the end of the experiment. (Or eventually runs out of power while recording).

  To convert the sequence to miniSEED the 'cube2mseed' utility must use the 
  time information contained in one file for the conversion of another file.
  Conceptually, this means that it must treat the Cube input as continuous 
  "trace" instead as separate, single files! (Which is the reason for the
  existence of this test case.)

    005-underground.0.cube ... contains 55 valid time tags (56 raw)
    005-underground.1.cube ... contains 4 valid time tags (4 raw)
    005-underground.2.cube ... no time tags
    005-underground.3.cube ... no time tags
    005-underground.4.cube ... no time tags
    005-underground.5.cube ... no time tags
    005-underground.6.cube ... no time tags
    005-underground.7.cube ... no time tags
    005-underground.8.cube ... no time tags
    005-underground.9.cube ... contains valid 1 time tag (2 raw)

  Resulting miniSEED files (generated using options '--timing-control=LLS', 
  '--resample=NONE', and '--fringe-samples=NOMINAL')

    005-channel-0.mseed
    005-channel-1.mseed
    005-channel-2.mseed

