$Id: Readme.txt 2273 2016-08-25 13:47:24Z lendl $

This directory contains a set of test files containing "synthetic" time tags
for testing the various "timing quality" control algorithms used by the 
GIPPtools when reading Cube files.

Usually, files containing the input for the JUnit tests are denoted by >all< 
in their filename. Files with >bad< in the filename contain KNOWN bad time 
tags. "Timing quality" filter should always remove them from the input.
To save disk space, the time tags are read from plain text files instead of 
Cube files. 

Important! Depending on it's (configured) sensitivity, a filter may decide to 
remove even more time tags! But no matter what, it should remove at least the 
ones in the >bad< file!

The opposite is true for files containing >good< in their filename. The time 
tags in this selection are KNOWN to be good and should still be there after 
filtering. Again there may be additional >good< time tags in the input.

In other words:   "all" >=  "good" + "bad" !

         (All time tags not necessarily are the sum of good and bad time tags.) 


Note: Most test files in this directory only contain information required for 
      testing the "timing quality" algorithms (the sample ordinal number and 
      sample time). The other information time tags usually contain (such as
      file name and offset, geographic position and elevation) were omitted.


Test 001 -- Perfect continuous timing information
-------------------------------------------------

  About one day of time tags, one every second (simulating a continuously
  running GPS clock). The time was directly computed from the sample rate, 
  so there is absolutely no timing error at all. Consequently, the file 
  usually containing the "bad" time tags is empty!
  
  Files:
  
    001-perfect-timing.all.txt ... all time tags under test
    001-perfect-timing.bad.txt ... known bad tags, in this case an empty file

    001-perfect-timing.bash ...... script used to generate PDF plot.
    001-perfect-timing.pdf ....... plot of the time tags in this test case


Test 002 -- Perfect timing with five outliers
---------------------------------------------

  Like test case #001 but with five bad time tags. The "all" input file was
  created by manually editing the associated time of five randomly selected 
  time tags. Consequently, the "bad" time tag file is not longer empty.
  
   Files:

    002-perfect-outliers.all.txt ... all time tags under test
    002-perfect-outliers.bad.txt ... known bad tags

    002-perfect-outliers.bash ...... script used to generate PDF plot.
    002-perfect-outliers.pdf ....... plot of the time tags in this test case


Test 003 -- Realistic timing information
----------------------------------------
 
  About one day of time tags, one every second (simulating a continuously 
  running GPS clock). To be more realistic, several "real world" complications 
  were added to the "pure" synthetic time (see also test #001 above): 

  - Due to manufacturing imperfections the frequency of the internal oscillator 
    crystal build into Cube units will deviate from the nominal value! As a 
    consequence the actual sampling rate used by the Cube unit will differ 
    slightly from the nominal sample rate. 

    In this file an accumulated drift per day of 10ms is used as estimate for 
    this error. (This represents a worst case scenario. Usually Cubes do 
    perform much more butter.)

  - Temperature is large influence on the accuracy of the oscillator crystal. 
    The file simulates a varying (Cube) clock due to the temperature changes 
    over the day. The temperature is assumed to follow a sine wave causing a 
    maximum time offset of 10 millisecond around noon.

  - Cubes still measure (!) the time. A simulated measurement error (normal 
    distribution, standard deviation of 500 nanoseconds) was added.

  - The Cube hardware records time in multiples of 2.44140625 milliseconds. 
    Consequently, the final times are discretized to the closes multiple of 
    that time period.

  - Time series parameters:
      GPS mode     : continuously (one time tag per second)
      Trace length :   1 day
      Sample rate  : 100 Hz

  Besides the above mentioned "imperfections" the files do not contain any 
  bad (GPS) time tags nor are there outliers of any sort.

  Files:

    003-realistic-timing.all.txt .. all time tags under test
    003-realistic-timing.bad.txt .. known bad tags (an empty file)

    003-realistic-timing.bash ..... script used to generate PDF plot.
    003-realistic-timing.pdf ...... plot of the tags in this test case


Test 004 -- Realistic timing with outliers
------------------------------------------

  Same data base as test case #003 but with added bad time tags ("outliers").

  Files:
  
    004-realistic-outliers.all.txt .. all time tags under test
    004-realistic-outliers.bad.txt .. known bad tags
    
    004-realistic-outliers.bash ..... script used to generate PDF plot.
    004-realistic-outliers.pdf ...... plot of the tags in this test case
   
   
Test 005 -- Cycled GPS with Single Outliers
-------------------------------------------

  Uses basically the same "setup" as the test cases #003 and #004. However,
  instead of continues mode a GPS in cycled mode is simulated.
  
  - Time series parameters:
  
      GPS mode     :   5 minutes GPS "on" during every 55 minute (flush) cycle.
      Trace length :  14 days
      Sample rate  : 200 Hz

  Files:
  
    005-cycled-outliers.all.txt .. all time tags under test
    005-cycled-outliers.bad.txt .. known bad tags
    
    005-cycled-outliers.bash ..... script used to generate PDF plot.
    005-cycled-outliers.pdf ...... plot of the tags in this test case


Test 006 -- Outliers at first/last sample of GPS ON segment
-----------------------------------------------------------

  Small synthetic file with manually added outliers. All outliers are located 
  at the very first or very last sample of a GPS power "ON" segment.
  
  The reasoning behind this test case is that it may be a problem for an 
  algorithm (or rather its implementation) to detect an outlier if the 
  respective time tag is the very first or last element in a list.

  Time series parameters:
  
      GPS mode     :  5 minutes GPS "on" during every 30 minute (flush) cycle.
      Trace length :  6 hours
      Sample rate  : 50 Hz

  Files:
  
    006-first-last-outliers.all.txt .. all time tags under test
    006-first-last-outliers.bad.txt .. known bad tags
    
    006-first-last-outliers.bash ..... script used to generate PDF plot.
    006-first-last-outliers.pdf ...... plot of the tags in this test case


Test 007 -- Large Gaussian noise
--------------------------------

  Each GPS power "ON" segment in this file contains a varying amount (0..100%) 
  of unusable time tags. The respective time tags were made "unusable" by 
  adding a large (5 milliseconds instead of the usual 0.5 microseconds) amount 
  of pseudo random Gaussian noise.

  In this test case, the timing quality filter must not only remove all "noisy"
  time tags but it also needs decide when to discard the whole segment due to
  an overall "suspicious" situation.  
  
  Time series parameters:
  
      GPS mode     :  5 minutes GPS "on" during every 30 minute (flush) cycle.
      Trace length :  6 hours
      Sample rate  : 50 Hz

  Files:
  
    007-gaussian-noise.all.txt ... all time tags under test
    007-gaussian-noise.bad.txt ... known bad tags
    007-gaussian-noise.good.txt .. known good tags
    
    007-gaussian-noise.bash ...... script used to generate PDF plot.
    007-gaussian-noise.pdf ....... plot of the tags in this test case

  Please note that this test case also uses a "known good tags" file!

  