$Id: Readme.txt 2676 2019-11-28 09:47:14Z lendl $

This directory contains miniSEED examples useful for (unit-) testing the
miniSEED modification program 'mseed2mseed'.


Test 001 -- Modify textual header fields
----------------------------------------

  Uses a simple EDL miniSEED file as input (3 channels with three miniSEED
  records multiplexed into one file). There are no gaps in the time series
  data, no funny channel names nor any other silly surprises.

  001-original.mseed      The original miniSEED input file.
  001-station.mseed       Same as the input file but with "station id" changed
                          from 'e3377' to 'e3399'
  001-channel.mseed       Same as the input file but with "channel id" changed
                          from 'p1' to 'EHN'. The channels 'p0' and 'p2' are
                          not modified.
  001-location.mseed      Almost the same as the input file. This time the
                          "location id" was changed from '11' to '22' for
                          every input record with a "sequence number" of '3'.

                          Note: Changing the "location id" of a single record
                                creates a data stream that is NOT continuous!
                                Consequently, the "sequence number" of the
                                resulting output stream as well as some of the
                                (Steim-1) integration constants change as well!

  001-network.mseed       Same as the input file but with an empty / default
                          "network id". (I.e. the records contain two spaces
                          in place of the "network id")

  001-*.rules             The various rule files can be used to "automatically"
                          edit the original miniSEED file, resulting in the
                          corresponding miniSEED file listed above.


Test 002 -- Modify (binary) record format
-----------------------------------------

  The same simple EDL miniSEED file stored in various formats differing only
  in used "byte order", "record size" and "encoding scheme".

  002-big512steim1.mseed       big endian,  512 byte records, Steim-1
  002-big1024steim1.mseed      big endian, 1024 byte records, Steim-1
  002-big4096steim1.mseed      big endian, 4096 byte records, Steim-1

  002-little512steim1.mseed    little endian,  512 byte records, Steim-1
  002-little1024steim1.mseed   little endian, 1024 byte records, Steim-1
  002-little4096steim1.mseed   little endian, 4096 byte records, Steim-1

  002-big1024steim2.mseed      big endian, 1024 byte records, Steim-2

  002-big8192int32.mseed       big endian, 8192 byte records, 32 bit integer


Test 003 -- Shift start time of record
--------------------------------------

  Test the '--shift-time' command line option. The samples remain the same 
  only the "start time" fields in the miniSEED record change.
  
  003-original.mseed            The "original" miniSEED input file.
  
  003-one-minute-later.mseed    The input file shifted by +60 seconds.
  003-one-minute-earlier.mseed  The input file shifted by -60 seconds.


Test 004 -- Rounding error in start time of record
--------------------------------------------------

  The EDR firmware release 3.35 (maybe others as well?) contains an error 
  concerning the start time of miniSEED records. Apparently, the EDR uses 
  floating point numbers when computing the start time of a miniSEED record. 
  The problem seems to be that the resulting start time value is not rounded 
  correctly but simply truncated. This bug results in (for EDR data logger) 
  Simpossible start times. Example:

     wrong:  21:01:34.299900    correct:  21:01:34.300000
     wrong:  21:01:53.154900    correct:  21:01:53.155000

  These rounding errors do not affect all miniSEED records. The start time of 
  the very first miniSEED record in a file is always correct! Any (but usually 
  not all) following records may contain a faulty start time.
  
  The 'mseed2mseed' utility contains a (hidden) action to correct the bad start 
  time, which is tested here. 

  004-starttime-buggy.mseed   Ten miniSEED records, seven of them with a 
                              erroneous start time.
                                 
  004-starttime-fixed.mseed   The corrected miniSEED file.
  
  
  The roughly three minutes of test data were taken from the "Eifel 2016" 
  experiment, which partly functioned as an instrument test for the EDR 
  loggers as well.
  

Test 005 -- Shift start time of record by 2348548096 seconds
------------------------------------------------------------

  This test checks that shifting the start time of miniSEED records also works
  for very large time shifts. In this context, very large means more than 68 
  years! Or to be more precise, more than 2147483647 seconds, which derives 
  from the Java Integer.MAX_VALUE constant. In other words, the test verifies
  that the "--shift-time" command line argument accepts "Long" values.

  The issue came up when Sigward Funke (Uni Leipzig) had to manually correct 
  some recordings that were erroneously placed in the year 1944. (The cause of 
  the shift was an GPS receiver malfunction but otherwise the recorded data 
  was fine.)

  005-year-1944-buggy.mseed ..... The misplaced recording.
  005-year-2018-correct.mseed ... The same recording with correct start time.


Test 006 -- GPS week number rollover (WNRO) problems
----------------------------------------------------
  
  The GPS system tracks time by using two counters. A week number counter 
  (relative to the GPS epoch) and a milliseconds counter relative to the 
  beginning of the week. Unfortunately, the week number counter is only 
  10 bits long, hence a "rollover" happens every 1024 weeks (about 19.7 
  years). 

  If a GPS receiver is not prepared for this situation (i.e. it's missing a 
  software update) and the time of the recorded will be wrong! Ideally, it 
  simply is off by a full GPS epoch after the week number rollover (WNRO) 
  event.

  Note: The last epoch change of the GPS satellite system was April 6th, 1999.
        However, depending on the build-in GPS receiver firmware, WNRO problems 
        may also occur on another day. (E.g. it happened on July 28th, 1999 for
        the GPS receivers build into the EDLs.)
        
  Unfortunately, there is an additional second problem with EDL loggers. The 
  (unhandled) GPS epoch change on April 6th, 2019 would normally shift newly 
  recorded data by one GPS epoch (i.e. 19.7 years) into the past. So, right 
  after the WNRO the data is seemingly recorded in the year 1999. This is the 
  expected effect of WNRO. However, because the EDL did not exist before the 
  year 2000, the build-in firmware was not designed to  handle dates before 
  2000-01-01. That is why an EDL internal number overflow catapults the 
  recording dates into the year 2031!
  
  The following test case cover the moment when the EDL recorded times shift 
  from 1999 to 2031 ("forward jump") and later, when it shifts from 2031 
  to 2000 ("backward jump").
  
  004-edl-forward-jump-buggy.mseed ... 10 seconds of miniSEED data recording 
                                       the forward time jump.
  004-edl-fowward-jump-fixed.mseed ... The corrected recording.
  
  004-edl-backward-jump-buggy.mseed .. 14 seconds of miniSEED data recording 
                                       the backward time jump.   
  004-edl-backward-jump-fixed.mseed .. The corrected recording
  
  
Test 007 -- Set timing quality
------------------------------

  MiniSEED record may contain a blockette #1001, which offers a (one byte
  long) field to qualify the timing quality of the recording.

  The following files cover several test cases for the 'mseed2mseed' utility,
  when it is used to manipulate the timing quality field.

  007-valid-input.mseed ..... Contains 15 miniSEED records with varying timing
                              quality values set. Specifically, the values for
                              the individual records are:

       Record #000001:   timing quality = N/A   (no blockette #1001)
              #000002:   timing quality =   0   (undefined or bad timing)
              #000003:   timing quality =   1   (bad timing)
              #000004:   timing quality =  10
              #000005:   timing quality =  20
              #000006:   timing quality =  30
              #000007:   timing quality =  40
              #000008:   timing quality =  50
              #000009:   timing quality = N/A   (no blockette #1001)
              #000010:   timing quality =  60
              #000011:   timing quality =  70
              #000012:   timing quality =  80
              #000013:   timing quality =  90
              #000014:   timing quality = 100   (perfect timing)
              #000015:   timing quality = N/A   (no blockette #1001)

  007-invalid-input.mseed .. Contains the same 15 miniSEED records as the
                             "valid input" file above. However, some quality
                             values are not in the valid range from 0 to 100.
                             Instead, the values are larger and cover the
                             range from 0x65 (101%) to 0xFF (255%)!

  Note:  Both input files contain the same continuous data stream. They
         only differ in the timing quality fields. Hence, the output should
         be the same no matter which input file is used.

  Action tests:

  007-set-quality.mseed ........ Timing quality values set to e.g. 55%.
  007-best-quality.mseed ....... Timing quality values set to 100%.
  007-worst-quality.mseed ...... Timing quality values set to 1%.
  007-reset-quality.mseed ...... Timing quality values set to 0.

  There is nothing special about the "action" tests. Timing quality is simply
  set to the respective value.

  Note: A timing quality of zero ('0') functions can also be interpreted as
        an indicator that no timing quality information is available!

 Condition tests:

  007-condition-equal.mseed .... Exactly match the timing quality.
  007-condition-larger.mseed ... Greater than comparison.
  007-condition-less.mseed ..... Less than comparison.
  007-condition-range.mseed .... Combination of less and greater than.

  Note: To achieve a numeric range effect a "more than" and a "less than"
        condition must be combined.
