Manipulating Date/Time Data

User Guide > Working with Date/Time Data > Manipulating Date/Time Data

PV‑WAVE provides several functions for manipulating date/time variables. These functions are:

DT_ADD

DT_SUBTRACT

DT_DURATION

CREATE_WEEKENDS

CREATE_HOLIDAYS

LOAD_HOLIDAYS

LOAD WEEKENDS

DT_COMPRESS

Once you have converted your date/time data, you may want to alter it. The manipulation functions provide you with the tools for adding or subtracting date/times, or removing holidays and weekends from your date/time variables. This section briefly describes each of these functions. For more information about these functions, see the PV‑WAVE Reference.

Adding to a Date/Time Variable

You may wish to add any number of date/time units to one or more existing date/time variables with the DT_ADD function. The form of the function is:

result = DT_ADD(dt_value)

Example 1

This example illustrates how to add 30 hours to a single date/time variable to produce a new variable.

; Create a date/time variable.

dtvar = VAR_TO_DT(1992, 12, 31, 15)

; Create a new date/time variable by adding thirty hours to dtvar,

; an existing date/time variable.

dtvar1= DT_ADD(dtvar, Hour = 30)

PRINT, dtvar1

; PV-WAVE prints: { 1993 1 1 21 0 .0000 87768.875 0}

Example 2

The second example shows how to use the DT_ADD function to create a date/time variable that contains all the days of the month of May excluding weekends.

; Creates a date/time variable to read date/time data into.

dates = REPLICATE({!DT}, 21)

; Defines Saturday and Sunday as weekend days.

CREATE_WEEKENDS, ['sun', 'sat']

; Creates an initial date/time variable to use with DT_ADD.

dates(0) = VAR_TO_DT(1992, 5, 1)

; Generates Date/Time structures for the remaining days of the

; month. The Compress keyword excludes the weekend days.

FOR I = 1,20 DO dates(I)= DT_ADD(dates(I-1), /day, /Compress)

Subtracting from a Date/Time Variable

The function DT_SUBTRACT subtracts a value from a date/time variable or array of variables. (This function is very similar to DT_ADD.) The basic form of the function is:

result = DT_SUBTRACT(dt_value)

Example

; Create a date/time variable.

dtvar = VAR_TO_DT(1993, 1, 1, 21)

; Create a new date/time variable by subtracting 30 hours from

; dtvar.

dtvar1= DT_SUBTRACT(dtvar, Hour = 30)

PRINT, dtvar1

; PV-WAVE prints: { 1992 12 31 15 0 0.0000 87767.625 0}

New date/time variable is 30 hours less than dtvar. Notice that for this example the year, month, day and Julian day have changed.

Finding Elapsed Time between Two Date/Time Variables

The DT_DURATION function determines the elapsed time between two date/time variables. The return units are a double-precision value or array of values expressed in days and fractions of days. The function has the form:

result = DT_DURATION(dt_var_1, dt_var_2)

Example

Assume two date/time variables, dtarray and dtarray1, have been created. The contents of dtarray are:

{ 1992 3 17 6 35 23.0000 87478.275 0}

{ 1993 4 18 7 38 47.0000 87875.319 0}

The contents of dtarray1 are:

{ 1989 5 22 9 32 22.0000 86448.397 0}

{ 1995 7 26 10 33 27.0000 88704.440 0}

You can use the DT_DURATION function to find the number of days between corresponding elements of the arrays.

dtdiff = DT_DURATION(dtarray, dtarray1)

PRINT, dtdiff

; PV-WAVE prints: 1029.8771 -829.12130

Note that the function returns a negative number for the second value since the second element in dtarray1 is more recent than the second element in dtarray.

Excluding Days from Date/Time Variables

You can exclude holidays and weekend days from date/time plots using the following functions.

CREATE_HOLIDAYS Procedure

If you wish to skip particular days such as holidays in your plots, first you must define them. The form of the procedure is:

CREATE_HOLIDAYS, dt_list

Example

Assume that you want to exclude Christmas and New Years from a date/time variable.

; Create a variable that contains the dates of holidays you wish

; to exclude.

dates = ['1-1-92', '12-25-92']

; Create a variable that contains the date/time structures for

; Christmas and New Year.

holidays = STR_TO_DT(dates, Date_Fmt = 1)

; Use the CREATE_HOLIDAYS procedure to create and store the

; holidays in the system variable !Holiday_List.

CREATE_HOLIDAYS, holidays

PRINT, !Holiday_List

; PV-WAVE prints the following:

; { 1992 12 25 0 0 0.00000 87761.000 0}

; { 1992 1 1 0 0 0.00000 87402.000 0}

;            .

;            .

; { 0 0 0 0 0 0 0 0 0 0}

note	You can create and store up to 50 holidays. To exclude the holidays from date/time variables, you use the keyword Compress or the system variable !PDT.Compress. The system variable !PDT.Exclude_Holiday must also be set to a value of 1 (the default value).

LOAD_HOLIDAYS Procedure

This procedure is called by the CREATE_HOLIDAYS procedure. It passes the value of the !Holiday_List system variable to the conversion functions. You need to run this procedure after restoring any session in which you used the CREATE_HOLIDAYS function or if you directly changed the value of the !Holiday_List system variable.

CREATE_WEEKENDS Procedure

This function allows you to define certain days of the week to skip when performing date/time operations. CREATE_WEEKENDS defines weekend days and makes this definition available to the conversion functions and procedures. The syntax of the procedure is:

CREATE_WEEKENDS, day_names

note	Do not set all seven days in the week to be weekend days. This will generate an error message.

Example

CREATE_WEEKENDS, ['Saturday', 'Sunday']

; Makes Saturday and Sunday the weekend days.

PRINT, !Weekend_List

1 0 0 0 0 0 1

; The system variable !Weekend_List is an array of integers where

; one = weekend and zero = weekday.

LOAD_WEEKENDS Procedure

This procedure is called by the CREATE_WEEKENDS procedure. It passes the value of the !Weekend_List system variable to the conversion functions. You only need to run this procedure after restoring a session in which you used the CREATE_WEEKENDS function or if you directly changed the value of the !Weekend_List system variable.

note	Do not set all seven days in the week to be weekend days. This will generate an error message.

Example

; Current contents of !Weekend_List system variable.

PRINT, !Weekend_List
; PV-WAVE prints: 0   0   0   0   0   0   1

; Add Sunday to the weekend list.

!Weekend_List = [1, 0, 0, 0, 0, 0, 1]

; Run LOAD_WEEKENDS so the new weekend value will take effect.

LOAD_WEEKENDS

DT_COMPRESS Function

This function compresses an array of date/time values. The function returns an array of floating point values containing the compressed Julian days—all holidays and weekends are removed from the array.

note

This function is only used for specialized plotting applications, such as bar charts. In most cases, you do not need to use this function. Instead use the Compress keyword to remove holidays and weekends from the results of date/time functions and plots. For detailed information, see the description of the DT_COMPRESS function in the PV‑WAVE Reference.

Version 2017.0