NAG CL Interface
g13bac (multi_​filter_​arima)

Settings help

CL Name Style:


1 Purpose

g13bac filters a time series by an ARIMA model.

2 Specification

#include <nag.h>
void  g13bac (const double y[], Integer ny, Nag_ArimaOrder *arimaf, Nag_ArimaOrder *arimav, const double par[], Integer npar, double cy, double b[], Integer nb, NagError *fail)
The function may be called by the names: g13bac, nag_tsa_multi_filter_arima or nag_tsa_arma_filter.

3 Description

From a given series y1,y2,,yn, a new series b1,b2,,bn is calculated using a supplied (filtering) ARIMA model. This model will be one which has previously been fitted to a series xt with residuals at. The equations defining bt in terms of yt are very similar to those by which at is obtained from xt. The only dissimilarity is that no constant correction is applied after differencing. This is because the series yt is generally distinct from the series xt with which the model is associated, though yt may be related to xt. Whilst it is appropriate to apply the ARIMA model to yt so as to preserve the same relationship between bt and at as exists between yt and xt, the constant term in the ARIMA model is inappropriate for yt. The consequence is that bt will not necessarily have zero mean.
The equations are precisely:
wt=dsDyt, (1)
the appropriate differencing of yt; both the seasonal and non-seasonal inverted autoregressive operations are then applied,
ut=wt-Φ1wt-s--ΦPwt-s×P (2)
vt=ut-ϕ1ut-1--ϕput-p (3)
followed by the inverted moving average operations
zt=vt+Θ1zt-s++ΘQzt-s×Q (4)
bt=zt+θ1bt-1++θqbt-q. (5)
Because the filtered series value bt depends on present and past values yt,yt-1,, there is a problem arising from ignorance of y0,y−1, which particularly affects calculation of the early values b1,b2,, causing ‘transient errors’. The function allows two possibilities.
  1. (i)The equations (1), (2) and (3) are applied from successively later time points so that all terms on their right-hand sides are known, with vt being defined for t=(1+d+s×D+s×P),,n. Equations (4) and (5) are then applied over the same range, taking any values on the right-hand side associated with previous time points to be zero.
    This procedure may still however result in unacceptably large transient errors in early values of bt.
  2. (ii)The unknown values y0,y−1, are estimated by backforecasting. This requires that an ARIMA model distinct from that which has been supplied for filtering, should have been previously fitted to yt.
For efficiency, you are asked to supply both this ARIMA model for yt and a limited number of backforecasts which are prefixed to the known values of yt. Within the function further backforecasts of yt, and the series wt, ut, vt in (1), (2) and (3) are then easily calculated, and a set of linear equations solved for backforecasts of zt,bt for use in (4) and (5) in the case that q+Q>0.
Even if the best model for yt is not available, a very approximate guess such as
yt=c+et  
or
yt=et  
can help to reduce the transients substantially.
The backforecasts which need to be prefixed to yt are of length Qy=qy+sy×Qy, where qy and Qy are the non-seasonal and seasonal moving average orders and sy the seasonal period for the ARIMA model of yt. Thus you need not carry out the backforecasting exercise if Qy=0. Otherwise, the series y1,y2,,yn should be reversed to obtain yn,yn-1,,y1 and g13bjc should be used to forecast Qy values, y^0,,y^1-Qy. The ARIMA model used is that fitted to yt (as a forward series) except that, if dy+Dy is odd, the constant should be changed in sign (to allow, for example, for the fact that a forward upward trend is a reversed downward trend). The ARIMA model for yt supplied to the filtering function must however have the appropriate constant for the forward series.
The series y^1-Qy,,y^0,y1,,yn is then supplied to the function, and a corresponding set of values returned for bt.

4 References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

5 Arguments

1: y[ny] const double Input
On entry: the Qy backforecasts, starting with backforecast at time 1-Qy to backforecast at time 0, followed by the time series starting at time 1, where Qy=arimav.q+arimav.bigq×arimav.s. If there are no backforecasts, either because the ARIMA model for the time series is not known, or because it is known but has no moving average terms, then the time series starts at the beginning of y.
2: ny Integer Input
On entry: the total number of backforecasts and time series data points in array y.
Constraint: nymax(1+Qy,npar).
3: arimaf Nag_ArimaOrder * Input
On entry: the orders for the filtering ARIMA model as a pointer to structure of type Nag_ArimaOrder with the following members:
pInteger
dIntegerInput
qIntegerInput
bigpIntegerInput
bigdIntegerInput
bigqIntegerInput
sIntegerInput
On entry: these seven members of arimaf must specify the orders vector (p,d,q,P,D,Q,s), respectively, of the ARIMA model for the output noise component.
p, q, P and Q refer, respectively, to the number of autoregressive (ϕ), moving average (θ), seasonal autoregressive (Φ) and seasonal moving average (Θ) parameters.
d, D and s refer, respectively, to the order of non-seasonal differencing, the order of seasonal differencing and the seasonal period.
Constraints:
  • arimaf.p0 ;
  • arimaf.d0 ;
  • arimaf.q0 ;
  • arimaf.bigp0 ;
  • arimaf.bigd0 ;
  • arimaf.bigq0 ;
  • arimaf.s0 ;
  • arimaf.s1 ;
  • arimaf.p+arimaf.q+arimaf.bigp+arimaf.bigq>0 ;
  • if arimaf.s=0, arimaf.bigp+arimaf.bigd+arimaf.bigq=0 ;
  • if arimaf.s0, arimaf.bigp+arimaf.bigd+arimaf.bigq0 .
4: arimav Nag_ArimaOrder * Input
On entry: if available, the orders for the ARIMA model for the series as a pointer to structure of type Nag_ArimaOrder with the following members:
pInteger
dIntegerInput
qIntegerInput
bigpIntegerInput
bigdIntegerInput
bigqIntegerInput
sIntegerInput
On entry: these seven members of arimav must specify the orders vector (p,d,q,P,D,Q,s), respectively, of the ARIMA model for the output noise component.
p, q, P and Q refer, respectively, to the number of autoregressive (ϕ), moving average (θ), seasonal autoregressive (Φ) and seasonal moving average (Θ) parameters.
d, D and s refer, respectively, to the order of non-seasonal differencing, the order of seasonal differencing and the seasonal period.
If no ARIMA model for the series is to be supplied arimav should be set to a NULL pointer.
Constraints:
  • arimav.p0 ;
  • arimav.d0 ;
  • arimav.q0 ;
  • arimav.bigp0 ;
  • arimav.bigd0 ;
  • arimav.bigq0 ;
  • arimav.s0 ;
  • arimav.s1 ;
  • if arimav.s=0, arimav.bigp+arimav.bigd+arimav.bigq=0 ;
  • if arimav.s0, arimav.bigp+arimav.bigd+arimav.bigq0 .
5: par[npar] const double Input
On entry: the parameters of the filtering model, followed by the parameters of the ARIMA model for the time series, if supplied. Within each model the parameters are in the standard order of non-seasonal AR and MA followed by seasonal AR and MA.
6: npar Integer Input
On entry: the total number of parameters held in array par.
Constraints:
  • if arimavis notNULL, npar=arimaf.p+arimaf.q+arimaf.bigp+arimaf.bigq;
  • if arimavisNULL, npar=arimaf.p+arimaf.q+arimaf.bigp+arimaf.bigq+ arimav.p+arimav.q+arimav.bigp+arimav.bigq.
Note: the first constraint (i.e., arimaf.p+arimaf.q+arimaf.bigp+arimaf.bigq>0) on the orders of the filtering model, in argument arimav, ensures that npar>0.
7: cy double Input
On entry: if the ARIMA model is known, cy must specify the constant term of the ARIMA model for the time series. If this model is not known, cy is not used.
8: b[nb] double Output
On exit: the filtered output series. If the ARIMA model for the time series was known, and hence Qy backforecasts were supplied in y, then b contains Qy ‘filtered’ backforecasts followed by the filtered series. Otherwise, the filtered series begins at the start of b just as the original series began at the start of y. In either case, if the value of the series at time t is held in y[t-1], then the filtered value at time t is held in b[t-1].
9: nb Integer Input
On entry: the dimension of the array b. In addition to holding the returned filtered series, b is also used as an intermediate work array if the ARIMA model for the time series was known.
Constraints:
  • if arimavisNULL, nbny+max(K3,K1+K2);
  • if arimavis notNULL, nbny.
Where
  • K1=arimaf.p+arimaf.bigp×arimaf.s;
  • K2=arimaf.d+arimaf.bigd×arimaf.s;
  • K3=arimaf.q+arimaf.bigq×arimaf.s.
10: fail NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
NE_ARRAY_SIZE
On entry, nb=value and the minimum size required=value.
Constraint: if arimav is not NULL then nbny+max(K3,K1+K2), otherwise nbny.
NE_BAD_PARAM
On entry, argument value had an illegal value.
NE_CONSTRAINT
Constraint: arimaf.bigd0 .
Constraint: arimaf.bigp0 .
Constraint: arimaf.bigq0 .
Constraint: arimaf.d0 .
Constraint: arimaf.p+arimaf.q+arimaf.bigp+arimaf.bigq>0 .
Constraint: arimaf.p0 .
Constraint: arimaf.q0 .
Constraint: arimaf.s1 .
Constraint: arimaf.s0 .
Constraint: arimav.bigd0 .
Constraint: arimav.bigp0 .
Constraint: arimav.bigq0 .
Constraint: arimav.d0 .
Constraint: arimav.p0 .
Constraint: arimav.q0 .
Constraint: arimav.s1 .
Constraint: arimav.s0 .
Constraint: if arimaf.s=0, arimaf.bigp+arimaf.bigd+arimaf.bigq=0 .
Constraint: if arimaf.s0, arimaf.bigp+arimaf.bigd+arimaf.bigq0 .
Constraint: if arimav.s=0, arimav.bigp+arimav.bigd+arimav.bigq=0 .
Constraint: if arimav.s0, arimav.bigp+arimav.bigd+arimav.bigq0 .
On entry, npar is inconsistent with arimaf and arimav: npar=value.
NE_INIT_FILTER
The initial values of the filtered series are indeterminate for the given models.
NE_INT
On entry, ny=value and the minimum size required=value.
Constraint: nymax(1+Qy,npar).
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.
NE_ORDERS_ARIMA
On entry, arimaf or arimav is invalid.
The orders vector for the ARIMA model is invalid.
NE_ORDERS_FILTER
The orders vector for the filtering model is invalid.

7 Accuracy

Accuracy and stability are high except when the MA parameters are close to the invertibility boundary.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
g13bac is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g13bac makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

If an ARIMA model is supplied, local workspace arrays of fixed lengths are allocated internally by g13bac. The total size of these arrays amounts to K Integer elements and K×(K+2) double elements, where K=arimaf.q+arimaf.bigq×arimaf.s+arimav.p+arimav.d+(arimav.bigp+arimav.bigd)×arimav.s.
The time taken by g13bac is approximately proportional to
ny×(arimaf.p+arimaf.q+arimaf.bigp+arimaf.bigq),  
with an appreciable fixed increase if an ARIMA model is supplied for the time series.

10 Example

This example reads a time series of length 296. It reads the univariate ARIMA (4,0,2,0,0,0,0) model and the ARIMA filtering (3,0,0,0,0,0,0) model for the series. Two initial backforecasts are required and these are calculated by a call to g13bjc. The backforecasts are inserted at the start of the series and g13bac is called to perform the calculations.

10.1 Program Text

Program Text (g13bace.c)

10.2 Program Data

Program Data (g13bace.d)

10.3 Program Results

Program Results (g13bace.r)