Examples

Here we give a few examples of entries in data files and the corresponding Free Time Format variable metadata for reading such files. A comment line for counting columns is included in each example to ease readibility.

!123456789012345678901234567890123456789012345678901234567890
1985-09-11 14:22:46.667  -3.38101     -1.07421     2.34547       
1985-09-11 14:23:06.667  -3.16654     -1.41437     1.90424

This example is in fact taken from a real .qft file which has its time in ISO format. By way of illustration, in Free Time Format, it would have the following header fragment for the time field:

Start_variable = epoch
Column_start = 0
Column_width = 25
! scalar, no Size entry
Data_type = epoch
Time_format = FREE_TIME_FORMAT
TIME_FORMAT_STRING = YYYY-MO-DD HH:MI:SS.sssXX
End_variable = epoch

Note the use of the pad characters `XX' to ensure that the TIME_FORMAT_STRING is 25 characters wide after being stripped of leading and trailing white space. An alternative would be to specify Column_width = 23. The hyphens, space, colons, AND decimal point are all pad characters here which mimic the time string in the data file, thereby reducing the chance of error. We could have written instead

TIME_FORMAT_STRING = YYYYXMOXDDXHHXMIXSSXsssXX

which is much harder to read. Other alternative format strings include:

TIME_FORMAT_STRING = YYYY-MO-DD HH:MI:SS.MCCXX
and
TIME_FORMAT_STRING = YYYY-MO-DD HH:MI:SSSSSSXX
but NOT
TIME_FORMAT_STRING = YYYY-MO-DD HH:MI:SS.SSSXX

This last form would find the first `SS' as the seconds field and IGNORE the `SSS'.

Here is another example:

!123456789012345678901234567890123456789012345678901234567890
940921-Time N Vx Vy Vz 
00:00:05.161  1.482  -218    13   -13 
00:00:17.105  1.543  -216    13   -11

This file needs a header which skips the first two lines (using, e.g. `&2' as the last line of the detached .qfh header or pre-pended .qft header). The date is in the second line, which can not be read directly by QIE, so here we use the `All_records_time' facility:

Start_variable = epoch
Column_start = 0
Column_width = 12
! scalar, no Size entry
Data_type = epoch
YY_offset = 1900
Time_format = FREE_TIME_FORMAT
TIME_FORMAT_STRING = HH:MI:SS.MCC
All_records_format = YYMODD
All_records_time   = 940921
End_variable = epoch

We could have also written:

All_records_format = YYYY-MON-DD
All_records_time =   1994-SEP-21

Another example:

!123456789012345678901234567890123456789012345678901234567890
 94 207 JUL 26  04:10:22.046  0   16    0.40599    0.01591

Coping with the leading space character is achieved either by using

Column_start = 1
Column_width = 27
YY_offset = 1900
TIME_FORMAT_STRING = YY Doy XXX XX  HH:MI:SSSSS

or

Column_start = 0
Column_width = 28
YY_offset = 1900
TIME_FORMAT_STRING = XYY Doy XXX XX  HH:MI:SSSSS

and we could have picked up the month/day instead of the date:

YY_offset = 1900
TIME_FORMAT_STRING = XYY XXX MON DD  HH:MI:SSSSS

One final example:

!123456789012345678901234567890123456789012345678901234567890
1985-09-11 14:22:46.667 ,-3.381,2.43,27.987
1985-09-11 14:23:06.667 ,-3.16654,1.346,5.793

This is a comma delimited file (.qfd), and can be read by:

Start_variable = epoch
! scalar, no Size entry
Data_type = epoch
Time_format = FREE_TIME_FORMAT
TIME_FORMAT_STRING = YYYY-MO-DD HH:MI:SS.sssX
End_variable = epoch

Here the trailing X is ESSENTIAL, as the time variable will be read in as a string up to the delimiting comma. Also, if instead it were a space delimited file, we could not read it as the date and time components would end up in two variables.

Reading flat files requires accurate header writing, and this is doubly so for Free Time Formats which depend critically on position and case. We recommend headers be checked by running Qtran to convert, for example, the .qft file (or if a large file just the first few records) with a Free Time Format specification into a .qfd file using the command Qtran -od $<$file$>$ and visually comparing the results prior to, e.g., reading directly into Qsas or converting to cdf.