IMSL C Stat Library
difference
Differences a seasonal or nonseasonal time series.
Synopsis
#include <imsls.h>
float *imsls_f_difference (int n_observations, float z[], int n_differences, int periods[], ..., 0)
The type double function is imsls_d_difference.
Required Arguments
int n_observations (Input)
Number of observations.
float z[] (Input)
Array of length n_observations containing the time series.
int n_differences (Input)
Number of differences to perform. Argument n_differences must be greater than or equal to 1.
int periods[] (Input)
Array of length n_differences containing the periods at which z is to be differenced.
Return Value
Pointer to an array of length n_observations containing the differenced series.
Synopsis with Optional Arguments
#include <imsls.h>
float *imsls_f_difference (int n_observations, float z[], int n_differences, int periods[],
IMSLS_ORDERS, int orders[],
IMSLS_LOST, int *n_lost,
IMSLS_EXCLUDE_FIRST, or
IMSLS_SET_FIRST_TO_NAN,
IMSLS_RETURN_USER, float w[],
0)
Optional Arguments
IMSLS_ORDERS, int orders[] (Input)
Array of length n_differences containing the order of each difference given in periods. The elements of orders must be greater than or equal to 0.
IMSLS_LOST, int *n_lost (Output)
Number of observations lost because of differencing the time series z.
IMSLS_EXCLUDE_FIRST (Input)
or
IMSLS_SET_FIRST_TO_NAN (Input)
If IMSLS_EXCLUDE_FIRST is specified, the first n_lost are excluded from w due to differencing. The differenced series w is of length n_observations - n_lost. If IMSLS_SET_FIRST_TO_NAN is specified, the first n_lost observations are set to NaN (Not a Number). This is the default if neither IMSLS_EXCLUDE_FIRST nor IMSLS_SET_FIRST_TO_NAN is specified.
IMSLS_RETURN_USER, float w[] (Output)
If specified, w contains the differenced series. If IMSLS_EXCLUDE_FIRST also is specified, w is of length n_observations. If IMSLS_SET_FIRST_TO_NAN is specified or neither IMSLS_EXCLUDE_FIRST nor IMSLS_SET_FIRST_TO_NAN is specified, w is of length n_observations - n_lost.
Description
Function imsls_f_difference performs m = n_differences successive backward differences of period si = periods [i - 1] and order di = orders [i - 1] for i = 1, ..., m on the n = n_observations observations {Zt} for t = 1, 2, ..., n.
Consider the backward shift operator B given by
for all k. Then, the backward difference operator with period s is defined by the following:
Note that and are defined only for t = (s + 1), ..., n. Repeated differencing with period s is simply
where d  0 is the order of differencing. Note that
is defined only for t = (sd + 1), ..., n.
The general difference formula used in the function imsls_f_difference is given by
where nL represents the number of observations “lost” because of differencing and NaN represents the missing value code. See the functions imsls_f_machine and imsls_d_machineto 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 can enable model identification and parameter estimation in the class of homogeneous stationary autoregressive moving average models.
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. Function imsls_f_difference is used to compute
for t = 14, 15, ..., 24.
 
#include <imsls.h>
#include <stdio.h>
 
int main()
{
int i;
int n_observations = 24;
int n_differences = 2;
int periods[2] = {1, 12};
float *z;
float *difference;
 
z = imsls_f_data_sets (4,
0);
 
difference = imsls_f_difference (n_observations, z, n_differences,
periods,
0);
 
printf ("i\tz[i]\tdifference[i]\n");
 
for (i = 0; i < n_observations; i++)
printf ("%d\t%f\t%f\n", i, z[i], difference[i]);
}
Output
 
i z[i] difference[i]
0 112.000000 NaN
1 118.000000 NaN
2 132.000000 NaN
3 129.000000 NaN
4 121.000000 NaN
5 135.000000 NaN
6 148.000000 NaN
7 148.000000 NaN
8 136.000000 NaN
9 119.000000 NaN
10 104.000000 NaN
11 118.000000 NaN
12 115.000000 NaN
13 126.000000 5.000000
14 141.000000 1.000000
15 135.000000 -3.000000
16 125.000000 -2.000000
17 149.000000 10.000000
18 170.000000 8.000000
19 170.000000 0.000000
20 158.000000 0.000000
21 133.000000 -8.000000
22 114.000000 -4.000000
23 140.000000 12.000000
Example 2
The data for this example is the same as that for the initial example. The first n_lost observations are excluded from W due to differencing, and n_lost is also output.
 
#include <imsls.h>
#include <stdio.h>
 
int main()
{
int i;
int n_observations = 24;
int n_differences = 2;
int periods[2] = {1, 12};
int n_lost;
float *z;
float *difference;
 
/* Get airline data */
z = imsls_f_data_sets (4,
0);
 
/* Compute differenced time series when observations
lost are excluded from the differencing */
difference = imsls_f_difference (n_observations, z, n_differences,
periods,
IMSLS_EXCLUDE_FIRST,
IMSLS_LOST, &n_lost,
0);
 
/* Print the number of lost observations */
printf ("n_lost equals %d\n", n_lost);
printf ("\n\ni\tz[i]\t difference[i]\n");
 
/* Print the original time series and the differenced
time series */
for (i = 0; i < n_observations - n_lost; i++)
printf ("%d\t%f\t%f\n", i, z[i], difference[i]);
}
Output
 
n_lost equals 13
 
 
i z[i] difference[i]
0 112.000000 5.000000
1 118.000000 1.000000
2 132.000000 -3.000000
3 129.000000 -2.000000
4 121.000000 10.000000
5 135.000000 8.000000
6 148.000000 0.000000
7 148.000000 0.000000
8 136.000000 -8.000000
9 119.000000 -4.000000
10 104.000000 12.000000
Fatal Errors
IMSLS_PERIODS_LT_ZERO
period[#]” = #. All elements of “period” must be greater than 0.
IMSLS_ORDER_NEGATIVE
order[#]” = #. All elements of “order” must be nonnegative.
IMSLS_Z_CONTAINS_NAN
z[#]” = NaN; “z” can not contain missing values. There may be other elements of “z” that are equal to NaN.