DT_COMPRESS Function

Identifies previously defined weekends and/or holidays within an array of date/time variables.

Usage

result = DT_COMPRESS(dt_array)

Input Parameters

dt_array — A date/time variable containing an array of date/time structures.

Returned Value

Returns an array of the double-precision Julian values from the array of date/time structures, with those values corresponding to weekends and/or holidays marked for easy removal.

Keywords

SetToZero — The Julian values that correspond to weekends and/or holidays are set to 0.00. All other values are unchanged. This keyword is OFF by default.

Discussion

By default, this function is primarily used to generate compressed date/time data for specialized, user-written plotting applications, such as bar charts. If the XType keyword is set to 2, the compressed data can be used with the OPLOT Procedure and PLOT Procedures .

Note: Avoid using DT_COMPRESS for normal XY plotting with the PLOT and OPLOT commands. Use the Compress keyword with PLOT and OPLOT to create compressed date/time results.

The value of the system variables !PDT.Exclude_Holiday and/or !PDT.Exclude_Weekend must be set to one (the default) before DT_COMPRESS is called. In addition, the CREATE_WEEKENDS Procedure and CREATE_HOLIDAYS Procedure must be run before you use DT_COMPRESS.

Note that the result of DT_COMPRESS is a double-precision array of Julian days, not another array of !DT structures.

By default, this routine resets the decimal portion of the Julian days it extracts from the input date/time array to .0 for normal days and to .5 for weekends and/or holidays. This can lead to inconsistent Julian values which may not correspond to the original dates and times in the input date/time array and are suitable only for the specialized plotting routines mentioned above. This behavior is maintained for backwards compatibility only. We recommend that you use the SetToZero keyword.

When the SetToZero keyword is set, the returned array of Julian values contains zeros (0.00) for elements corresponding to weekends and/or holidays in the input date/time array. The Julian values for non-weekend/holiday elements are unchanged. You can then pass this array, to the JUL_TO_DT Function to generate a new array of date/time variables. The weekends and/or holidays in the new date/time array contain a Julian day value of 0.00 and may be passed to the standard PV-WAVE plotting routines. The excluded days appear on the plot with no data associated with them.

Alternatively, you can use the WHERE Function on the Julian array returned by DT_COMPRESS with the SetToZero keyword set to generate a list of indices into the input date/time array that you then use to generate a new date/time array which does not contain the excluded days. Again, this new date/time array is suitable for use with standard PV-WAVE XY plotting routines.

Example 1

This example demonstrates how DT_COMPRESS can be used to compress the weekend days from a date/time variable containing the days in the month of March, 1992. The resulting array of compressed Julian numbers is then processed so that it can be used to create a date/time plot in a specialized plotting application.

; Create and print out a variable march1 which is a date/time 
; variable. Note the Julian Day carefully, 87462. 
; After compression, this value will be smaller.
; This is because all the weekends from Julian day 1
; (September 14, 1752) are compressed.
march1 = VAR_TO_DT(1992, 3, 1, 11, 30, 0)
PRINT, march1
; PV-WAVE prints: { 1992 3 1 11 30 0.00000 87462.479, 0}

; Generate date/time array containing the 31 days of March, 1992.
marray = DTGEN(march1, 31, /Day)
PRINT, marray

; Define Saturday and Sunday as weekend days.
CREATE_WEEKENDS, ['Saturday', 'Sunday']
 
; Create and print out a compressed array for the month of
; March, 1992. Weekend (compressed) days can be identified
; by fraction .5. 
; Note that the values of the weekend days fall between the end
; and beginning of the week. Also note that the Julian numbers
; are smaller than in the original array. This is because all
; of the weekends from Julian day 1 are compressed.
cmarray = DT_COMPRESS(marray)
PRINT, cmarray

Example 2

This example defines some holidays for the year 1992 with the CREATE_HOLIDAYS procedure, creates an array with all the days of the year, and then excludes these holidays using the DT_COMPRESS function.

; Create and print out a date/time variable for Christmas. 
; The purpose is to show the Julian day before using
; DT_COMPRESS. Note the Julian Day is 87761.
christmas = VAR_TO_DT(1992, 12, 25)
PRINT, christmas
; PV-WAVE prints: { 1992 12 31 0 0 0.00000 87761.000 0}

; Create a variable day1 which is used to generate an array that 
; contains all the days of the year (where 366 is used because
; 1992 is a leap year).
day1 = VAR_TO_DT(1992, 1, 1)

; Create an array containing date information for the following 
; holidays: New Years, Memorial day, Fourth of July, Labor Day,
; Thanksgiving, and Christmas.
yarray = DTGEN(day1, 366)
x = ['1-1-92', '5-31-92','7-4-92', $
'9-1-92', '11-24-92', '12-25-92']

; Create a date/time variable for the holidays.
holidays = STR_TO_DT(x, Date_Fmt=1)

; Define holidays by setting the !Holiday_List system variable.
CREATE_HOLIDAYS, holidays

; Create an array that excludes the holidays for 1992. The 
; compressed array cyarray appends the .5 decimal to all of the 
; holidays. Non-holidays end in .0.
; When you print out cyarray, note the Julian day for Christmas
; is 87755.5. This is six days less than for the yarray, because
; six holidays were defined and compressed out of the result.
cyarray = DT_COMPRESS(yarray)

Example 3

This example defines some holidays and weekends for the year 2015 with the CREATE_HOLIDAYS and CREATE_WEEKENDS procedures, creates an array with all the days of the year, and then removes these holidays and weekends using the DT_COMPRESS function with the SetToZero keyword set.

christmas = VAR_TO_DT(2015, 12, 25)
PRINT, christmas

day1 = VAR_TO_DT(2015, 1, 1)
yarray = DTGEN(day1, 365)

; Create an array containing date information for the following 
; Holidays in 2015: New Years, Memorial day, Fourth of July, Labor Day,
; Thanksgiving, and Christmas.
x = ['1-1-2015', '5-25-2015','7-4-2015', '9-7-2015', '11-26-2015', '12-25-2015']
holidays = STR_TO_DT(x, Date_Fmt=1)
CREATE_HOLIDAYS, holidays

; Define Saturday and Sunday as weekend days.
CREATE_WEEKENDS, ['Saturday', 'Sunday']

; Create a Bar chart for the month of December.
WINDOW, 1, Xsize=1000, Ysize=300
cyarray = DT_COMPRESS(yarray, /SetToZero)
x = INDGEN(31)+1
!X.Margin = [18, 3]
BAR, cyarray(334:364), Xtickname=x, Title='Holidays and Weekends in December 2015', $
   XTitle='December', Ytickname = ['Holiday/Weekend', 'Workday']
; Reset !X.Margin to default values
!X.Margin = [10, 3]

; Use the WHERE function to generate a list of indices into the input date/time array.
index = WHERE(cyarray EQ 0, count)
PRINT, index