# NAG Library Routine Document

## 1Purpose

g13bbf filters a time series by a transfer function model.

## 2Specification

Fortran Interface
 Subroutine g13bbf ( y, ny, mr, nmr, par, npar, cy, wa, iwa, b, nb,
 Integer, Intent (In) :: ny, mr(nmr), nmr, npar, iwa, nb Integer, Intent (Inout) :: ifail Real (Kind=nag_wp), Intent (In) :: y(ny), par(npar), cy Real (Kind=nag_wp), Intent (Out) :: wa(iwa), b(nb)
#include nagmk26.h
 void g13bbf_ (const double y[], const Integer *ny, const Integer mr[], const Integer *nmr, const double par[], const Integer *npar, const double *cy, double wa[], const Integer *iwa, double b[], const Integer *nb, Integer *ifail)

## 3Description

From a given series ${y}_{1},{y}_{2},\dots ,{y}_{n}$ a new series ${b}_{1},{b}_{2},\dots ,{b}_{n}$ is calculated using a supplied (filtering) transfer function model according to the equation
 $bt=δ1bt-1+δ2bt-2+⋯+δpbt-p+ω0yt-b-ω1yt-b-1-⋯-ωqyt-b-q.$ (1)
As in the use of g13baf, large transient errors may arise in the early values of ${b}_{t}$ due to ignorance of ${y}_{t}$ for $t<0$, and two possibilities are allowed.
 (i) The equation (1) is applied from $t=1+b+q,\dots ,n$ so all terms in ${y}_{t}$ on the right-hand side of (1) are known, the unknown set of values ${b}_{t}$ for $t=b+q,\dots ,b+q+1-p$ being taken as zero. (ii) The unknown values of ${y}_{t}$ for $t\le 0$ are estimated by backforecasting exactly as for g13baf.

## 4References

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

## 5Arguments

1:     $\mathbf{y}\left({\mathbf{ny}}\right)$ – Real (Kind=nag_wp) arrayInput
On entry: the ${Q}_{y}^{\prime }$ backforecasts starting with backforecast at time $1-{Q}_{y}^{\prime }$ to backforecast at time $0$ followed by the time series starting at time $1$, where ${Q}_{y}^{\prime }={\mathbf{mr}}\left(6\right)+{\mathbf{mr}}\left(9\right)×{\mathbf{mr}}\left(10\right)$. 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:     $\mathbf{ny}$ – IntegerInput
On entry: the total number of backforecasts and time series data points in array y.
Constraint: ${\mathbf{ny}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1+{Q}_{y}^{\prime },{\mathbf{npar}}\right)$.
3:     $\mathbf{mr}\left({\mathbf{nmr}}\right)$ – Integer arrayInput
On entry: the orders vector for the filtering transfer function model followed by the orders vector for the ARIMA model for the time series if the latter is known. The transfer function model orders appear in the standard form $\left(b,q,p\right)$ as given in the G13 Chapter Introduction. Note that if the ARIMA model for the time series is supplied then the routine will assume that the first ${Q}_{y}^{\prime }$ values of the array y are backforecasts.
Constraints:
the filtering model is restricted in the following way:
• ${\mathbf{mr}}\left(1\right)\text{, ​}{\mathbf{mr}}\left(2\right)\text{, ​}{\mathbf{mr}}\left(3\right)\ge 0$.
the ARIMA model for the time series is restricted in the following ways:
• ${\mathbf{mr}}\left(\mathit{k}\right)\ge 0$, for $\mathit{k}=4,5,\dots ,10$;
• if ${\mathbf{mr}}\left(10\right)=0$, ${\mathbf{mr}}\left(7\right)+{\mathbf{mr}}\left(8\right)+{\mathbf{mr}}\left(9\right)=0$;
• if ${\mathbf{mr}}\left(10\right)\ne 0$, ${\mathbf{mr}}\left(7\right)+{\mathbf{mr}}\left(8\right)+{\mathbf{mr}}\left(9\right)\ne 0$;
• ${\mathbf{mr}}\left(10\right)\ne 1$.
4:     $\mathbf{nmr}$ – IntegerInput
On entry: the number of values supplied in the array mr. It takes the value $3$ if no ARIMA model for the time series is supplied but otherwise it takes the value $10$. Thus nmr acts as an indicator as to whether backforecasting can be carried out.
Constraint: ${\mathbf{nmr}}=3$ or $10$.
5:     $\mathbf{par}\left({\mathbf{npar}}\right)$ – Real (Kind=nag_wp) arrayInput
On entry: the parameters of the filtering transfer function model followed by the parameters of the ARIMA model for the time series. In the transfer function model the parameters are in the standard order of MA-like followed by AR-like operator parameters. In the ARIMA model the parameters are in the standard order of non-seasonal AR and MA followed by seasonal AR and MA.
6:     $\mathbf{npar}$ – IntegerInput
On entry: the total number of parameters held in array par.
Constraints:
• if ${\mathbf{nmr}}=3$, ${\mathbf{npar}}={\mathbf{mr}}\left(2\right)+{\mathbf{mr}}\left(3\right)+1$;
• if ${\mathbf{nmr}}=10$, ${\mathbf{npar}}={\mathbf{mr}}\left(2\right)+{\mathbf{mr}}\left(3\right)+1+{\mathbf{mr}}\left(4\right)+{\mathbf{mr}}\left(6\right)+{\mathbf{mr}}\left(7\right)+{\mathbf{mr}}\left(9\right)$.
7:     $\mathbf{cy}$ – Real (Kind=nag_wp)Input
On entry: if the ARIMA model is known (i.e., ${\mathbf{nmr}}=10$), cy must specify the constant term of the ARIMA model for the time series. If this model is not known (i.e., ${\mathbf{nmr}}=3$) then cy is not used.
8:     $\mathbf{wa}\left({\mathbf{iwa}}\right)$ – Real (Kind=nag_wp) arrayWorkspace
9:     $\mathbf{iwa}$ – IntegerInput
On entry: the dimension of the array wa as declared in the (sub)program from which g13bbf is called.
Constraints:
let $K={\mathbf{mr}}\left(3\right)+{\mathbf{mr}}\left(4\right)+{\mathbf{mr}}\left(5\right)+\left({\mathbf{mr}}\left(7\right)+{\mathbf{mr}}\left(8\right)\right)×{\mathbf{mr}}\left(10\right)$,
then
• if ${\mathbf{nmr}}=3$, ${\mathbf{iwa}}\ge {\mathbf{mr}}\left(1\right)+{\mathbf{npar}}$;
• if ${\mathbf{nmr}}=10$, ${\mathbf{iwa}}\ge {\mathbf{mr}}\left(1\right)+{\mathbf{npar}}+K×\left(K+2\right)$.
10:   $\mathbf{b}\left({\mathbf{nb}}\right)$ – Real (Kind=nag_wp) arrayOutput
On exit: the filtered output series. If the ARIMA model for the time series was known, and hence ${Q}_{y}^{\prime }$ backforecasts were supplied in y, then b contains ${Q}_{y}^{\prime }$ ‘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 ${\mathbf{y}}\left(t\right)$, then the filtered value at time $t$ is held in ${\mathbf{b}}\left(t\right)$.
11:   $\mathbf{nb}$ – IntegerInput
On entry: the dimension of the array b as declared in the (sub)program from which g13bbf is called.
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 is known.
Constraints:
• if ${\mathbf{nmr}}=3$, ${\mathbf{nb}}\ge {\mathbf{ny}}$;
• if ${\mathbf{nmr}}=10$, ${\mathbf{nb}}\ge {\mathbf{ny}}+\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{mr}}\left(1\right)+{\mathbf{mr}}\left(2\right),{\mathbf{mr}}\left(3\right)\right)$.
12:   $\mathbf{ifail}$ – IntegerInput/Output
On entry: ifail must be set to $0$, $-1\text{​ or ​}1$. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{​ or ​}1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is $0$. When the value $-\mathbf{1}\text{​ or ​}\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{nmr}}\ne 3$ and ${\mathbf{nmr}}\ne 10$, or ${\mathbf{mr}}\left(\mathit{i}\right)<0$, for $\mathit{i}=1,2,\dots ,{\mathbf{nmr}}$, or ${\mathbf{nmr}}=10$ and ${\mathbf{mr}}\left(10\right)=1$, or ${\mathbf{nmr}}=10$ and ${\mathbf{mr}}\left(10\right)=0$ and ${\mathbf{mr}}\left(7\right)+{\mathbf{mr}}\left(8\right)+{\mathbf{mr}}\left(9\right)\ne 0$, or ${\mathbf{nmr}}=10$ and ${\mathbf{mr}}\left(10\right)\ne 0$, and ${\mathbf{mr}}\left(7\right)+{\mathbf{mr}}\left(8\right)+{\mathbf{mr}}\left(9\right)=0$, or npar is inconsistent with the contents of mr, or wa is too small, or b is too small.
${\mathbf{ifail}}=2$
A supplied model has parameter values which have failed the validity test.
${\mathbf{ifail}}=3$
The supplied time series is too short to carry out the requested filtering successfully.
${\mathbf{ifail}}=4$
This only occurs when an ARIMA model for the time series has been supplied. The matrix which is used to solve for the starting values for MA filtering is singular.
${\mathbf{ifail}}=-99$
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

## 7Accuracy

Accuracy and stability are high except when the AR-like parameters are close to the invertibility boundary. All calculations are performed in basic precision except for one inner product type calculation which on machines of low precision is performed in additional precision.

## 8Parallelism and Performance

g13bbf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g13bbf 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 routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

If an ARIMA model is supplied, a local workspace array of fixed length is allocated internally by g13bbf. The total size of this array amounts to $K$ integer elements, where $K$ is the expression defined in the description of the argument wa.
The time taken by g13bbf is roughly proportional to the product of the length of the series and number of parameters in the filtering model with appreciable increase if an ARIMA model is supplied for the time series.

## 10Example

This example reads a time series of length $296$. It reads one univariate ARIMA $\left(1,1,0,0,1,1,12\right)$ model for the series and the $\left(0,13,12\right)$ filtering transfer function model. $12$ initial backforecasts are required and these are calculated by a call to g13ajf . The backforecasts are inserted at the start of the series and g13bbf is called to perform the filtering.

### 10.1Program Text

Program Text (g13bbfe.f90)

### 10.2Program Data

Program Data (g13bbfe.d)

### 10.3Program Results

Program Results (g13bbfe.r)

© The Numerical Algorithms Group Ltd, Oxford, UK. 2017