**Time Format Keyword Proposal**

**Background:**

A goal of the PDS label is to describe data in a standardized way such
that generic software can be written to read and manipulate the data
file based on the content of the label. One of the original PDS mandates
was to develop a set of standards that allow data formats to be
described and not prescribed. It was clear that numerous data formats
were already in existence and that pre-existing software (analysis and
display) require data to be in these formats. In addition, different
forms of data inherently lend themselves to different data file
architectures. The flexibility of the PDS label to describe these forms
is it\'s most valuable and saleable asset. PDS does not need to tell
scientists that they must reformat their data into some prescribed
format the way that data systems based on HDF or CDF formats must.

However there is currently a problem with the existing PDS label that is
making the development of generic software for the access and graphic
display of time ordered data sets difficult at best. The time tag within
these data sets is not identified in a machine-readable form. The
present labels must use some combination of the NAME and DESCRIPTION
fields to distinguish time columns within data files unless the time
column is in PDS standard time format. There is a standard value for the
DATA_TYPE keyword that is TIME but this value means PDS formatted time.
Through this oversight, the PDS label is effectively prescribing a time
format for data sets.

**Proposal:**

PPI is proposing a new set of keywords for use in data file labels that
are used to describe the format of time columns (character strings). The
primary new keyword is TIME_FORMAT. This keyword is used to modify the
meaning of the keyword-value pair DATA_TYPE = TIME. It can only be used
in data element (column, field) definitions where the DATA_TYPE is set
to TIME. If the TIME_FORMAT keyword does not appear in the data element
object, then DATA_TYPE=TIME will have the default interpretation of time
in PDS standard time format. This caveat provides backward compatibility
with existing labels. This proposal does not alter in any way the
requirement that catalog data (templates) still require time in PDS
standard format. PDS is fully justified in prescribing the format of
metadata.

The values that TIME_FORMAT can take will be based on a formation rule
construct using a set of element tokens that are themselves are part of
a standard value set. The list of standard value tokens can grow as
needed like any other standard value set. However, since software that
will be written that interprets these tags, it is clearly in our best
interest to define a comprehensive list up front so that future
additions will be minimal.

The label construct will go something like:

OBJECT = COLUMN

NAME = \"START TIME\"

DATA_TYPE = TIME

TIME_FORMAT = \"xxxxxxxxxxxxxxxx\"

BYTES = string length of all characters that form the time tag

.

.

.

END_OBJECT = COLUMN

There is one other keyword (REFERENCE_TIME) that can be used to clarify
the value assigned to TIME_FORMAT.

This proposal contains an initial set of tokens as discussion starting
point. Any character within the specified element (column) that is not
explicitly described by a token is interpreted as a literal character.
Floating-point forms are terminated either by a non-numeric character or
an end of the field (out of bytes). Any precision can be specified. Any
date/time element that is not specified is assumed to be zero. However
by not specifying lower order date/time elements a precision is implied.
The % character is used as the token delimiter at both ends (start/end)
of the proposed tokens. The parsing of the time format string by
software will be made easier by using both leading and trailing
delimiters.

There are two classes of tokens (specific and generic) that are required
to provide the necessary generality. Specific tokens describe values
that are themselves part of a standard value set. Examples are tokens
that describing things like \"month\", \"day of month\", \"hour of
day\", etc. These values are typically character strings or non-negative
integers. Generic tokens are used to describe relative time or date
elements that do not lend themselves to such rigid definitions. Generic
tokens are used to describe numeric time/date elements that may be
positive or negative and whose reference origin may not be a traditional
date/time origin. Examples of time elements that must be described by a
generic token are \'seconds after periapsis\', \'fractional seconds\',
\'fractional day since launch\', etc. A generic token describes a value
that can either be referenced to another value (next largest date/time
token) within the TIME_FORMAT string, or to an origin defined by using
the REFERENCE_TIME keyword. This keyword is used to provide a zero
reference for generic date/time tokens when none is provided within the
data file. The reference \'time\' within the REFERENCE_TIME keyword must
be stated to implied precision of the token it modifies. REFERENCE_TIME
values are given in the PDS standard date/time format
YYYY-MM-DDThh:mm:ss.s\[s\].

The selection of tokens used to describe a time word is non-unique. This
is not a problem or concern. As long as interpretation of the time
format tokens results in a unique time value the time word is properly
described. Both the time format tokens and the elements of a time string
that they identify are explicitly case insensitive. Users should not
attribute any particular meaning to the use of all uppercase in the
token specification below. Spacecraft clock formats are specifically
excluded from this usage. Spacecraft clock values already have a set of
descriptive keywords.

Each of the tokens are described as follows:

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**%YEAR%** is the four-digit integer year token.

**%YR%** is the two-digit integer year token. Values greater then 50 are
referenced to 1900 and values\
less or equal to 50 are referenced to 2000 unless modified by an
REFERENCE_TIME keyword.

**%YEARBC%** is the four-digit integer year BC token.

**%FYEAR%** is the generic fractional year token. There can be any
number of digits before the decimal\
point, however, four should be sufficient for most data sets. If less
than 4 digits precede the decimal\
point, leading zeros are implied. This token may be used to indicate
fractional years since some\
starting date/time by using the REFERENCE_TIME keyword to specify the
reference date/time.\
If the REFERENCE_TIME token is not used, FYEAR is referenced to 0001 AD
for positive\
values and negative values indicate years BC.

**%MM%** is the two-digit integer month token. If only one digit is
found, then a leading zero is implied.\
Valid range is 1-12.

**%MON%** is the three character month abbreviation token from the set

{**JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC**}.

The set is not case sensitive so that **Jan = jan = JAN**.

**%MONTH%** is the full month name (English) token where month is from
the set {**January, February,\
March, April, May, June, July, August, September, October, November,
December**}. The month\
value is not case sensitive so that **May = may = MAY**.

**%DD%** is the two-digit integer day of month token. If only one digit
is found, then a leading zero is\
implied. Valid range is 1-31.

**%DAY%** alias for %DD%

**%DOY%** is a three-digit integer day of year token where Jan 1 = 001.
If less than three digits are found\
then leading zero\'s are implied. Valid range is 1-366

**%DOY1%** alias for %DOY%

**%DOY0%** is a three-digit integer day of year token where Jan 1 = 000.
If less than three digits are found\
then leading zero\'s are implied. Valid range is 0-365

**%FDAY%** is the generic fractional day token. The field is terminated
by a non-numeric character or\
when the column BYTES is reached. FDAY can be either floating point or
integer and can be either

positive or negative. The start (FDAY=0.0) date/time for the generic
FDAY counter can be specified\
by a year elsewhere in the TIME_FORMAT string or by using the
REFERENCE_TIME keyword.\
Julian dates (absolute and relative) are specified by using the FDAY
token and a\
REFERENCE_TIME keyword that specifies the reference date/time.

FDAY can be used with TIME_FORMAT tokens that specify time of day.

**%HR%** is the two digit integer hour of day token. If only one digit
is found, then a leading zero is implied.\
Valid range is 0-23.

**%FHR%** is the generic fractional hour token. The field is terminated
by a non-numeric character or\
when the column BYTES is reached. FHR can be either floating point or
integer and can be either

positive or negative. The start date/time for the generic FHR can be set
elsewhere in the\
TIME_FORMAT string by the next largest time element token (default) or
by using the\
REFERENCE_TIME keyword to specify the reference date/time.

**%MIN%** is the two-digit integer minute of hour token. If only one
digit is found, then a leading zero is\
implied. Valid range is 0-59.

**%FMIN%** is the generic fractional minute token. The field is
terminated by a non-numeric character or\
when the column BYTES is reached. FMIN can be either floating point or
integer and can be either

positive or negative. The start date/time for the generic FMIN can be
set elsewhere in the\
TIME_FORMAT string by the next largest time element token (default) or
by using the\
REFERENCE_TIME keyword to specify the reference date/time.

**%SEC%** is the two-digit second of minute token. If only one digit is
found, then a leading zero is implied.\
The valid range is 0-59.

**%FSEC%** is the generic fractional second token. The field is
terminated by a non-numeric character or\
when the column BYTES is reached. FSEC can be either floating point or
integer and can be either

> positive or negative. The start date/time for the generic FSEC is set
> by the next largest time element token in the TIME_FORMAT string.

**%ESEC%** is the total elapsed fractional seconds (including
leapseconds) since some reference time.

Values can be positive, negative, or zero. The REFERENCE\_ TIME keyword
is used to specify the

date/time origin.

**%USEC%** is the total elapsed fractional UTC seconds (no leapseconds)
since some reference time.

Values can be positive, negative, or zero. The REFERENCE\_ TIME keyword
is used to specify the

date/time origin.

**%MSEC%** is the three-digit integer millisecond of second token. If
less than 3 digits are found, then\
leading zeros are implied. The valid range is 0-999.

**%FMSEC%** is the generic fractional millisecond token. The field is
terminated by a non-numeric\
character or when the column BYTES is reached. FMSEC can be either
floating point or integer and\
can be either positive or negative. The start date/time for the generic
FMSEC is set by the

next largest time element token in the TIME_FORMAT string.

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

Usage Examples:

All representations given below are for the same time.

**1994-08-17T03:31:27.400Z** PDS standard formatted time

TIME_FORMAT = \"%YEAR%-%MM%-%DD%T%HR%:%MIN%:%SEC%.%MSEC%\"

= \"%YEAR%-%MM%-%DD%T%HR%:%MIN%:%FSEC%\"

**August 17, 1994 03:31:27.400**

TIME_FORMAT = \"%MONTH% %DD%, %YEAR% %HR%:%MIN%:%SEC%.%MSEC%\"

**94229 12687.4** Standard date/time form used by PVO mission

TIME_FORMAT = \"%YR%%DOY% %FSEC%\"

**903324087.400** Commonly called Clinetime after Neal Cline

TIME_FORMAT = \"%USEC%

REFERENCE\_ TIME = 1966-01-01T00:00:00.000 - 1 millisecond precision
implied

**1994 228.14684** FDAY takes origin to be 1984-01-01 00:00:00 UT

TIME_FORMAT = \"%YEAR% %FDAY% Value above has 1 second precision

**228.14684** Year omitted in data file, reference time required

TIME_FORMAT = \"%FDAY%

REFERENCE\_ TIME = 1994-01-01T00:00:00 - 1 second precision implied

**Impact:**

The primary impacts of adopting proposal will be in the software and
documentation area. Software that are may be impacted includes TBTOOL,
NASAVIEW, and the label/volume verifier software (VV, SLVTOOL, TOOLD).
Since this software does not affect the interpretation of time in
catalog templates, there should be **NO IMPACT ON THE CATALOG LOADER OR
DATA INGESTION**.

**TBTOOL** - will complain that the label contains an unknown keyword
but will still allow users to view table\
contents. This response has been verified.

**NASAVIEW** - same response as TBTOOL (verified). However, if NASAVIEW
is upgraded to provide a\
graphics capability for tables (already supported for tables generated
from NIMS cubes) then it would be\
natural to allow users to plot tabular data vs. time that would require
a parsing capability for time formats.

**VV** - The label verifier component of this software (SLVTOOL) should
be modified to validate the usage of\
this keyword and it\'s valid values. I expect that w/o modification the
software will simply complain about

an unknown keyword (repeatedly!) and then fail to validate the proper
formation of the value.

**DOCUMENTATION** - Time and time formats are discussed throughout the
various PDS standards\
documents (STANDARDS REF, DATA PREPARER\'S WORKBOOK, DATA DICTIONARY).
All of these\
documents would have to be updated to reflect the impact of this new
keyword/value pair.

**L^3^** - The easiest way to implement the changes in the various PDS
tools is to update the underlying library.\
The parsing of TIME_FORMAT values should be added to L^3^.