IMSL_DIFFERENCE

The IMSL_DIFFERENCE function differences a seasonal or nonseasonal time series.

Note
This routine requires an IDL Advanced Math and Stats license. For more information, contact your ITT Visual Information Solutions sales or technical support representative.

Syntax

Result = IMSL_DIFFERENCE(z, periods [, /DOUBLE] [, /EXCLUDE_FIRST]
[, /FIRST_TO_NAN] [, NUM_LOST=variable] [, ORDERS=array] )

Return Value

One-dimensional array of length N_ELEMENTS (z) containing the differenced series.

Arguments

z

One-dimensional array containing the time series.

periods

One-dimensional array containing the periods at which z is to be differenced.

Keywords

DOUBLE

If present and nonzero, double precision is used.

EXCLUDE_FIRST

If Exclude_First is present and nonzero, the first Num_Lost observations are excluded from the solution due to differencing. The differenced series is of length N_ELEMENTS(periods) – Num_Lost. If First_To_Nan is specified, the first Num_Lost observations are set to NaN (Not a Number). This is the default if neither Exclude_First nor First_To_Nan is specified. Default: First_To_Nan

FIRST_TO_NAN

NUM_LOST

Named variable into which the number of observations "lost" because of differencing the time series z is stored.

ORDERS

One-dimensional array of length N_ELEMENTS(periods) containing the order of each difference given in periods. The elements of Orders must be greater than or equal to 0. Default: all the elements equal 1

Discussion

The IMSL_DIFFERENCE function performs m = N_ELEMENTS(periods) successive backward differences of period s_i = periods(i – 1) and d_i = Orders(i – 1) for i = 1, ..., m on the n = N_ELEMENTS(x) observations {Z_t} for t = 1, 2, ..., n. Consider the backward shift operator B given by:

B^kZ_t = Z_{t – k}

for all k. Then, the backward difference operator with period s is defined by the following:

Note that B_sZ_tand Δ_sZ_tare defined only for t = (s + 1), ..., n. Repeated differencing with period s is simply:

where d ≥ 0 is the order of differencing. Note that Δ^d_sZ_tis defined only for
t = (sd + 1), ..., n.

The general difference formula used in IMSL_DIFFERENCE is given by:

where n_Lrepresents the number of observations "lost" because of differencing and NaN represents the missing value code. See IMSL_MACHINE to retrieve missing values. Note that:

A homogeneous, stationary time series can be arrived at by appropriately differencing a homogeneous, nonstationary time series (Box and Jenkins 1976, p. 85). Preliminary application of an appropriate transformation followed by differencing of a series enables model identification and parameter estimation in the class of homogeneous stationary IMSL_ARMA.

Examples

Example 1

Consider the Airline Data (Box and Jenkins 1976, p. 531) consisting of the monthly total number of international airline passengers from January 1949 through December 1960. The entire data, after taking a natural logarithm, are shown in Figure 20-3. The plot shows a linear trend and a seasonal pattern with a period of 12 months. This suggests that the data needs a nonseasonal difference operator, Δ₁, and a seasonal difference operator, Δ₁₂, to make the series stationary. The IMSL_DIFFERENCE function is used to compute:

W_t = Δ₁Δ₁₂Z_t = (Z_t – Z_{t – 12}) – (Z_{t – 1} – Z_{t – 13})

for t = 14, 15, ..., 24.

ztemp = ALOG(IMSL_STATDATA(4)) 
; Get the data set. 
PLOT, INDGEN(144), ztemp, Psym = -6, Symsize = .5, $ 
   YStyle = 1, Title  = 'Complete Airline Data', $ 
   XTitle = 'Month (beginning 1949)', $ 
   YTitle = '!8ln!3(thousands of Passengers)'  
; Plot the complete data set. 
z = ztemp(0:23) 
periods = [1, 12] 
difference = IMSL_DIFFERENCE(z, periods) 
; Call IMSL_DIFFERENCE. 
matrix = [[INDGEN(24)], [z], [difference]] 
; Create a matrix of the data to make the output easier. 
PM, matrix, FORMAT = '(i4, x, 2f7.1)', $ 
   Title = '   I    z(i)   difference(i)' 
 
; Output the results. 
   I     z(i)   difference(i) 
   0     4.7    NaN 
   1     4.8    NaN 
   2     4.9    NaN 
   3     4.9    NaN 
   4     4.8    NaN 
   5     4.9    NaN 
   6     5.0    NaN 
   7     5.0    NaN 
   8     4.9    NaN 
   9     4.8    NaN 
  10     4.6    NaN 
  11     4.8    NaN 
  12     4.7    NaN 
  13     4.8    0.0 
  14     4.9    0.0 
  15     4.9   -0.0 
  16     4.8   -0.0 
  17     5.0    0.1 
  18     5.1    0.0 
  19     5.1    0.0 
  20     5.1    0.0 
  21     4.9   -0.0 
  22     4.7   -0.0 
  23     4.9    0.1

Figure 20-3: Complete Airline Data Plot

Example 2

The data for this example is the same as that for the initial example. The first Num_Lost observations are excluded from W due to differencing, and Num_Lost also is output.

ztemp = ALOG(IMSL_STATDATA(4)) 
z = ztemp(0:23) 
periods = [1, 12] 
diff = IMSL_DIFFERENCE(z, periods, $ 
   /EXCLUDE_FIRST, NUM_LOST = num_lost) 
num_valid = N_ELEMENTS(z) - num_lost 
; Use Num_Lost to compute the number of rows in the result 
; that have valid values. 
matrix = [[INDGEN(num_valid)], [z(0:num_valid-1)], $ 
   [DIFF(0:num_valid-1)]] 
; Put the data in one matrix to make printing easier. 
PM, matrix, FORMAT = '(i4, x, 2f7.1)', $ 
   TITLE = '   i    z(i)   IMSL_DIFFERENCE(i)' 
 
   i     z(i)   IMSL_DIFFERENCE(i) 
   0     4.7    0.0 
   1     4.8    0.0 
   2     4.9   -0.0 
   3     4.9   -0.0 
   4     4.8    0.1 
   5     4.9    0.0 
   6     5.0    0.0 
   7     5.0    0.0 
   8     4.9   -0.0 
   9     4.8   -0.0 
  10     4.6    0.1

Errors

Fatal Errors

STAT_PERIODS_LT_ZERO—Parameter periods (#) = #. All elements of Periods must be greater than zero.

STAT_ORDER_NEGATIVE—Parameter order (#) = #. All elements of order must be nonnegative.

STAT_Z_CONTAINS_NAN—Parameter z (#) = NaN; z cannot contain missing values. Other elements of z may be equal to NaN.

Version History


6.4	Introduced