Date/Time Data

Dates and times are among the many types of information that numerical data can represent. IDL provides a number of routines that offer specialized support for generating, analyzing, and displaying date- and time- based data (herein referred to as date/time data).

Julian Dates and Times

Within IDL, dates and times are typically stored as Julian dates. A Julian date is defined to be the number of days elapsed since noon on January 1, 4713 BCE. Following the astronomical convention, a Julian day is defined to start at 12pm (noon). The following table shows a few examples of calendar dates and their corresponding Julian dates.

Table 13-3: Example Julian Dates
Calendar Date	Julian Date
January 1, 4713 B.C.E., at 12pm	0
January 2, 4713 B.C.E., at 12pm	1
January 1, 2000 at 12pm	2451545

Julian dates can also include fractional portions of a day, thereby incorporating hours, minutes, and seconds. If the day fraction is included in a Julian date, it is represented as a double-precision floating point value. The day fraction is computed as follows:

One advantage of using Julian dates to represent dates and times is that a given date/time can be stored within a single variable (rather than storing the year, month, day, hour, minute, and second information in six different variables). Because each Julian date is simply a number, IDL's numerical routines can be applied to Julian dates just as for any other type of number.

Note
Julian values must be in the range -1095 to 1827933925, which corresponds to calendar dates 1 Jan 4716 B.C.E. and 31 Dec 5000000, respectively.

Precision of Date/Time Data

The precision of any numerical value is defined as the smallest possible number that can be added to that value that produces a new value different from the first. Precision is typically limited by the data type of the variable used to store the number and the magnitude of the number itself. Within IDL, the following guide should be used when choosing a data format for date/time data:

Time values that require a high precision, and that span a range of a few days or less, should be stored as double-precision values in units of "time elapsed" since the starting time, rather than in Julian date format. An example would be the "seconds elapsed" since the beginning of an experiment. In this case, the data can be treated within IDL as standard numeric data without the need to utilize IDL's specialized date/time features.

Date values that do not include the time of day may be stored as long-integer Julian dates. The Julian date format has the advantage of being compact (one value per date) and being evenly spaced in days. As an example, January 1st for the years 2000, 2001, and 2002 can be stored as Julian days 2451545, 2451911, and 2452276. The precision of this format is 1 day.

Date values where it is necessary to include the time of day can be stored as double-precision Julian dates, with the time included as a day fraction. Because of the large magnitude of the Julian date (such as Julian day 2451545 for 1 January 2000), the precision of most Julian dates is limited to 1 millisecond (0.001 seconds).

To determine the precision of a Julian date/time value, you can use the IDL MACHAR function:

; Set date to January 1, 2000, at 12:15pm: 
julian = JULDAY(1,1,2000,12,15,0)  
 
; Get machine characteristics: 
machine = MACHAR(/DOUBLE)  
 
; Multiply by floating-point precision: 
precision = julian*machine.eps 
 
; Convert to seconds: 
PRINT, precision*86400d0

How to Generate Date/Time Data

The TIMEGEN function returns an array of double precision floating point values that represent date/time in terms of Julian dates. The first value of the returned array corresponds to a start date/time, and each subsequent value corresponds to the start date/time plus that array element's one-dimensional subscript multiplied by a step size for a given date/time unit. Unlike the other array generation routines in IDL, TIMEGEN includes a START keyword, which is necessary if the starting date/time is originally provided in calendar (month, day, year) form.

The following example begins with a start date of March 1, 2000 and increments every month for a full year:

date_time = TIMEGEN(12, UNIT = 'Months', $ 
   START = JULDAY(3, 1, 2000))

where the UNIT keyword is set to 'Months' to increment by month and the START keyword is set to the Julian date form of March 1, 2000. The results of the above call to TIMEGEN can be output using either of the following methods:

Using the CALDAT procedure to convert the Julian dates to calendar dates:

CALDAT, date_time, month, day, year 
FOR i = 0, (N_ELEMENTS(date_time) - 1) DO PRINT, $ 
   month[i], day[i], year[i], $ 
   FORMAT = '(i2.2, "/", i2.2, "/", i4)'

Using the calendar format codes:

PRINT, date_time, format = '(C(CMOI2.2, "/", CDI2.2, "/", CYI))'

The resulting calendar dates are printed out as follows:

The TIMEGEN routine contains several keywords to provide specific date/time data generation. For more information, see the "TIMEGEN" (IDL Reference Guide).

Date/Time Data Examples

You can display date/time data on IDLgrAxis objects (through the TICKFORMAT property) plots, contours, and surfaces by setting tick mark attributes. See Displaying Date/Time Data on Axis Objects (Object Programming) and the routines LABEL_DATE and "CONTOUR" (IDL Reference Guide) routine for examples.