# NAG CL Interfaceg13bbc (multi_​filter_​transf)

Settings help

CL Name Style:

## 1Purpose

g13bbc filters a time series by a transfer function model.

## 2Specification

 #include
 void g13bbc (const double y[], Integer ny, Nag_TransfOrder *transfv, Nag_ArimaOrder *arimas, const double par[], Integer npar, double cy, double b[], Integer nb, NagError *fail)
The function may be called by the names: g13bbc, nag_tsa_multi_filter_transf or nag_tsa_transf_filter.

## 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 g13bac, 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.
1. (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.
2. (ii)The unknown values of ${y}_{t}$ for $t\le 0$ are estimated by backforecasting exactly as for g13bac.

## 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]$const double Input
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{arimas}}\mathbf{.}\mathbf{q}+{\mathbf{arimas}}\mathbf{.}\mathbf{bigq}×{\mathbf{arimas}}\mathbf{.}\mathbf{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: $\mathbf{ny}$Integer Input
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{transfv}$Nag_TransfOrder * Input
On entry: the orders of the transfer function model where the triplet (transfv. nag_b, transfv. nag_q, transfv. nag_p) corresponds to the triplet $\left(b,q,p\right)$ as described in Section 2.3.1 in the G13 Chapter Introduction.
Constraints:
• ${\mathbf{transfv}}\mathbf{.}\mathbf{nag_b}\ge 0$;
• ${\mathbf{transfv}}\mathbf{.}\mathbf{nag_q}\ge 0$;
• ${\mathbf{transfv}}\mathbf{.}\mathbf{nag_p}\ge 0$.
4: $\mathbf{arimas}$Nag_ArimaOrder * Input
On entry: if available, the orders for the filtering ARIMA model for the time 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 arimas must specify the orders vector $\left(p,d,q,P,D,Q,s\right)$, respectively, of the ARIMA model for the output noise component.
$p$, $q$, $P$ and $Q$ refer, respectively, to the number of autoregressive ($\varphi$), moving average ($\theta$), seasonal autoregressive ($\Phi$) and seasonal moving average ($\Theta$) 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 arimas should be set to a NULL pointer.
Constraints:
• ${\mathbf{arimas}}\mathbf{.}\mathbf{p}\ge 0$;
• ${\mathbf{arimas}}\mathbf{.}\mathbf{d}\ge 0$;
• ${\mathbf{arimas}}\mathbf{.}\mathbf{q}\ge 0$;
• ${\mathbf{arimas}}\mathbf{.}\mathbf{bigp}\ge 0$;
• ${\mathbf{arimas}}\mathbf{.}\mathbf{bigd}\ge 0$;
• ${\mathbf{arimas}}\mathbf{.}\mathbf{bigq}\ge 0$;
• ${\mathbf{arimas}}\mathbf{.}\mathbf{s}\ge 0$;
• ${\mathbf{arimas}}\mathbf{.}\mathbf{s}\ne 1$;
• if ${\mathbf{arimas}}\mathbf{.}\mathbf{s}=0$, ${\mathbf{arimas}}\mathbf{.}\mathbf{bigp}+{\mathbf{arimas}}\mathbf{.}\mathbf{bigd}+{\mathbf{arimas}}\mathbf{.}\mathbf{bigq}=0$;
• if ${\mathbf{arimas}}\mathbf{.}\mathbf{s}\ne 0$, ${\mathbf{arimas}}\mathbf{.}\mathbf{bigp}+{\mathbf{arimas}}\mathbf{.}\mathbf{bigd}+{\mathbf{arimas}}\mathbf{.}\mathbf{bigq}\ne 0$.
5: $\mathbf{par}\left[{\mathbf{npar}}\right]$const double Input
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}$Integer Input
On entry: the total number of parameters held in array par.
Constraints:
• if ${\mathbf{arimas}}\phantom{\rule{0.25em}{0ex}}\text{is not}\phantom{\rule{0.25em}{0ex}}\mathbf{NULL}$, ${\mathbf{npar}}={\mathbf{transfv}}\mathbf{.}\mathbf{nag_q}+{\mathbf{transfv}}\mathbf{.}\mathbf{nag_p}+1$;
• if ${\mathbf{arimas}}\phantom{\rule{0.25em}{0ex}}\text{is}\phantom{\rule{0.25em}{0ex}}\mathbf{NULL}$, ${\mathbf{npar}}={\mathbf{transfv}}\mathbf{.}\mathbf{nag_q}+{\mathbf{transfv}}\mathbf{.}\mathbf{nag_p}+1+{\mathbf{arimas}}\mathbf{.}\mathbf{p}+\phantom{\rule{0ex}{0ex}}{\mathbf{arimas}}\mathbf{.}\mathbf{q}+{\mathbf{arimas}}\mathbf{.}\mathbf{bigp}+{\mathbf{arimas}}\mathbf{.}\mathbf{bigq}$.
7: $\mathbf{cy}$double Input
On entry: if the ARIMA model is known (i.e., ${\mathbf{arimas}}\phantom{\rule{0.25em}{0ex}}\text{is}\phantom{\rule{0.25em}{0ex}}\mathbf{NULL}$), cy must specify the constant term of the ARIMA model for the time series. If this model is not known (i.e., ${\mathbf{arimas}}\phantom{\rule{0.25em}{0ex}}\text{is not}\phantom{\rule{0.25em}{0ex}}\mathbf{NULL}$) then cy is not used.
8: $\mathbf{b}\left[{\mathbf{nb}}\right]$double Output
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-1\right]$, then the filtered value at time $t$ is held in ${\mathbf{b}}\left[t-1\right]$.
9: $\mathbf{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 is known.
Constraints:
• if ${\mathbf{arimas}}\phantom{\rule{0.25em}{0ex}}\text{is not}\phantom{\rule{0.25em}{0ex}}\mathbf{NULL}$, ${\mathbf{nb}}\ge {\mathbf{ny}}$;
• if ${\mathbf{arimas}}\phantom{\rule{0.25em}{0ex}}\text{is}\phantom{\rule{0.25em}{0ex}}\mathbf{NULL}$, ${\mathbf{nb}}\ge {\mathbf{ny}}+\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{transfv}}\mathbf{.}\mathbf{nag_b}+{\mathbf{transfv}}\mathbf{.}\mathbf{nag_q},{\mathbf{transfv}}\mathbf{.}\mathbf{nag_p}\right)$.
10: $\mathbf{fail}$NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

## 6Error 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, ${\mathbf{nb}}=⟨\mathit{\text{value}}⟩$ and the minimum size $\text{required}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{arimas}}\phantom{\rule{0.25em}{0ex}}\text{is}\phantom{\rule{0.25em}{0ex}}\mathbf{NULL}$arimas is not NULL then ${\mathbf{nb}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(b,p,q\right)$, otherwise ${\mathbf{nb}}\ge {\mathbf{ny}}$.
On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.
NE_CONSTRAINT
Constraint: ${\mathbf{arimas}}\mathbf{.}\mathbf{bigd}\ge 0$.
Constraint: ${\mathbf{arimas}}\mathbf{.}\mathbf{bigp}\ge 0$.
Constraint: ${\mathbf{arimas}}\mathbf{.}\mathbf{bigq}\ge 0$.
Constraint: ${\mathbf{arimas}}\mathbf{.}\mathbf{d}\ge 0$.
Constraint: ${\mathbf{arimas}}\mathbf{.}\mathbf{p}\ge 0$.
Constraint: ${\mathbf{arimas}}\mathbf{.}\mathbf{q}\ge 0$.
Constraint: ${\mathbf{arimas}}\mathbf{.}\mathbf{s}\ne 1$.
Constraint: ${\mathbf{arimas}}\mathbf{.}\mathbf{s}\ge 0$.
Constraint: if ${\mathbf{arimas}}\mathbf{.}\mathbf{s}=0$, ${\mathbf{arimas}}\mathbf{.}\mathbf{bigp}+{\mathbf{arimas}}\mathbf{.}\mathbf{bigd}+{\mathbf{arimas}}\mathbf{.}\mathbf{bigq}=0$.
Constraint: if ${\mathbf{arimas}}\mathbf{.}\mathbf{s}\ne 0$, ${\mathbf{arimas}}\mathbf{.}\mathbf{bigp}+{\mathbf{arimas}}\mathbf{.}\mathbf{bigd}+{\mathbf{arimas}}\mathbf{.}\mathbf{bigq}\ne 0$.
Constraint: ${\mathbf{transfv}}\mathbf{.}\mathbf{nag_b}\ge 0$.
Constraint: ${\mathbf{transfv}}\mathbf{.}\mathbf{nag_p}\ge 0$.
Constraint: ${\mathbf{transfv}}\mathbf{.}\mathbf{nag_q}\ge 0$.
NE_INT
On entry, npar is inconsistent with transfv and arimas: ${\mathbf{npar}}=⟨\mathit{\text{value}}⟩$.
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_MODEL_PARAMS
A supplied model has invalid parameters.
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_SINGULAR
The matrix used to solve for starting values for MA is singular.
NE_TIME_SERIES
The supplied time series is too short.

## 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

g13bbc is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g13bbc 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.

If an ARIMA model is supplied, local workspace arrays of fixed lengths are allocated internally by g13bbc. The total size of these arrays amounts to $K$ Integer elements and $K×\left(K+2\right)$ double elements, where $K={\mathbf{transfv}}\mathbf{.}\mathbf{nag_p}+{\mathbf{arimas}}\mathbf{.}\mathbf{p}+{\mathbf{arimas}}\mathbf{.}\mathbf{d}+\left({\mathbf{arimas}}\mathbf{.}\mathbf{bigp}+{\mathbf{arimas}}\mathbf{.}\mathbf{bigd}\right)×{\mathbf{arimas}}\mathbf{.}\mathbf{s}$.
The time taken by g13bbc 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 g13bjc. The backforecasts are inserted at the start of the series and g13bbc is called to perform the filtering.

### 10.1Program Text

Program Text (g13bbce.c)

### 10.2Program Data

Program Data (g13bbce.d)

### 10.3Program Results

Program Results (g13bbce.r)