NAG FL Interface
g13bef (multi_​inputmod_​estim)

Settings help

FL Name Style:

FL Specification Language:

1 Purpose

g13bef fits a multi-input 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, g13bef fits a univariate ARIMA model.

2 Specification

Fortran Interface
Subroutine g13bef ( mr, nser, mt, para, npara, kfc, nxxy, xxy, ldxxy, kef, nit, kzsp, zsp, itc, sd, cm, ldcm, s, d, ndf, kzef, res, sttf, isttf, nsttf, wa, iwa, mwa, imwa, kpriv, ifail)
Integer, Intent (In) :: mr(7), nser, mt(4,nser), npara, kfc, nxxy, ldxxy, kef, nit, kzsp, ldcm, kzef, isttf, iwa, imwa, kpriv
Integer, Intent (Inout) :: ifail
Integer, Intent (Out) :: itc, ndf, nsttf, mwa(imwa)
Real (Kind=nag_wp), Intent (Inout) :: para(npara), xxy(ldxxy,nser), zsp(4), cm(ldcm,npara)
Real (Kind=nag_wp), Intent (Out) :: sd(npara), s, d, res(nxxy), sttf(isttf), wa(iwa)
C Header Interface
#include <nag.h>
void  g13bef_ (const Integer mr[], const Integer *nser, const Integer mt[], double para[], const Integer *npara, const Integer *kfc, const Integer *nxxy, double xxy[], const Integer *ldxxy, const Integer *kef, const Integer *nit, const Integer *kzsp, double zsp[], Integer *itc, double sd[], double cm[], const Integer *ldcm, double *s, double *d, Integer *ndf, const Integer *kzef, double res[], double sttf[], const Integer *isttf, Integer *nsttf, double wa[], const Integer *iwa, Integer mwa[], const Integer *imwa, const Integer *kpriv, Integer *ifail)
The routine may be called by the names g13bef or nagf_tsa_multi_inputmod_estim.

3 Description

3.1 The Multi-input Model

The output series yt, for t=1,2,,n, is assumed to be the sum of (unobserved) components zi,t which are due respectively to the inputs xi,t, for i=1,2,,m.
Thus yt=z1,t++zm,t+nt where nt is the error, or output noise component.
A typical component zt may be either
  1. (a)a simple regression component, zt=ωxt (here xt is called a simple input), or
  2. (b)a transfer function model component which allows for the effect of lagged values of the variable, related to xt by
    zt = δ1 zt-1 + δ2 zt-2 + + δp zt-p + ω0 xt-b - ω1 x t-b-1 - - ωq x t-b-q .  
The noise nt is assumed to follow a (possibly seasonal) ARIMA model, i.e., may be represented in terms of an uncorrelated series, at, by the hierarchy of equations
  1. (i) d sD nt = c+wt
  2. (ii) wt = Φ1 wt-s + Φ2 w t-2×s ++ ΦP w t-P×s + et - Θ1 et-s - Θ2 et-2×s -- ΘQ et-Q×s
  3. (iii) et = ϕ1 et-1 + ϕ2 e t-2 ++ ϕp et-p +at - θ1 at-1 - θ2 at-2 -- θq at-q
as outlined in Section 3 in g13aef.
Note:  the orders p,q appearing in each of the transfer function models and the ARIMA model are not necessarily the same; dsDnt is the result of applying non-seasonal differencing of order d and seasonal differencing of seasonality s and order D to the series nt: the differenced series is then of length N=n-d-s×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 at is a sequence of independent Normal variates having mean 0 and variance σa2. 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 pre-period terms z0,z−1,,z1-p and x0,x−1,,x1-b-q which are in theory necessary to re-create the component series z1,z2,,zn, 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 z1,z2,, you are advised first to correct the input series xt by subtracting from all the terms a suitable constant to make the early values x1,x2,, close to zero. The series mean x¯ is one possibility, but for a series with strong trend the constant might be simply x1.
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,, along with the other inputs, this being the form of the transient. If the output yt 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 you align the input xt with the output by using in its place the shifted series xt-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 routine. 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 routine searches for parameter values which minimize this criterion. For a proposed set of parameter values it is derived by calculating
  1. (i)the components z1,t,z2,t,,zm,t as the responses to the input series x1,t,x2,t,xm,t using the equations (a) or (b) above,
  2. (ii)the discrepancy between the output and the sum of these components, as the noise
    n t = y t - ( z 1 , t + z 2 , t ++ z m , t ) ,  
  3. (iii)the residual series at from nt by reversing the recursive equations (i), (ii) and (iii) above.
This last step again requires treatment of the effect of unknown pre-period values of nt and other terms in the equations regenerating at. This is identical to the treatment given in Section 3 in g13aef, and leads to a criterion which is a sum of squares function S, of the residuals at. It may be shown that the finite algorithm presented there is equivalent to taking the infinite set of past values n0,n−1,n−2,, 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 n0,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 n1,n2,,nn requires theoretical integration over the range of the past set. Fortunately this yields a criterion of the form D=M×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 1, and M tends to 1 for any fixed parameter set as the sample size n tends to . 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 n0,n−1,n−2,. These coefficients, together with the constant term c used to represent the mean of wt, are in effect treated as random variables with highly dispersed distributions. This leads to the criterion D=M×S again, but with a different value of M which now depends on the simple input series values xt. 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.
g13bef 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.

3.3 The Estimation Procedure

This is the minimization of the estimation criterion or objective function D (for deviance). The routine 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 presented at the initial parameter values, except for 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 erv= Sdf , where df=N-(total number of parameters estimated), is the residual degrees of freedom. The pre-period nuisance parameters 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 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 at is available upon completion of the iterations over the range t=1+d+s×D,,n corresponding to the differenced noise series wt.
Because of the algorithm used for backforecasting, these are only true residuals for t1+q+s×Q-p-s×P-d-s×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 z1,t,,zm,t and nt may optionally be returned in place of the supplied series values, in order to assess the effects of the various inputs on the output.

3.5 Forecasting Information

For the purpose of constructing forecasts of the output series at future time points t=n+1,n+2, using g13bhf, it is not necessary to use the whole set of observations yt and x1,t,x2,t,,xm,t, for t=1,2,,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+1-k for k=1 up to the maximum lag associated with that series in the equations. Note that (i) implicitly includes past values of nt and intermediate differences of nt such as d-1sD.
If later observations of the series become available, it is possible to update the state set (without re-estimating the model) using g13bgf. If time series data is supplied with a previously estimated model, it is possible to construct the state set (and forecasts) using g13bjf.

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 Arguments

1: mr(7) Integer array Input
On entry: the orders vector (p,d,q,P,D,Q,s) 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.
  • p, d, q, P, D, Q, s0;
  • p+q+P+Q>0;
  • s1;
  • if s=0, P+D+Q=0;
  • if s>1, P+D+Q>0;
  • d+s×(P+D)n;
  • p+d-q+s×(P+D-Q)n.
2: nser 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.
  • nser1;
  • if there are no parameters in the model (that is, p=q=P=Q=0 and kfc=0), nser>1.
3: mt(4,nser) Integer array Input
On entry: the transfer function model orders b, p and q of each of the input series. The order parameters for input series i are held in column i. Row 1 holds the value bi, row 2 holds the value qi and row 3 holds the value pi. For a simple input, bi=qi=pi=0.
Row 4 holds the value ri, where ri=1 for a simple input, ri=2 for a transfer function input for which no allowance is to be made for pre-observation period effects, and ri=3 for a transfer function input for which pre-observation period effects will be treated by estimation of appropriate nuisance parameters.
When ri=1, any nonzero contents of rows 1, 2, and 3 of column i are ignored.
Constraint: mt(4,i)=1, ​2​ or ​3, for i=1,2,,nser-1.
4: para(npara) Real (Kind=nag_wp) array 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,,ωq1, δ1,δ2,,δp1 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+nser+(pi+qi), the summation being over all the piqi supplied in mt. c must be included, whether fixed or estimated.
6: kfc Integer Input
On entry: 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: kfc=0 or 1.
7: nxxy Integer Input
On entry: the (common) length of the original, undifferenced input and output time series.
8: xxy(ldxxy,nser) Real (Kind=nag_wp) array Input/Output
On entry: the columns of xxy must contain the nxxy original, undifferenced values of each of the input series and the output series xt in that order.
On exit: if kzef=0, xxy remains unchanged on exit.
If kzef0, the columns of xxy hold the corresponding values of the input component series zt in place of xt and the output noise component nt in place of yt, in that order.
9: ldxxy Integer Input
On entry: the first dimension of the array xxy as declared in the (sub)program from which g13bef is called.
Constraint: ldxxynxxy.
10: kef Integer Input
On entry: indicates the likelihood option.
Gives least squares.
Gives exact likelihood.
Gives marginal likelihood.
Constraint: kef=1, 2 or 3.
11: nit Integer Input
On entry: the maximum required number of iterations.
No change is made to any of the model parameters in array para except that the constant c (if kfc=1) 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: nit0.
12: kzsp Integer Input
On entry: must be set to 1 if the routine is to use the input values of zsp in the minimization procedure, and to any other value if the default values of zsp are to be used.
13: zsp(4) Real (Kind=nag_wp) array Input/Output
On entry: if kzsp=1, then zsp must contain the four values used to control the strategy of the search procedure.
Contains α, the value used to constrain the magnitude of the search procedure steps.
Contains β, the multiplier which regulates the value of α.
Contains δ, the value of the stationarity and invertibility test tolerance factor.
Contains γ, the value of the convergence criterion.
If kzsp1 before entry, default values of zsp are supplied by the routine. These are 0.01, 10.0, 1000.0 and max(100×machine precision,0.0000001), respectively.
On exit: contains the values, default or otherwise, used by the routine.
if kzsp=1,
  • zsp(1)>0.0, ;
  • zsp(2)>1.0, ;
  • zsp(3)1.0, ;
  • 0zsp(4)<1.0.
14: itc Integer Output
On exit: the number of iterations carried out.
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 kfc=1). This value of itc usually indicates a failure in a consequent step of estimating transfer function input pre-observation period nuisance parameters.
Indicates that estimates have been obtained up to this point for the constant c (if kfc=1), for simple input coefficients ω and for the nuisance parameters relating to the backforecasts and to transfer function input pre-observation period effects.
15: sd(npara) Real (Kind=nag_wp) array 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. However, if an exit value of ifail=3, 8 or 10, then the contents of sd will be indeterminate.
16: cm(ldcm,npara) Real (Kind=nag_wp) array Output
On exit: 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.
17: ldcm Integer Input
On entry: the first dimension of the array cm as declared in the (sub)program from which g13bef is called.
Constraint: ldcmnpara.
18: s Real (Kind=nag_wp) Output
On exit: the residual sum of squares, S, at the latest set of valid parameter estimates.
19: d Real (Kind=nag_wp) Output
On exit: the objective function, D, at the latest set of valid parameter estimates.
20: ndf Integer Output
On exit: the number of degrees of freedom associated with S.
21: kzef Integer Input
On entry: must not be set to 0, if the values of the input component series zt and the values of the output noise component nt are to overwrite the contents of xxy on exit, and must be set to 0 if xxy is to remain unchanged.
22: res(nxxy) Real (Kind=nag_wp) array Output
On exit: 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.
23: sttf(isttf) Real (Kind=nag_wp) array Output
On exit: the nsttf values of the state set array.
24: isttf Integer Input
On entry: the dimension of the array sttf as declared in the (sub)program from which g13bef is called.
Constraint: isttf(P×s)+d+(D×s)+q+max(p,Q×s)+ncg, where ncg=(bi+qi+pi) over all input series for which ri>1.
25: nsttf Integer Output
On exit: the number of values in the state set array sttf.
26: wa(iwa) Real (Kind=nag_wp) array Output
27: iwa Integer Input
28: mwa(imwa) Integer array Output
29: imwa Integer Input
These arguments are no longer accessed by g13bef. Workspace is provided internally by dynamic allocation instead.
30: kpriv Integer Input
On entry: must not be set to 0, if it is required to monitor the course of the optimization. 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 ϕ, THETA for θ, SPHI for Φ, STHETA for Θ, OMEGA/SI for ω in a simple input, OMEGA for ω in a transfer function input, DELTA for δ 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 print-out of the above information is not required.
31: ifail Integer Input/Output
On entry: ifail must be set to 0, −1 or 1 to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of 0 causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of −1 means that an error message is printed while a value of 1 means that it is not.
If halting is not appropriate, the value −1 or 1 is recommended. If message printing is undesirable, then the value 1 is recommended. Otherwise, the value −1 is recommended since useful values can be provided in some output arguments even when ifail0 on exit. When the value -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry ifail=0 or −1, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
Note: in some cases g13bef may return useful information.
On entry, kef=value.
Constraint: kef=1, 2 or 3.
On entry, kfc=value.
Constraint: kfc=0 or 1.
On entry, ldcm=value and npara=value.
Constraint: ldcmnpara.
On entry, ldxxy=value and nxxy=value.
Constraint: ldxxynxxy.
On entry, nit=value.
Constraint: nit0.
On entry, nser=value.
Constraint: nser1.
On entry, nser=1 and there are no parameters in the model.
On entry, i=value and mt(4,i)=value.
Constraint: mt(4,i)=1, 2 or 3.
On entry, ndf=value.
Constraint: ndf>0.
On entry, npara=value and kfc=value.
Constraint: npara, kfc, mr and mt must be consistent.
The orders vector mr is invalid.
On entry, or during execution, one or more sets of delta parameters do not satisfy the stationarity or invertibility conditions.
On entry, zsp(1)=value.
Constraint: zsp(1)>0.0.
On entry, zsp(2)=value.
Constraint: zsp(2)>1.0.
On entry, zsp(3)=value.
Constraint: zsp(3)1.0.
On entry, zsp(4)=value.
Constraint: 0.0zsp(4)<1.0.
Unable to calculate the latest parameter estimates.
Failure in inversion of second derivative matrix.
On entry, or during execution, one or more sets of ARIMA parameters do not satisfy the stationarity or invertibility conditions.
On entry, isttf too small.
Constraint: isttf(P×s)+d+(D×s)+q+max(p,Q×s)+ncg.
The routine has failed to converge after value 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.
On entry, nit=value.
isttf is too small and the process failed to converge after nit iterations.
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

The computation used is believed to be stable.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
g13bef is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g13bef makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The time taken by g13bef is approximately proportional to nxxy×itc×npara2.

10 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 zt and nt, the values of the state set and the number of degrees of freedom.

10.1 Program Text

Program Text (g13befe.f90)

10.2 Program Data

Program Data (g13befe.d)

10.3 Program Results

Program Results (g13befe.r)