Custom Output Format Help

SPICE and WebGeocalc support user-specified custom output time formats. All format specifications — called format “pictures” — supported by the SPICE routine TIMOUT are allowed.

An overview of format pictures is given here; full details are provided in the API documentation of TIMOUT.

Format picture

A format picture is simply a string of characters that lets WebGeocalc know where various components of a time representation should be placed during creation of the time string.

Note: format pictures are CASE SENSITIVE. For example, the (lower case) string

    yyyy

is not recognized and will simply be copied into the output string.

Here's an example of a format picture:

    MON DD,YYYY  HR:MN:SC.#### (TDB) ::TDB

Here is a sample of the times that would be created by using this format.

    JAN 12,1992  12:28:18.2772 (TDB)
    FEB 13,1994  23:18:25.2882 (TDB)
    AUG 21,1995  00:02:00.1881 (TDB)

Here's an example of a UTC day-of-year format picture:

    YYYY-DOY/HR:MN:SC.###

An example of a time string created using this format is:

    2002-012/12:27:14.092

Note that the time system is assumed to be UTC when it's not specified in the picture.

Here's an example of a TDB Julian date format picture:

    JULIAND.###### (TDB) ::TDB

An example of a time string created using this picture is

    2452287.019655 (TDB)

As you can see from the samples above for the first format picture

    MON DD,YYYY  HR:MN:SC.#### (TDB) ::TDB

this format picture specifies that output time strings begin with a three-letter abbreviation for the month, followed by a space and the day of the month. The day of month is followed immediately by a comma and the year. The year component is followed by two spaces. Next are the output hours, represented as a two digit integer, a colon, minutes as a two digit integer, another colon, and seconds rounded to 4 decimal places and having a two digit integer part. This is followed by a space and the string "(TDB)". The special marker "::TDB" in the time picture is an “invisible” marker. It is used to specify the time system that should be used in creating the time string (in this case Barycentric Dynamical Time).

WebGeocalc does not recognize all of the parts of the time format picture in the example above. The list of recognized parts and unrecognized parts are listed in the table below.

    Recognized       Unrecognized
    ----------       ------------
    "MON"            " "
    "DD"             ","
    "YYYY"           "  "
    "HR"             ":"
    "MN"             "(TDB)"
    "SC"
    ".####"
    "::TDB"

The unrecognized parts are called literal markers. They are copied exactly as they appear in the picture into the output string. The recognized parts of the picture are replaced by a component of time or, as in the case of "::TDB", are used as instructions about the overall properties of the time string.

The full list of recognized markers, their classification and meaning are given below.

    MARKER        CLASS      MEANING
    -----------   --------   -----------------------------------------
    ".##..."      modifier   represents a numeric component that
                             immediately precedes this in a decimal
                             format. Number of decimal places
                             equals the number of "#" characters

    "::GCAL"      meta       dates are reported in Gregorian Calendar

    "::JCAL"      meta       dates are reported in Julian Calendar

    "::MCAL"      meta       dates after 15 October, 1582 are reported
                             in Gregorian Calendar, before that
                             dates are reported in Julian Calendar

    "::RND"       meta       round output to places specified by
                             the least significant component

    "::TDB"       meta       all components should be TDB

    "::TDT"       meta       all components should be TDT (TT)

    "::TT"        meta       all components should be TT (TDT)

    "::TRNC"      meta       truncate all output components (default)

    "::UTC"       meta       all components should be UTC (default)

    "::UTC+h:m"   meta       all components in UTC offset by +h (hours)
                             and +m (minutes) so as to allow time zones

    "::UTC-h:m"   meta       all components in UTC offset by -h (hours)
                             and -m (minutes) so as to allow time zones

    "AMPM"        string     String (either "A.M."  or "P.M.")
                             indicating whether hours are before
                             or after noon

    "ampm"        string     String (either "a.m."  or "p.m.")
                             indicating whether hours are before
                             or after noon

    "AP"          numeric    AM/PM equivalents of the hour component
                             of a time

    "DD"          numeric    Day of month

    "DOY"         numeric    Day of year

    "ERA"         string     String (either "B.C."  or "A.D.") giving
                             era associated with an epoch

    "?ERA?"       string     String: either "B.C." or "A.D." if the
                             year is before 1000 A.D., otherwise a
                             blank: " "

    "era"         string     String (either "b.c."  or "a.d.") giving
                             era associated with an epoch

    "?era?"       string     String: either "b.c." or "a.d." if the
                             year is before 1000 A.D., otherwise a
                             blank: " "

    "HR"          numeric    hour component of time

    "JULIAND"     numeric    julian date component of time

    "MM"          numeric    numeric representation of month component

    "MN"          numeric    minute component of time

    "MON"         string     upper case three letter abbreviation for
                             month

    "Mon"         string     capitalized three letter abbreviation for
                             month

    "mon"         string     lower case three letter abbreviation for
                             month

    "MONTH"       string     upper case full name of month

    "Month"       string     capitalized full name of month

    "month"       string     lower case full name of month

    "SC"          numeric    seconds component of time

    "SP1950"      numeric    seconds past 1950 component of time

    "SP2000"      numeric    seconds past 2000 component of time

    "YR"          numeric    last two digits of year component of time

    "YYYY"        numeric    year component of time

    "WEEKDAY"     string     upper case day of week

    "Weekday"     string     capitalized day of week

    "weekday"     string     lower case day of week

    "WKD"         string     upper case three letter abbreviation for
                             day of week

    "Wkd"         string     capitalized three letter abbreviation for
                             day of week

    "wkd"         string     lower case three letter abbreviation for
                             day of week

The details of each of the marker classes presented in the list above is provided in the following table:

Marker class	Description
string	String markers are portions of the format picture that will be replaced with a character string representing the corresponding component of a time.
numeric	Numeric markers are portions of the format picture that will be replaced with a decimal string that represents the corresponding component of a time.
meta	Meta markers (listed under the class “meta” in the table above) are used to indicate "global" properties of your time string. You may specify the time system and how rounding should be performed on the components of time in your output string. Meta markers may be placed anywhere in your format picture. They do not contribute to placement of characters in output time strings. Also there are no restrictions on how many meta markers you may place in the format picture. However, if you supply conflicting meta markers (for example `"::TDT"` and `"::TDB"`) in your picture the first marker listed (in left to right order) overrules the conflicting marker that appears later in the picture.
modifier	The numeric markers listed in the table above stand for integers unless they are modified through use of a modifier marker. The strings .# .## .### .#### are used to this end. When a numeric marker is followed immediately by one of these modifiers, the corresponding time component will be written with the number of decimal places indicated by number of successive occurrences of the character `"#"`. Any numeric token may be modified.

Default behaviour with no Meta Markers

Even without a time system maker, WebGeocalc will produce the expected result as it uses the time system selected in the Time system drop-down manu. For convenience, the applied time picture is provided in the list of Input Values on the Results.

If you do not specify a calendar or time zone through the use of a Meta Marker, WebGeocalc uses the default calendar, which is the Gregorian calendar. By default, no time zone offset is used.

By default, all components of time are truncated to the precision specified by the marker or any modifier.

Rounding vs. Truncation

The meta markers "::TRNC" and "::RND" allow you to control how the output time picture is rounded. If you specify "::TRNC" all components of time are simply truncated to the precision specified by the marker and any modifier. If you specify "::RND" the output time is rounded to the least significant component of the format picture. The default action is truncation.

Whether an output time string should be rounded or truncated depends upon what you plan to do with the string. For example suppose you simply want to get the calendar date associated with a time and not the time of day. Then you probably do not want round your output. Rounding 1992 Dec 31, 13:12:00 to the nearest day produces 1993 Jan 1. Thus in this case rounding is probably not appropriate.

However, if you are producing output for plotting using Julian Date, seconds past an 1950 or or seconds past 2000, you will probably want your output rounded so as to produce a smoother plot.

Time Systems

WebGeocalc Custom Format can produce output strings for each epoch relative to any of the systems UTC, TT or TDB, or TDB, either by using one of the Meta Markers "::UTC", "::TT", "::TDT", or "::TDB" respectively, or without any time system Meta Marker. In the later case, WebGeocalc will use the requested Time system.

If a time system Meta Marker is used, this shall be compatible with the selected Time system. Note that TDT and TT are equivalent time systems and both could be used as Meta Markers when TDT is the requested Time system.

Time Zones

The meta markers "::UTC+h:m" and "::UTC-h:m" allow you offset UTC times so that you may represent times in a time zone other than GMT. For example you can output times in Pacific Standard time by placing the meta-marker "::UTC-8" in your format picture.

For example if you use the picture

    YYYY Mon DD, HR:MN:SC ::UTC

you will get output strings such as:

    1995 Jan 03, 12:00:00

If you use the picture

    YYYY Mon DD, HR:MN:SC ::UTC-8

you will get output strings such as:

    1995 Jan 03, 04:00:00

Finally, if you use the picture

    YYYY Mon DD, HR:MN:SC ::UTC-8:15

you will get output string

    1995 Jan 03, 03:45:00

Note that the minutes are always added or subtracted based on the sign present in the time zone specifier. In the case of "::UTC+h:m", minutes are added. In the case "::UTC-h:m", minutes are subtracted.

The unsigned part of the hours component can be no more than 12. The unsigned part of the minutes can be no more than 59.

Calendars

The calendar currently used by western countries is the Gregorian calendar. This calendar begins on Oct 15, 1582. Prior to Gregorian calendar the Julian calendar was used. The last Julian calendar date prior to the beginning of the Gregorian calendar is Oct 5, 1582.

The primary difference between the Julian and Gregorian calendars is in the determination of leap years. Nevertheless, both can be formally extended backward and forward in time indefinitely.

By default WebGeocalc uses the Gregorian calendar. However you may specify that WebGeocalc use a specific calendar through use of one of the calendar Meta Markers: "::JCAL" for the Julian calendar, "::GCAL" the Gregorian calendar or "::MCAL" for a mixture of both.

If you specify "::MCAL", epochs that occur after the beginning of the Gregorian calendar will be represented using the Gregorian calendar, and epochs prior to the beginning of the Gregorian calendar will be represented using the Julian calendar.