NAG C Library, Mark 7 : g13bec

#include <nag.h> #include <nagg13.h>
void nag_tsa_multi_inp_model_estim	(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)

3 Description

3.1 The Multi-input Model

The output series

y_{t}

, for

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_{i, t}

, for

i = 1, 2, \dots, m

Thus

y_{t} = z_{1, t} + \dots + z_{m, t} + n_{t}

where

n_{t}

is the error, or output noise component.

A typical component

z_{t}

may be either:

A simple regression component, $z_{t} = ω x_{t}$ (here $x_{t}$ is called a simple input) or

A transfer function model component which allows for the effect of lagged values of the variable, related to

x_{t}

z_{t} = δ_{1} z_{t - 1} + δ_{2} z_{t - 2} + \dots + δ_{p} z_{t - p} + ω_{0} x_{t - b} - ω_{1} x_{t - b - 1} - \dots - ω_{q} x_{t - b - q} .

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:

\begin{matrix} \nabla^{d} \nabla_{s}^{D} n_{t} & c + w_{t} \\ w_{t} & Φ_{1} w_{t - s} + Φ_{2} w_{t - 2 \times s} + \dots + Φ_{P} w_{t - P \times s} + e_{t} - Θ_{1} e_{t - s} - Θ_{2} e_{t - 2 \times s} - \dots - Θ_{Q} e_{t - Q \times s} \\ e_{t} & ϕ_{1} e_{t - 1} + ϕ_{2} e_{t - 2} + \dots + ϕ_{p} e_{t - p} + a_{t} - θ_{1} a_{t - 1} - θ_{2} a_{t - 2} - \dots - θ_{q} a_{t - q} \end{matrix}

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 non-seasonal 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 = n - d - s \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

σ_{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, the user has to decide what values are to be assumed for the pre-period terms

z_{0}, z_{- 1}, \dots, z_{1 - p}

and

x_{0}, x_{- 1}, \dots, x_{1 - b - q}

which are in theory necessary to re-create 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,

the user is 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

\bar{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 pre-period 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 δ^{t}

, for

t = 1, 2, 3, \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

δ

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

\max (p, b + q)

, with a corresponding loss of degrees of freedom in the residuals. If the user aligns the input

x_{t}

with the output by using in its place the shifted series

x_{t - b}

, 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 pre-period nuisance parameters, these parameters may be co-linear 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 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:

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,
the discrepancy between the output and the sum of these components, as the noise
$n_{t} = y_{t} - (z_{1, t} + z_{2, t} + \dots + z_{m, t}),$
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 pre-period 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 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 Box and Jenkins (1976) page 273, who prove that

S = \sum_{- \infty}^{n} a_{t}^{2} .

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}, \dots

, 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

\geq 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

. 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_inp_model_estim (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 a parameter

α

, which is increased or decreased by a factor

β

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

γ

, while

α < 1

Certain model parameters (in fact all excluding the

ω

's) are subject to stability constraints which are checked throughout to within a specified tolerance multiple

δ

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 computed at the initial parameter values, except for the estimation of any pre-period 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 re-estimation of the backforecasts to their optimal values, corresponding to the model parameters presented at that iteration. This is not true for any pre-period 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 re-estimated together with the backforecasts at each iteration, to values which are optimal for the other parameter values presented.

3.4 Further Results

The residual variance is taken as

e r v = \frac{S}{d f}

where

d f = N -

(total number of parameters 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 pre-period nuisance parameters for the input series are included in the reduction of

d f

, as is the constant if it is estimated.

The covariance matrix of the vector of model parameter estimates is given by

e r v \times H^{- 1}

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 \geq 1 + q + s \times Q - p - s \times P - d - s \times D

, provided this is positive. Estimation of pre-period 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

Marquardt D W (1963) An algorithm for least-squares estimation of nonlinear parameters J. Soc. Indust. Appl. Math. 11 431

5 Parameters

1: arimav – Nag_ArimaOrder

Pointer to structure of type Nag_ArimaOrder with the following members:

p – Integer
d – Integer Input
q – Integer Input
bigp – Integer Input
bigd – Integer Input
bigq – Integer Input
s – Integer Input: On entry: these seven members of arimav must specify the orders vector $(p, d, q, P, D, Q, s)$ , respectively, of the ARIMA model for the output noise component.
$p$ , $q$ , $P$ and $Q$ refer, respectively, to the number of autoregressive $(ϕ)$ , moving average $(θ)$ , seasonal autoregressive $(Φ)$ and seasonal moving average $(Θ)$ parameters.

$d$ , $D$ and $s$ refer, respectively, to the order of non-seasonal differencing, the order of seasonal differencing and the seasonal period.

2: 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:

nseries > 1

if there are no parameters in the model (that is

p = q = P = Q = 0

and

options.cfixed = TRUE

nseries \geq 1

otherwise .

3: 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 nag_tsa_transf_orders (g13byc) which allocates $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 parameters for input series $i$ are held in the $i$ th element of the allocated memory for each pointer. $b [i - 1]$ holds the value $b_{i}$ , $q [i - 1]$ holds the value $q_{i}$ and $p [i - 1]$ holds the value $p_{i}$ . For a simple input, $b_{i} = q_{i} = p_{i} = 0$ . $r [i - 1]$ 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 pre-observation period effects, and $r_{i} = 3$ for a transfer function input for which pre-observation period effects will be treated by estimation of appropriate nuisance parameters. When $r_{i} = 1$ , any non-zero contents of the $i$ th element of b, q and p are ignored.

Constraint: $r [i - 1]$ $=$ $1$ , $2$ or $3$ , for $i = 1, 2, \dots, nseries - 1$
The memory allocated to the members of transfv must be freed by a call to nag_tsa_trans_free (g13bzc)

4: para[npara] – double Input/Output

On entry: initial values of the multi-input model parameters. These are in order, firstly the ARIMA model parameters:

p

values of

ϕ

parameters,

q

values of

θ

parameters,

P

values of

Φ

parameters and

Q

values of

Θ

parameters. These are followed by initial values of the transfer function model parameters

ω_{0}, ω_{1}, \dots, ω_{q_{1}}

δ_{1}, δ_{2}, \dots, δ_{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 parameters.

5: npara – Integer Input

On entry: the exact number of

ϕ

θ

Φ

Θ

ω

δ

and

c

parameters.

Constraint:

npara = p + q + P + Q + nseries + \sum (p_{i} + q_{i})

, the summation being over all the input series. (

c

must be included, whether fixed or estimated.) .

6: nxxy – Integer Input

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

7: xxy[nxxy][tdxxy] – const double Input

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: tdxxy – Integer Input

On entry: the second dimension of the array xxy as declared in the subroutine from which nag_tsa_multi_inp_model_estim (g13bec) is called.

Constraint:

tdxxy \geq nseries

9: sd[npara] – double Output

On exit: 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 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.

10: rss – double *Output

On exit: the residual sum of squares,

S

, at the latest set of valid parameter estimates.

11: objf – double *Output

On exit: the objective function,

D

, at the latest set of valid parameter estimates.

12: df – double *Output

On exit: the degrees of freedom associated with

S

13: 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 nag_tsa_multi_inp_model_estim (g13bec). If the optional parameters are not required, then the null pointer, G13_DEFAULT, can be used in the function call to nag_tsa_multi_inp_model_estim (g13bec). Details of the optional parameters and their types are given below in Section 10.2.

14: fail – NagError *Input/Output

The NAG error parameter, see the Essential Introduction.

6 Error Indicators and Warnings

NE_G13_OPTIONS_NOT_INIT: On entry, the option structure, options, has not been initialised using nag_tsa_options_init (g13bxc).
NE_INT_ARRAY_2: Value $〈value〉$ given to transfv. $r [〈value〉]$ not valid. Correct range for elements of transfv.r is $1 \leq r [i] \leq 3$ .
NE_G13_ORDERS_NOT_INIT: On entry, the orders array structure, transfv, has not been successfully initialised using function nag_tsa_transf_orders (g13byc).
NE_BAD_PARAM: On entry, parameter options.cfixed had an illegal value.
On entry, parameter options.criteria had an illegal value.
On entry, parameter options.print_level had an illegal value.
NE_INT_ARG_LT: On entry, nseries must not be less than 1: $nseries = 〈value〉$ .
On entry, options.max_iter must not be less than 0: $options.max_iter = 〈value〉$ .
NE_2_INT_ARG_LT: On entry $tdxxy = 〈value〉$ while $nseries = 〈value〉$ . These parameters must satisfy $tdxxy \geq nseries$ .
NE_REAL_ARG_LE: On entry, options.alpha must not be less than or equal to 0.0: $options.alpha = 〈value〉$ .
On entry, options.beta must not be less than or equal to 1.0: $options.beta = 〈value〉$ .
NE_REAL_ARG_LT: On entry, options.delta must not be less than 1.0: $options.delta = 〈value〉$ .
On entry, options.gamma must not be less than 0.0: $options.gamma = 〈value〉$ .
NE_REAL_ARG_GE: On entry, options.gamma must not be greater than or equal to 1.0: $options.gamma = 〈value〉$ .
NE_ALLOC_FAIL: Memory allocation failed.
NE_INVALID_NSER: On entry, $nseries = 1$ and there are no parameters in the model, i.e., ( $p = q = P = Q = 0$ and $options.cfixed = TRUE$ ).
NE_NSER_INCONSIST: Value of nseries passed to nag_tsa_transf_orders (g13byc) was $〈value〉$ which is not equal to the value $〈value〉$ passed in this function.
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_DELTA_TEST_FAILED: On entry, or during execution, one or more sets of $δ$ parameters do not satisfy the stationarity or invertibility test conditions.
NE_SOLUTION_FAIL_CONV: Iterative refinement has failed to improve the solution of the equations giving the latest estimates of the parameters. This occurred because the matrix of the set of equations is too ill-conditioned.
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_ARIMA_TEST_FAILED: On entry, or during execution, one or more sets of the ARIMA ( $ϕ$ , $θ$ , $Φ$ or $Θ$ ) parameters do not satisfy the stationarity or invertibility test conditions.
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 consult NAG for assistance.
NE_ITER_FAIL_NIT: The function has failed to converge after options.max_iter iterations, where $options.max_iter = 〈value〉$ . If steady decreases in the objective function, $D$ , were monitored up to the point where this exit occurred, see the optional parameter options.print_level, then options.max_iter was probably set too small. If so the calculations should be restarted from the final point held in para.
NE_DIFORDER_LEN_INCONSIST: The orders of differencing specified in the structure arimav must satisfy $nxxy > arimav . d +$ (arimav.s * arimav.bigd), $nxxy = 〈value〉$ , arimav. $d = 〈value〉$ , arimav. $s = 〈value〉$ , arimav. $bigd = 〈value〉$ .; If the intermediate results of optimization are written to a file using the optional parameter options.outfile, then the following errors could also occur.
NE_NOT_APPEND_FILE: Cannot open file $〈string〉$ for appending.
NE_WRITE_ERROR: Error occurred when writing to file $〈string〉$ .
NE_NOT_CLOSE_FILE: Cannot close file $〈string〉$ .

7 Accuracy

The computation used is believed to be stable.

8 Further Comments

The time taken by nag_tsa_multi_inp_model_estim (g13bec) is approximately proportional to

nxxy \times options.iter \times {npara}^{2}

9 Example

This example illustrates the use of the default option G13_DEFAULT in a call to nag_tsa_multi_inp_model_estim (g13bec). An example showing the use of optional parameters is given in Section 11 There is one example program file, the main program of which calls both examples. The main program is given below.

Program Text (g13bece.c)

9.1 Example 1

This example illustrates the use of the default option G13_DEFAULT in a call to nag_tsa_multi_inp_model_estim (g13bec).

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

(ϕ)

and one seasonal moving average

(Θ)

parameter (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

ω

(initially set to 2.0) and one

δ

(initially set to 0.5), and allows for pre-observation period effects.

After the successful call to nag_tsa_multi_inp_model_estim (g13bec), the following are computed and printed out: the number of full iterations required to obtain satisfactory results, the final values of the para parameters and their standard errors sd, the residual sum of squares rss, the objective function objf and the degrees of freedom.

10 Optional Parameters

A number of optional input and output parameters to nag_tsa_multi_inp_model_estim (g13bec) are available through the structure argument options of type Nag_G13_Opt. A parameter may be selected by assigning an appropriate value to the relevant structure member. Those parameters not selected will be assigned default values. If no use is to be made of any of the optional parameters the user should use the null pointer, G13_DEFAULT, in place of options when calling nag_tsa_multi_inp_model_estim (g13bec); the default settings will then be used for all parameters.

Before assigning values to options the structure must be initialised by a call to the function nag_tsa_options_init (g13bxc). Values may then be assigned directly to the structure members in the normal C manner.

Options selected are checked within nag_tsa_multi_inp_model_estim (g13bec) for being within the required range, if outside the range, an error message is generated.

When all calls to nag_tsa_multi_inp_model_estim (g13bec) have been completed and the results contained in the options structure are no longer required; then nag_tsa_free (g13xzc) should be called to free the NAG allocated memory from options.

10.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 nag_tsa_multi_inp_model_estim (g13bec) together with their default values where relevant.

ε

is the machine precision.

Boolean options.list	TRUE
Nag_PrintType options.print_level	Nag_Soln
char outfile[80]	stdout
void (*options.print_fun)()	NULL
Boolean options.cfixed	FALSE
Nag_Likelihood options.criteria	Nag_Exact
Integeroptions.max_iter	50
double options.alpha	0.01
double options.beta	10.0
double options.delta	1000.0
double options.gamma	$\max (100 ε, 10^{- 7})$
Integer options.iter	double *options.cm
double *options.res	Integer options.lenres
double *options.zt	double *options.noise

10.2 Description of Optional Parameters

list – Boolean

Input

On entry: if

list = TRUE

then the parameter settings which are used in the call to nag_tsa_multi_inp_model_estim (g13bec) will be printed.

print_level – Nag_PrintType

Input

On entry: the level of results produced by nag_tsa_multi_inp_model_estim (g13bec). The following values are available.

Nag_NoPrint	No output.
Nag_Soln	The final solution.
Nag_Iter	One line of output for each iteration.
Nag_Soln_Iter	The final solution and one line of output for each iteration.
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:

options.print_level

=

Nag_PrintNotSet, Nag_Soln, Nag_Iter, Nag_Soln_Iter or Nag_Soln_Iter_Full.

outfile – char[80]

Input

On entry: name of file to which the results of monitoring the course of the optimization should be printed. If

outfile [0] = \ 0

then the stdout stream is used.

print_fun – pointer to function

Input

On entry: printing function defined by the user; the prototype of print_fun is

void (*print_fun)(const Nag_UserPrintFun *bfx, Nag_Comm *Comm);

See Section 10.3.1 below for further details.

cfixed – Boolean

Input

On entry: cfixed must be set to TRUE if the constant

c

is to remain fixed at its initial value, and to FALSE if it is to be estimated.

criteria – Nag_Likelihood

Input

On entry: indicates the likelihood option for the estimation criterion. criteria must be set to Nag_LeastSquares, Nag_Exact or Nag_Marginal, to select the least-squares, exact or marginal likelihood, respectively.

Constraint:

options.criteria

=

Nag_LeastSquares, Nag_Exact or Nag_Marginal.

max_iter – Integer

Input

On entry: the maximum required number of iterations. If

max_iter = 0

, no change is made to any of the model parameters in array para except that the constant

c

(if

options.cfixed = FALSE

) and any

ω

relating to simple input series are estimated. (Apart from these, estimates are always derived for the nuisance parameters relating to any backforecasts and any pre-observation period effects for transfer function inputs.)

Constraint:

options.max_iter \geq 0

alpha – double

Input

On entry:

α

, the value used to constrain the magnitude of the search procedure steps (see Section 3.3).

Constraint:

options.alpha > 0.0

beta – double

Input

On entry:

β

, the multiplier which regulates the value of

α

(see Section 3.3).

Constraint:

options.beta > 1.0

delta – double

Input

On entry:

δ

, the value of the stationarity and invertibility test tolerance factor (see Section 3.3).

Constraint:

options.delta \geq 1.0

gamma – double

Input

On entry:

γ

, the convergence criterion (see Section 3.3).

Constraint:

0.0 \leq options.gamma < 1.0

iter – Integer

Output

On exit: the number of iterations carried out. A value of

iter = - 1

on exit 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

ω

and for the constant

c

(if

options.cfixed = FALSE

). This value of iter usually indicates a failure in a consequent step of estimating transfer function input pre-observation period nuisance parameters. A value of

iter = 0

on exit indicates that estimates have been obtained up to this point for the constant

c

(if

options.cfixed = FALSE

), for simple input coefficients

ω

and for the nuisance parameters relating to the backforecasts and to transfer function input pre-observation period effects.

cm – double

Output

On exit: this pointer is allocated memory internally with

npara \times npara

elements corresponding to npara rows by npara columns. The 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. 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 cm will be indeterminate.

res – double

Output

On exit: the values of the residuals relating to the differenced values of the output series. This pointer is allocated memory internally with options.lenres elements.

lenres – Integer

Output

On exit: the length of options.res.

zt – double

Output

On exit: this pointer is allocated memory internally with

nxxy \times (nseries - 1)

elements corresponding to nxxy rows by

(nseries - 1)

columns. The columns of zt hold the values of the input component series

z_{t}

noise – double

Output

On exit: this pointer is allocated memory internally with nxxy elements. It holds the output noise component

n_{t}

10.3 Description of Printed Output

The level of printed output can be controlled by the user with the structure members options.list and options.print_level, see section 7.2. If

options.list = TRUE

then the parameter values to nag_tsa_multi_inp_model_estim (g13bec) are listed, whereas the printout of results is governed by the value of options.print_level. The default of

options.print_level

=

Nag_Soln which provides a printout of the final solution. This section describes all of the possible levels of results printout available from nag_tsa_multi_inp_model_estim (g13bec). When

options.print_level

=

Nag_Iter or Nag_Soln_Iter a single line of output is produced at each iteration, this gives the following values.

Iter	the current iteration number, options.iter.
Residual	the residual sum of squares, rss.
Objf	the objective function at the latest set of parameter estimates.

When

options.print_level

=

Nag_Soln_Iter_Full a description and value for each of the parameters in the para array is output. The descriptions are phi for

ϕ

, theta for

θ

, sphi for

Φ

. stheta for

Θ

, omega/si for

ω

in a simple input, omega for

ω

in a transfer function input, options.delta for

δ

and constant for

c

. In addition series 1, series 2, etc, indicate the input series relevant to the omega and options.delta parameters.

options.print_level

=

Nag_Soln, Nag_Soln_Iter or Nag_Soln_Iter_Full the final solution is printed out. This consists of:

i	the parameter number.
para[i]	the values of the parameter.
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.

options.print_level

=

Nag_NoPrint then printout will be suppressed; the user can print the final solution when nag_tsa_multi_inp_model_estim (g13bec) returns to the calling program.

10.3.1 Output of results via a user defined printing function

The user may also specify their own print function for output of iteration results and the final solution by use of the options.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 user-defined function is assigned to options.print_fun this will be called in preference to the internal print function of nag_tsa_multi_inp_model_estim (g13bec). Calls to the user-defined function are again controlled by means of the options.print_level member. Information is provided through two structure arguments to options.print_fun, the structure of type Nag_UserPrintFun contains the following members relevant to nag_tsa_multi_inp_model_estim (g13bec):

itc – Integer *: the number of the particular iteration being monitored.

rss – double: 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 npara latest values of the estimates of the multi-input model parameters.

npara – Integer *: the exact number of $ϕ$ , $θ$ , $Φ$ , $Θ$ , $ω$ , $δ$ and $c$ parameters.

npe – Integer *: the number of ARIMA ( $ϕ$ , $θ$ , $Φ$ , $Θ$ ), omega $(ω)$ , options.delta $(δ)$ , and $c$ parameters being estimated.

mtyp – Integer *

mser – Integer *

the pointers to memory, each with npe elements. The value of each element in mtyp and mser corresponds to the description of each parameter estimated in para. The following should be read in conjuction with the description of the parameter print. The relevant description for the value of para is:

$mtyp [i]$	Description
1	phi
2	theta
3	sphi
4	stheta
5	omega/si	series $mser [i]$
6	omega	series $mser [i]$
7	options.delta	series $mser [i]$
8	constant

for

i = 0, 1, \dots, npe

. For the phi, theta, sphi, stheta and constant parameters,

mser [i] = 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.

11 Example 2

This example illustrates the use of the options parameter in a call to nag_tsa_multi_inp_model_estim (g13bec).

The data in the example relate to the same 40 observations of an output time series and of a single input time series as in Example 1. The noise series has one autoregressive

(ϕ)

and one seasonal moving average

(Θ)

parameter (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

ω

(initially set to 2.0) and one

δ

(initially set to 0.5), and allows for pre-observation period effects. The constant (initially set to zero) is to be estimated so that the flag for the constant

c

, options.cfixed, remains unchanged from its default value of FALSE. Default values of zsp are used. Up to 20 iterations are allowed so that options.max_iter is set to 20, and the progress of these is monitored and solution output by setting

options.print_level

=

Nag_Soln_Iter_Full. Marginal likelihood is the chosen estimation criterion so that

options.criteria

=

Nag_Marginal.

After the successful call to nag_tsa_multi_inp_model_estim (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}

Chapter Contents

Chapter Introduction

NAG C Library Contents

NAG C Library Function Document

nag_tsa_multi_inp_model_estim (g13bec)

+− Contents

1 Purpose

2 Specification

3 Description

3.1 The Multi-input Model

3.2 The Estimation Criterion

3.3 The Estimation Procedure

3.4 Further Results

4 References

5 Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

9.1 Example 1

9.1.1 Program Text

9.1.2 Program Data

9.1.3 Program Results

10 Optional Parameters

10.1 Optional Parameters Checklist and Default Values

10.2 Description of Optional Parameters

10.3 Description of Printed Output

10.3.1 Output of results via a user defined printing function

11 Example 2

11.1 Program Text

11.2 Program Data

11.3 Program Results

NAG C Library Function Documentnag_tsa_multi_inp_model_estim (g13bec)

+− Contents

NAG C Library Function Document

nag_tsa_multi_inp_model_estim (g13bec)