Example 9.14 Incrementing a Date by an Interval

Goal

Increment a date by a specific interval such as days, weeks, months, or years. For each starting date, specify the number of times to increment the starting date and the interval to increment it by.

Example Features

Input Data Set

Data set SCHED_APPTS has a list of appointments for nine patients and information about scheduling new appointments for them. The values of variable APPTDATE are SAS date values, and they are formatted in the listing with the WORDDATE format. The other variables are described in the Example Overview.

                          SCHED_APPTS

 Obs patient          apptdate interval units nappts alignment
  1   CVM4   Wed, Feb 20, 2008 week        1     3     same
  2   JD3A   Fri, Jan 25, 2008 week2       1     3     same
  3   QI1U    Tue, Feb 5, 2008 week       10     2     same
  4   W23V   Mon, Jan 21, 2008 weekday    10     2     same
  5   AB5U   Wed, Jan 30, 2008 month       1     2     same
  6   PO6I   Fri, Feb 15, 2008 month       7     1
  7   JA1L   Fri, Feb 15, 2008 month       6     1     end
  8   U21B   Fri, Feb 15, 2008 semiyear    1     1
  9   TN62   Thu, Jan 10, 2008 qtr         1     3

Resulting Data Set

                                 Example 9.14 NEXT_APPTS

  Obs  patient           apptdate          nextappt1          nextappt2           nextappt3

   1    CVM4    Wed, Feb 20, 2008  Wed, Feb 27, 2008   Wed, Mar 5, 2008   Wed, Mar 12, 2008
   2    JD3A    Fri, Jan 25, 2008   Fri, Feb 8, 2008  Fri, Feb 22, 2008    Fri, Mar 7, 2008
   3    QI1U     Tue, Feb 5, 2008  Tue, Apr 15, 2008  Tue, Jun 24, 2008                   .
   4    W23V    Mon, Jan 21, 2008   Mon, Feb 4, 2008  Mon, Feb 18, 2008                   .
   5    AB5U    Wed, Jan 30, 2008  Fri, Feb 29, 2008  Sat, Mar 29, 2008                   .
   6    PO6I    Fri, Feb 15, 2008   Mon, Sep 1, 2008                  .                   .
   7    JA1L    Fri, Feb 15, 2008  Sun, Aug 31, 2008                  .                   .
   8    U21B    Fri, Feb 15, 2008   Tue, Jul 1, 2008                  .                   .
   9    TN62    Thu, Jan 10, 2008   Tue, Apr 1, 2008   Tue, Jul 1, 2008    Wed, Oct 1, 2008

Example Overview

The following DATA step shows several applications of the INTNX function, which can increment date and time values by specific intervals. It uses the INTNX function to schedule appointments.

Data set SCHED_APPTS has appointments for nine people. The DATA step schedules one or more new appointments for these nine people based on information that is supplied in each person's observation.

Variable APPTDATE stores the initial appointment date and it is the starting point from which to generate new appointment dates. The second argument to the INTNX function call in the DATA step is APPTDATE.

The following four variables control how the DATA step generates new appointment dates. Three of the variables, INTERVAL, UNITS, and ALIGNMENT, are arguments to the INTNX function.

• INTERVAL, which contains the date interval in which to increment APPTDATE. It is the first argument to INTNX. The values of INTERVAL are keywords that are recognized by INTNX. The interval value that is supplied to INTNX can include a numeric suffix that serves as a multiplier of the interval value.

• UNITS, which specifies the number of intervals of the type that are specified by variable INTERVAL to increment the date. It is the third argument to INTNX.

• ALIGNMENT, which specifies the position within the interval in which to select the new appointment date. It is the fourth argument to INTNX. The values of ALIGNMENT are keywords that are recognized by INTNX.

• NAPPTS, which is the number of new appointments to generate. The DATA step is written to expect the value to be between 1 and 3 inclusively.

The DATA step can create up to three new appointments. The new dates are saved in variables NEXTAPPT1, NEXTAPPT2, and NEXTAPPT3.

"Understanding the Processing of the INTNX Function in This Example" in the "A Closer Look" section provides details about how the specifications that are supplied to INTNX determine the new appointment dates.

Program

Create data set NEXT_APPTS. Read the observations in SCHED_APPTS.

Specify an array that contains the starting appointment date and the new appointment dates.

When an alignment within the date interval is not specified, default to the beginning of the interval, which is also the SAS default for INTNX. Iterate a DO loop the number of times equal to the number of appointments to make. Using the current element of the ALLAPPTS array, generate a new appointment date and save it in the next element of the APPAPPTS array. On the first iteration of the DO loop, start with APPTDATE. On iterations after the first, use the previously generated appointment date as the starting date. Determine the next appointment date based on the date interval in INTERVAL. Increment from the starting date the number of units of the date interval as specified in UNITS. Position the new date within the interval according to the value of ALIGNMENT.

data next_appts;
  set sched_appts;

  keep patient apptdate nextappt1-nextappt3;
  array allappts{*} apptdate nextappt1-nextappt3;

  format nextappt1-nextappt3 mmddyy10.;
  if alignment=' ' then alignment='beginning';


  do i=1 to nappts;


    allappts{i+1}=intnx(interval, allappts{i},
                        units, alignment);

  end;
run;

A Closer Look

Understanding SAS Date and Time Intervals

A SAS date or time interval is a unit of measurement that SAS can count within an elapsed period of time, such as days, months, or hours. SAS determines date and time intervals based on fixed points on the calendar, the clock, or both.

Functions INTNX and INTCK both accept date and time intervals as arguments. The interval specifications are coded the same way for both functions. The INTNX function as shown in this example's DATA step shifts a date value or time value based on the interval that is supplied to it. The INTCK counts the number of intervals between two date or time values. Example 9.13 showed how to use INTCK to determine a person's age by counting the months between the date of birth and another date.

Coding of intervals that are supplied to these functions can be complex. An understanding of how SAS determines the start of an interval is necessary to correctly shift a date or time value and accurately count the number of intervals between two date or time values.

SAS defaults to the beginning of the interval in which the starting date value or starting time value falls. Depending on the other arguments to the function, this point might not be the actual starting date. For example, if you are shifting a date by months, SAS determines the starting point of the interval to be the first of the month of that date regardless of where the date actually is within that month. For example, when using MONTHS as the interval, SAS determines that the number of months between March 31, 2009, and May 1, 2009, is 2. The following DATA step shows how to write the INTCK function to calculate the number of months between these two dates.

data _null_;
  nmonths=intck('months','31mar2009'd,'1may2009'd);
  put nmonths=;
run;

When the INTNX function shifts a date or time value by an interval, SAS by default aligns the new value to the beginning of the interval. You can override this default and align the value instead to the middle or end of the interval by using either the "MIDDLE" or "END" keywords. Additionally, when you use the INTNX function to shift dates, you can specify the alignment to be the same calendar date after computing the interval increment. The keyword for this specification is "SAME".

Multiples of intervals can be expressed different ways. With INTCK and INTNX, you can add a suffix to the interval keyword that specifies the multiplier of the interval. The third argument to INTNX can also be used to shift multiple intervals.

The two methods of shifting multiple intervals do not work identically so it is important to understand how SAS defines intervals and think through how you need to shift dates. They might or might not produce the same results. The following DATA steps illustrate how the methods differ.

The next DATA step produces the same shifted dates because the three calls to INTNX specify the "SAME" argument for date alignment. For DATE1 and DATE2, the "SAME" keyword causes the alignment to be based on the interval's shift period, which is three months from March 29, 2008, not the interval, which is months.

data _null_;
  date1=intnx('months','29mar2008'd,3,'same'),
  date2=intnx('months3','29mar2008'd,1,'same'),
  date3=intnx('qtr','29mar2008'd,1,'same'),
  put (date1 date2 date3 ) (=mmddyy10.);
run;

The SAS log shows the values of DATE1, DATE2, and DATE3:

date1=06/29/2008 date2=06/29/2008 date3=06/29/2008

Omitting the "SAME" argument causes the INTNX function to default to the beginning of the interval when determining the shifted date. The first call to INTNX has a different value for the beginning of the interval from the other two calls.

data _null_;
  date1=intnx('months','29mar2008'd,3);
  date2=intnx('months3','29mar2008'd,1);
  date3=intnx('qtr','29mar2008'd,1);
  put (date1 date2 date3 ) (=mmddyy10.);
run;

The first call to INTNX where the interval is "MONTHS" places the beginning of the interval at the first of the month, which is March 1, 2008. Shifting three months and aligning to the beginning of the next interval assigns June 1, 2008, to DATE1.

The second call to INTNX where the interval is "MONTHS3" places the beginning of the interval at the first day in the three-month interval, which is January 1, 2008. Shifting three months to the beginning of the next interval assigns April 1, 2008, to DATE2.

The third call to INTNX where the interval is "QTR" places the beginning of the interval at the first day in the quarter of the starting date, which is January 1, 2008. Shifting one quarter to the beginning of the next interval, which is the beginning of the second quarter, assigns April 1, 2008, to DATE3.

The SAS log shows the values of DATE1, DATE2, and DATE3:

date1=06/01/2008 date2=04/01/2008 date3=04/01/2008

You can also add a "shift-index" to your interval specification. A shift-index shifts the start of the interval. The default starting point for an interval is "1". That means, for example, that the keyword "YEAR" causes the starting date to be January 1, and the keyword "HOUR" causes the starting time to be at midnight. If you wanted to define a fiscal year that runs from October 1 to September 30, you can write the interval as "YEAR.10".

As you can see, coding intervals can quickly become quite complicated. It is important to think through and test the kind of intervals and increments to use so that you produce correct results.

For more usage information about SAS date and time intervals, see SAS documentation.

Understanding the Processing of the INTNX Function in This Example

Table 9.2 describes how the appointments should be made for each observation in data set SCHED_APPTS.