PDF version (NAG web site
, 64bit version, 64bit version)
NAG Toolbox: nag_tsa_multi_inputmod_estim (g13be)
Purpose
nag_tsa_multi_inputmod_estim (g13be) fits a multiinput model relating one output series to the input series with a choice of three different estimation criteria: nonlinear least squares, exact likelihood and marginal likelihood. When no input series are present, nag_tsa_multi_inputmod_estim (g13be) fits a univariate ARIMA model.
Syntax
[
para,
xxy,
zsp,
itc,
sd,
cm,
s,
d,
ndf,
res,
sttf,
nsttf,
ifail] = g13be(
mr,
mt,
para,
xxy, 'nser',
nser, 'npara',
npara, 'kfc',
kfc, 'nxxy',
nxxy, 'kef',
kef, 'nit',
nit, 'zsp',
zsp, 'iwa',
iwa, 'imwa',
imwa, 'kpriv',
kpriv)
[
para,
xxy,
zsp,
itc,
sd,
cm,
s,
d,
ndf,
res,
sttf,
nsttf,
ifail] = nag_tsa_multi_inputmod_estim(
mr,
mt,
para,
xxy, 'nser',
nser, 'npara',
npara, 'kfc',
kfc, 'nxxy',
nxxy, 'kef',
kef, 'nit',
nit, 'zsp',
zsp, 'iwa',
iwa, 'imwa',
imwa, 'kpriv',
kpriv)
Note: the interface to this routine has changed since earlier releases of the toolbox:
At Mark 23: 
isttf, kzef and kzsp were removed from the interface; iwa, imwa, zsp, kfc, nit, kef and kpriv were made optional 
At Mark 22: 
nxxy was made optional 
Description
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}_{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
(i) 
${\nabla}^{d}{\nabla}_{s}^{D}{n}_{t}=c+{w}_{t}$ 
(ii) 
${w}_{t}={\Phi}_{1}{w}_{ts}+{\Phi}_{2}{w}_{t2\times s}+\cdots +{\Phi}_{P}{w}_{tP\times s}+{e}_{t}{\Theta}_{1}{e}_{ts}{\Theta}_{2}{e}_{t2\times s}\cdots {\Theta}_{Q}{e}_{tQ\times s}$ 
(iii) 
${e}_{t}={\varphi}_{1}{e}_{t1}+{\varphi}_{2}{e}_{t2}+\cdots +{\varphi}_{p}{e}_{tp}+{a}_{t}{\theta}_{1}{a}_{t1}{\theta}_{2}{a}_{t2}\cdots {\theta}_{q}{a}_{tq}$ 
as outlined in
Description in
nag_tsa_uni_arima_estim (g13ae).
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 parameter $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 \text{}$, 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 \text{}$, close to zero. The series mean $\stackrel{}{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 parameters and estimate them along with the other parameters. 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 parameters 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 parameters, these parameters may be colinear and lead to failure of the function. The option must then be ‘switched off’ for one or more inputs.
The Estimation Criterion
This is a measure of how well a proposed set of parameters in the transfer function and noise ARIMA models matches the data. The estimation function searches for parameter values which minimize this criterion. For a proposed set of parameter 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 (i), (ii) and (iii) 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}$.
This is identical to the treatment given in
Description in
nag_tsa_uni_arima_estim (g13ae), and leads to a criterion which is a sum of squares function
$S$, of the residuals
${a}_{t}$.
It may be shown that the finite algorithm presented there is equivalent to taking the infinite set of past values
${n}_{0},{n}_{1},{n}_{2},\dots $, as (linear) nuisance parameters.
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 page 273 of
Box and Jenkins (1976), 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 parameters. The second is the exact likelihood criterion which considers the past set ${n}_{0},{n}_{1},{n}_{2}$ not as simple nuisance parameters, 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 parameters. The value of $M$ is always $\text{}\ge 1$, and $M$ tends to $1$ for any fixed parameter 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 parameters 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 \text{}$. 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 parameters which is caused by estimation of the simple inputs. This is particularly important in relatively short series.
nag_tsa_multi_inputmod_estim (g13be) can be used with no input series present, to estimate a univariate ARIMA model for the output 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.
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 a parameter
$\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 parameters (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 parameters ‘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 presented at the initial parameter values, except for 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 parameters 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 parameter values presented, unless convergence of those parameters 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 parameter values presented.
Further Results
The residual variance is taken as $\mathit{erv}=\frac{S}{\mathit{df}}$, where $\mathit{df}=N\text{}$(total number of parameters estimated), is the residual degrees of freedom.
The preperiod nuisance parameters for the input series are included in the reduction of $\mathit{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 linearized 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 place of the supplied series values, in order to assess the effects of the various inputs on the output.
Forecasting Information
For the purpose of constructing forecasts of the output series at future time points
$t=n+1,n+2,\dots \text{}$ using
nag_tsa_multi_inputmod_forecast_state (g13bh), it is not necessary to use the whole set of observations
${y}_{t}$ and
${x}_{1,\mathit{t}},{x}_{2,\mathit{t}},\dots ,{x}_{m,\mathit{t}}$, for
$\mathit{t}=1,2,\dots ,m$. It is sufficient to retain a limited set of quantities constituting the ‘state set’ as follows: for each series which appears with lagged subscripts in equations
(a),
(b),
(i),
(ii) and
(iii) above, include the values at times
$n+1k$ for
$k=1$ up to the maximum lag associated with that series in the equations. Note that
(i) implicitly includes past values of
${n}_{t}$ and intermediate differences of
${n}_{t}$ such as
${\nabla}^{d1}{\nabla}_{s}^{D}$.
If later observations of the series become available, it is possible to update the state set (without reestimating the model) using
nag_tsa_multi_inputmod_update (g13bg). If time series data is supplied with a previously estimated model, it is possible to construct the state set (and forecasts) using
nag_tsa_multi_inputmod_forecast (g13bj).
References
Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day
Marquardt D W (1963) An algorithm for least squares estimation of nonlinear parameters J. Soc. Indust. Appl. Math. 11 431
Parameters
Compulsory Input Parameters
 1:
$\mathrm{mr}\left(7\right)$ – int64int32nag_int array

The orders vector
$\left(p,d,q,P,D,Q,s\right)$ 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)$ parameters.
$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:
$\mathrm{mt}\left(4,{\mathbf{nser}}\right)$ – int64int32nag_int array

The transfer function model orders
$b$,
$p$ and
$q$ of each of the input series. The order arguments for input series
$i$ are held in column
$i$. Row
$1$ holds the value
${b}_{i}$, row 2 holds the value
${q}_{i}$ and row 3 holds the value
${p}_{i}$. For a simple input,
${b}_{i}={q}_{i}={p}_{i}=0$.
Row 4 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 parameters.
When ${r}_{i}=1$, any nonzero contents of rows 1, 2, and 3 of column $i$ are ignored.
Constraint:
${\mathbf{mt}}\left(4,\mathit{i}\right)=1\text{,}2\text{ or}3$, for $\mathit{i}=1,2,\dots ,{\mathbf{nser}}1$.
 3:
$\mathrm{para}\left({\mathbf{npara}}\right)$ – double array

Initial values of the multiinput model parameters. These are in order, firstly the ARIMA model parameters:
$p$ values of
$\varphi $ parameters,
$q$ values of
$\theta $ parameters,
$P$ values of
$\Phi $ parameters and
$Q$ values of
$\Theta $ parameters. These are followed by initial values of the transfer function model parameters
${\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.
 4:
$\mathrm{xxy}\left(\mathit{ldxxy},{\mathbf{nser}}\right)$ – double array

ldxxy, the first dimension of the array, must satisfy the constraint
$\mathit{ldxxy}\ge {\mathbf{nxxy}}$.
The columns of
xxy must contain the
nxxy original, undifferenced values of each of the input series and the output series
${x}_{t}$ in that order.
Optional Input Parameters
 1:
$\mathrm{nser}$ – int64int32nag_int scalar

Default:
the second dimension of the arrays
mt,
xxy. (An error is raised if these dimensions are not equal.)
The total number of input and output series. There may be any number of input series (including none), but always one output series.
Constraints:
 ${\mathbf{nser}}\ge 1$;
 if there are no parameters in the model (that is, $p=q=P=Q=0$ and ${\mathbf{kfc}}=0$), ${\mathbf{nser}}>1$.
 2:
$\mathrm{npara}$ – int64int32nag_int scalar

Default:
the dimension of the array
para.
The exact number of $\varphi ,\theta ,\Phi ,\Theta $, $\omega ,\delta $ and $c$ parameters.
Constraint:
${\mathbf{npara}}=p+q+P+Q+{\mathbf{nser}}+\sum \left({p}_{i}+{q}_{i}\right)$, the summation being over all the
${p}_{i}\ne {q}_{i}$ supplied in
mt.
$c$ must be included, whether fixed or estimated.
 3:
$\mathrm{kfc}$ – int64int32nag_int scalar
Default:
$1$
Must be set to $0$ if the constant $c$ is to remain fixed at its initial value, and $1$ if it is to be estimated.
Constraint:
${\mathbf{kfc}}=0$ or $1$.
 4:
$\mathrm{nxxy}$ – int64int32nag_int scalar

Default:
the first dimension of the array
xxy.
The (common) length of the original, undifferenced input and output time series.
 5:
$\mathrm{kef}$ – int64int32nag_int scalar
Default:
$2$
Indicates the likelihood option.
 ${\mathbf{kef}}=1$
 Gives least squares.
 ${\mathbf{kef}}=2$
 Gives exact likelihood.
 ${\mathbf{kef}}=3$
 Gives marginal likelihood.
Constraint:
${\mathbf{kef}}=1$, $2$ or $3$.
 6:
$\mathrm{nit}$ – int64int32nag_int scalar
Default:
$1000$
The maximum required number of iterations.
 ${\mathbf{nit}}=0$
 No change is made to any of the model parameters in array para except that the constant $c$ (if ${\mathbf{kfc}}=1$) and any $\omega $ relating to simple input series are estimated. (Apart from these, estimates are always derived for the nuisance parameters relating to any backforecasts and any preobservation period effects for transfer function inputs.)
Constraint:
${\mathbf{nit}}\ge 0$.
 7:
$\mathrm{zsp}\left(4\right)$ – double array

If
$\mathit{kzsp}=1$, then
zsp must contain the four values used to control the strategy of the search procedure.
 ${\mathbf{zsp}}\left(1\right)$
 Contains $\alpha $, the value used to constrain the magnitude of the search procedure steps.
 ${\mathbf{zsp}}\left(2\right)$
 Contains $\beta $, the multiplier which regulates the value of $\alpha $.
 ${\mathbf{zsp}}\left(3\right)$
 Contains $\delta $, the value of the stationarity and invertibility test tolerance factor.
 ${\mathbf{zsp}}\left(4\right)$
 Contains $\gamma $, the value of the convergence criterion.
If
$\mathit{kzsp}\ne 1$ before entry, default values of
zsp are supplied by the function. These are
$0.01$,
$10.0$,
$1000.0$ and
$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(100\times \mathit{machineprecision},0.0000001\right)$, respectively.
Constraint:
if $\mathit{kzsp}=1$, ${\mathbf{zsp}}\left(1\right)>0.0$, ${\mathbf{zsp}}\left(2\right)>1.0$, ${\mathbf{zsp}}\left(3\right)\ge 1.0$, $0\le {\mathbf{zsp}}\left(4\right)<1.0$.
 8:
$\mathrm{iwa}$ – int64int32nag_int scalar
Default:
$5\times \left(2\times {\mathrm{ncd}}^{2}+\mathrm{nce}\times \left(\mathrm{ncf}+4\right)\right)$
The dimension of the array
wa.
It is not practical to outline a method for deriving the exact minimum permissible value of
iwa, but the following gives a reasonably good conservative approximation. (It should be noted that if
iwa is too small (but not grossly so) then the exact minimum is printed if
${\mathbf{kpriv}}\ne 0$.)
Let ${q}^{\prime}=q+\left(Q\times s\right)$ and ${d}^{\prime}=d+\left(D\times s\right)$ where the orders of the output noise model are $p$, $d$, $q$, $P$, $D$, $Q$, $s$.
Let there be $l$ input series, where $l={\mathbf{nser}}1$.
Let
where the transfer function model orders for input
$i$ are given by
${b}_{i}$,
${q}_{i}$,
${p}_{i}$,
${r}_{i}$.
Let $qx=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({q}^{\prime},m{x}_{1},m{x}_{2},\dots ,m{x}_{l}\right)$.
Let $\mathit{ncd}={\mathbf{npara}}+{\mathbf{kfc}}+qx+{\displaystyle \sum _{i=1}^{l}}m{x}_{i}$ and $\mathit{nce}={\mathbf{nxxy}}+{d}^{\prime}+6\times qx$.
Finally, let $\mathit{ncf}={\mathbf{nser}}$, and then increment $\mathit{ncf}$ by $1$ every time any of the following conditions is satisfied. (The last six conditions should be applied separately to each input series, so that, for example, if we have two input series and if ${p}_{1}>0$ and ${p}_{2}>0$ then $\mathit{ncf}$ is incremented by $2$.)
Then ${\mathbf{iwa}}\ge 2\times {\left(\mathit{ncd}\right)}^{2}+\left(\mathit{nce}\right)\times \left(\mathit{ncf}+4\right)$.
 9:
$\mathrm{imwa}$ – int64int32nag_int scalar
Default:
$5\times \left(16\times {\mathbf{nser}}+7\times \mathrm{ncd}+3\times {\mathbf{npara}}+3\times {\mathbf{kfc}}+27\right)$
The dimension of the array
mwa.
Constraint:
${\mathbf{imwa}}\ge \left(16\times {\mathbf{nser}}\right)+\left(7\times \mathit{ncd}\right)+\left(3\times {\mathbf{npara}}\right)+\left(3\times {\mathbf{kfc}}\right)+27$, where the derivation of
$\mathit{ncd}$ is shown under
iwa.
If
imwa is too small then if
${\mathbf{kpriv}}\ne 0$ it is printed.
 10:
$\mathrm{kpriv}$ – int64int32nag_int scalar
Default:
$0$
Must not be set to
$0$, if it is required to monitor the course of the optimization or to print out the requisite minimum values of
iwa or
imwa in the event of an error of the type
${\mathbf{ifail}}={\mathbf{6}}$ or
${\mathbf{7}}$. The course of the optimization is monitored by printing out at each iteration the iteration count (
itc), the residual sum of squares (
s), the objective function (
d) and a description and value for each of the parameters in the
para array. 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, DELTA for
$\delta $ and CONSTANT for
$c$. In addition SERIES 1, SERIES 2, etc. indicate the input series relevant to the OMEGA and DELTA parameters.
kpriv must be set to
$0$ if the printout of the above information is not required.
Output Parameters
 1:
$\mathrm{para}\left({\mathbf{npara}}\right)$ – double array

The latest values of the estimates of these parameters.
 2:
$\mathrm{xxy}\left(\mathit{ldxxy},{\mathbf{nser}}\right)$ – double array

the columns of
xxy hold the corresponding values of the input component series
${z}_{t}$ in place of
${x}_{t}$ and the output noise component
${n}_{t}$ in place of
${y}_{t}$, in that order.
 3:
$\mathrm{zsp}\left(4\right)$ – double array

Contains the values, default or otherwise, used by the function.
 4:
$\mathrm{itc}$ – int64int32nag_int scalar

The number of iterations carried out.
 ${\mathbf{itc}}=1$
 Indicates that the only estimates obtained up to this point have been for the nuisance parameters 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{kfc}}=1$). This value of itc usually indicates a failure in a consequent step of estimating transfer function input preobservation period nuisance parameters.
 ${\mathbf{itc}}=0$
 Indicates that estimates have been obtained up to this point for the constant $c$ (if ${\mathbf{kfc}}=1$), for simple input coefficients $\omega $ and for the nuisance parameters relating to the backforecasts and to transfer function input preobservation period effects.
 5:
$\mathrm{sd}\left({\mathbf{npara}}\right)$ – double array

The
npara values of the standard deviations corresponding to each of the parameters 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. However, if an exit value of
${\mathbf{ifail}}={\mathbf{3}}$,
${\mathbf{8}}$ or
${\mathbf{10}}$, then the contents of
sd will be indeterminate.
 6:
$\mathrm{cm}\left(\mathit{ldcm},{\mathbf{npara}}\right)$ – double array

The first
npara rows and columns of
cm contain the correlation coefficients relating to each pair of parameters in
para. All coefficients relating to the constant will be zero if the constant is fixed. The contents of
cm will be indeterminate under the same conditions as
sd.
 7:
$\mathrm{s}$ – double scalar

The residual sum of squares, $S$, at the latest set of valid parameter estimates.
 8:
$\mathrm{d}$ – double scalar

The objective function, $D$, at the latest set of valid parameter estimates.
 9:
$\mathrm{ndf}$ – int64int32nag_int scalar

The number of degrees of freedom associated with $S$.
 10:
$\mathrm{res}\left({\mathbf{nxxy}}\right)$ – double array

The values of the residuals relating to the differenced values of the output series. The remainder of the first
nxxy terms in the array will be zero.
 11:
$\mathrm{sttf}\left(\mathbf{isttf}\right)$ – double array

The
nsttf values of the state set array.
 12:
$\mathrm{nsttf}$ – int64int32nag_int scalar

The number of values in the state set array
sttf.
 13:
$\mathrm{ifail}$ – int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see
Error Indicators and Warnings).
Error Indicators and Warnings
Note: nag_tsa_multi_inputmod_estim (g13be) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:
 ${\mathbf{ifail}}=1$

On entry,  ${\mathbf{kfc}}<0$, 
or  ${\mathbf{kfc}}>1$, 
or  $\mathit{ldxxy}<{\mathbf{nxxy}}$, 
or  $\mathit{ldcm}<{\mathbf{npara}}$, 
or  ${\mathbf{kef}}<1$, 
or  ${\mathbf{kef}}>3$, 
or  ${\mathbf{nit}}<0$, 
or  ${\mathbf{nser}}<1$, 
or  ${\mathbf{nser}}=1$ and there are no parameters in the model ($p=q=P=Q=0$ and ${\mathbf{kfc}}=0$). 
 ${\mathbf{ifail}}=2$

On entry, there is inconsistency between
npara and
kfc on the one hand and the orders in arrays
mr and
mt on the other, or one of the
${r}_{i}$, stored in
${\mathbf{mt}}\left(4,i\right)\ne 1$,
$2$ or
$3$.
 ${\mathbf{ifail}}=3$

On entry or during execution, one or more sets of $\delta $ parameters do not satisfy the stationarity or invertibility test conditions.
 ${\mathbf{ifail}}=4$

On entry,  when $\mathit{kzsp}=1$, ${\mathbf{zsp}}\left(1\right)\le 0.0$, 
or  ${\mathbf{zsp}}\left(2\right)\le 1.0$, 
or  ${\mathbf{zsp}}\left(3\right)<1.0$, 
or  ${\mathbf{zsp}}\left(4\right)<0.0$, 
or  ${\mathbf{zsp}}\left(4\right)\ge 1.0$. 
 ${\mathbf{ifail}}=5$

On entry,
iwa is too small by a considerable margin. No information is supplied about the requisite minimum size.
 ${\mathbf{ifail}}=6$

On entry,
iwa is too small, but the requisite minimum size is returned in
$\mathit{mwa}\left(1\right)$, which is printed if
${\mathbf{kpriv}}\ne 0$.
 ${\mathbf{ifail}}=7$

On entry,
imwa is too small, but the requisite minimum size is returned in
$\mathit{mwa}\left(1\right)$, which is printed if
${\mathbf{kpriv}}\ne 0$.
 ${\mathbf{ifail}}=8$

This indicates a failure in
nag_linsys_real_posdef_solve_1rhs (f04as) which is used to solve the equations giving the latest estimates of the parameters.
 ${\mathbf{ifail}}=9$

This indicates a failure in the inversion of the second derivative matrix. This is needed in the calculation of the correlation matrix and the standard deviations of the parameter estimates.
 ${\mathbf{ifail}}=10$

On entry or during execution, one or more sets of the ARIMA ($\varphi $, $\theta $, $\Phi $ or $\Theta $) parameters do not satisfy the stationarity or invertibility test conditions.
 ${\mathbf{ifail}}=11$

On entry,
isttf is too small. The state set information will not be produced and if
$\mathbf{kzef}\ne 0$ array
xxy will remain unchanged. All other arguments will be produced correctly.
 ${\mathbf{ifail}}=12$

The function has failed to converge after
nit iterations. If steady decreases in the objective function,
$D$, were monitored up to the point where this exit occurred, then the exit probably occurred because
nit was set too small, so the calculations should be restarted from the final point held in
para.
 ${\mathbf{ifail}}=13$

On entry,
isttf is too small (see
${\mathbf{ifail}}={\mathbf{11}}$) and
nit iterations were carried out without the convergence conditions being satisfied (see
${\mathbf{ifail}}={\mathbf{12}}$).
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
Accuracy
The computation used is believed to be stable.
Further Comments
The time taken by nag_tsa_multi_inputmod_estim (g13be) is approximately proportional to ${\mathbf{nxxy}}\times {\mathbf{itc}}\times {{\mathbf{npara}}}^{2}$.
Example
After the full
$11$ iterations, the following are computed and printed out: the final values of the
para parameters and their standard errors, the correlation matrix, the residuals for the
$36$ differenced values, the values of
${z}_{t}$ and
${n}_{t}$, the values of the state set and the number of degrees of freedom.
Open in the MATLAB editor:
g13be_example
function g13be_example
fprintf('g13be example results\n\n');
mr = [int64(1); 0; 0; 0; 0; 1; 4];
mt = zeros(4, 2, 'int64');
mt(1:4,1) = [1; 0; 1; 3];
para = [0; 0; 2; 0.5; 0];
xxy = [8.075, 105; 7.819, 119; 7.366, 119; 8.113, 109;
7.380, 117; 7.134, 135; 7.222, 126; 7.768, 112;
7.386, 116; 6.965, 122; 6.478, 115; 8.105, 115;
8.060, 122; 7.684, 138; 7.580, 135; 7.093, 125;
6.129, 115; 6.026, 108; 6.679, 100; 7.414, 96;
7.112, 107; 7.762, 115; 7.645, 123; 8.639, 122;
7.667, 128; 8.080, 136; 6.678, 140; 6.739, 122;
5.569, 102; 5.049, 103; 5.642, 89; 6.808, 77;
6.636, 89; 8.241, 94; 7.968, 104; 8.044, 108;
7.791, 119; 7.024, 126; 6.102, 119; 6.053, 103];
nxxy = size(xxy,1);
kef = int64(3);
[para, xxy, zsp, itc, sd, cm, s, d, ndf, res, sttf, nsttf, ifail] = ...
g13be( ...
mr, mt, para, xxy, 'kef', kef);
fprintf('The number of iterations carried out is %4d\n\n', itc);
fprintf('Final values of the parameters and their standard deviations\n\n');
fprintf(' i parameter sd\n\n');
ivar = [1:numel(para)]';
fprintf('%4d%20.6f%20.6f\n', [ivar para sd]');
fprintf('\n');
[ifail] = x04ca( ...
'General', ' ', cm, 'The correlation matrix is');
fprintf('\nThe residuals and the z and n values are\n\n');
fprintf(' i res z n\n\n');
ndv = nxxy  mr(2)  mr(5)*mr(7);
ival = double([1:ndv]');
fprintf('%4d%15.3f%15.3f%15.3f\n', [ival res xxy(1:ndv,:)]');
ival = double([ndv+1:nxxy]');
fprintf('%4d%30.3f%15.3f\n', [ival xxy(ndv+1:nxxy,:)]');
fprintf('\nThe state set consists of %4d values\n\n', nsttf);
disp(sttf');
fprintf('\nThe number of degrees of freedom is %4d\n', ndf);
g13be example results
The number of iterations carried out is 11
Final values of the parameters and their standard deviations
i parameter sd
1 0.380924 0.166379
2 0.257786 0.178178
3 8.956084 0.948061
4 0.659641 0.060239
5 75.435521 33.505341
The correlation matrix is
1 2 3 4 5
1 1.0000 0.1839 0.1775 0.0340 0.1394
2 0.1839 1.0000 0.0518 0.2547 0.2860
3 0.1775 0.0518 1.0000 0.3070 0.2926
4 0.0340 0.2547 0.3070 1.0000 0.8185
5 0.1394 0.2860 0.2926 0.8185 1.0000
The residuals and the z and n values are
i res z n
1 0.397 180.567 75.567
2 3.086 191.430 72.430
3 2.818 196.302 77.302
4 9.941 195.460 86.460
5 5.061 201.594 84.594
6 14.053 199.076 64.076
7 2.624 195.211 69.211
8 5.823 193.450 81.450
9 2.147 197.179 81.179
10 0.216 196.217 74.217
11 2.517 191.812 76.812
12 7.916 184.544 69.544
13 1.423 194.322 72.322
14 11.936 200.369 62.369
15 5.117 200.990 65.990
16 5.672 200.468 75.468
17 5.681 195.763 80.763
18 1.637 184.025 76.025
19 1.019 175.360 75.360
20 2.623 175.492 79.492
21 3.283 182.162 75.162
22 6.896 183.857 68.857
23 5.395 190.797 67.797
24 0.875 194.327 72.327
25 4.153 205.558 77.558
26 6.206 204.261 68.261
27 4.208 207.104 67.104
28 2.387 196.423 74.423
29 11.803 189.924 87.924
30 6.435 175.158 72.158
31 1.342 160.761 71.761
32 4.924 156.575 79.575
33 4.799 164.256 75.256
34 0.074 167.783 73.783
35 6.023 184.483 80.483
36 6.427 193.055 85.055
37 2.527 199.390 80.390
38 2.039 201.302 75.302
39 0.243 195.695 76.695
40 3.166 183.738 80.738
The state set consists of 6 values
6.0530 183.7384 5.7855 0.1645 0.1800 3.0977
The number of degrees of freedom is 34
PDF version (NAG web site
, 64bit version, 64bit version)
© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015