NAG CL Interface
g13bec (multi_inputmod_estim)
1
Purpose
g13bec fits a time series model to one output series relating it to any input series with a choice of three different estimation criteria – nonlinear least squares, exact likelihood and marginal likelihood. When no input series are present, g13bec fits a univariate ARIMA model.
2
Specification
void 
g13bec (Nag_ArimaOrder *arimav,
Integer nseries,
Nag_TransfOrder *transfv,
double para[],
Integer npara,
Integer nxxy,
const double xxy[],
Integer tdxxy,
double sd[],
double *rss,
double *objf,
double *df,
Nag_G13_Opt *options,
NagError *fail) 

The function may be called by the names: g13bec, nag_tsa_multi_inputmod_estim or nag_tsa_multi_inp_model_estim.
3
Description
3.1
The Multiinput Model
The output series ${y}_{\mathit{t}}$, for $\mathit{t}=1,2,\dots ,n$, is assumed to be the sum of (unobserved) components ${z}_{\mathit{i},t}$ which are due respectively to the inputs ${x}_{\mathit{i},t}$, for $\mathit{i}=1,2,\dots ,m$.
Thus ${y}_{t}={z}_{1,t}+\cdots +{z}_{m,t}+{n}_{t}$ where ${n}_{t}$ is the error, or output noise component.
A typical component
${z}_{t}$ may be either:

(a)A simple regression component, ${z}_{t}=\omega {x}_{t}$ (here ${x}_{t}$ is called a simple input) or

(b)A transfer function model component which allows for the effect of lagged values of the variable, related to ${x}_{t}$ by
The noise
${n}_{t}$ is assumed to follow a (possibly seasonal) ARIMA model, i.e., may be represented in terms of an uncorrelated series,
${a}_{t}$, by the hierarchy of equations:
Note: the orders $p,q$ appearing in each of the transfer function models and the ARIMA model are not necessarily the same; ${\nabla}^{d}{\nabla}_{s}^{D}{n}_{t}$ is the result of applying nonseasonal differencing of order $d$ and seasonal differencing of seasonality $s$ and order $D$ to the series ${n}_{t}$, the differenced series is then of length $N=nds\times D$; the constant term argument $c$ may optionally be held fixed at its initial value (usually, but not necessarily zero) rather than being estimated.
For the purpose of defining an estimation criterion it is assumed that the series ${a}_{t}$ is a sequence of independent Normal variates having mean 0 and variance ${\sigma}_{a}^{2}$. An allowance has to be made for the effects of unobserved data prior to the observation period. For the noise component an allowance is always made using a form of backforecasting.
For each transfer function input, you have to decide what values are to be assumed for the preperiod terms ${z}_{0},{z}_{1},\dots ,{z}_{1p}$ and ${x}_{0},{x}_{1},\dots ,{x}_{1bq}$ which are in theory necessary to recreate the component series ${z}_{1},{z}_{2},\dots ,{z}_{n}$, during the estimation procedure.
The first choice is to assume that all these values are zero. In this case in order to avoid undesirable transient distortion of the early values ${z}_{1},{z}_{2},\dots ,$ you are advised first to correct the input series ${x}_{t}$ by subtracting from all the terms a suitable constant to make the early values ${x}_{1},{x}_{2},\dots ,$ close to zero. The series mean $\overline{x}$ is one possibility, but for a series with strong trend, the constant might be simply ${x}_{1}$.
The second choice is to treat the unknown preperiod terms as nuisance arguments and estimate them along with the other arguments. This choice should be used with caution. For example, if $p=1$ and $b=q=0$, it is equivalent to fitting to the data a decaying geometric curve of the form $A{\delta}^{\mathit{t}}$, for $\mathit{t}=1,2,\dots $, along with the other inputs, this being the form of the transient. If the output ${y}_{t}$ contains a strong trend of this form, which is not otherwise represented in the model, it will have a tendency to influence the estimate of $\delta $ away from the value appropriate to the transfer function model.
In most applications the first choice should be adequate, with the option possibly being used as a refinement at the end of the modelling process. The number of nuisance arguments is then $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(p,b+q\right)$, with a corresponding loss of degrees of freedom in the residuals. If you align the input ${x}_{t}$ with the output by using in its place the shifted series ${x}_{tb}$, then setting $b=0$ in the transfer function model, there is some improvement in efficiency. On some occasions when the model contains two or more inputs, each with estimation of preperiod nuisance arguments, these arguments may be colinear and lead to failure of the function. The option must then be ‘switched off’ for one or more inputs.
3.2
The Estimation Criterion
This is a measure of how well a proposed set of arguments in the transfer function and noise ARIMA models, matches the data. The estimation function searches for argument values which minimize this criterion. For a proposed set of argument values it is derived by calculating:

(i)the components ${z}_{1,t},{z}_{2,t},\dots ,{z}_{m,t}$ as the responses to the input series ${x}_{1,t},{x}_{2,t},\dots ,{x}_{m,t}$ using the equations (a) or (b) above,

(ii)the discrepancy between the output and the sum of these components, as the noise

(iii)the residual series ${a}_{t}$ from ${n}_{t}$ by reversing the recursive equations (c), (d) and (e) above.
This last step again requires treatment of the effect of unknown preperiod values of
${n}_{t}$ and other terms in the equations regenerating
${a}_{t}$. One approach is to use a sum of squares function as the estimation criteria, which is equivalent to taking the infinite set of past values
${n}_{0},{n}_{1},{n}_{2},\dots ,$ as (linear) nuisance arguments. There is no loss of degrees of freedom however, because the sum of squares function
$S$ may be expressed as including the corresponding set of past residuals – see
Box and Jenkins (1976) page 273, who prove that
The function
$D=S$ is the first of the three possible criteria, and is quite adequate for moderate to long series with no seasonal arguments. The second is the exact likelihood criterion which considers the past set
${n}_{0},{n}_{1},{n}_{2},\dots $, not as simple nuisance arguments, but as unobserved random variables with known distribution. Calculation of the likelihood of the observed set
${n}_{1},{n}_{2},\dots ,{n}_{n}$ requires theoretical integration over the range of the past set. Fortunately this yields a criterion of the form
$D=M\times S$ (whose minimization is equivalent to maximizing the exact likelihood of the data), where
$S$ is exactly as before, and the multiplier
$M$ is a function calculated from the ARIMA model arguments. The value of
$M$ is always
$\ge 1$, and
$M$ tends to 1 for any fixed argument set as the sample size
$n$ tends to
$\infty $. There is a moderate computational overhead in using this option, but its use avoids appreciable bias in the ARIMA model arguments and yields a better conditioned estimation problem.
The third criterion of marginal likelihood treats the coefficients of the simple inputs in a manner analogous to that given to the past set ${n}_{0},{n}_{1},{n}_{2},\dots $. These coefficients, together with the constant term $c$ used to represent the mean of ${w}_{t}$, are in effect treated as random variables with highly dispersed distributions. This leads to the criterion $D=M\times S$ again, but with a different value of $M$ which now depends on the simple input series values ${x}_{t}$. In the presence of a moderate to large number of simple inputs, the marginal likelihood criterion can counteract bias in the ARIMA model arguments which is caused by estimation of the simple inputs. This is particularly important in relatively short series.
g13bec can be used with no input series present, to estimate a univariate ARIMA model for the ouput alone. The marginal likelihood criterion is then distinct from exact likelihood only if a constant term is being estimated in the model, because this is treated as an implicit simple input.
3.3
The Estimation Procedure
This is the minimization of the estimation criterion or objective function
$D$ (for deviance). The function uses an extension of the algorithm of
Marquardt (1963). The step size in the minimization is inversely related to an argument
$\alpha $, which is increased or decreased by a factor
$\beta $ at successive iterations, depending on the progress of the minimization. Convergence is deemed to have occurred if the fractional reduction of
$D$ in successive iterations is less than a value
$\gamma $, while
$\alpha <1$.
Certain model arguments (in fact all excluding the $\omega $'s) are subject to stability constraints which are checked throughout to within a specified tolerance multiple $\delta $ of machine accuracy. Using the least squares criterion, the minimization may halt prematurely when some arguments ‘stick’ at a constraint boundary. This can happen particularly with short seasonal series (with a small number of whole seasons). It will not happen using the exact likelihood criterion, although convergence to a point on the boundary may sometimes be rather slow, because the criterion function may be very flat in such a region. There is also a smaller risk of a premature halt at a constraint boundary when marginal likelihood is used.
A positive, or zero number of iterations can be specified. In either case, the value $D$ of the objective function at iteration zero is computed at the initial argument values, except for the estimation of any preperiod terms for the input series, backforecasts for the noise series, and the coefficients of any simple inputs, and the constant term (unless this is held fixed).
At any later iteration, the value of $D$ is computed after reestimation of the backforecasts to their optimal values, corresponding to the model arguments presented at that iteration. This is not true for any preperiod terms for the input series which, although they are updated from the previous iteration, may not be precisely optimal for the argument values presented, unless convergence of those arguments has occurred. However, in the case of marginal likelihood being specified, the coefficients of the simple inputs and the constant term are also reestimated together with the backforecasts at each iteration, to values which are optimal for the other argument values presented.
3.4
Further Results
The residual variance is taken as $erv=\frac{S}{df}$ where $df=N$ (total number of arguments estimated), is the residual degrees of freedom (for definition of $S$ see Section 3.2 and for definition of $N$ see Section 3.1). The preperiod nuisance arguments for the input series are included in the reduction of $df$, as is the constant if it is estimated.
The covariance matrix of the vector of model parameter estimates is given by
where
$H$ is the linearised least squares matrix taken from the final iteration of the algorithm of Marquardt. From this expression are derived the vector of standard deviations, and the correlation matrix of parameter estimates. These are approximations which are only valid asymptotically, and must be treated with great caution when the parameter estimates are close to their constraint boundaries.
The residual series ${a}_{t}$ is available upon completion of the iterations over the range $t=1+d+s\times D,\dots ,n$ corresponding to the differenced noise series ${w}_{t}$.
Because of the algorithm used for backforecasting, these are only true residuals for $t\ge 1+q+s\times Qps\times Pds\times D$, provided this is positive. Estimation of preperiod terms for the inputs will also tend to reduce the magnitude of the early residuals, sometimes severely.
The model component series ${z}_{1,t},\dots ,{z}_{m,t}$ and ${n}_{t}$ may optionally be returned in order to assess the effects of the various inputs on the output.
4
References
Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day
Byng M Fitting a seasonal ARIMA model using the NAG C Library
NAG Technical Report TR3/09 https://www.nag.co.uk/technicalreportrepository#tr0309
Marquardt D W (1963) An algorithm for least squares estimation of nonlinear parameters J. Soc. Indust. Appl. Math. 11 431
5
Arguments

1:
$\mathbf{arimav}$ – Nag_ArimaOrder *

Pointer to structure of type Nag_ArimaOrder with the following members:
 p – Integer
 d – IntegerInput
 q – IntegerInput
 bigp – IntegerInput
 bigd – IntegerInput
 bigq – IntegerInput
 s – IntegerInput

On entry: these seven members of
arimav 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 $\left(\varphi \right)$, moving average $\left(\theta \right)$, seasonal autoregressive $\left(\Phi \right)$ and seasonal moving average $\left(\Theta \right)$ arguments.
$d$, $D$ and $s$ refer, respectively, to the order of nonseasonal differencing, the order of seasonal differencing and the seasonal period.
Constraints:
 $p$, $d$, $q$, $P$, $D$, $Q$, $s\ge 0$;
 $p+q+P+Q>0$;
 $s\ne 1$;
 if $s=0$, $P+D+Q=0$;
 if $s>1$, $P+D+Q>0$;
 $d+s\times \left(P+D\right)\le n$;
 $p+dq+s\times \left(P+DQ\right)\le n$.

2:
$\mathbf{nseries}$ – Integer
Input

On entry: the total number of input and output series. There may be any number of input series (including none), but always one output series.
Constraint:
${\mathbf{nseries}}>1$ if there are no arguments in the model (that is $p=q=P=Q=0$ and ${\mathbf{options}}\mathbf{.}{\mathbf{cfixed}}=\mathrm{Nag\_TRUE}$), ${\mathbf{nseries}}\ge 1$ otherwise.

3:
$\mathbf{transfv}$ – Nag_TransfOrder *

Pointer to structure of type Nag_TransfOrder with the following members:
 b – Integer *Input/Output
 q – Integer *Input/Output
 p – Integer *
 r – Integer *Input/Output

On entry/exit: before use these member pointers
must be allocated memory by calling
g13byc which allocates
${\mathbf{nseries}}1$ elements to each pointer. The memory allocated to these pointers must be given the transfer function model orders
$b$,
$q$ and
$p$ of each of the input series. The order arguments for input series
$i$ are held in the
$i$th element of the allocated memory for each pointer.
$\mathbf{transfv}\mathbf{\to}\mathbf{b}\left[i1\right]$ holds the value
${b}_{i}$,
$\mathbf{transfv}\mathbf{\to}\mathbf{q}\left[i1\right]$ holds the value
${q}_{i}$ and
$\mathbf{transfv}\mathbf{\to}\mathbf{p}\left[i1\right]$ holds the value
${p}_{i}$. For a simple input,
${b}_{i}={q}_{i}={p}_{i}=0$.
$\mathbf{transfv}\mathbf{\to}\mathbf{r}\left[i1\right]$ holds the value
${r}_{i}$, where
${r}_{i}=1$ for a simple input,
${r}_{i}=2$ for a transfer function input for which no allowance is to be made for preobservation period effects, and
${r}_{i}=3$ for a transfer function input for which preobservation period effects will be treated by estimation of appropriate nuisance arguments. When
${r}_{i}=1$, any nonzero contents of the
$i$th element of
$\mathbf{transfv}\mathbf{\to}\mathbf{b}$,
$\mathbf{transfv}\mathbf{\to}\mathbf{q}$ and
$\mathbf{transfv}\mathbf{\to}\mathbf{p}$ are ignored.
Constraint:
$\mathbf{transfv}\mathbf{\to}\mathbf{r}\left[\mathit{i}1\right]=1$,
$2$ or
$3$, for
$\mathit{i}=1,2,\dots ,{\mathbf{nseries}}1$The memory allocated to the members of transfv must be freed by a call to
g13bzc

4:
$\mathbf{para}\left[{\mathbf{npara}}\right]$ – double
Input/Output

On entry: initial values of the multiinput model arguments. These are in order, firstly the ARIMA model arguments:
$p$ values of
$\varphi $ arguments,
$q$ values of
$\theta $ arguments,
$P$ values of
$\Phi $ arguments and
$Q$ values of
$\Theta $ arguments. These are followed by initial values of the transfer function model arguments
${\omega}_{0},{\omega}_{1},\dots ,{\omega}_{{q}_{1}}$,
${\delta}_{1},{\delta}_{2},\dots ,{\delta}_{{p}_{1}}$ for the first of any input series and similarly for each subsequent input series. The final component of
para is the initial value of the constant
$c$, whether it is fixed or is to be estimated.
On exit: the latest values of the estimates of these arguments.

5:
$\mathbf{npara}$ – Integer
Input

On entry: the exact number of $\varphi $, $\theta $, $\Phi $, $\Theta $, $\omega $, $\delta $ and $c$ arguments.
Constraint:
${\mathbf{npara}}=p+q+P+Q+{\mathbf{nseries}}+\sum \left({p}_{i}+{q}_{i}\right)$, the summation being over all the input series. ($c$ must be included, whether fixed or estimated.)

6:
$\mathbf{nxxy}$ – Integer
Input

On entry: the (common) length of the original, undifferenced input and output time series.

7:
$\mathbf{xxy}\left[{\mathbf{nxxy}}\times {\mathbf{tdxxy}}\right]$ – const double
Input

Note: the $\left(i,j\right)$th element of the matrix is stored in ${\mathbf{xxy}}\left[\left(i1\right)\times {\mathbf{tdxxy}}+j1\right]$.
On entry: the columns of
xxy must contain the
nxxy original, undifferenced values of each of the input series,
${x}_{t}$, and the output series,
${y}_{t}$, in that order.

8:
$\mathbf{tdxxy}$ – Integer
Input

On entry: the stride separating matrix column elements in the array
xxy.
Constraint:
${\mathbf{tdxxy}}\ge {\mathbf{nseries}}$.

9:
$\mathbf{sd}\left[{\mathbf{npara}}\right]$ – double
Output

On exit: the
npara values of the standard deviations corresponding to each of the arguments in
para. When the constant is fixed its standard deviation is returned as zero. When the values of
para are valid, the values of
sd are usually also valid unless the function fails to invert the second derivative matrix in which case
fail will have an exit value of
NE_MAT_NOT_POS_DEF.

On exit: the residual sum of squares, $S$, at the latest set of valid parameter estimates.

11:
$\mathbf{objf}$ – double *
Output

On exit: the objective function, $D$, at the latest set of valid parameter estimates.

12:
$\mathbf{df}$ – double *
Output

On exit: the degrees of freedom associated with $S$.

13:
$\mathbf{options}$ – Nag_G13_Opt *
Input/Output

On entry/exit: a pointer to a structure of type Nag_G13_Opt whose members are optional parameters for
g13bec. If the optional parameters are not required, then the null pointer,
G13_DEFAULT, can be used in the function call to
g13bec. Details of the optional parameters and their types are given below in
Section 11.2.

14:
$\mathbf{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
 If the intermediate results of optimization are written to a file using the optional parameter ${\mathbf{options}}\mathbf{.}{\mathbf{outfile}}$, then NE_NOT_APPEND_FILE, NE_WRITE_ERROR and NE_NOT_CLOSE_FILE could also occur.
 NE_2_INT_ARG_LT

On entry, ${\mathbf{tdxxy}}=\u2329\mathit{\text{value}}\u232a$ while ${\mathbf{nseries}}=\u2329\mathit{\text{value}}\u232a$. These arguments must satisfy ${\mathbf{tdxxy}}\ge {\mathbf{nseries}}$.
 NE_ALLOC_FAIL

Dynamic memory allocation failed.
 NE_ARIMA_TEST_FAILED

On entry, or during execution, one or more sets of the ARIMA ($\varphi $, $\theta $, $\Phi $ or $\Theta $) arguments do not satisfy the stationarity or invertibility test conditions.
 NE_BAD_PARAM

On entry, argument ${\mathbf{options}}\mathbf{.}{\mathbf{cfixed}}$ had an illegal value.
On entry, argument ${\mathbf{options}}\mathbf{.}{\mathbf{criteria}}$ had an illegal value.
On entry, argument ${\mathbf{options}}\mathbf{.}{\mathbf{print\_level}}$ had an illegal value.
 NE_CONSTRAINT

General constraint: $\u2329\mathit{\text{value}}\u232a$.
 NE_DELTA_TEST_FAILED

On entry, or during execution, one or more sets of $\delta $ arguments do not satisfy the stationarity or invertibility test conditions.
 NE_DIFORDER_LEN_INCONSIST

The orders of differencing specified in the structure arimav must satisfy ${\mathbf{nxxy}}>\mathbf{arimav}\mathbf{\to}\mathbf{d}+$ ($\mathbf{arimav}\mathbf{\to}\mathbf{s}*\mathbf{arimav}\mathbf{\to}\mathbf{bigd}$), ${\mathbf{nxxy}}=\u2329\mathit{\text{value}}\u232a$, $\mathbf{arimav}\mathbf{\to}\mathbf{d}=\u2329\mathit{\text{value}}\u232a$, $\mathbf{arimav}\mathbf{\to}\mathbf{s}=\u2329\mathit{\text{value}}\u232a$, $\mathbf{arimav}\mathbf{\to}\mathbf{bigd}=\u2329\mathit{\text{value}}\u232a$.
 NE_G13_OPTIONS_NOT_INIT

On entry, the option structure,
options, has not been initialized using
g13bxc.
 NE_G13_ORDERS_NOT_INIT

On entry, the orders array structure,
transfv, has not been successfully initialized using function
g13byc.
 NE_INT_ARG_LT

On entry, ${\mathbf{nseries}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{nseries}}\ge 1$.
On entry, ${\mathbf{options}}\mathbf{.}{\mathbf{gamma}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{options}}\mathbf{.}{\mathbf{gamma}}\ge 0.0$.
On entry, ${\mathbf{options}}\mathbf{.}{\mathbf{max\_iter}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{options}}\mathbf{.}{\mathbf{max\_iter}}\ge 0$.
 NE_INT_ARRAY_2

Value
$\u2329\mathit{\text{value}}\u232a$ given to
transfv.
$\mathbf{transfv}\mathbf{\to}\mathbf{r}\left[\u2329\mathit{\text{value}}\u232a\right]$ not valid. Correct range for elements of
transfv.
$\mathbf{transfv}\mathbf{\to}\mathbf{r}$ is
$1\le \mathbf{transfv}\mathbf{\to}\mathbf{r}\left[i\right]\le 3$.
 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.
 NE_INVALID_NSER

On entry, ${\mathbf{nseries}}=1$ and there are no arguments in the model, i.e., ($p=q=P=Q=0$ and ${\mathbf{options}}\mathbf{.}{\mathbf{cfixed}}=\mathrm{Nag\_TRUE}$).
 NE_ITER_FAIL_NIT

The function has failed to converge after
${\mathbf{options}}\mathbf{.}{\mathbf{max\_iter}}$ iterations, where
${\mathbf{options}}\mathbf{.}{\mathbf{max\_iter}}=\u2329\mathit{\text{value}}\u232a$. If steady decreases in the objective function,
$D$, were monitored up to the point where this exit occurred, see the optional parameter
${\mathbf{options}}\mathbf{.}{\mathbf{print\_level}}$, then
${\mathbf{options}}\mathbf{.}{\mathbf{max\_iter}}$ was probably set too small. If so the calculations should be restarted from the final point held in
para.
 NE_MAT_NOT_POS_DEF

Attempt to invert the second derivative matrix needed in the calculation of the covariance matrix of the parameter estimates has failed. The matrix is not positive definite, possibly due to rounding errors.
 NE_NOT_APPEND_FILE

Cannot open file $\u2329\mathit{string}\u232a$ for appending.
 NE_NOT_CLOSE_FILE

Cannot close file $\u2329\mathit{string}\u232a$.
 NE_NPARA_MR_MT_INCONSIST

On entry, there is inconsistency between
npara on the one hand and the elements in the orders structures,
arimav and
transfv on the other.
 NE_NSER_INCONSIST

Value of
nseries passed to
g13byc was
$\u2329\mathit{\text{value}}\u232a$ which is not equal to the value
$\u2329\mathit{\text{value}}\u232a$ passed in this function.
 NE_REAL_ARG_GE

On entry, ${\mathbf{options}}\mathbf{.}{\mathbf{gamma}}$ must not be greater than or equal to 1.0: ${\mathbf{options}}\mathbf{.}{\mathbf{gamma}}=\u2329\mathit{\text{value}}\u232a$.
 NE_REAL_ARG_LE

On entry, ${\mathbf{options}}\mathbf{.}{\mathbf{alpha}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{options}}\mathbf{.}{\mathbf{alpha}}>0.0$.
On entry, ${\mathbf{options}}\mathbf{.}{\mathbf{beta}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{options}}\mathbf{.}{\mathbf{beta}}>1.0$.
 NE_REAL_ARG_LT

On entry, ${\mathbf{options}}\mathbf{.}{\mathbf{delta}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{options}}\mathbf{.}{\mathbf{delta}}\ge 1.0$.
 NE_SOLUTION_FAIL_CONV

Iterative refinement has failed to improve the solution of the equations giving the latest estimates of the arguments. This occurred because the matrix of the set of equations is too illconditioned.
 NE_WRITE_ERROR

Error occurred when writing to file $\u2329\mathit{string}\u232a$.
7
Accuracy
The computation used is believed to be stable.
8
Parallelism and Performance
g13bec is not threaded in any implementation.
The time taken by g13bec is approximately proportional to ${\mathbf{nxxy}}\times {\mathbf{options}}\mathbf{.}{\mathbf{iter}}\times {{\mathbf{npara}}}^{2}$.
10
Example
The data in the example relate to 40 observations of an output time series and of a single input time series. The noise series has one autoregressive $\left(\varphi \right)$ and one seasonal moving average $\left(\Theta \right)$ argument (both of which are initially set to zero) for which the seasonal period is $4$. The input series is defined by orders ${b}_{1}=1$, ${q}_{1}=0$, ${p}_{1}=1$, ${r}_{1}=3$, so that it has one $\omega $ (initially set to 2.0) and one $\delta $ (initially set to 0.5), and allows for preobservation period effects. The constant (initially set to zero) is to be estimated so that the flag for the constant $c$, ${\mathbf{options}}\mathbf{.}{\mathbf{cfixed}}$, remains unchanged from its default value of Nag_FALSE. Default values of zsp are used. Up to 20 iterations are allowed so that ${\mathbf{options}}\mathbf{.}{\mathbf{max\_iter}}$ is set to $20$, and the progress of these is monitored and solution output by setting ${\mathbf{options}}\mathbf{.}{\mathbf{print\_level}}=\mathrm{Nag\_Soln\_Iter\_Full}$. Marginal likelihood is the chosen estimation criterion so that ${\mathbf{options}}\mathbf{.}{\mathbf{criteria}}=\mathrm{Nag\_Marginal}$.
After the successful call to g13bec, the following are computed and printed out: the correlation matrix, the residuals for the 36 differenced values and the values of ${z}_{t}$ and ${n}_{t}$.
An additional example showing how to use
g13bec to fit a seasonal ARIMA model can be found in
Byng.
10.1
Program Text
10.2
Program Data
10.3
Program Results
11
Optional Parameters
A number of optional input and output arguments to
g13bec are available through the structure argument
options of type Nag_G13_Opt. An argument may be selected by assigning an appropriate value to the relevant structure member. Those arguments not selected will be assigned default values. If no use is to be made of any of the optional parameters you should use the null pointer,
G13_DEFAULT, in place of
options when calling
g13bec; the default settings will then be used for all arguments.
Before assigning values to
options the structure must be initialized by a call to the function
g13bxc. Values may then be assigned directly to the structure members in the normal C manner.
Options selected are checked within g13bec for being within the required range, if outside the range, an error message is generated.
When all calls to
g13bec have been completed and the results contained in the options structure are no longer required; then
g13xzc should be called to free the NAG allocated memory from
options.
11.1
Optional Parameters Checklist and Default Values
For easy reference, the following list shows the input and output members of
options which are valid for
g13bec together with their default values where relevant.
$\epsilon $ is the
machine precision.
Boolean ${\mathbf{options}}\mathbf{.}{\mathbf{list}}$ 
Nag_TRUE 
Nag_PrintType ${\mathbf{options}}\mathbf{.}{\mathbf{print\_level}}$ 
$\mathrm{Nag\_Soln}$ 
char outfile[80] 
stdout 
void (*${\mathbf{options}}\mathbf{.}{\mathbf{print\_fun}}$)() 
NULL 
Boolean ${\mathbf{options}}\mathbf{.}{\mathbf{cfixed}}$ 
Nag_FALSE 
Nag_Likelihood ${\mathbf{options}}\mathbf{.}{\mathbf{criteria}}$ 
$\mathrm{Nag\_Exact}$ 
Integer${\mathbf{options}}\mathbf{.}{\mathbf{max\_iter}}$ 
50 
double ${\mathbf{options}}\mathbf{.}{\mathbf{alpha}}$ 
0.01 
double ${\mathbf{options}}\mathbf{.}{\mathbf{beta}}$ 
10.0 
double ${\mathbf{options}}\mathbf{.}{\mathbf{delta}}$ 
1000.0 
double ${\mathbf{options}}\mathbf{.}{\mathbf{gamma}}$ 
$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(100\epsilon ,{10}^{7}\right)$ 
Integer ${\mathbf{options}}\mathbf{.}{\mathbf{iter}}$ 
double *${\mathbf{options}}\mathbf{.}{\mathbf{cm}}$ 
double *${\mathbf{options}}\mathbf{.}{\mathbf{res}}$ 
Integer ${\mathbf{options}}\mathbf{.}{\mathbf{lenres}}$ 
double *${\mathbf{options}}\mathbf{.}{\mathbf{zt}}$ 
double *${\mathbf{options}}\mathbf{.}{\mathbf{noise}}$ 
11.2
Description of the Optional Parameters
On entry: if ${\mathbf{options}}\mathbf{.}{\mathbf{list}}=\mathrm{Nag\_TRUE}$ then the argument settings which are used in the call to g13bec will be printed.
print_level – Nag_PrintType   
On entry: the level of results produced by
g13bec. The following values are available:
$\mathrm{Nag\_NoPrint}$ 
No output. 
$\mathrm{Nag\_Soln}$ 
The final solution. 
$\mathrm{Nag\_Iter}$ 
One line of output for each iteration. 
$\mathrm{Nag\_Soln\_Iter}$ 
The final solution and one line of output for each iteration. 
$\mathrm{Nag\_Soln\_Iter\_Full}$ 
The final solution and detailed printout at each iteration. 
Details of each level of results printout are described in Section 7.3.
Constraint:
${\mathbf{options}}\mathbf{.}{\mathbf{print\_level}}=\mathrm{Nag\_PrintNotSet}$, $\mathrm{Nag\_Soln}$, $\mathrm{Nag\_Iter}$, $\mathrm{Nag\_Soln\_Iter}$ or $\mathrm{Nag\_Soln\_Iter\_Full}$.
On entry: name of file to which the results of monitoring the course of the optimization should be printed. If ${\mathbf{options}}\mathbf{.}{\mathbf{outfile}}\left[0\right]=\text{''}\backslash 0\text{''}$ then the stdout stream is used.
print_fun – pointer to function   
On entry: printing function defined by you; the prototype of
${\mathbf{options}}\mathbf{.}{\mathbf{print\_fun}}$ is
void (*print_fun)(const Nag_UserPrintFun *bfx, Nag_Comm *Comm);
See
Section 11.3.1 below for further details.
On entry: ${\mathbf{options}}\mathbf{.}{\mathbf{cfixed}}$ must be set to Nag_TRUE if the constant $c$ is to remain fixed at its initial value, and to Nag_FALSE if it is to be estimated.
criteria – Nag_Likelihood   
On entry: indicates the likelihood option for the estimation criterion. ${\mathbf{options}}\mathbf{.}{\mathbf{criteria}}$ must be set to $\mathrm{Nag\_LeastSquares}$, $\mathrm{Nag\_Exact}$ or $\mathrm{Nag\_Marginal}$, to select the least squares, exact or marginal likelihood, respectively.
Constraint:
${\mathbf{options}}\mathbf{.}{\mathbf{criteria}}=\mathrm{Nag\_LeastSquares}$, $\mathrm{Nag\_Exact}$ or $\mathrm{Nag\_Marginal}$.
On entry: the maximum required number of iterations. If
${\mathbf{options}}\mathbf{.}{\mathbf{max\_iter}}=0$, no change is made to any of the model arguments in array
para except that the constant
$c$ (if
${\mathbf{options}}\mathbf{.}{\mathbf{cfixed}}=\mathrm{Nag\_FALSE}$) and any
$\omega $ relating to simple input series are estimated. (Apart from these, estimates are always derived for the nuisance arguments relating to any backforecasts and any preobservation period effects for transfer function inputs.)
Constraint:
${\mathbf{options}}\mathbf{.}{\mathbf{max\_iter}}\ge 0$.
On entry:
$\alpha $, the value used to constrain the magnitude of the search procedure steps (see
Section 3.3).
Constraint:
${\mathbf{options}}\mathbf{.}{\mathbf{alpha}}>0.0$.
On entry:
$\beta $, the multiplier which regulates the value of
$\alpha $ (see
Section 3.3).
Constraint:
${\mathbf{options}}\mathbf{.}{\mathbf{beta}}>1.0$.
On entry:
$\delta $, the value of the stationarity and invertibility test tolerance factor (see
Section 3.3).
Constraint:
${\mathbf{options}}\mathbf{.}{\mathbf{delta}}\ge 1.0$.
On entry:
$\gamma $, the convergence criterion (see
Section 3.3).
Constraint:
$0.0\le {\mathbf{options}}\mathbf{.}{\mathbf{gamma}}<1.0$.
On exit: the number of iterations carried out. A value of ${\mathbf{options}}\mathbf{.}{\mathbf{iter}}=1$ on exit indicates that the only estimates obtained up to this point have been for the nuisance arguments relating to backforecasts, unless the marginal likelihood option is used in which case estimates have also been obtained for simple input coefficients $\omega $ and for the constant $c$ (if ${\mathbf{options}}\mathbf{.}{\mathbf{cfixed}}=\mathrm{Nag\_FALSE}$). This value of ${\mathbf{options}}\mathbf{.}{\mathbf{iter}}$ usually indicates a failure in a consequent step of estimating transfer function input preobservation period nuisance arguments. A value of ${\mathbf{options}}\mathbf{.}{\mathbf{iter}}=0$ on exit indicates that estimates have been obtained up to this point for the constant $c$ (if ${\mathbf{options}}\mathbf{.}{\mathbf{cfixed}}=\mathrm{Nag\_FALSE}$), for simple input coefficients $\omega $ and for the nuisance arguments relating to the backforecasts and to transfer function input preobservation period effects.
On exit: this pointer is allocated memory internally with
${\mathbf{npara}}\times {\mathbf{npara}}$ elements corresponding to
npara rows by
npara columns. The
npara rows and columns of
${\mathbf{options}}\mathbf{.}{\mathbf{cm}}$ contain the correlation coefficients relating to each pair of arguments in
para. All coefficients relating to the constant will be zero if the constant is fixed. However, if the function fails to invert the second derivative matrix, in which case
fail will have an exit value of
NE_MAT_NOT_POS_DEF, then the contents of
${\mathbf{options}}\mathbf{.}{\mathbf{cm}}$ will be indeterminate.
On exit: the values of the residuals relating to the differenced values of the output series. This pointer is allocated memory internally with ${\mathbf{options}}\mathbf{.}{\mathbf{lenres}}$ elements.
On exit: the length of ${\mathbf{options}}\mathbf{.}{\mathbf{res}}$.
On exit: this pointer is allocated memory internally with
${\mathbf{nxxy}}\times \left({\mathbf{nseries}}1\right)$ elements corresponding to
nxxy rows by
$\left({\mathbf{nseries}}1\right)$ columns. The columns of
${\mathbf{options}}\mathbf{.}{\mathbf{zt}}$ hold the values of the input component series
${z}_{t}$.
On exit: this pointer is allocated memory internally with
nxxy elements. It holds the output noise component
${n}_{t}$.
11.3
Description of Printed Output
The level of printed output can be controlled with the structure members
${\mathbf{options}}\mathbf{.}{\mathbf{list}}$ and
${\mathbf{options}}\mathbf{.}{\mathbf{print\_level}}$, see Section 7.2. If
${\mathbf{options}}\mathbf{.}{\mathbf{list}}=\mathrm{Nag\_TRUE}$ then the argument values to
g13bec are listed, whereas the printout of results is governed by the value of
${\mathbf{options}}\mathbf{.}{\mathbf{print\_level}}$. The default of
${\mathbf{options}}\mathbf{.}{\mathbf{print\_level}}=\mathrm{Nag\_Soln}$ which provides a printout of the final solution. This section describes all of the possible levels of results printout available from
g13bec. When
${\mathbf{options}}\mathbf{.}{\mathbf{print\_level}}=\mathrm{Nag\_Iter}$ or
$\mathrm{Nag\_Soln\_Iter}$ a single line of output is produced at each iteration, this gives the following values.
Iter 
the current iteration number, ${\mathbf{options}}\mathbf{.}{\mathbf{iter}}$. 
Residual 
the residual sum of squares, $\mathbf{print\_fun}\mathbf{\to}\mathbf{rss}$. 
Objf 
the objective function at the latest set of parameter estimates. 
When
${\mathbf{options}}\mathbf{.}{\mathbf{print\_level}}=\mathrm{Nag\_Soln\_Iter\_Full}$ a description and value for each of the arguments in the para array is output. The descriptions are phi for
$\varphi $, theta for
$\theta $, sphi for
$\Phi $. stheta for
$\Theta $, omega/si for
$\omega $ in a simple input, omega for
$\omega $ in a transfer function input,
${\mathbf{options}}\mathbf{.}{\mathbf{delta}}$ for
$\delta $ and constant for
$c$. In addition series 1, series 2, etc, indicate the input series relevant to the omega and
${\mathbf{options}}\mathbf{.}{\mathbf{delta}}$ arguments.
If ${\mathbf{options}}\mathbf{.}{\mathbf{print\_level}}=\mathrm{Nag\_Soln}$, $\mathrm{Nag\_Soln\_Iter}$ or $\mathrm{Nag\_Soln\_Iter\_Full}$ the final solution is printed out. This consists of:
i 
the argument number. 
para[i] 
the values of the argument. 
sd 
the standard deviations. 
options.iter 
the number of iterations carried out. 
rss 
the residual sum of squares. 
objf 
the objective function. 
df 
the degrees of freedom. 
If ${\mathbf{options}}\mathbf{.}{\mathbf{print\_level}}=\mathrm{Nag\_NoPrint}$ then printout will be suppressed; you can print the final solution when g13bec returns to the calling program.
11.3.1
Output of results via a userdefined printing function
You may also specify their own print function for output of iteration results and the final solution by use of the ${\mathbf{options}}\mathbf{.}{\mathbf{print\_fun}}$ function pointer, prototype
void (*print_fun) (const Nag_UserPrintFun *bfx, Nag_Comm *Comm);
The rest of this section can be skipped if the default printing facilities provide the required functionality. When a userdefined function is assigned to ${\mathbf{options}}\mathbf{.}{\mathbf{print\_fun}}$ this will be called in preference to the internal print function of g13bec. Calls to the userdefined function are again controlled by means of the ${\mathbf{options}}\mathbf{.}{\mathbf{print\_level}}$ member. Information is provided through two structure arguments to ${\mathbf{options}}\mathbf{.}{\mathbf{print\_fun}}$, the structure of type $\mathrm{Nag\_UserPrintFun}$ contains the following members relevant to g13bec:
 itc – Integer

The number of the particular iteration being monitored.

The residual sum of squares, $S$, at the latest set of valid parameter estimates.
 objf – double *

The objective function, $D$, at the latest set of valid parameter estimates.
 para – double *

The pointer to memory containing $\mathbf{print\_fun}\mathbf{\to}\mathbf{npara}$ latest values of the estimates of the multiinput model arguments.
 npara – Integer

The exact number of $\varphi $, $\theta $, $\Phi $, $\Theta $, $\omega $, $\delta $ and $c$ arguments.
 npe – Integer

The number of ARIMA ($\varphi $, $\theta $, $\Phi $, $\Theta $), omega $\left(\omega \right)$, ${\mathbf{options}}\mathbf{.}{\mathbf{delta}}$ $\left(\delta \right)$, and $c$ arguments being estimated.
 mtyp – Integer
 mser – Integer

The pointers to memory, each with
$\mathbf{print\_fun}\mathbf{\to}\mathbf{npe}$ elements. The value of each element in
$\mathbf{print\_fun}\mathbf{\to}\mathbf{mtyp}$ and
$\mathbf{print\_fun}\mathbf{\to}\mathbf{mser}$ corresponds to the description of each parameter estimated in
$\mathbf{print\_fun}\mathbf{\to}\mathbf{para}$. The following should be read in conjunction with the description of the argument
print. The relevant description for the value of
$\mathbf{print\_fun}\mathbf{\to}\mathbf{para}$ is:
$\mathbf{print\_fun}\mathbf{\to}\mathbf{mtyp}\left[i\right]$ 
Description 
1 
phi 
2 
theta 
3 
sphi 
4 
stheta 
5 
omega/si 
series $\mathbf{print\_fun}\mathbf{\to}\mathbf{mser}\left[i\right]$ 
6 
omega 
series $\mathbf{print\_fun}\mathbf{\to}\mathbf{mser}\left[i\right]$ 
7 
${\mathbf{options}}\mathbf{.}{\mathbf{delta}}$ 
series $\mathbf{print\_fun}\mathbf{\to}\mathbf{mser}\left[i\right]$ 
8 
constant 
for $i=0,1,\dots ,\mathbf{print\_fun}\mathbf{\to}\mathbf{npe}$. For the phi, theta, sphi, stheta and constant arguments, $\mathbf{print\_fun}\mathbf{\to}\mathbf{mser}\left[i\right]=0$.
 sd – double *

The pointer to memory containing the npara values of the standard deviations.
 df – double *

The number of degrees of freedom associated with S.