# Source code for naginterfaces.library.tsa

# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 28.5 tsa Chapter.

tsa - Time Series Analysis

This module provides facilities for investigating and modelling the statistical structure of series of observations collected at points in time.
The models may then be used to forecast the series.

The module covers the following models and approaches:

(1) univariate time series analysis, including autocorrelation functions and autoregressive moving average (ARMA) models;

(#) univariate spectral analysis;

(#) transfer function (multi-input) modelling, in which one time series is dependent on other time series;

(#) bivariate spectral methods including coherency, gain and input response functions;

(#) vector ARMA models for multivariate time series;

(#) Kalman filter models (linear and nonlinear);

(#) GARCH models for volatility;

(#) inhomogeneous time series.

--------
naginterfaces.library.examples.tsa :
This subpackage contains examples for the tsa module.
See also the :ref:library_tsa_ex subsection.

Functionality Index
-------------------

**ARMA modelling**

ACF: :meth:uni_autocorr

diagnostic checking: :meth:uni_arima_resid

Dickey--Fuller unit root test: :meth:uni_dickey_fuller_unit

differencing: :meth:uni_diff

estimation (comprehensive): :meth:uni_arima_estim

estimation (easy-to-use): :meth:uni_arima_estim_easy

forecasting from fully specified model: :meth:uni_arima_forcecast

forecasting from state set: :meth:uni_arima_forecast_state

mean/range: :meth:uni_means

PACF: :meth:uni_autocorr_part

preliminary estimation: :meth:uni_arima_prelim

update state set: :meth:uni_arima_update

**Change point**

detection

binary segmentation: :meth:cp_binary

PELT: :meth:cp_pelt

Exponential smoothing: :meth:uni_smooth_exp

**GARCH**

EGARCH

fitting: :meth:uni_garch_exp_estim

forecasting: :meth:uni_garch_exp_forecast

GJR GARCH

fitting: :meth:uni_garch_gjr_estim

forecasting: :meth:uni_garch_gjr_forecast

symmetric or type I AGARCH

fitting: :meth:uni_garch_asym1_estim

forecasting: :meth:uni_garch_asym1_forecast

type II AGARCH

fitting: :meth:uni_garch_asym2_estim

forecasting: :meth:uni_garch_asym2_forecast

**Inhomogeneous series**

iterated exponential moving average

final value only returned: :meth:inhom_iema

intermediate values returned: :meth:inhom_iema_all

moving average: :meth:inhom_ma

**Kalman**

filter

time invariant

square root covariance: :meth:multi_kalman_sqrt_invar

time varying

square root covariance: :meth:multi_kalman_sqrt_var

unscented: :meth:kalman_unscented_state

unscented (reverse communication): :meth:kalman_unscented_state_revcom

**Spectral analysis**

Bivariate

Bartlett, Tukey, Parzen windows: :meth:multi_spectrum_lag

cross amplitude spectrum: :meth:multi_spectrum_bivar

direct smoothing: :meth:multi_spectrum_daniell

gain and phase: :meth:multi_gain_bivar

noise spectrum: :meth:multi_noise_bivar

Univariate

Bartlett, Tukey, Parzen windows: :meth:uni_spectrum_lag

direct smoothing: :meth:uni_spectrum_daniell

**Transfer function modelling**

cross-correlations: :meth:multi_xcorr

filtering: :meth:multi_filter_transf

fitting: :meth:multi_inputmod_estim

forecasting from fully specified model: :meth:multi_inputmod_forecast

forecasting from state set: :meth:multi_inputmod_forecast_state

preliminary estimation: :meth:multi_transf_prelim

pre-whitening: :meth:multi_filter_arima

update state set: :meth:multi_inputmod_update

**Vector ARMA**

cross-correlations: :meth:multi_corrmat_cross

diagnostic checks: :meth:multi_varma_diag

differencing: :meth:multi_diff

fitting: :meth:multi_varma_estimate

forecasting: :meth:multi_varma_forecast

partial autoregression matrices: :meth:multi_regmat_partial

partial correlation matrices: :meth:multi_corrmat_partlag

squared partial autocorrelations: :meth:multi_autocorr_part

update forecast: :meth:multi_varma_update

zeros of ARIMA operator: :meth:uni_arma_roots

For full information please refer to the NAG Library document

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13intro.html
"""

[docs]def uni_diff(x, nd, nds, ns):
r"""
uni_diff carries out non-seasonal and seasonal differencing on a time series.
Information which allows the original series to be reconstituted from the differenced series is also produced.
This information is required in time series forecasting.

.. _g13aa-py2-py-doc:

For full information please refer to the NAG Library document for g13aa

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13aaf.html

.. _g13aa-py2-py-parameters:

**Parameters**
**x** : float, array-like, shape :math:\left(\textit{nx}\right)
The undifferenced time series, :math:x_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,n.

**nd** : int
:math:d, the order of non-seasonal differencing.

**nds** : int
:math:D, the order of seasonal differencing.

**ns** : int
:math:s, the seasonality.

**Returns**
**xd** : float, ndarray, shape :math:\left(\textit{nx}\right)
The differenced values in elements :math:0 to :math:\mathrm{nxd}-1, and reconstitution data in the remainder of the array.

**nxd** : int
The number of differenced values in the array :math:\mathrm{xd}.

.. _g13aa-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{nds} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ns} = 0, :math:\mathrm{nds} \leq 0.

(errno :math:1)
On entry, :math:\mathrm{ns} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ns}\geq 0.

(errno :math:1)
On entry, :math:\mathrm{nds} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nds}\geq 0.

(errno :math:1)
On entry, :math:\mathrm{nd} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nd}\geq 0.

(errno :math:2)
On entry, :math:\textit{nx} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{nd} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{nds} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{ns} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nx} > \mathrm{nd}+\left(\mathrm{nds}\times \mathrm{ns}\right).

.. _g13aa-py2-py-notes:

**Notes**
Let :math:\nabla^d\nabla_s^Dx_i be the :math:i\ th value of a time series :math:x_i, for :math:i = 1,2,\ldots,n after non-seasonal differencing of order :math:d and seasonal differencing of order :math:D (with period or seasonality :math:s).
In general,

.. rst-class:: nag-rules-none nag-align-left

+---------------------------------------------------------------------------------------------+-------------+
|:math:\nabla^d\nabla_s^Dx_i = \nabla^{{d-1}}\nabla_s^Dx_{{i+1}}-\nabla^{{d-1}}\nabla_s^Dx_i|:math:d > 0|
+---------------------------------------------------------------------------------------------+-------------+
|:math:\nabla^d\nabla_s^Dx_i = \nabla^d\nabla_s^{{D-1}}x_{{i+s}}-\nabla^d\nabla_s^{{D-1}}x_i|:math:D > 0|
+---------------------------------------------------------------------------------------------+-------------+

Non-seasonal differencing up to the required order :math:d is obtained using

.. rst-class:: nag-rules-none nag-align-left

+---------------------------------------------------------------+-------------------------------------------+
|:math:\nabla^1x_i = x_{{i+1}}-x_i                            |for :math:i = 1,2,\ldots,\left(n-1\right)|
+---------------------------------------------------------------+-------------------------------------------+
|:math:\nabla^2x_i = \nabla^1x_{{i+1}}-\nabla^1x_i            |for :math:i = 1,2,\ldots,\left(n-2\right)|
+---------------------------------------------------------------+-------------------------------------------+
|:math:\quad \text{ }\quad \vdots                             |                                           |
+---------------------------------------------------------------+-------------------------------------------+
|:math:\nabla^dx_i = \nabla^{{d-1}}x_{{i+1}}-\nabla^{{d-1}}x_i|for :math:i = 1,2,\ldots,\left(n-d\right)|
+---------------------------------------------------------------+-------------------------------------------+

Seasonal differencing up to the required order :math:D is then obtained using

.. rst-class:: nag-rules-none nag-align-left

+---------------------------------------------------------------------------------------------+-----------------------------------------------------+
|:math:\nabla^d\nabla_s^1x_i = \nabla^dx_{{i+s}}-\nabla^dx_i                                |for :math:i = 1,2,\ldots,\left(n-d-s\right)        |
+---------------------------------------------------------------------------------------------+-----------------------------------------------------+
|:math:\nabla^d\nabla_s^2x_i = \nabla^d\nabla_s^1x_{{i+s}}-\nabla^d\nabla_s^1x_i            |for :math:i = 1,2,\ldots,\left(n-d-2s\right)       |
+---------------------------------------------------------------------------------------------+-----------------------------------------------------+
|:math:\quad \text{ }\quad \vdots                                                           |                                                     |
+---------------------------------------------------------------------------------------------+-----------------------------------------------------+
|:math:\nabla^d\nabla_s^Dx_i = \nabla^d\nabla_s^{{D-1}}x_{{i+s}}-\nabla^d\nabla_s^{{D-1}}x_i|for :math:i = 1,2,\ldots,\left(n-d-D\times s\right)|
+---------------------------------------------------------------------------------------------+-----------------------------------------------------+

Mathematically, the sequence in which the differencing operations are performed does not affect the final resulting series of :math:m = n-d-D\times s values.
"""
raise NotImplementedError

[docs]def uni_autocorr(x, nk):
r"""
uni_autocorr computes the sample autocorrelation function of a time series.
It also computes the sample mean, the sample variance and a statistic which may be used to test the hypothesis that the true autocorrelation function is zero.

.. _g13ab-py2-py-doc:

For full information please refer to the NAG Library document for g13ab

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13abf.html

.. _g13ab-py2-py-parameters:

**Parameters**
**x** : float, array-like, shape :math:\left(\textit{nx}\right)
The time series, :math:x_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,n.

**nk** : int
:math:K, the number of lags for which the autocorrelations are required. The lags range from :math:1 to :math:K and do not include zero.

**Returns**
**xm** : float
The sample mean of the input time series.

**xv** : float
The sample variance of the input time series.

**r** : float, ndarray, shape :math:\left(\mathrm{nk}\right)
The sample autocorrelation coefficient relating to lag :math:\textit{k}, for :math:\textit{k} = 1,2,\ldots,K.

**stat** : float
The statistic used to test the hypothesis that the true autocorrelation function of the time series is identically zero.

.. _g13ab-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{nx} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nk} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nx} > \mathrm{nk}.

(errno :math:1)
On entry, :math:\textit{nx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nx} > 1.

(errno :math:1)
On entry, :math:\mathrm{nk} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nk} > 0.

**Warns**
**NagAlgorithmicWarning**
(errno :math:2)
On entry, all values of :math:\mathrm{x} are practically identical.

.. _g13ab-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

The data consists of :math:n observations :math:x_i, for :math:\textit{i} = 1,2,\ldots,n from a time series.

The quantities calculated are

(a) The sample mean

.. math::
\bar{x} = \frac{{\sum_{{i = 1}}^nx_i}}{n}\text{.}

(#) The sample variance (for :math:n\geq 2)

.. math::
s^2 = \frac{{\sum_{{i = 1}}^n\left(x_i-\bar{x}\right)^2}}{\left(n-1\right)}\text{.}

(#) The sample autocorrelation coefficients of lags :math:k = 1,2,\ldots,K, where :math:K is a user-specified maximum lag, and :math:K < n, :math:n > 1.

The coefficient of lag :math:k is defined as

.. math::
r_k = \frac{{\sum_{{i = 1}}^{{n-k}}\left(x_i-\bar{x}\right)\left(x_{{i+k}}-\bar{x}\right)}}{{\sum_{{i = 1}}^n\left(x_i-\bar{x}\right)^2}}\text{.}

See page 496 of Box and Jenkins (1976) for further details.

(#) A test statistic defined as

.. math::
\mathrm{stat} = n\sum_{{k = 1}}^Kr_k^2\text{,}

which can be used to test the hypothesis that the true autocorrelation function is identically zero.

If :math:n is large and :math:K is much smaller than :math:n, :math:\mathrm{stat} has a :math:\chi_K^2 distribution under the hypothesis of a zero autocorrelation function.
Values of :math:\mathrm{stat} in the upper tail of the distribution provide evidence against the hypothesis; :meth:stat.prob_chisq <naginterfaces.library.stat.prob_chisq> can be used to compute the tail probability.

Section 8.2.2 of Box and Jenkins (1976) provides further details of the use of :math:\mathrm{stat}.

.. _g13ab-py2-py-references:

**References**
Box, G E P and Jenkins, G M, 1976, Time Series Analysis: Forecasting and Control, (Revised Edition), Holden--Day
"""
raise NotImplementedError

[docs]def uni_autocorr_part(r, nl):
r"""
uni_autocorr_part calculates partial autocorrelation coefficients given a set of autocorrelation coefficients.
It also calculates the predictor error variance ratios for increasing order of finite lag autoregressive predictor, and the autoregressive parameters associated with the predictor of maximum order.

.. _g13ac-py2-py-doc:

For full information please refer to the NAG Library document for g13ac

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13acf.html

.. _g13ac-py2-py-parameters:

**Parameters**
**r** : float, array-like, shape :math:\left(\textit{nk}\right)
The autocorrelation coefficient relating to lag :math:\textit{k}, for :math:\textit{k} = 1,2,\ldots,K.

**nl** : int
:math:L, the number of partial autocorrelation coefficients required.

**Returns**
**p** : float, ndarray, shape :math:\left(\mathrm{nl}\right)
:math:\mathrm{p}[\textit{l}-1] contains the partial autocorrelation coefficient at lag :math:\textit{l}, :math:p_{{\textit{l},\textit{l}}}, for :math:\textit{l} = 1,2,\ldots,\mathrm{nvl}.

**v** : float, ndarray, shape :math:\left(\mathrm{nl}\right)
:math:\mathrm{v}[\textit{l}-1] contains the predictor error variance ratio :math:v_{\textit{l}}, for :math:\textit{l} = 1,2,\ldots,\mathrm{nvl}.

**ar** : float, ndarray, shape :math:\left(\mathrm{nl}\right)
The autoregressive parameters of maximum order, i.e., :math:p_{{L\textit{j}}} if no exception or warning is raised, or :math:p_{{l_0-1,\textit{j}}} if :math:\mathrm{errno} = 3, for :math:\textit{j} = 1,2,\ldots,\mathrm{nvl}.

**nvl** : int
The number of valid values in each of :math:\mathrm{p}, :math:\mathrm{v} and :math:\mathrm{ar}. Thus in the case of premature termination at iteration :math:l_0 (see :ref:Notes <g13ac-py2-py-notes>), :math:\mathrm{nvl} is returned as :math:l_0-1.

.. _g13ac-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{nk} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nl} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nk}\geq \mathrm{nl}.

(errno :math:1)
On entry, :math:\mathrm{nl} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nl} > 0.

(errno :math:1)
On entry, :math:\textit{nk} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nk} > 0.

(errno :math:2)
On entry, the autocorrelation coefficient of lag :math:1 has absolute value greater than or equal to :math:1.

**Warns**
**NagAlgorithmicWarning**
(errno :math:3)
The autocorrelation coefficients do not form a positive definite sequence.

.. _g13ac-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

The data consist of values of autocorrelation coefficients :math:r_1,r_2,\ldots,r_K, relating to lags :math:1,2,\ldots,K.
These will generally (but not necessarily) be sample values such as may be obtained from a time series :math:x_t using :meth:uni_autocorr.

The partial autocorrelation coefficient at lag :math:l may be identified with the parameter :math:p_{{l,l}} in the autoregression

.. math::
x_t = c_l+p_{{l,1}}x_{{t-1}}+p_{{l,2}}x_{{t-2}} + \cdots +p_{{l,l}}x_{{t-l}}+e_{{l,t}}

where :math:e_{{l,t}} is the predictor error.

The first subscript :math:l of :math:p_{{l,l}} and :math:e_{{l,t}} emphasizes the fact that the parameters will in general alter as further terms are introduced into the equation (i.e., as :math:l is increased).

The parameters are determined from the autocorrelation coefficients by the Yule--Walker equations

.. math::
r_i = p_{{l,1}}r_{{i-1}}+p_{{l,2}}r_{{i-2}} + \cdots +p_{{l,l}}r_{{i-l}}\text{, }\quad i = 1,2,\ldots,l

taking :math:r_j = r_{{\left\lvert j\right\rvert }} when :math:j < 0, and :math:r_0 = 1.

The predictor error variance ratio :math:v_l = \mathrm{var}\left(e_{{l,t}}\right)/\mathrm{var}\left(x_t\right) is defined by

.. math::
v_l = 1-p_{{l,1}}r_1-p_{{l,2}}r_2 - \cdots -p_{{l,l}}r_l\text{.}

The above sets of equations are solved by a recursive method (the Durbin--Levinson algorithm).
The recursive cycle applied for :math:l = 1,2,\ldots,\left(L-1\right), where :math:L is the number of partial autocorrelation coefficients required, is initialized by setting :math:p_{{1,1}} = r_1 and :math:v_1 = 1-r_1^2.

Then

.. math::
\begin{array}{lcl} p_{{l+1,l+1}} & = & \left(r_{{l+1}}-p_{{l,1}}r_l-p_{{l,2}}r_{{l-1}} - \cdots -p_{{l,l}}r_1\right) / v_l \\ p_{{l+1,j}} & = & p_{{l,j}} - p_{{l+1,l+1}} p_{{l,l+1-j}} \text{, }\quad j = 1,2,\ldots,l \\ v_{{l+1}} & = & v_l \left({1-p_{{l+1,l+1}}}\right) \left(1+p_{{l+1,l+1}}\right) \text{.} \end{array}

If the condition :math:\left\lvert p_{{l,l}}\right\rvert \geq 1 occurs, say when :math:l = l_0, it indicates that the supplied autocorrelation coefficients do not form a positive definite sequence (see Hannan (1960)), and the recursion is not continued.
The autoregressive parameters are overwritten at each recursive step, so that upon completion the only available values are :math:p_{{Lj}}, for :math:\textit{j} = 1,2,\ldots,L, or :math:p_{{l_0-1,j}} if the recursion has been prematurely halted.

.. _g13ac-py2-py-references:

**References**
Box, G E P and Jenkins, G M, 1976, Time Series Analysis: Forecasting and Control, (Revised Edition), Holden--Day

Durbin, J, 1960, The fitting of time series models, Rev. Inst. Internat. Stat. (28), 233

Hannan, E J, 1960, Time Series Analysis, Methuen
"""
raise NotImplementedError

[docs]def uni_arima_prelim(mr, r, xv):
r"""
uni_arima_prelim calculates preliminary estimates of the parameters of an autoregressive integrated moving average (ARIMA) model from the autocorrelation function of the appropriately differenced times series.

For full information please refer to the NAG Library document for g13ad

**Parameters**
**mr** : int, array-like, shape :math:\left(7\right)
The orders vector :math:\left(p, d, q, P, D, Q, s\right) of the ARIMA model whose parameters are to be estimated. :math:p, :math:q, :math:P and :math:Q refer respectively to the number of autoregressive :math:\left(\phi \right), moving average :math:\left(\theta \right), seasonal autoregressive :math:\left(\Phi \right) and seasonal moving average :math:\left(\Theta \right) parameters. :math:d, :math:D and :math:s refer respectively to the order of non-seasonal differencing, the order of seasonal differencing and the seasonal period.

**r** : float, array-like, shape :math:\left(\textit{nk}\right)
The autocorrelations (starting at lag :math:1), which must have been calculated after the time series has been appropriately differenced.

**xv** : float
The series sample variance, calculated after appropriate differencing has been applied to the series.

**Returns**
**par** : float, ndarray, shape :math:\left(:\right)
The first :math:\textit{npar} elements of :math:\mathrm{par} contain the preliminary estimates of the ARIMA model parameters, in standard order.

**rv** : float
An estimate of the residual variance of the preliminarily estimated model.

**isf** : int, ndarray, shape :math:\left(4\right)
Contains success/failure indicators, one for each of the four types of parameter (autoregressive, moving average, seasonal autoregressive, seasonal moving average).

The indicator has the interpretation:

.. rst-class:: nag-rules-none nag-align-left

+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:0 |No parameter of this type is in the model.                                                                                                                                                                         |
+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:1 |Parameters of this type appear in the model and satisfactory preliminary estimates of this type were obtained.                                                                                                     |
+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:-1|Parameters of this type appear in the model but satisfactory preliminary estimates of this type were not obtainable. The estimates of this type of parameter were set to :math:0.0 in array :math:\mathrm{par}.|
+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

**Raises**
**NagValueError**
(errno :math:1)
The orders vector :math:\mathrm{mr} is invalid.

(errno :math:2)
On entry, :math:\textit{nk} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nk}\geq \mathrm{max}\left({p+q}, {s\times \left(P+Q\right)}\right).

(errno :math:3)
On entry, :math:\mathrm{r}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:{-1.0}\leq \mathrm{r}[\textit{i}]\leq 1.0, for :math:i = 1,2,\ldots \textit{nk}.

(errno :math:4)
On entry, :math:\mathrm{xv} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{xv} > 0.0.

(errno :math:5)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npar} = p+q+P+Q.

**Warns**
**NagAlgorithmicWarning**
(errno :math:7)
Satisfactory parameter estimates could not be obtained for all parameter types in the model.

**Notes**
No equivalent traditional C interface for this routine exists in the NAG Library.

Preliminary estimates of the :math:p non-seasonal autoregressive parameters :math:\phi_1,\phi_2,\ldots,\phi_p and the :math:q non-seasonal moving average parameters :math:\theta_1,\theta_2,\ldots,\theta_q may be obtained from the sample autocorrelations relating to lags :math:1 to :math:p+q, i.e., :math:r_1,\ldots,r_{{p+q}}, of the differenced :math:\nabla^d\nabla_s^Dx_t, where :math:x_t is assumed to follow a (possibly) seasonal ARIMA model (see :ref:Notes for uni_arima_estim <g13ae-py2-py-notes> for the specification of an ARIMA model).

Taking :math:r_0 = 1 and :math:r_{{-k}} = r_k, the :math:\phi_i, for :math:\textit{i} = 1,2,\ldots,p are the solutions to the equations

.. math::
r_{{q+i-1}}\phi_1+r_{{q+i-2}}\phi_2 + \cdots +r_{{q+i-p}}\phi_p = r_{{q+i}}\text{, }\quad i = 1,2,\ldots,p\text{.}

The :math:\theta_j, for :math:\textit{j} = 1,2,\ldots,q, are obtained from the solutions to the equations

.. math::
c_j = \tau_0\tau_j+\tau_1\tau_{{j+1}} + \cdots +\tau_{{q+j}}\tau_q\text{, }\quad j = 0,1,\ldots,q

(Cramer Wold-factorization), by setting

.. math::
\theta_j = -\frac{\tau_j}{\tau_0}\text{,}

where :math:c_j are the 'covariances' modified in a two stage process by the autoregressive parameters.

Stage 1:

.. math::
\begin{array}{ll}d_j = r_j-\phi_1r_{{j-1}} - \cdots -\phi_pr_{{j-p}}, &j = 0,1,\ldots,q\text{;}\\d_j = 0\text{,}&j = q+1,q+2,\ldots,p+q\text{.}\end{array}

Stage 2:

.. math::
c_j = d_j-\phi_1d_{{j+1}}-\phi_2d_{{j+2}} - \cdots -\phi_pd_{{j+p}}\text{, }\quad j = 0,1,\ldots,q\text{.}

The :math:P seasonal autoregressive parameters :math:\Phi_1,\Phi_2,\ldots,\Phi_P and the :math:Q seasonal moving average parameters :math:\Theta_1,\Theta_2,\ldots,\Theta_Q are estimated in the same way as the non-seasonal parameters, but each :math:r_j is replaced in the calculation by :math:r_{{s\times j}}, where :math:s is the seasonal period.

An estimate of the residual variance is obtained by successively reducing the sample variance, first for non-seasonal, and then for seasonal, parameter estimates.
If moving average parameters are estimated, the variance is reduced by a multiplying factor of :math:\tau_0^2, but otherwise by :math:c_0.

**References**
Box, G E P and Jenkins, G M, 1976, Time Series Analysis: Forecasting and Control, (Revised Edition), Holden--Day
"""
raise NotImplementedError

[docs]def uni_arima_estim(mr, par, c, x, iex, igh, ist, kpiv, zsp, kzsp, kfc=1, piv=None, nit=100, data=None, io_manager=None):
r"""
uni_arima_estim fits a seasonal autoregressive integrated moving average (ARIMA) model to an observed time series, using a nonlinear least squares procedure incorporating backforecasting. Parameter estimates are obtained, together with appropriate standard errors.
The residual series is returned, and information for use in forecasting the time series is produced for use by the functions :meth:uni_arima_update and :meth:uni_arima_forecast_state.

The estimation procedure is iterative, starting with initial parameter values such as may be obtained using :meth:uni_arima_prelim.
It continues until a specified convergence criterion is satisfied, or until a specified number of iterations has been carried out.
The progress of the procedure can be monitored by means of a user-supplied function.

.. _g13ae-py2-py-doc:

For full information please refer to the NAG Library document for g13ae

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13aef.html

.. _g13ae-py2-py-parameters:

**Parameters**
**mr** : int, array-like, shape :math:\left(7\right)
The orders vector :math:\left(p, d, q, P, D, Q, s\right) of the ARIMA model whose parameters are to be estimated. :math:p, :math:q, :math:P and :math:Q refer respectively to the number of autoregressive (:math:\phi), moving average :math:\left(\theta \right), seasonal autoregressive (:math:\Phi) and seasonal moving average (:math:\Theta) parameters. :math:d, :math:D and :math:s refer respectively to the order of non-seasonal differencing, the order of seasonal differencing and the seasonal period.

**par** : float, array-like, shape :math:\left(\textit{npar}\right)
The initial estimates of the :math:p values of the :math:\phi parameters, the :math:q values of the :math:\theta parameters, the :math:P values of the :math:\Phi parameters and the :math:Q values of the :math:\Theta parameters, in that order.

**c** : float
If :math:\mathrm{kfc} = 0, :math:\mathrm{c} must contain the expected value, :math:c, of the differenced series.

If :math:\mathrm{kfc} = 1, :math:\mathrm{c} must contain an initial estimate of :math:c.

**x** : float, array-like, shape :math:\left(\textit{nx}\right)
The :math:n values of the original undifferenced time series.

**iex** : int
The dimension of the arrays :math:\mathrm{ex}, :math:\mathrm{exr} and :math:\mathrm{al}.

**igh** : int
The dimension of the arrays :math:\mathrm{g} and :math:\mathrm{sd}.

The second dimension of the arrays :math:\mathrm{h} and :math:\mathrm{hc}.

**ist** : int
The dimension of the array :math:\mathrm{st}.

**kpiv** : int
Must be nonzero if the progress of the optimization is to be monitored using :math:\mathrm{piv}. Otherwise :math:\mathrm{kpiv} must contain :math:0.

**zsp** : float, array-like, shape :math:\left(4\right)
When :math:\mathrm{kzsp} = 1, the first four elements of :math:\mathrm{zsp} must contain the four values used to guide the search procedure. These are as follows.

:math:\mathrm{zsp}[0] contains :math:\alpha, the value used to constrain the magnitude of the search procedure steps.

:math:\mathrm{zsp}[1] contains :math:\beta, the multiplier which regulates the value :math:\alpha.

:math:\mathrm{zsp}[2] contains :math:\delta, the value of the stationarity and invertibility test tolerance factor.

:math:\mathrm{zsp}[3] contains :math:\gamma, the value of the convergence criterion.

If :math:\mathrm{kzsp}\neq 1 on entry, default values for :math:\mathrm{zsp} are supplied by the function.

These are :math:0.001, :math:10.0, :math:1000.0 and :math:\mathrm{max}\left(100\times \text{machine precision},0.0000001\right) respectively.

**kzsp** : int
The value :math:1 if the function is to use the input values of :math:\mathrm{zsp}, and any other value if the default values of :math:\mathrm{zsp} are to be used.

**kfc** : int, optional
Must be set to :math:1 if the constant, :math:c, is to be estimated and :math:0 if it is to be held fixed at its initial value.

**piv** : None or callable piv(mr, par, c, kfc, icount, s, g, h, itc, zsp, data=None), optional
Note: if this argument is **None** then a NAG-supplied facility will be used.

:math:\mathrm{piv} is used to monitor the progress of the optimization.

**Parameters**
**mr** : int, ndarray, shape :math:\left(7\right)
:math:\mathrm{mr}, defined as for uni_arima_estim.

**par** : float, ndarray, shape :math:\left(\textit{npar}\right)
:math:\mathrm{par}, defined as for uni_arima_estim.

**c** : float
:math:\mathrm{c}, defined as for uni_arima_estim.

**kfc** : int
:math:\mathrm{kfc}, defined as for uni_arima_estim.

**icount** : int, ndarray, shape :math:\left(6\right)
:math:\mathrm{icount}, defined as for uni_arima_estim.

**s** : float
:math:\mathrm{s}, defined as for uni_arima_estim.

**g** : float, ndarray, shape :math:\left(\textit{igh}\right)
:math:\mathrm{g}, defined as for uni_arima_estim.

**h** : float, ndarray, shape :math:\left(:, \textit{igh}\right)
:math:\mathrm{h}, defined as for uni_arima_estim.

**itc** : int
:math:\mathrm{itc}, defined as for uni_arima_estim.

**zsp** : float, ndarray, shape :math:\left(4\right)
:math:\mathrm{zsp}, defined as for uni_arima_estim.

**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.

**nit** : int, optional
The maximum number of iterations to be performed.

**data** : arbitrary, optional
User-communication data for callback functions.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**par** : float, ndarray, shape :math:\left(\textit{npar}\right)
The latest values of the estimates of these parameters.

**c** : float
If :math:\mathrm{kfc} = 0, :math:\mathrm{c} is unchanged.

If :math:\mathrm{kfc} = 1, :math:\mathrm{c} contains the latest estimate of :math:c.

Therefore, if :math:\mathrm{c} and :math:\mathrm{kfc} are both zero on entry, there is no constant correction.

**icount** : int, ndarray, shape :math:\left(6\right)
Size of various output arrays.

:math:\mathrm{icount}[0]

Contains :math:q+\left(Q\times s\right), the number of backforecasts.

:math:\mathrm{icount}[1]

Contains :math:n-d-\left(D\times s\right), the number of differenced values.

:math:\mathrm{icount}[2]

Contains :math:d+\left(D\times s\right), the number of values of reconstitution information.

:math:\mathrm{icount}[3]

Contains :math:n+q+\left(Q\times s\right), the number of values held in each of the series :math:\mathrm{ex}, :math:\mathrm{exr} and :math:\mathrm{al}.

:math:\mathrm{icount}[4]

Contains :math:n-d-\left(D\times s\right)-p-q-P-Q-\mathrm{kfc}, the number of degrees of freedom associated with :math:S.

:math:\mathrm{icount}[5]

Contains :math:\mathrm{icount}[0]+\textit{npar}+\mathrm{kfc}, the number of parameters being estimated.

These values are always computed regardless of the exit value of :math:\textit{errno}.

**ex** : float, ndarray, shape :math:\left(\mathrm{iex}\right)
The extended differenced series which is made up of:

:math:\mathrm{icount}[0] backforecast values of the differenced series.

:math:\mathrm{icount}[1] actual values of the differenced series.

:math:\mathrm{icount}[2] values of reconstitution information.

The total number of these values held in :math:\mathrm{ex} is :math:\mathrm{icount}[3].

If the function exits because of a faulty input parameter, the contents of :math:\mathrm{ex} will be indeterminate.

**exr** : float, ndarray, shape :math:\left(\mathrm{iex}\right)
The values of the model residuals which is made up of:

:math:\mathrm{icount}[0] residuals corresponding to the backforecasts in the differenced series.

:math:\mathrm{icount}[1] residuals corresponding to the actual values in the differenced series.

The remaining :math:\mathrm{icount}[2] values contain zeros.

If the function exits with :math:\textit{errno} holding a value other than :math:0 or :math:9, the contents of :math:\mathrm{exr} will be indeterminate.

**al** : float, ndarray, shape :math:\left(\mathrm{iex}\right)
The intermediate series which is made up of:

:math:\mathrm{icount}[0] intermediate series values corresponding to the backforecasts in the differenced series.

:math:\mathrm{icount}[1] intermediate series values corresponding to the actual values in the differenced series.

The remaining :math:\mathrm{icount}[2] values contain zeros.

If an exception is raised, the contents of :math:\mathrm{al} will be indeterminate.

**s** : float
The residual sum of squares after the latest series of parameter estimates has been incorporated into the model. If the function exits with a faulty input parameter, :math:\mathrm{s} contains zero.

**g** : float, ndarray, shape :math:\left(\mathrm{igh}\right)
The latest value of the derivatives of :math:S with respect to each of the parameters being estimated (backforecasts, :math:\mathrm{par} parameters, and where relevant the constant -- in that order). The contents of :math:\mathrm{g} will be indeterminate if the function exits with a faulty input parameter.

**sd** : float, ndarray, shape :math:\left(\mathrm{igh}\right)
The standard deviations corresponding to each of the parameters being estimated (backforecasts, :math:\mathrm{par} parameters, and where relevant the constant, in that order).

If the function exits with :math:\textit{errno} containing a value other than :math:0 or :math:9, or if the required number of iterations is zero, the contents of :math:\mathrm{sd} will be indeterminate.

**h** : float, ndarray, shape :math:\left(1+\textit{q}+\left(\textit{Q}\times \textit{s}\right)+\textit{npar}+\mathrm{kfc}, \mathrm{igh}\right)
The second derivative of :math:S and correlation coefficients.

(a) the latest values of an approximation to the second derivative of :math:S with respect to each of the :math:\left(q+Q\times s+\textit{npar}+\mathrm{kfc}\right) parameters being estimated (backforecasts, :math:\mathrm{par} parameters, and where relevant the constant -- in that order), and

(#) the correlation coefficients relating to each pair of these parameters.

These are held in a matrix defined by the first :math:\left(q+Q\times s+\textit{npar}+\mathrm{kfc}\right) rows and the first :math:\left(q+Q\times s+\textit{npar}+\mathrm{kfc}\right) columns of :math:\mathrm{h}. (Note that :math:\mathrm{icount}[5] contains the value of this expression.) The values of \(a) are contained in the upper triangle, and the values of \(b) in the strictly lower triangle.

These correlation coefficients are zero during intermediate printout using :math:\mathrm{piv}, and indeterminate if :math:\textit{errno} contains on exit a value other than :math:0 or :math:9.

All the contents of :math:\mathrm{h} are indeterminate if the required number of iterations are zero.

The :math:\left(q+\left(Q\times s\right)+\textit{npar}+\mathrm{kfc}+1\right)\ th row of :math:\mathrm{h} is used internally as workspace.

**st** : float, ndarray, shape :math:\left(\mathrm{ist}\right)
The :math:\mathrm{nst} values of the state set array. If the function exits with :math:\textit{errno} containing a value other than :math:0 or :math:9, the contents of :math:\mathrm{st} will be indeterminate.

**nst** : int
The number of values in the state set array :math:\mathrm{st}.

**itc** : int
The number of iterations performed.

**zsp** : float, ndarray, shape :math:\left(4\right)
:math:\mathrm{zsp} contains the values, default or otherwise, used by the function.

**isf** : int, ndarray, shape :math:\left(4\right)
Contains success/failure indicators, one for each of the four types of parameter in the model (autoregressive, moving average, seasonal autoregressive, seasonal moving average), in that order.

Each indicator has the interpretation:

.. rst-class:: nag-rules-none nag-align-left

+----------+-------------------------------------------------------------------------------------------------------------------------------+
|:math:-2|On entry parameters of this type have initial estimates which do not satisfy the stationarity or invertibility test conditions.|
+----------+-------------------------------------------------------------------------------------------------------------------------------+
|:math:-1|The search procedure has failed to converge because the latest set of parameter estimates of this type is invalid.             |
+----------+-------------------------------------------------------------------------------------------------------------------------------+
|:math:0 |No parameter of this type is in the model.                                                                                     |
+----------+-------------------------------------------------------------------------------------------------------------------------------+
|:math:1 |Valid final estimates for parameters of this type have been obtained.                                                          |
+----------+-------------------------------------------------------------------------------------------------------------------------------+

.. _g13ae-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{kfc} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{kfc} = 0 or :math:1.

(errno :math:1)
The orders vector :math:\mathrm{mr} is invalid.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npar} = p+q+P+Q.

(errno :math:2)
The model is over-parameterised.

(errno :math:3)
On entry, :math:\mathrm{nit} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nit} \geq 0.

(errno :math:3)
On entry, :math:\mathrm{zsp}[3] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:0.0\leq \mathrm{zsp}[3] < 1.0.

(errno :math:3)
On entry, :math:\mathrm{zsp}[2] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{zsp}[2]\geq 1.0.

(errno :math:3)
On entry, :math:\mathrm{zsp}[1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{zsp}[1] > 1.0.

(errno :math:3)
On entry, :math:\mathrm{zsp}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{zsp}[0] > 0.0.

(errno :math:4)
On entry, :math:\mathrm{ist} = \langle\mathit{\boldsymbol{value}}\rangle and the minimum size :math:\text{required} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ist}\geq \left(P\times s\right)+d+\left(D\times s\right)+q+\mathrm{max}\left(p, {Q\times s}\right).

**Warns**
**NagAlgorithmicWarning**
(errno :math:6)
On entry, :math:\textit{ldh} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ldh}\geq q\times \left(Q\times s\right)+\textit{npar}+\mathrm{kfc}.

(errno :math:6)
On entry, :math:\mathrm{igh} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{igh}\geq q\times \left(Q\times s\right)+\textit{npar}+\mathrm{kfc}.

(errno :math:6)
On entry, :math:\mathrm{iex} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iex}\geq q\times \left(Q\times s\right)+\textit{nx}.

(errno :math:7)
A failure in the search procedure has occurred.

(errno :math:8)
Failure to invert :math:H.

(errno :math:9)
Unable to calculate the latest estimates of the backforecasts.

(errno :math:10)
Satisfactory parameter estimates could not be obtained for all parameter types in the model.

.. _g13ae-py2-py-notes:

**Notes**
No equivalent traditional C interface for this routine exists in the NAG Library.

The time series :math:x_1,x_2,\ldots,x_n supplied to uni_arima_estim is assumed to follow a seasonal autoregressive integrated moving average (ARIMA) model defined as follows:

.. math::
\nabla^d\nabla_s^Dx_t-c = w_t\text{,}

where :math:\nabla^d\nabla_s^Dx_t is the result of applying non-seasonal differencing of order :math:d and seasonal differencing of seasonality :math:s and order :math:D to the series :math:x_t, as outlined in the description of :meth:uni_diff.
The differenced series is then of length :math:N = n-d^{\prime }, where :math:d^{\prime } = d+\left(D\times s\right) is the generalized order of differencing.
The scalar :math:c is the expected value of the differenced series, and the series :math:w_1,w_2,\ldots,w_N follows a zero-mean stationary autoregressive moving average (ARMA) model defined by a pair of recurrence equations.
These express :math:w_t in terms of an uncorrelated series :math:a_t, via an intermediate series :math:e_t.
The first equation describes the seasonal structure:

.. math::
w_t = \Phi_1w_{{t-s}}+\Phi_2w_{{t-2\times s}} + \cdots +\Phi_Pw_{{t-P\times s}}+e_t-\Theta_1e_{{t-s}}-\Theta_2e_{{t-2\times s}} - \cdots -\Theta_Qe_{{t-Q\times s}}\text{.}

The second equation describes the non-seasonal structure.
If the model is purely non-seasonal the first equation is redundant and :math:e_t above is equated with :math:w_t:

.. math::
e_t = \phi_1e_{{t-1}}+\phi_2e_{{t-2}} + \cdots +\phi_pe_{{t-p}}+a_t-\theta_1a_{{t-1}}-\theta_2a_{{t-2}} - \cdots -\theta_qa_{{t-q}}\text{.}

Estimates of the model parameters defined by

.. math::
\begin{array}{l}\phi_1,\phi_2,\ldots,\phi_p,\theta_1,\theta_2,\ldots,\theta_q\text{,}\\\Phi_1,\Phi_2,\ldots,\Phi_P,\Theta_1,\Theta_2,\ldots,\Theta_Q\end{array}

and (optionally) :math:c are obtained by minimizing a quadratic form in the vector :math:w = \left(w_1, w_2, \ldots, w_N\right)^{\prime }.

This is :math:QF = w^{\prime }V^{-1}w, where :math:V is the covariance matrix of :math:w, and is a function of the model parameters.
This matrix is not explicitly evaluated, since :math:QF may be expressed as a 'sum of squares' function.
When moving average parameters :math:\theta_i or :math:\Theta_i are present, so that the generalized moving average order :math:q^{\prime } = q+s\times Q is positive, backforecasts :math:w_{{1-q^{\prime }}},w_{{2-q^{\prime }}},\ldots,w_0 are introduced as nuisance parameters.
The 'sum of squares' function may then be written as

.. math::
S\left(pm\right) = \sum_{{t = 1-q^{\prime }}}^Na_t^2-\sum_{{t = 1-q^{\prime }-p^{\prime }}}^{{-q^{\prime }}}b_t^2\text{,}

where :math:pm is a combined vector of parameters, consisting of the backforecasts followed by the ARMA model parameters.

The terms :math:a_t correspond to the ARMA model residual series :math:a_t, and :math:p^{\prime } = p+s\times P is the generalized autoregressive order.
The terms :math:b_t are only present if autoregressive parameters are in the model, and serve to correct for transient errors introduced at the start of the autoregression.

The equations defining :math:a_t and :math:b_t are precisely:

:math:e_t = w_t-\Phi_1w_{{t-s}}-\Phi_2w_{{t-2\times s}} - \cdots -\Phi_Pw_{{t-P\times s}}+\Theta_1e_{{t-s}}+\Theta_2e_{{t-2\times s}} + \cdots +\Theta_Qe_{{t-Q\times s}},
for :math:t = 1-q^{\prime },2-q^{\prime },\ldots,n.

:math:a_t = e_t-\phi_1e_{{t-1}}-\phi_2e_{{t-2}} - \cdots -\phi_pe_{{t-p}}+\theta_1a_{{t-1}}+\theta_2a_{{t-2}} + \cdots +\theta_qa_{{t-q}},
for :math:t = 1-q^{\prime },2-q^{\prime },\ldots,n.

:math:f_t = w_t-\Phi_1w_{{t+s}}-\Phi_2w_{{t+2\times s}} - \cdots -\Phi_Pw_{{t+P\times s}}+\Theta_1f_{{t-s}}+\Theta_2f_{{t-2\times s}} + \cdots +\Theta_Qf_{{t-Q\times s}},
for :math:t = \left(1-q^{\prime }-s\times P\right),\left(2-q^{\prime }-s\times P\right),\ldots,\left(-q^{\prime }+P\right)

:math:b_t = f_t-\phi_1f_{{t+1}}-\phi_2f_{{t+2}} - \cdots -\phi_pf_{{t+p}}+\theta_1b_{{t-1}}+\theta_2b_{{t-2}} + \cdots +\theta_qb_{{t-q}},
for :math:t = \left(1-q^{\prime }-p^{\prime }\right),\left(2-q^{\prime }-p^{\prime }\right),\ldots,\left(-q^{\prime }\right).

For all four of these equations, the following conditions hold:

:math:w_i = 0 if :math:i < 1-q^{\prime }

:math:e_i = 0 if :math:i < 1-q^{\prime }

:math:a_i = 0 if :math:i < 1-q^{\prime }

:math:f_i = 0 if :math:i < 1-q^{\prime }-s\times P

:math:b_i = 0 if :math:i < 1-q^{\prime }-p^{\prime }

Minimization of :math:S with respect to :math:pm uses an extension of the algorithm of Marquardt (1963).

The first derivatives of :math:S with respect to the parameters are calculated as

.. math::
2\times \sum a_t\times a_{{t,i}}-2\sum b_t\times b_{{t,i}} = 2\times G_i\text{,}

where :math:a_{{t,i}} and :math:b_{{t,i}} are derivatives of :math:a_t and :math:b_t with respect to the :math:i\ th parameter.

The second derivative of :math:S is approximated by

.. math::
2\times \sum a_{{t,i}}\times a_{{t,j}}-2\times \sum b_{{t,i}}\times b_{{t,j}} = 2\times H_{{ij}}\text{.}

Successive parameter iterates are obtained by calculating a vector of corrections :math:\textit{dpm} by solving the equations

.. math::
\left(H+\alpha \times D\right)\times \textit{dpm} = -G\text{,}

where :math:G is a vector with elements :math:G_i, :math:H is a matrix with elements :math:H_{{ij}}, :math:\alpha is a scalar used to control the search and :math:D is the diagonal matrix of :math:H.

The new parameter values are then :math:pm+\textit{dpm}.

The scalar :math:\alpha controls the step size, to which it is inversely related.

If a step results in new parameter values which give a reduced value of :math:S, then :math:\alpha is reduced by a factor :math:\beta.
If a step results in new parameter values which give an increased value of :math:S, or in ARMA model parameters which in any way contravene the stationarity and invertibility conditions, then the new parameters are rejected, :math:\alpha is increased by the factor :math:\beta, and the revised equations are solved for a new parameter correction.

This action is repeated until either a reduced value of :math:S is obtained, or :math:\alpha reaches the limit of :math:10^9, which is used to indicate a failure of the search procedure.

This failure may be due to a badly conditioned sum of squares function or to too strict a convergence criterion.
Convergence is deemed to have occurred if the fractional reduction in the residual sum of squares in successive iterations is less than a value :math:\gamma, while :math:\alpha < 1.0.

The stationarity and invertibility conditions are tested to within a specified tolerance multiple :math:\delta of machine accuracy.
Upon convergence, or completion of the specified maximum number of iterations without convergence, statistical properties of the estimates are derived.
In the latter case the sequence of iterates should be checked to ensure that convergence is adequate for practical purposes, otherwise these properties are not reliable.

The estimated residual variance is

.. math::
\textit{erv} = S_{\mathrm{min}}/{\textit{df}}\text{,}

where :math:S_{\mathrm{min}} is the final value of :math:S, and the residual number of degrees of freedom is given by

.. math::

The covariance matrix of the vector of estimates :math:pm is given by

.. math::
\textit{erv}\times H^{-1}\text{,}

where :math:H is evaluated at the final parameter values.

From this expression are derived the vector of standard deviations, and the correlation matrix for the whole parameter set.
These are asymptotic approximations.

The differenced series :math:w_t (now uncorrected for the constant), intermediate series :math:e_t and residual series :math:a_t are all available upon completion of the iterations over the range (extended by backforecasts)

.. math::
t = 1-q^{\prime },2-q^{\prime },\ldots,N\text{.}

The values :math:a_t can only properly be interpreted as residuals for :math:t\geq 1+p^{\prime }-q^{\prime }, as the earlier values are corrupted by transients if :math:p^{\prime } > 0.

In consequence of the manner in which differencing is implemented, the residual :math:a_t is the one step ahead forecast error for :math:x_{{t+d^{\prime }}}.

For convenient application in forecasting, the following quantities constitute the 'state set', which contains the minimum amount of time series information needed to construct forecasts:

(i) the differenced series :math:w_t, for :math:\left(N-s\times P\right) < t\leq N,

(#) the :math:d^{\prime } values required to reconstitute the original series :math:x_t from the differenced series :math:w_t,

(#) the intermediate series :math:e_t, for :math:\left(N-\mathrm{max}\left(p, {Q\times s}\right)\right) < t\leq N,

(#) the residual series :math:a_t, for :math:\left(N-q\right) < t\leq N.

This state set is available upon completion of the iterations.
The function may be used purely for the construction of this state set, given a previously estimated model and time series :math:x_t, by requesting zero iterations.
Backforecasts are estimated, but the model parameter values are unchanged.
If later observations become available and it is desired to update the state set, :meth:uni_arima_update can be used.

.. _g13ae-py2-py-references:

**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
"""
raise NotImplementedError

[docs]def uni_arima_estim_easy(mr, par, c, x, nppc, kfc=1, kpiv=0, nit=100, ires=None, io_manager=None):
r"""
uni_arima_estim_easy is an easy-to-use version of :meth:uni_arima_estim.
It fits a seasonal autoregressive integrated moving average (ARIMA) model to an observed time series, using a nonlinear least squares procedure incorporating backforecasting. Parameter estimates are obtained, together with appropriate standard errors.
The residual series is returned, and information for use in forecasting the time series is produced for use in :meth:uni_arima_update and :meth:uni_arima_forecast_state.

The estimation procedure is iterative, starting with initial parameter values such as may be obtained using :meth:uni_arima_prelim.
It continues until a specified convergence criterion is satisfied or until a specified number of iterations have been carried out.
The progress of the iteration can be monitored by means of an optional printing facility.

.. _g13af-py2-py-doc:

For full information please refer to the NAG Library document for g13af

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13aff.html

.. _g13af-py2-py-parameters:

**Parameters**
**mr** : int, array-like, shape :math:\left(7\right)
The orders vector :math:\left(p, d, q, P, D, Q, s\right) of the ARIMA model whose parameters are to be estimated. :math:p, :math:q, :math:P and :math:Q refer respectively to the number of autoregressive :math:\left(\phi \right), moving average :math:\left(\theta \right), seasonal autoregressive :math:\left(\Phi \right) and seasonal moving average :math:\left(\Theta \right) parameters. :math:d, :math:D and :math:s refer respectively to the order of non-seasonal differencing, the order of seasonal differencing and the seasonal period.

**par** : float, array-like, shape :math:\left(\textit{npar}\right)
The initial estimates of the :math:p values of the :math:\phi parameters, the :math:q values of the :math:\theta parameters, the :math:P values of the :math:\Phi parameters and the :math:Q values of the :math:\Theta parameters, in that order.

**c** : float
If :math:\mathrm{kfc} = 0, :math:\mathrm{c} must contain the expected value, :math:c, of the differenced series.

If :math:\mathrm{kfc} = 1, :math:\mathrm{c} must contain an initial estimate of :math:c.

Therefore, if :math:\mathrm{c} and :math:\mathrm{kfc} are both zero on entry, there is no constant correction.

**x** : float, array-like, shape :math:\left(\textit{nx}\right)
The :math:n values of the original undifferenced time series.

**nppc** : int
The number of :math:\phi, :math:\theta, :math:\Phi, :math:\Theta and :math:c parameters to be estimated. :math:\mathrm{nppc} = p+q+P+Q+1 if the constant is being estimated and :math:\mathrm{nppc} = p+q+P+Q if not.

**kfc** : int, optional
Must be set to :math:1 if the constant, :math:c, is to be estimated and :math:0 if it is to be held fixed at its initial value.

**kpiv** : int, optional
Must be nonzero if the progress of the optimization is to be monitored using the built-in printing facility. Otherwise :math:\mathrm{kpiv} must contain zero. If selected, monitoring output will be sent to the file object associated with the advisory I/O unit (see :class:~naginterfaces.base.utils.FileObjManager). For each iteration, the heading

::

G13AFZ MONITORING OUTPUT - ITERATION n

followed by the argument values, and residual sum of squares, are printed.

**nit** : int, optional
The maximum number of iterations to be performed.

**ires** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:15\times \left(\textit{q}+\textit{Q}\times \textit{s}\right)+11\times \textit{nx}+13\times \left(\textit{npar}+\mathrm{kfc}\right)+8\times \left(\textit{p}+\textit{P}\times \textit{s}\right)+12+2\times \left(\textit{q}+\textit{Q}\times \textit{s}+\textit{npar}+\mathrm{kfc}\right)^2.

The dimension of the array :math:\mathrm{res}.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**par** : float, ndarray, shape :math:\left(\textit{npar}\right)
Contains the latest values of the estimates of these parameters.

**c** : float
If :math:\mathrm{kfc} = 0, :math:\mathrm{c} is unchanged.

If :math:\mathrm{kfc} = 1, :math:\mathrm{c} contains the latest estimate of :math:c.

**s** : float
The residual sum of squares after the latest series of parameter estimates has been incorporated into the model. If the function exits with a faulty input parameter, :math:\mathrm{s} contains zero.

**ndf** : int
The number of degrees of freedom associated with :math:\mathrm{s},

:math:\mathrm{ndf} = n-d-D\times s-p-q-P-Q-\mathrm{kfc}.

**sd** : float, ndarray, shape :math:\left(\mathrm{nppc}\right)
The standard deviations corresponding to the parameters in the model (:math:p autoregressive, :math:q moving average, :math:P seasonal autoregressive, :math:Q seasonal moving average and :math:c, if estimated, in that order). If the function exits with :math:\textit{errno} containing a value other than :math:0 or :math:9, or if the required number of iterations is zero, the contents of :math:\mathrm{sd} will be indeterminate.

**cm** : float, ndarray, shape :math:\left(\mathrm{nppc}, \mathrm{nppc}\right)
The correlation coefficients associated with each pair of the :math:\mathrm{nppc} parameters. These are held in the first :math:\mathrm{nppc} rows and the first :math:\mathrm{nppc} columns of :math:\mathrm{cm}. These correlation coefficients are indeterminate if :math:\textit{errno} contains on exit a value other than :math:0 or :math:9, or if the required number of iterations is zero.

**st** : float, ndarray, shape :math:\left(\textit{nx}\right)
The value of the state set in its first :math:\mathrm{nst} elements. If the function exits with :math:\textit{errno} containing a value other than :math:0 or :math:9, the contents of :math:\mathrm{st} will be indeterminate.

**nst** : int
The size of the state set. :math:\mathrm{nst} = P\times s+D\times s+d+q+\mathrm{max}\left(p, {Q\times s}\right).

:math:\mathrm{nst} should be used subsequently in :meth:uni_arima_update and :meth:uni_arima_forecast_state as the dimension of :math:\mathrm{st}.

**itc** : int
The number of iterations performed.

**isf** : int, ndarray, shape :math:\left(4\right)
The first four elements of :math:\mathrm{isf} contain success/failure indicators, one for each of the four types of parameter in the model (autoregressive, moving average, seasonal autoregressive, seasonal moving average), in that order.

Each indicator has the interpretation:

.. rst-class:: nag-rules-none nag-align-left

+----------+-------------------------------------------------------------------------------------------------------------------------------+
|:math:-2|On entry parameters of this type have initial estimates which do not satisfy the stationarity or invertibility test conditions.|
+----------+-------------------------------------------------------------------------------------------------------------------------------+
|:math:-1|The search procedure has failed to converge because the latest set of parameter estimates of this type is invalid.             |
+----------+-------------------------------------------------------------------------------------------------------------------------------+
|:math:0 |No parameter of this type is in the model.                                                                                     |
+----------+-------------------------------------------------------------------------------------------------------------------------------+
|:math:1 |Valid final estimates for parameters of this type have been obtained.                                                          |
+----------+-------------------------------------------------------------------------------------------------------------------------------+

**res** : float, ndarray, shape :math:\left(\mathrm{ires}\right)
The first :math:\mathrm{nres} elements of :math:\mathrm{res} contain the model residuals derived from the differenced series. If the function exits with :math:\textit{errno} holding a value other than :math:0 or :math:9, these elements of :math:\mathrm{res} will be indeterminate. The rest of the array :math:\mathrm{res} is used as workspace.

**nres** : int
The number of model residuals returned in :math:\mathrm{res}.

.. _g13af-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{kfc} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{kfc} = 0 or :math:1.

(errno :math:1)
The orders vector :math:\mathrm{mr} is invalid.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npar} = p+q+P+Q.

(errno :math:2)
The model is over-parameterised.

(errno :math:3)
On entry, :math:\mathrm{nit} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nit} \geq 0.

(errno :math:4)
On entry, :math:\textit{nx} = \langle\mathit{\boldsymbol{value}}\rangle and minimum required size for the state set :math:\text{array} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:5)
On entry, :math:\mathrm{ires} = \langle\mathit{\boldsymbol{value}}\rangle and the minimum size :math:\text{required} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ires}\geq 15\times Q^{\prime }+11n+13\times \mathrm{nppc}+8\times P^{\prime }+12+2\times \left(Q^{\prime }+\mathrm{nppc}\right)^2.

**Warns**
**NagAlgorithmicWarning**
(errno :math:7)
A failure in the search procedure has occurred.

(errno :math:8)
The inversion of the Hessian matrix in the calculation of the covariance matrix of the parameter estimates has failed.

(errno :math:9)
Failure whilst calculating backforecasts.

(errno :math:10)
Satisfactory parameter estimates could not be obtained for all parameter types in the model.

.. _g13af-py2-py-notes:

**Notes**
No equivalent traditional C interface for this routine exists in the NAG Library.

The time series :math:x_1,x_2,\ldots,x_n supplied to the function is assumed to follow a seasonal autoregressive integrated moving average (ARIMA) model defined as follows:

.. math::
\nabla^d\nabla_s^Dx_t-c = w_t\text{,}

where :math:\nabla^d\nabla_s^Dx_t is the result of applying non-seasonal differencing of order :math:d and seasonal differencing of seasonality :math:s and order :math:D to the series :math:x_t, as outlined in the description of :meth:uni_diff.
The differenced series is then of length :math:N = n-d^{\prime }, where :math:d^{\prime } = d+\left(D\times s\right) is the generalized order of differencing.
The scalar :math:c is the expected value of the differenced series, and the series :math:w_1,w_2,\ldots,w_N follows a zero-mean stationary autoregressive moving average (ARMA) model defined by a pair of recurrence equations.
These express :math:w_t in terms of an uncorrelated series :math:a_t, via an intermediate series :math:e_t.
The first equation describes the seasonal structure:

.. math::
w_t = \Phi_1w_{{t-s}}+\Phi_2w_{{t-2\times s}} + \cdots +\Phi_Pw_{{t-P\times s}}+e_t-\Theta_1e_{{t-s}}-\Theta_2e_{{t-2\times s}} - \cdots -\Theta_Qe_{{t-Q\times s}}\text{.}

The second equation describes the non-seasonal structure.
If the model is purely non-seasonal the first equation is redundant and :math:e_t above is equated with :math:w_t:

.. math::
e_t = \phi_1e_{{t-1}}+\phi_2e_{{t-2}} + \cdots +\phi_pe_{{t-p}}+a_t-\theta_1a_{{t-1}}-\theta_2a_{{t-2}} - \cdots -\theta_qa_{{t-q}}\text{.}

Estimates of the model parameters defined by

.. math::
\begin{array}{l}\phi_1,\phi_2,\ldots,\phi_p,\theta_1,\theta_2,\ldots,\theta_q\text{,}\\\Phi_1,\Phi_2,\ldots,\Phi_P,\Theta_1,\Theta_2,\ldots,\Theta_Q\end{array}

and (optionally) :math:c are obtained by minimizing a quadratic form in the vector :math:w = \left(w_1, w_2, \ldots, w_N\right)^{\prime }.

The minimization process is iterative, iterations being performed until convergence is achieved (see :ref:Notes for uni_arima_estim <g13ae-py2-py-notes> for full details), or until the user-specified maximum number of iterations are completed.

The final values of the residual sum of squares and the parameter estimates are used to obtain asymptotic approximations to the standard deviations of the parameters, and the correlation matrix for the parameters.
The 'state set' array of information required by forecasting is also returned.

**Note:** if the maximum number of iterations are performed without convergence, these quantities may not be reliable.
In this case, the sequence of iterates should be checked, using the optional monitoring function, to verify that convergence is adequate for practical purposes.

.. _g13af-py2-py-references:

**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
"""
raise NotImplementedError

[docs]def uni_arima_update(st, mr, par, c, anx):
r"""
uni_arima_update accepts a series of new observations of a time series, the model of which is already fully specified, and updates the 'state set' information for use in constructing further forecasts.
The previous specifications of the time series model should have been obtained by using :meth:uni_arima_estim or :meth:uni_arima_estim_easy to estimate the relevant parameters.
The supplied state set will originally have been produced by :meth:uni_arima_estim or :meth:uni_arima_estim_easy, but may since have been updated by earlier calls to uni_arima_update.

A set of residuals corresponding to the new observations is returned.
These may be of use in checking that the new observations conform to the previously fitted model.

.. _g13ag-py2-py-doc:

For full information please refer to the NAG Library document for g13ag

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13agf.html

.. _g13ag-py2-py-parameters:

**Parameters**
**st** : float, array-like, shape :math:\left(\textit{nst}\right)
The state set derived from :meth:uni_arima_estim or :meth:uni_arima_estim_easy, or as modified using earlier calls of uni_arima_update.

**mr** : int, array-like, shape :math:\left(7\right)
The orders vector :math:\left(p, d, q, P, D, Q, s\right) of the ARIMA model, in the usual notation.

**par** : float, array-like, shape :math:\left(\textit{npar}\right)
The estimates of the :math:p values of the :math:\phi parameters, the :math:q values of the :math:\theta parameters, the :math:P values of the :math:\Phi parameters and the :math:Q values of the :math:\Theta parameters in the model -- in that order, using the usual notation.

**c** : float
The constant to be subtracted from the differenced data.

**anx** : float, array-like, shape :math:\left(\textit{nuv}\right)
The new undifferenced observations which are to be used to update :math:\mathrm{st}.

**Returns**
**st** : float, ndarray, shape :math:\left(\textit{nst}\right)
The updated values of the state set.

**anexr** : float, ndarray, shape :math:\left(\textit{nuv}\right)
The residuals corresponding to the new observations in :math:\mathrm{anx}.

.. _g13ag-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
The orders vector :math:\mathrm{mr} is invalid.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npar} = p+q+P+Q.

(errno :math:2)
On entry, :math:\textit{nst} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nst} = P\times s+D\times s+d+q+\mathrm{max}\left({Q\times s}, p\right).

(errno :math:3)
On entry, :math:\textit{nuv} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nuv} > 0.

(errno :math:4)
On entry, :math:\textit{nwa} = \langle\mathit{\boldsymbol{value}}\rangle and the minimum size :math:\text{required} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nwa}\geq 4\times \textit{npar}+3\times \textit{nst}.

.. _g13ag-py2-py-notes:

**Notes**
No equivalent traditional C interface for this routine exists in the NAG Library.

The time series model is specified as outlined in :ref:Notes for uni_arima_estim <g13ae-py2-py-notes> and :ref:Notes for uni_arima_estim_easy <g13af-py2-py-notes>.
This also describes how the state set, which contains the minimum amount of time series information needed to construct forecasts, is made up of

(i) the differenced series :math:w_t (uncorrected for the constant :math:c), for :math:\left(N-P\times s\right) < t\leq N,

(#) the :math:d^{\prime } values required to reconstitute the original series :math:x_t from the differenced series :math:w_t,

(#) the intermediate series :math:e_t, for :math:\left(N-\mathrm{max}\left(p, {Q\times s}\right)\right) < t\leq N, and

(#) the residual series :math:a_t, for :math:\left(N-q\right) < t\leq N.

If the number of original undifferenced observations was :math:n, then :math:d^{\prime } = d+\left(D\times s\right) and :math:N = n-d^{\prime }.

To update the state set, given a number of new undifferenced observations :math:x_t, :math:t = n+1,n+2,\ldots,n+k, the four series above are first reconstituted.

Differencing and residual calculation operations are then applied to the new observations and :math:k new values of :math:w_t,e_t and :math:a_t are derived.

The first :math:k values in these three series are then discarded and a new state set is obtained.

The residuals in the :math:a_t series corresponding to the :math:k new observations are preserved in an output array.
The parameters of the time series model are not changed in this function.
"""
raise NotImplementedError

[docs]def uni_arima_forecast_state(st, mr, par, c, rms, nfv):
r"""
uni_arima_forecast_state produces forecasts of a time series, given a time series model which has already been fitted to the time series using :meth:uni_arima_estim or :meth:uni_arima_estim_easy.
The original observations are not required, since uni_arima_forecast_state uses as input either the original state set produced by :meth:uni_arima_estim or :meth:uni_arima_estim_easy or the state set updated by a series of new observations using :meth:uni_arima_update.
Standard errors of the forecasts are also provided.

.. _g13ah-py2-py-doc:

For full information please refer to the NAG Library document for g13ah

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ahf.html

.. _g13ah-py2-py-parameters:

**Parameters**
**st** : float, array-like, shape :math:\left(\textit{nst}\right)
The state set derived from :meth:uni_arima_estim or :meth:uni_arima_estim_easy originally, or as modified using earlier calls of :meth:uni_arima_update.

**mr** : int, array-like, shape :math:\left(7\right)
The orders vector :math:\left(p, d, q, P, D, Q, s\right) of the ARIMA model, in the usual notation.

**par** : float, array-like, shape :math:\left(\textit{npar}\right)
The estimates of the :math:p values of the :math:\phi parameters, the :math:q values of the :math:\theta parameters, the :math:P values of the :math:\Phi parameters and the :math:Q values of the :math:\Theta parameters which specify the model and which were output originally by :meth:uni_arima_estim or :meth:uni_arima_estim_easy.

**c** : float
:math:c, the value of the model constant. This will have been output by :meth:uni_arima_estim or :meth:uni_arima_estim_easy.

**rms** : float
:math:V, the residual variance associated with the model.

If :meth:uni_arima_estim_easy was used to estimate the model, :math:\mathrm{rms} should be set to :math:{\textit{s}}/{\textit{ndf}}, where :math:\textit{s} and :math:\textit{ndf} were output by :meth:uni_arima_estim_easy.

If :meth:uni_arima_estim was used to estimate the model, :math:\mathrm{rms} should be set to :math:{\textit{s}}/{\textit{icount}}[4], where :math:\textit{s} and :math:{\textit{icount}}[4] were output by :meth:uni_arima_estim.

**nfv** : int
:math:L, the required number of forecasts.

**Returns**
**fva** : float, ndarray, shape :math:\left(\mathrm{nfv}\right)
:math:\mathrm{nfv} forecast values relating to the original undifferenced series.

**fsd** : float, ndarray, shape :math:\left(\mathrm{nfv}\right)
The standard errors associated with each of the :math:\mathrm{nfv} forecast values in :math:\mathrm{fva}.

.. _g13ah-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
The orders vector :math:\mathrm{mr} is invalid.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npar} = p+q+P+Q.

(errno :math:2)
On entry, :math:\textit{nst} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nst} = P\times s+D\times s+d+q+\mathrm{max}\left({Q\times s}, p\right).

(errno :math:3)
On entry, :math:\mathrm{nfv} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nfv} > 0.

(errno :math:4)
On entry, :math:\textit{nwa} = \langle\mathit{\boldsymbol{value}}\rangle and the minimum size :math:\text{required} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nwa}\geq 4\times \textit{npar}+3\times \textit{nst}.

(errno :math:5)
On entry, :math:\mathrm{rms} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{rms}\geq 0.0.

.. _g13ah-py2-py-notes:

**Notes**
No equivalent traditional C interface for this routine exists in the NAG Library.

The original time series is :math:x_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,n and parameters have been fitted to the model of this time series using :meth:uni_arima_estim or :meth:uni_arima_estim_easy.

Forecasts of :math:x_{\textit{t}}, for :math:\textit{t} = n+1,\ldots,n+L, are calculated in five stages, as follows:

(i) set :math:a_t = 0 for :math:t = N+1,N+2,\ldots,N+L, where :math:N = n-d-\left(D\times s\right) is the number of differenced values in the series;

(#) calculate the values of :math:e_{\textit{t}}, for :math:\textit{t} = N+1,\ldots,N+L, and :math:e_{\textit{t}} = \phi_1\times e_{{t-1}} + \cdots + \phi_p\times e_{{t-p}}+a_t-\theta_1\times a_{{t-1}} - \cdots -\theta_q\times a_{{t-q}};

(#) calculate the values of :math:w_{\textit{t}}, for :math:\textit{t} = N+1,\ldots,N+L, where :math:w_t = \Phi_1\times w_{{t-s}} + \cdots + \Phi_P\times w_{{t-s\times P}}+e_t-\Theta_1\times e_{{t-s}} - \cdots -\Theta_Q\times e_{{t-s\times Q}} and :math:w_t for :math:t\leq N are the first :math:s\times P values in the state set, corrected for the constant;

(#) add the constant term :math:c to give the differenced series :math:\nabla^d\nabla_s^Dx_{\textit{t}} = w_{\textit{t}}+c, for :math:\textit{t} = N+1,\ldots,N+L;

(#) the differencing operations are reversed to reconstitute :math:x_{\textit{t}}, for :math:\textit{t} = n+1,\ldots,n+L.

The standard errors of these forecasts are given by :math:s_{\textit{t}} = \left[{V\times \left(\psi_0^2+\psi_1^2 + \cdots +\psi_{{\textit{t}-n-1}}^2\right)}\right]^{{1/2}}, for :math:\textit{t} = n+1,\ldots,n+L, where :math:\psi_0 = 1, :math:V is the residual variance of :math:a_t, and :math:\psi_j is the coefficient expressing the dependence of :math:x_t on :math:a_{{t-j}}.

To calculate :math:\psi_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,\left(L-1\right), the following device is used.

A copy of the state set is initialized to zero throughout and the calculations outlined above for the construction of forecasts are carried out with the settings :math:a_{{N+1}} = 1, and :math:a_{\textit{t}} = 0, for :math:\textit{t} = N+2,\ldots,N+L.

The resulting quantities corresponding to the sequence :math:x_{{N+1}},x_{{N+2}},\ldots,x_{{N+L}} are precisely :math:1, :math:\psi_1,\psi_2,\ldots,\psi_{{L-1}}.

The supplied time series model is used throughout these calculations, with the exception that the constant term :math:c is taken to be zero.
"""
raise NotImplementedError

[docs]def uni_arima_forcecast(mr, par, c, kfc, x, ist, nfv, ifv):
r"""
uni_arima_forcecast applies a fully specified seasonal ARIMA model to an observed time series, generates the state set for forecasting and (optionally) derives a specified number of forecasts together with their standard deviations.

.. _g13aj-py2-py-doc:

For full information please refer to the NAG Library document for g13aj

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ajf.html

.. _g13aj-py2-py-parameters:

**Parameters**
**mr** : int, array-like, shape :math:\left(7\right)
The orders vector :math:\left(p, d, q, P, D, Q, s\right) of the ARIMA model, in the usual notation.

**par** : float, array-like, shape :math:\left(\textit{npar}\right)
The :math:p values of the :math:\phi parameters, the :math:q values of the :math:\theta parameters, the :math:P values of the :math:\Phi parameters, and the :math:Q values of the :math:\Theta parameters, in that order.

**c** : float
:math:c, the expected value of the differenced series (i.e., :math:c is the constant correction). Where there is no constant term, :math:\mathrm{c} must be set to :math:0.0.

**kfc** : int
Must be set to :math:0 if :math:\mathrm{c} was not estimated, and :math:1 if :math:\mathrm{c} was estimated. This is irrespective of whether or not :math:\mathrm{c} = 0.0. The only effect is that the residual degrees of freedom are one greater when :math:\mathrm{kfc} = 0. Assuming the supplied time series to be the same as that to which the model was originally fitted, this ensures an unbiased estimate of the residual mean-square.

**x** : float, array-like, shape :math:\left(\textit{nx}\right)
The :math:n values of the original undifferenced time series.

**ist** : int
The dimension of the array :math:\mathrm{st}.

**nfv** : int
The required number of forecasts. If :math:\mathrm{nfv}\leq 0, no forecasts will be computed.

**ifv** : int
The dimension of the arrays :math:\mathrm{fva} and :math:\mathrm{fsd}.

**Returns**
**rms** : float
The residual variance (mean square) associated with the model.

**st** : float, ndarray, shape :math:\left(\mathrm{ist}\right)
The :math:\mathrm{nst} values of the state set.

**nst** : int
The number of values in the state set array :math:\mathrm{st}.

**fva** : float, ndarray, shape :math:\left(\mathrm{ifv}\right)
If :math:\mathrm{nfv} > 0, :math:\mathrm{fva} contains the :math:\mathrm{nfv} forecast values relating to the original undifferenced time series.

**fsd** : float, ndarray, shape :math:\left(\mathrm{ifv}\right)
If :math:\mathrm{nfv} > 0, :math:\mathrm{fsd} contains the estimated standard errors of the :math:\mathrm{nfv} forecast values.

**isf** : int, ndarray, shape :math:\left(4\right)
Contains validity indicators, one for each of the four possible parameter types in the model (autoregressive, moving average, seasonal autoregressive, seasonal moving average), in that order.

Each indicator has the interpretation:

.. rst-class:: nag-rules-none nag-align-left

+----------+---------------------------------------------------------------------------------------------------------------------+
|:math:-1|On entry the set of parameter values of this type does not satisfy the stationarity or invertibility test conditions.|
+----------+---------------------------------------------------------------------------------------------------------------------+
|:math:0 |No parameter of this type is in the model.                                                                           |
+----------+---------------------------------------------------------------------------------------------------------------------+
|:math:1 |Valid parameter values of this type have been supplied.                                                              |
+----------+---------------------------------------------------------------------------------------------------------------------+

.. _g13aj-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{kfc} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{kfc} = 0 or :math:1.

(errno :math:1)
The orders vector :math:\mathrm{mr} is invalid.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npar} = p+q+P+Q.

(errno :math:2)
The model is over-parameterised.

(errno :math:4)
On entry, :math:\mathrm{ist} = \langle\mathit{\boldsymbol{value}}\rangle and the minimum size :math:\text{required} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ist}\geq \left(P\times s\right)+d+\left(D\times s\right)+q+\mathrm{max}\left(p, {Q\times s}\right).

(errno :math:5)
Unable to calculate the latest estimates of the backforecasts.

(errno :math:6)
Satisfactory parameter estimates could not be obtained for all parameter types in the model.

(errno :math:7)
On entry, :math:\mathrm{ifv} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nfv} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ifv}\geq \mathrm{max}\left(1, \mathrm{nfv}\right).

.. _g13aj-py2-py-notes:

**Notes**
No equivalent traditional C interface for this routine exists in the NAG Library.

The time series :math:x_1,x_2,\ldots,x_n supplied to the function is assumed to follow a seasonal autoregressive integrated moving average (ARIMA) model with known parameters.

The model is defined by the following relations.

(a) :math:\nabla^d\nabla_s^Dx_t-c = w_t where :math:\nabla^d\nabla_s^Dx_t is the result of applying non-seasonal differencing of order :math:d and seasonal differencing of seasonality :math:s and order :math:D to the series :math:x_t, and :math:c is a constant.

(#) :math:w_t = \Phi_1w_{{t-s}}+\Phi_2w_{{t-2\times s}} + \cdots +\Phi_Pw_{{t-P\times s}}+e_t-\Theta_1e_{{t-s}}-\Theta_2e_{{t-2\times s}} - \cdots -\Theta_Qe_{{t-Q\times s}}\text{.}

This equation describes the seasonal structure with seasonal period :math:s; in the absence of seasonality it reduces to :math:w_t = e_t.

(#) :math:e_t = \phi_1e_{{t-1}}+\phi_2e_{{t-2}} + \cdots +\phi_pe_{{t-p}}+a_t-\theta_1a_{{t-1}}-\theta_2a_{{t-2}} - \cdots -\theta_qa_{{t-q}}\text{.}

This equation describes the non-seasonal structure.

Given the series, the constant :math:c, and the model parameters :math:\Phi, :math:\Theta, :math:\phi, :math:\theta, the function computes the following.

(a) The state set required for forecasting. This contains the minimum amount of information required for forecasting and comprises:

(i) the differenced series :math:w_t, for :math:\left(N-s\times P\right)\leq t\leq N;

(#) the :math:\left(d+D\times s\right) values required to reconstitute the original series :math:x_t from the differenced series :math:w_t;

(#) the intermediate series :math:e_t, for :math:N-\mathrm{max}\left(p, {Q\times s}\right) < t\leq N;

(#) the residual series :math:a_t, for :math:\left(N-q\right) < t\leq N, where :math:N = n-\left(d+D\times s\right).

(#) A set of :math:L forecasts of :math:x_t and their estimated standard errors, :math:s_t, for :math:\textit{t} = n+1,\ldots,n+L (:math:L may be zero).

The forecasts and estimated standard errors are generated from the state set, and are identical to those that would be produced from the same state set by :meth:uni_arima_forecast_state.

Use of uni_arima_forcecast should be confined to situations in which the state set for forecasting is unknown.
Forecasting from the series requires recalculation of the state set and this is relatively expensive.

.. _g13aj-py2-py-references:

**References**
Box, G E P and Jenkins, G M, 1976, Time Series Analysis: Forecasting and Control, (Revised Edition), Holden--Day
"""
raise NotImplementedError

[docs]def uni_smooth_exp(mode, itype, p, param, y, k, init, nf, comm):
r"""
uni_smooth_exp performs exponential smoothing using either single exponential, double exponential or a Holt--Winters method.

.. _g13am-py2-py-doc:

For full information please refer to the NAG Library document for g13am

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13amf.html

.. _g13am-py2-py-parameters:

**Parameters**
**mode** : int
Indicates if uni_smooth_exp is continuing from a previous call or, if not, how the initial values are computed.

:math:\mathrm{mode} = 0

Required values for :math:m_0, :math:r_0 and :math:s_{{-\textit{j}}}, for :math:\textit{j} = 0,1,\ldots,p-1, are supplied in :math:\mathrm{init}.

:math:\mathrm{mode} = 1

uni_smooth_exp continues from a previous call using values that are supplied in :math:\mathrm{comm}\ ['r'].

:math:\mathrm{mode} = 2

Required values for :math:m_0, :math:r_0 and :math:s_{{-\textit{j}}}, for :math:\textit{j} = 0,1,\ldots,p-1, are estimated using the first :math:k observations.

**itype** : int
The smoothing function.

:math:\mathrm{itype} = 1

Single exponential.

:math:\mathrm{itype} = 2

Brown double exponential.

:math:\mathrm{itype} = 3

Linear Holt.

:math:\mathrm{itype} = 4

:math:\mathrm{itype} = 5

Multiplicative Holt--Winters.

**p** : int
If :math:\mathrm{itype} = 4 or :math:5, the seasonal order, :math:p, otherwise :math:\mathrm{p} is not referenced.

**param** : float, array-like, shape :math:\left(:\right)
Note: the required length for this argument is determined as follows: if :math:\mathrm{itype}\text{ in } (1, 2): :math:1; if :math:\mathrm{itype}=3: :math:3; if :math:\mathrm{itype}\text{ in } (4, 5): :math:4; otherwise: :math:0.

The smoothing parameters.

If :math:\mathrm{itype} = 1 or :math:2, :math:\mathrm{param}[0] = \alpha and any remaining elements of :math:\mathrm{param} are not referenced.

If :math:\mathrm{itype} = 3, :math:\mathrm{param}[0] = \alpha, :math:\mathrm{param}[1] = \gamma, :math:\mathrm{param}[2] = \phi and any remaining elements of :math:\mathrm{param} are not referenced.

If :math:\mathrm{itype} = 4 or :math:5, :math:\mathrm{param}[0] = \alpha, :math:\mathrm{param}[1] = \gamma, :math:\mathrm{param}[2] = \beta and :math:\mathrm{param}[3] = \phi.

**y** : float, array-like, shape :math:\left(n\right)
The time series.

**k** : int
If :math:\mathrm{mode} = 2, the number of observations used to initialize the smoothing.

If :math:\mathrm{mode} \neq 2, :math:\mathrm{k} is not referenced.

**init** : float, array-like, shape :math:\left(:\right)
Note: the required length for this argument is determined as follows: if :math:\mathrm{itype}=1: :math:1; if :math:\mathrm{itype}\text{ in } (2, 3): :math:2; if :math:\mathrm{itype}\text{ in } (4, 5): :math:{2+\mathrm{p}}; otherwise: :math:0.

If :math:\mathrm{mode} = 0, the initial values for :math:m_0, :math:r_0 and :math:s_{{-\textit{j}}}, for :math:\textit{j} = 0,1,\ldots,p-1, used to initialize the smoothing.

If :math:\mathrm{itype} = 1, :math:\mathrm{init}[0] = m_0 and the remaining elements of :math:\mathrm{init} are not referenced.

If :math:\mathrm{itype} = 2 or :math:3, :math:\mathrm{init}[0] = m_0 and :math:\mathrm{init}[1] = r_0 and the remaining elements of :math:\mathrm{init} are not referenced.

If :math:\mathrm{itype} = 4 or :math:5, :math:\mathrm{init}[0] = m_0, :math:\mathrm{init}[1] = r_0 and :math:\mathrm{init}[2] to :math:\mathrm{init}[p+1] hold the values for :math:s_{{-\textit{j}}}, for :math:\textit{j} = 0,1,\ldots,p-1.

The remaining elements of :math:\mathrm{init} are not referenced.

**nf** : int
The number of forecasts required beyond the end of the series. Note, the one step ahead forecast is always produced.

**comm** : dict, communication object, modified in place
Communication structure for the reference vector.

If :math:\mathrm{mode} = 1, this argument must have been initialized by a prior call to uni_smooth_exp.

**Returns**
**init** : float, ndarray, shape :math:\left(:\right)
If :math:\mathrm{mode} \neq 1, the values used to initialize the smoothing. These are in the same order as described above.

**fv** : float, ndarray, shape :math:\left(\mathrm{nf}\right)
:math:\hat{y}_{{t+\textit{f}}}, for :math:\textit{f} = 1,2,\ldots,\mathrm{nf}, the next :math:\mathrm{nf} step forecasts. Where :math:t = n, if :math:\mathrm{mode} \neq 1, else :math:t is the total number of smoothed and forecast values already produced.

**fse** : float, ndarray, shape :math:\left(\mathrm{nf}\right)
The forecast standard errors for the values given in :math:\mathrm{fv}.

**yhat** : float, ndarray, shape :math:\left(n\right)
:math:\hat{y}_{{\textit{t}+1}}, for :math:\textit{t} = 1,2,\ldots,n, the one step ahead forecast values, with :math:\mathrm{yhat}[i-1] being the one step ahead forecast of :math:\mathrm{y}[i-2].

**res** : float, ndarray, shape :math:\left(n\right)
The residuals, :math:\left(y_{{\textit{t}+1}}-\hat{y}_{{\textit{t}+1}}\right), for :math:\textit{t} = 1,2,\ldots,n.

**dv** : float
The square root of the mean deviation.

The mean absolute deviation.

.. _g13am-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{mode} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mode} = 0, :math:1 or :math:2.

(errno :math:2)
On entry, :math:\mathrm{itype} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{itype} = 1, :math:2, :math:3, :math:4 or :math:5.

(errno :math:3)
On entry, :math:\mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{itype} = 4 or :math:5, :math:\mathrm{p} > 1.

(errno :math:4)
On entry, :math:\mathrm{param}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:0.0\leq \mathrm{param}[\langle\mathit{\boldsymbol{value}}\rangle]\leq 1.0.

(errno :math:4)
On entry, :math:\mathrm{param}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{itype} = 2, :math:0.0 < \mathrm{param}[\langle\mathit{\boldsymbol{value}}\rangle]\leq 1.0.

(errno :math:4)
On entry, :math:\mathrm{param}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{param}[\langle\mathit{\boldsymbol{value}}\rangle]\geq 0.0.

(errno :math:5)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 0.

(errno :math:6)
A multiplicative Holt--Winters model cannot be used with the supplied data.

(errno :math:7)
On entry, :math:\mathrm{k} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{mode} = 2 and :math:\mathrm{itype} = 4 or :math:5, :math:1\leq \mathrm{k}\leq n.

(errno :math:7)
On entry, :math:\mathrm{k} = \langle\mathit{\boldsymbol{value}}\rangle, :math:2\times \mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{mode} = 2 and :math:\mathrm{itype} = 4 or :math:5, :math:2\times \mathrm{p}\leq \mathrm{k}.

(errno :math:9)
On entry, :math:\mathrm{nf} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nf}\geq 0.

(errno :math:16)
On entry, the array :math:\mathrm{comm}\ ['r'] has not been initialized correctly.

.. _g13am-py2-py-notes:

**Notes**
Exponential smoothing is a relatively simple method of short term forecasting for a time series. uni_smooth_exp provides five types of exponential smoothing; single exponential, Brown's double exponential, linear Holt (also called double exponential smoothing in some references), additive Holt--Winters and multiplicative Holt--Winters.
The choice of smoothing method used depends on the characteristics of the time series.
If the mean of the series is only slowly changing then single exponential smoothing may be suitable.
If there is a trend in the time series, which itself may be slowly changing, then double exponential smoothing may be suitable.
If there is a seasonal component to the time series, e.g., daily or monthly data, then one of the two Holt--Winters methods may be suitable.

For a time series :math:y_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,n, the five smoothing functions are defined by the following:

Single Exponential Smoothing

.. math::
\begin{array}{ccc}m_t& = & \alpha y_t + \left(1-\alpha \right) m_{{t-1}} \\\hat{y}_{{t+f}}& = &m_t\\ \mathrm{var}\left(\hat{y}_{{t+f}}\right) & = & \mathrm{var}\left(\epsilon_t\right) \left(1+\left(f-1\right)\alpha^2\right) \end{array}

Brown Double Exponential Smoothing

.. math::
\begin{array}{ccc}m_t& = & \alpha y_t + \left(1-\alpha \right) m_{{t-1}} \\r_t& = & \alpha \left(m_t-m_{{t-1}}\right) + \left(1-\alpha \right) r_{{t-1}} \\ \hat{y}_{{t+f}} & = & m_t + \left(\left(f-1\right)+1/\alpha \right) r_t \\ \mathrm{var}\left(\hat{y}_{{t+f}}\right) & = & \mathrm{var}\left(\epsilon_t\right) \left(1+\sum_{0}^{f-1}{\left(2\alpha +\left(i-1\right)\alpha^2\right)^2}\right) \end{array}

Linear Holt Smoothing

.. math::
\begin{array}{ccc}m_t& = & \alpha y_t + \left(1-\alpha \right) \left(m_{{t-1}}+\phi r_{{t-1}}\right) \\r_t& = & \gamma \left(m_t-m_{{t-1}}\right) + \left(1-\gamma \right) \phi r_{{t-1}} \\ \hat{y}_{{t+f}} & = & m_t + \sum_{1}^{f}{\phi^i} r_t \\ \mathrm{var}\left(\hat{y}_{{t+f}}\right) & = & \mathrm{var}\left(\epsilon_t\right) \left(1+\sum_{1}^{{f-1}}{\left(\alpha +\frac{{\alpha \gamma \phi \left(\phi^i-1\right)}}{\left(\phi -1\right)}\right)^2}\right) \end{array}

.. math::
\begin{array}{ccc} m_t & = & \alpha \left(y_t-s_{{t-p}}\right) + \left(1-\alpha \right) \left(m_{{t-1}}+\phi r_{{t-1}}\right) \\r_t& = & \gamma \left(m_t-m_{{t-1}}\right) + \left(1-\gamma \right) \phi r_{{t-1}} \\s_t& = & \beta \left(y_t-m_t\right) + \left(1-\beta \right) s_{{t-p}} \\ \hat{y}_{{t+f}} & = & m_t + \left(\sum_{1}^{f}{\phi^i}r_t\right) + s_{{t-p}} \\ \mathrm{var}\left(\hat{y}_{{t+f}}\right) & = & \mathrm{var}\left(\epsilon_t\right) \left(1+\sum_{1}^{{f-1}}{\psi_i^2}\right) \\\psi_i & = & \left\{\begin{array}{cc}0&\text{if }i\geq f\\ \alpha + \frac{{\alpha \gamma \phi \left(\phi^i-1\right)}}{{\left(\phi -1\right)}} & \text{if } i mod p\neq 0 \\ \alpha + \frac{{\alpha \gamma \phi \left(\phi^i-1\right)}}{\left(\phi -1\right)} +\beta \left(1-\alpha \right) &\text{otherwise}\end{array}\right. \end{array}

Multiplicative Holt--Winters Smoothing

.. math::
\begin{array}{ccc}m_t& = & \alpha y_t / s_{{t-p}} + \left(1-\alpha \right) \left(m_{{t-1}}+\phi r_{{t-1}}\right) \\r_t& = & \gamma \left(m_t-m_{{t-1}}\right) + \left(1-\gamma \right) \phi r_{{t-1}} \\s_t& = & \beta y_t / m_t + \left(1-\beta \right) s_{{t-p}} \\ \hat{y}_{{t+f}} & = & \left(m_t+\sum_{1}^{f}{\phi^i}r_t\right) \times s_{{t-p}} \\ \mathrm{var}\left(\hat{y}_{{t+f}}\right) & = & {\mathrm{var}\left(\epsilon_t\right)\left(\sum_{0}^{\infty }{\sum_{0}^{{p-1}}{\left(\psi_{{j+ip}}\frac{{s_{{t+f}}}}{{s_{{t+f-j}}}}\right)^2}}\right)} \end{array}

and :math:\psi is defined as in the additive Holt--Winters smoothing,

where :math:m_t is the mean, :math:r_t is the trend and :math:s_t is the seasonal component at time :math:t with :math:p being the seasonal order.
The :math:f-step ahead forecasts are given by :math:\hat{y}_{{t+f}} and their variances by :math:\mathrm{var}\left(\hat{y}_{{t+f}}\right).
The term :math:\mathrm{var}\left(\epsilon_t\right) is estimated as the mean deviation.

The parameters, :math:\alpha, :math:\beta and :math:\gamma control the amount of smoothing.
The nearer these parameters are to one, the greater the emphasis on the current data point.
Generally these parameters take values in the range :math:0.1 to :math:0.3.
The linear Holt and two Holt--Winters smoothers include an additional parameter, :math:\phi, which acts as a trend dampener.
For :math:0.0 < \phi < 1.0 the trend is dampened and for :math:\phi > 1.0 the forecast function has an exponential trend, :math:\phi = 0.0 removes the trend term from the forecast function and :math:\phi = 1.0 does not dampen the trend.

For all methods, values for :math:\alpha, :math:\beta, :math:\gamma and :math:\psi can be chosen by trying different values and then visually comparing the results by plotting the fitted values along side the original data.
Alternatively, for single exponential smoothing a suitable value for :math:\alpha can be obtained by fitting an :math:\mathrm{ARIMA}\left(0,1,1\right) model (see :meth:multi_inputmod_estim).
For Brown's double exponential smoothing and linear Holt smoothing with no dampening, (i.e., :math:\phi = 1.0), suitable values for :math:\alpha and :math:\gamma can be obtained by fitting an :math:\mathrm{ARIMA}\left(0,2,2\right) model.
Similarly, the linear Holt method, with :math:\phi \neq 1.0, can be expressed as an :math:\mathrm{ARIMA}\left(1,2,2\right) model and the additive Holt--Winters, with no dampening, (:math:\phi = 1.0), can be expressed as a seasonal ARIMA model with order :math:p of the form :math:\mathrm{ARIMA}\left(0,1,p+1\right)\left(0,1,0\right).
There is no similar procedure for obtaining parameter values for the multiplicative Holt--Winters method, or the additive Holt--Winters method with :math:\phi \neq 1.0.
In these cases parameters could be selected by minimizing a measure of fit using one of the nonlinear optimization functions in submodule :mod:~naginterfaces.library.opt.

In addition to values for :math:\alpha, :math:\beta, :math:\gamma and :math:\psi, initial values, :math:m_0, :math:r_0 and :math:s_{{-\textit{j}}}, for :math:\textit{j} = 0,1,\ldots,p-1, are required to start the smoothing process.
You can either supply these or they can be calculated by uni_smooth_exp from the first :math:k observations.
For single exponential smoothing the mean of the observations is used to estimate :math:m_0.
For Brown double exponential smoothing and linear Holt smoothing, a simple linear regression is carried out with the series as the dependent variable and the sequence :math:1,2,\ldots,k as the independent variable.
The intercept is then used to estimate :math:m_0 and the slope to estimate :math:r_0.
In the case of the additive Holt--Winters method, the same regression is carried out, but a separate intercept is used for each of the :math:p seasonal groupings.
The slope gives an estimate for :math:r_0 and the mean of the :math:p intercepts is used as the estimate of :math:m_0.
The seasonal parameters :math:s_{{-\textit{j}}}, for :math:\textit{j} = 0,1,\ldots,p-1, are estimated as the :math:p intercepts -- :math:m_0.
A similar approach is adopted for the multiplicative Holt--Winter's method.

One step ahead forecasts, :math:\hat{y}_{{t+1}} are supplied along with the residuals computed as :math:\left(y_{{t+1}}-\hat{y}_{{t+1}}\right).
In addition, two measures of fit are provided.
The mean absolute deviation,

.. math::
\frac{1}{n}\sum_{1}^{n}{\left\lvert y_t-\hat{y}_t\right\rvert }

and the square root of the mean deviation

.. math::
\sqrt{\frac{1}{n}\sum_{1}^{n}{\left(y_t-\hat{y}_t\right)^2}}\text{.}

.. _g13am-py2-py-references:

**References**
Chatfield, C, 1980, The Analysis of Time Series, Chapman and Hall
"""
raise NotImplementedError

[docs]def uni_arima_resid(v, mr, m, par, ishow, io_manager=None):
r"""
uni_arima_resid is a diagnostic checking function suitable for use after fitting a Box--Jenkins ARMA model to a univariate time series using :meth:uni_arima_estim or :meth:uni_arima_estim_easy. The residual autocorrelation function is returned along with an estimate of its asymptotic standard errors and correlations.
Also, uni_arima_resid calculates the Box--Ljung portmanteau statistic and its significance level for testing model adequacy.

.. _g13as-py2-py-doc:

For full information please refer to the NAG Library document for g13as

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13asf.html

.. _g13as-py2-py-parameters:

**Parameters**
**v** : float, array-like, shape :math:\left(n\right)
:math:\mathrm{v}[\textit{t}-1] must contain an estimate of :math:\epsilon_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,n.

If uni_arima_resid is used following a call to :meth:uni_arima_estim then the actual argument :math:\mathrm{v} must be :math:{\textit{exr}}[{\textit{icount}}[0]] as returned by :meth:uni_arima_estim.

If uni_arima_resid is used following a call to :meth:uni_arima_estim_easy then the actual argument :math:\mathrm{v} must be :math:\textit{res} as returned by :meth:uni_arima_estim_easy.

**mr** : int, array-like, shape :math:\left(7\right)
The orders vector (:math:p, :math:d, :math:q, :math:P, :math:D, :math:Q, :math:s) as supplied to :meth:uni_arima_estim or :meth:uni_arima_estim_easy.

**m** : int
The value of :math:m, the number of residual autocorrelations to be computed. See Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13asf.html#fcomments2>__ for advice on the value of :math:\mathrm{m}.

**par** : float, array-like, shape :math:\left(\textit{npar}\right)
The parameter estimates in the order :math:\phi_1,\phi_2,\ldots,\phi_p, :math:\theta_1,\theta_2,\ldots,\theta_q, :math:\Phi_1,\Phi_2,\ldots,\Phi_P, :math:\Theta_1,\Theta_2,\ldots,\Theta_Q only.

**ishow** : int
Must be nonzero if the residual autocorrelations, their standard errors and the portmanteau statistics are to be printed and zero otherwise.

These quantities are available also as output variables in :math:\mathrm{r}, :math:\mathrm{rcm}, :math:\mathrm{chi}, :math:\mathrm{idf} and :math:\mathrm{siglev}.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**r** : float, ndarray, shape :math:\left(\mathrm{m}\right)
An estimate of the residual autocorrelation coefficient at lag :math:\textit{l}, for :math:\textit{l} = 1,2,\ldots,m. If :math:\mathrm{errno} = 3 on exit then all elements of :math:\mathrm{r} are set to zero.

**rcm** : float, ndarray, shape :math:\left(\mathrm{m}, \mathrm{m}\right)
The estimated standard errors and correlations of the elements in the array :math:\mathrm{r}. The correlation between :math:\mathrm{r}[i-1] and :math:\mathrm{r}[j-1] is returned as :math:\mathrm{rcm}[i-1,j-1] except that if :math:i = j then :math:\mathrm{rcm}[i-1,j-1] contains the standard error of :math:\mathrm{r}[i-1]. If on exit, :math:\mathrm{errno} >= 5, then all off-diagonal elements of :math:\mathrm{rcm} are set to zero and all diagonal elements are set to :math:1/\sqrt{n}.

**chi** : float
The value of the portmanteau statistic, :math:Q_{\left(m\right)}. If :math:\mathrm{errno} = 3 on exit then :math:\mathrm{chi} is returned as zero.

**idf** : int
The number of degrees of freedom of :math:\mathrm{chi}.

**siglev** : float
The significance level of :math:\mathrm{chi} based on :math:\mathrm{idf} degrees of freedom. If :math:\mathrm{errno} = 3 on exit, :math:\mathrm{siglev} is returned as one.

.. _g13as-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{m} < n.

(errno :math:1)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{m} > \textit{npar}.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npar} \neq 0 and :math:\textit{npar} = p+q+P+Q.

(errno :math:1)
On entry, :math:\mathrm{mr}[3] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{mr}[5] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mr}[3] = 0 and :math:\mathrm{mr}[5] = 0.

(errno :math:1)
On entry, :math:\mathrm{mr}[6] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mr}[6]\geq 0.

(errno :math:1)
On entry, :math:\mathrm{mr}[5] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mr}[5]\geq 0.

(errno :math:1)
On entry, :math:\mathrm{mr}[3] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mr}[3]\geq 0.

(errno :math:1)
On entry, :math:\mathrm{mr}[2] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mr}[2]\geq 0.

(errno :math:1)
On entry, :math:\mathrm{mr}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mr}[0]\geq 0.

(errno :math:2)
On entry, the seasonal moving average operator is non-invertible.

(errno :math:2)
On entry, the seasonal autoregressive operator is nonstationary.

(errno :math:2)
On entry, the non-seasonal moving average operator is non-invertible.

(errno :math:2)
On entry, the non-seasonal autoregressive operator is nonstationary.

(errno :math:4)
Excessive iterations needed to find zeros of determinental polynomials.

(errno :math:5)
On entry, one or more of the AR operators has a factor in common with one or more of the MA operators.

(errno :math:6)
The matrix :math:\mathrm{rcm} could not be computed because one of its diagonal elements was found to be non-positive.

**Warns**
**NagAlgorithmicWarning**
(errno :math:3)
On entry, the elements of :math:\mathrm{v} are nearly identical giving near-zero variance.

.. _g13as-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

Consider the univariate multiplicative autoregressive-moving average model

.. math::
\phi \left(B\right)\Phi \left(B^s\right)\left(W_t-\mu \right) = \theta \left(B\right)\Theta \left(B^s\right)\epsilon_t

where :math:W_t, for :math:\textit{t} = 1,2,\ldots,n, denotes a time series and :math:\epsilon_t, for :math:\textit{t} = 1,2,\ldots,n, is a residual series assumed to be normally distributed with zero mean and variance :math:\sigma^2 (:math:\text{} > 0).
The :math:\epsilon_t's are also assumed to be uncorrelated.
Here :math:\mu is the overall mean term, :math:s is the seasonal period and :math:B is the backward shift operator such that :math:B^rW_t = W_{{t-r}}.
The polynomials in (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13asf.html#eqn1>__ are defined as follows:

.. math::
\phi \left(B\right) = 1-\phi_1B-\phi_2B^2 - \cdots -\phi_pB^p

is the non-seasonal autoregressive (AR) operator;

.. math::
\theta \left(B\right) = 1-\theta_1B-\theta_2B^2 - \cdots -\theta_qB^q

is the non-seasonal moving average (MA) operator;

.. math::
\Phi \left(B^s\right) = 1-\Phi_1B^s-\Phi_2B^{{2s}} - \cdots -\Phi_PB^{{Ps}}

is the seasonal AR operator; and

.. math::
\Theta \left(B^s\right) = 1-\Theta_1B^s-\Theta_2B^{{2s}} - \cdots -\Theta_QB^{{Qs}}

is the seasonal MA operator.
The model (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13asf.html#eqn1>__ is assumed to be stationary, that is the zeros of :math:\phi \left(B\right) and :math:\Phi \left(B^s\right) are assumed to lie outside the unit circle.
The model (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13asf.html#eqn1>__ is also assumed to be invertible, that is the zeros of :math:\theta \left(B\right) and :math:\Theta \left(B^s\right) are assumed to lie outside the unit circle.
When both :math:\Phi \left(B^s\right) and :math:\Theta \left(B^s\right) are absent from the model, that is when :math:P = Q = 0, then the model is said to be non-seasonal.

The estimated residual autocorrelation coefficient at lag :math:l, :math:\hat{r}_l, is computed as:

.. math::
\hat{r}_l = \frac{{\sum_{{t = l+1}}^n\left(\hat{\epsilon }_{{t-l}}-\bar{\epsilon }\right)\left(\hat{\epsilon }_t-\bar{\epsilon }\right)}}{{\sum_{{t = 1}}^n\left(\hat{\epsilon }_t-\bar{\epsilon }\right)^2}}\text{, }\quad l = 1,2,\ldots

where :math:\hat{\epsilon }_t denotes an estimate of the :math:t\ th residual, :math:\epsilon_t, and :math:\bar{\epsilon } = \sum_{{t = 1}}^n\hat{\epsilon }_t/n.
A portmanteau statistic, :math:Q_{\left(m\right)}, is calculated from the formula (see Box and Ljung (1978)):

.. math::
Q_{\left(m\right)} = n\left(n+2\right)\sum_{{l = 1}}^m\hat{r}_l^2/\left(n-l\right)

where :math:m denotes the number of residual autocorrelations computed. (Advice on the choice of :math:m is given in Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13asf.html#fcomments2>__.) Under the hypothesis of model adequacy, :math:Q_{\left(m\right)} has an asymptotic :math:\chi^2-distribution on :math:m-p-q-P-Q degrees of freedom.
Let :math:\hat{r}^\mathrm{T} = \left(\hat{r}_1, \hat{r}_2, \ldots, \hat{r}_m\right) then the variance-covariance matrix of :math:\hat{r} is given by:

.. math::
\mathrm{Var}\left(\hat{r}\right) = \left[I_m-X\left(X^\mathrm{T}X\right)^{-1}X^\mathrm{T}\right]/n\text{.}

The construction of the matrix :math:X is discussed in McLeod (1978). (Note that the mean, :math:\mu, and the residual variance, :math:\sigma^2, play no part in calculating :math:\mathrm{Var}\left(\hat{r}\right) and, therefore, are not required as input to uni_arima_resid.)

**Note:** for additive models with fixed parameter values (i.e., fitted by :meth:multi_varma_estimate) :meth:multi_varma_diag should be used instead of uni_arima_resid.

.. _g13as-py2-py-references:

**References**
Box, G E P and Ljung, G M, 1978, On a measure of lack of fit in time series models, Biometrika (65), 297--303

McLeod, A I, 1978, On the distribution of the residual autocorrelations in Box--Jenkins models, J. Roy. Statist. Soc. Ser. B (40), 296--302
"""
raise NotImplementedError

[docs]def uni_means(z, m, rs):
r"""
uni_means calculates the range (or standard deviation) and the mean for groups of successive time series values.
It is intended for use in the construction of range-mean plots.

.. _g13au-py2-py-doc:

For full information please refer to the NAG Library document for g13au

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13auf.html

.. _g13au-py2-py-parameters:

**Parameters**
**z** : float, array-like, shape :math:\left(n\right)
:math:\mathrm{z}[\textit{t}-1] must contain the :math:\textit{t}\ th observation :math:Z_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,n.

**m** : int
:math:m, the group size.

**rs** : str, length 1
Indicates whether ranges or standard deviations are to be calculated.

:math:\mathrm{rs} = \texttt{'R'}

Ranges are calculated.

:math:\mathrm{rs} = \texttt{'S'}

Standard deviations are calculated.

**Returns**
**y** : float, ndarray, shape :math:\left(\mathrm{int}\left(\left(n/\mathrm{m}\right)\right)\right)
:math:\mathrm{y}[\textit{i}-1] contains the range or standard deviation, as determined by :math:\mathrm{rs}, of the :math:\textit{i}\ th group of observations, for :math:\textit{i} = 1,2,\ldots,k.

**mean** : float, ndarray, shape :math:\left(\mathrm{int}\left(\left(n/\mathrm{m}\right)\right)\right)
:math:\mathrm{mean}[\textit{i}-1] contains the mean of the :math:\textit{i}\ th group of observations, for :math:\textit{i} = 1,2,\ldots,k.

.. _g13au-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{ngrps} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ngrps} = \mathrm{int}\left({n/\mathrm{m}}\right).

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq \mathrm{m}.

(errno :math:1)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{m} \geq 2.

(errno :math:2)
On entry, :math:\mathrm{rs} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{rs} = \texttt{'R'} or :math:\texttt{'S'}.

.. _g13au-py2-py-notes:

**Notes**
Let :math:Z_1,Z_2,\ldots,Z_n denote :math:n successive observations in a time series.
The series may be divided into groups of :math:m successive values and for each group the range or standard deviation (depending on a user-supplied option) and the mean are calculated.
If :math:n is not a multiple of :math:m then groups of equal size :math:m are found starting from the end of the series of observations provided, and any remaining observations at the start of the series are ignored.
The number of groups used, :math:k, is the integer part of :math:n/m.
If you wish to ensure that no observations are ignored then the number of observations, :math:n, should be chosen so that :math:n is divisible by :math:m.

The mean, :math:M_i, the range, :math:R_i, and the standard deviation, :math:S_i, for the :math:i\ th group are defined as

.. math::
\begin{array}{c}M_i = \frac{1}{m}{\sum_{{j = 1}}^m}Z_{{l+m\left(i-1\right)+j}}\\\\R_i = \mathrm{max}_{{1\leq j\leq m}}\left\{Z_{{l+m\left(i-1\right)+j}}\right\}-\mathrm{min}_{{1\leq j\leq m}}\left\{Z_{{l+m\left(i-1\right)+j}}\right\}\end{array}

and

.. math::
S_i = \sqrt{\left(\frac{1}{{m-1}}\right)\sum_{{j = 1}}^m{\left(Z_{{l+m\left(i-1\right)+j}}-M_i\right)}^2}

where :math:l = n-km, the number of observations ignored.

For seasonal data it is recommended that :math:m should be equal to the seasonal period.
For non-seasonal data the recommended group size is :math:8.

A plot of range against mean or of standard deviation against mean is useful for finding a transformation of the series which makes the variance constant.
If the plot appears random or the range (or standard deviation) seems to be constant irrespective of the mean level then this suggests that no transformation of the time series is called for.
On the other hand an approximate linear relationship between range (or standard deviation) and mean would indicate that a log transformation is appropriate.
Further details may be found in either Jenkins (1979) and McLeod (1982).

You have the choice of whether to use the range or the standard deviation as a measure of variability.
If the group size is small they are both equally good but if the group size is fairly large (e.g., :math:m = 12 for monthly data) then the range may not be as good an estimate of variability as the standard deviation.

.. _g13au-py2-py-references:

**References**
Jenkins, G M, 1979, Practical Experiences with Modelling and Forecasting Time Series, GJP Publications, Lancaster

McLeod, G, 1982, Box--Jenkins in Practice. 1: Univariate Stochastic and Single Output Transfer Function/Noise Analysis, GJP Publications, Lancaster
"""
raise NotImplementedError

[docs]def uni_dickey_fuller_unit(ut_type, p, y):
r"""
uni_dickey_fuller_unit returns the (augmented) Dickey--Fuller unit root test.

.. _g13aw-py2-py-doc:

For full information please refer to the NAG Library document for g13aw

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13awf.html

.. _g13aw-py2-py-parameters:

**Parameters**
**ut_type** : int
The type of unit test for which the probability is required.

:math:\mathrm{ut\_type} = 1

A unit root test will be performed and :math:\tau returned.

:math:\mathrm{ut\_type} = 2

A unit root test with drift will be performed and :math:\tau_{\mu } returned.

:math:\mathrm{ut\_type} = 3

A unit root test with drift and deterministic time trend will be performed and :math:\tau_{\tau } returned.

**p** : int
:math:p, the degree of the autoregressive (AR) component of the Dickey--Fuller test statistic. When :math:p > 1 the test is usually referred to as the augmented Dickey--Fuller test.

**y** : float, array-like, shape :math:\left(n\right)
:math:y, the time series.

**Returns**
**ts** : float
The (augmented) Dickey--Fuller test statistic: :math:\tau when :math:\mathrm{ut\_type} = 1; :math:\tau_{\mu } when :math:\mathrm{ut\_type} = 2 or :math:\tau_{\tau } when :math:\mathrm{ut\_type} = 3.

.. _g13aw-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:11)
On entry, :math:\mathrm{ut\_type} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ut\_type} = 1, :math:2 or :math:3.

(errno :math:21)
On entry, :math:\mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{p} > 0.

(errno :math:31)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ut\_type} = 1, :math:n > 2\mathrm{p} if :math:\mathrm{ut\_type} = 2, :math:n > 2\mathrm{p}+1 if :math:\mathrm{ut\_type} = 3, :math:n > 2\mathrm{p}+2

**Warns**
**NagAlgorithmicWarning**
(errno :math:41)
On entry, the design matrix used in the estimation of :math:\beta_1 is not of full rank, this is usually due to all elements of the series being virtually identical. The returned statistic is, therefore, not unique and likely to be meaningless.

(errno :math:42)
standard error of the parameter estimate is zero, therefore, depending on the sign of the parameter estimate, a large positive or negative value has been returned.

.. _g13aw-py2-py-notes:

**Notes**
If the root of the characteristic equation for a time series is one then that series is said to have a unit root.
Such series are nonstationary. uni_dickey_fuller_unit returns one of three types of (augmented) Dickey--Fuller test statistic: :math:\tau, :math:\tau_{\mu } or :math:\tau_{\tau }, used to test for a unit root, a unit root with drift or a unit root with drift and a deterministic time trend, respectively.

To test whether a time series, :math:y_t, for :math:\textit{t} = 1,2,\ldots,n, has a unit root, the regression model

.. math::
\nabla y_t = \beta_1y_{{t-1}}+\sum_{{i = 1}}^{{p-1}}\delta_i\nabla y_{{t-i}}+\epsilon_t

is fitted and the test statistic :math:\tau constructed as

.. math::
\tau = \frac{\hat{\beta }_1}{\sigma_{{11}}}

where :math:\nabla is the difference operator, with :math:\nabla y_t = y_t-y_{{t-1}}, and where :math:\hat{\beta }_1 and :math:\sigma_{{11}} are the least squares estimate and associated standard error for :math:\beta_1 respectively.

To test for a unit root with drift the regression model

.. math::
\nabla y_t = \beta_1y_{{t-1}}+\sum_{{i = 1}}^{{p-1}}\delta_i\nabla y_{{t-i}}+\alpha +\epsilon_t

is fit and the test statistic :math:\tau_{\mu } constructed as

.. math::
\tau_{\mu } = \frac{\hat{\beta }_1}{\sigma_{{11}}}

To test for a unit root with drift and deterministic time trend the regression model

.. math::
\nabla y_t = \beta_1y_{{t-1}}+\sum_{{i = 1}}^{{p-1}}\delta_i\nabla y_{{t-i}}+\alpha +\beta_2t+\epsilon_t

is fit and the test statistic :math:\tau_{\tau } constructed as

.. math::
\tau_{\tau } = \frac{\hat{\beta }_1}{\sigma_{{11}}}

The distributions of the three test statistics; :math:\tau, :math:\tau_{\mu } and :math:\tau_{\tau }, are nonstandard.
An associated probability can be obtained from :meth:stat.prob_dickey_fuller_unit <naginterfaces.library.stat.prob_dickey_fuller_unit>.

.. _g13aw-py2-py-references:

**References**
Dickey, A D, 1976, Estimation and hypothesis testing in nonstationary time series, PhD Thesis, Iowa State University, Ames, Iowa

Dickey, A D and Fuller, W A, 1979, Distribution of the estimators for autoregressive time series with a unit root, J. Am. Stat. Assoc. (74 366), 427--431

--------
:meth:naginterfaces.library.examples.tsa.uni_dickey_fuller_unit_ex.main
"""
raise NotImplementedError

[docs]def multi_filter_arima(y, mr, par, cy=None):
r"""
multi_filter_arima filters a time series by an ARIMA model.

.. _g13ba-py2-py-doc:

For full information please refer to the NAG Library document for g13ba

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13baf.html

.. _g13ba-py2-py-parameters:

**Parameters**
**y** : float, array-like, shape :math:\left(\textit{ny}\right)
The :math:Q_y^{\prime } backforecasts, starting with backforecast at time :math:1-Q_y^{\prime } to backforecast at time :math:0, followed by the time series starting at time :math:1, where :math:Q_y^{\prime } = \mathrm{mr}[9]+\mathrm{mr}[12]\times \mathrm{mr}[13]. If there are no backforecasts, either because the ARIMA model for the time series is not known, or because it is known but has no moving average terms, then the time series starts at the beginning of :math:\mathrm{y}.

**mr** : int, array-like, shape :math:\left(\textit{nmr}\right)
The orders vector for the filtering model, followed by the orders vector for the ARIMA model for the time series if the latter is known. The orders appear in the standard sequence :math:\left(p, d, q, P, D, Q, s\right) as given in the G13 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13intro.html>__. If the ARIMA model for the time series is supplied, the function will assume that the first :math:Q_y^{\prime } values of the array :math:\mathrm{y} are backforecasts.

**par** : float, array-like, shape :math:\left(\textit{npar}\right)
The parameters of the filtering model, followed by the parameters of the ARIMA model for the time series, if supplied. Within each model the parameters are in the standard order of non-seasonal AR and MA followed by seasonal AR and MA.

**cy** : None or float, optional
If the ARIMA model is known (i.e., :math:\textit{nmr} = 14), :math:\mathrm{cy} must specify the constant term of the ARIMA model for the time series. If this model is not known (i.e., :math:\textit{nmr} = 7), :math:\mathrm{cy} is not used.

**Returns**
**b** : float, ndarray, shape :math:\left(:\right)
The filtered output series. If the ARIMA model for the time series was known, and hence :math:Q_y^{\prime } backforecasts were supplied in :math:\mathrm{y}, then :math:\mathrm{b} contains :math:Q_y^{\prime } 'filtered' backforecasts followed by the filtered series. Otherwise, the filtered series begins at the start of :math:\mathrm{b} just as the original series began at the start of :math:\mathrm{y}. In either case, if the value of the series at time :math:t is held in :math:\mathrm{y}[t-1], then the filtered value at time :math:t is held in :math:\mathrm{b}[t-1].

.. _g13ba-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{nmr} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nmr} = 7 or :math:14.

(errno :math:2)
On entry, the orders vector :math:\mathrm{mr} is invalid.

(errno :math:3)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npar} must be inconsistent with :math:\mathrm{mr}.

(errno :math:4)
On entry, :math:\textit{ny} = \langle\mathit{\boldsymbol{value}}\rangle and the minimum size :math:\text{required} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ny}\geq \mathrm{max}\left({1+Q_y^{\prime }}, \textit{npar}\right).

(errno :math:7)
The orders vector for the filtering model is invalid.

(errno :math:8)
The orders vector for the ARIMA model is invalid.

(errno :math:9)
The initial values of the filtered series are indeterminate for the given models.

.. _g13ba-py2-py-notes:

**Notes**
From a given series :math:y_1,y_2,\ldots,y_n, a new series :math:b_1,b_2,\ldots,b_n is calculated using a supplied (filtering) ARIMA model.
This model will be one which has previously been fitted to a series :math:x_t with residuals :math:a_t.
The equations defining :math:b_t in terms of :math:y_t are very similar to those by which :math:a_t is obtained from :math:x_t.
The only dissimilarity is that no constant correction is applied after differencing.
This is because the series :math:y_t is generally distinct from the series :math:x_t with which the model is associated, though :math:y_t may be related to :math:x_t.
Whilst it is appropriate to apply the ARIMA model to :math:y_t so as to preserve the same relationship between :math:b_t and :math:a_t as exists between :math:y_t and :math:x_t, the constant term in the ARIMA model is inappropriate for :math:y_t.
The consequence is that :math:b_t will not necessarily have zero mean.

The equations are precisely:

.. math::
w_t = \nabla^d\nabla_s^Dy_t\text{,}

the appropriate differencing of :math:y_t; both the seasonal and non-seasonal inverted autoregressive operations are then applied,

.. math::
u_t = w_t-\Phi_1w_{{t-s}} - \cdots -\Phi_Pw_{{t-s\times P}}

.. math::
v_t = u_t-\phi_1u_{{t-1}} - \cdots -\phi_pu_{{t-p}}

followed by the inverted moving average operations

.. math::
z_t = v_t+\Theta_1z_{{t-s}} + \cdots +\Theta_Qz_{{t-s\times Q}}

.. math::
b_t = z_t+\theta_1b_{{t-1}} + \cdots +\theta_qb_{{t-q}}\text{.}

Because the filtered series value :math:b_t depends on present and past values :math:y_t,y_{{t-1}},\ldots \text{}, there is a problem arising from ignorance of :math:y_0,y_{-1},\ldots \text{} which particularly affects calculation of the early values :math:b_1,b_2,\ldots \text{}, causing 'transient errors'.
The function allows two possibilities.

(i) The equations (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13baf.html#eqn1>__, (2) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13baf.html#eqn1>__ and (3) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13baf.html#eqn1>__ are applied from successively later time points so that all terms on their right-hand sides are known, with :math:v_t being defined for :math:t = \left(1+d+s\times D+s\times P\right),\ldots,n. Equations (4) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13baf.html#eqn4>__ and (5) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13baf.html#eqn4>__ are then applied over the same range, taking any values on the right-hand side associated with previous time points to be zero.

This procedure may still however result in unacceptably large transient errors in early values of :math:b_t.

(#) The unknown values :math:y_0,y_{-1},\ldots \text{} are estimated by backforecasting. This requires that an ARIMA model distinct from that which has been supplied for filtering, should have been previously fitted to :math:y_t.

For efficiency, you are asked to supply both this ARIMA model for :math:y_t and a limited number of backforecasts which are prefixed to the known values of :math:y_t.
Within the function further backforecasts of :math:y_t, and the series :math:w_t, :math:u_t, :math:v_t in (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13baf.html#eqn1>__, (2) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13baf.html#eqn1>__ and (3) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13baf.html#eqn1>__ are then easily calculated, and a set of linear equations solved for backforecasts of :math:z_t,b_t for use in (4) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13baf.html#eqn4>__ and (5) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13baf.html#eqn4>__ in the case that :math:q+Q > 0.

Even if the best model for :math:y_t is not available, a very approximate guess such as

.. math::
y_t = c+e_t

or

.. math::
\nabla y_t = e_t

can help to reduce the transients substantially.

The backforecasts which need to be prefixed to :math:y_t are of length :math:Q_y^{\prime } = q_y+s_y\times Q_y, where :math:q_y and :math:Q_y are the non-seasonal and seasonal moving average orders and :math:s_y the seasonal period for the ARIMA model of :math:y_t.
Thus you need not carry out the backforecasting exercise if :math:Q_y^{\prime } = 0.
Otherwise, the series :math:y_1,y_2,\ldots,y_n should be reversed to obtain :math:y_n,y_{{n-1}},\ldots,y_1 and :meth:uni_arima_forcecast should be used to forecast :math:Q_y^{\prime } values, :math:\hat{y}_0,\ldots,\hat{y}_{{1-Q_y^{\prime }}}.
The ARIMA model used is that fitted to :math:y_t (as a forward series) except that, if :math:d_y+D_y is odd, the constant should be changed in sign (to allow, for example, for the fact that a forward upward trend is a reversed downward trend).
The ARIMA model for :math:y_t supplied to the filtering function must however have the appropriate constant for the forward series.

The series :math:\hat{y}_{{1-Q_y^{\prime }}},\ldots,\hat{y}_0,y_1,\ldots,y_n is then supplied to the function, and a corresponding set of values returned for :math:b_t.

.. _g13ba-py2-py-references:

**References**
Box, G E P and Jenkins, G M, 1976, Time Series Analysis: Forecasting and Control, (Revised Edition), Holden--Day
"""
raise NotImplementedError

[docs]def multi_filter_transf(y, mr, par, cy=None):
r"""
multi_filter_transf filters a time series by a transfer function model.

.. _g13bb-py2-py-doc:

For full information please refer to the NAG Library document for g13bb

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13bbf.html

.. _g13bb-py2-py-parameters:

**Parameters**
**y** : float, array-like, shape :math:\left(\textit{ny}\right)
The :math:Q_y^{\prime } backforecasts starting with backforecast at time :math:1-Q_y^{\prime } to backforecast at time :math:0 followed by the time series starting at time :math:1, where :math:Q_y^{\prime } = \mathrm{mr}[5]+\mathrm{mr}[8]\times \mathrm{mr}[9]. If there are no backforecasts either because the ARIMA model for the time series is not known or because it is known but has no moving average terms, then the time series starts at the beginning of :math:\mathrm{y}.

**mr** : int, array-like, shape :math:\left(\textit{nmr}\right)
The orders vector for the filtering transfer function model followed by the orders vector for the ARIMA model for the time series if the latter is known. The transfer function model orders appear in the standard form :math:\left(b, q, p\right) as given in the G13 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13intro.html>__. Note that if the ARIMA model for the time series is supplied then the function will assume that the first :math:Q_y^{\prime } values of the array :math:\mathrm{y} are backforecasts.

**par** : float, array-like, shape :math:\left(\textit{npar}\right)
The parameters of the filtering transfer function model followed by the parameters of the ARIMA model for the time series. In the transfer function model the parameters are in the standard order of MA-like followed by AR-like operator parameters. In the ARIMA model the parameters are in the standard order of non-seasonal AR and MA followed by seasonal AR and MA.

**cy** : None or float, optional
If the ARIMA model is known (i.e., :math:\textit{nmr} = 10), :math:\mathrm{cy} must specify the constant term of the ARIMA model for the time series. If this model is not known (i.e., :math:\textit{nmr} = 3) then :math:\mathrm{cy} is not used.

**Returns**
**b** : float, ndarray, shape :math:\left(:\right)
The filtered output series. If the ARIMA model for the time series was known, and hence :math:Q_y^{\prime } backforecasts were supplied in :math:\mathrm{y}, then :math:\mathrm{b} contains :math:Q_y^{\prime } 'filtered' backforecasts followed by the filtered series. Otherwise, the filtered series begins at the start of :math:\mathrm{b} just as the original series began at the start of :math:\mathrm{y}. In either case, if the value of the series at time :math:t is held in :math:\mathrm{y}[t-1], then the filtered value at time :math:t is held in :math:\mathrm{b}[t-1].

.. _g13bb-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{nb} = \langle\mathit{\boldsymbol{value}}\rangle and the minimum size :math:\text{required} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\textit{arimas} is not **None** then :math:\textit{nb}\geq \mathrm{max}\left(b, p, q\right), otherwise :math:\textit{nb}\geq \textit{ny}.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npar} must be inconsistent with :math:\mathrm{mr}.

(errno :math:1)
On entry, :math:\mathrm{mr}[6] = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{mr}[7] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{mr}[8] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mr}[6]+\mathrm{mr}[7]+\mathrm{mr}[8]\neq 0.

(errno :math:1)
On entry, :math:\mathrm{mr}[6] = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{mr}[7] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{mr}[8] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mr}[6]+\mathrm{mr}[7]+\mathrm{mr}[8] = 0.

(errno :math:1)
On entry, :math:\mathrm{mr}[9] = 1.

Constraint: :math:\mathrm{mr}[9]\neq 1.

(errno :math:1)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{mr}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mr}[i-1]\geq 0.

(errno :math:1)
On entry, :math:\textit{nmr} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nmr} = 3 or :math:10.

(errno :math:2)
A supplied model has invalid parameters.

(errno :math:3)
The supplied time series is too short.

(errno :math:4)
The matrix used to solve for starting values for MA is singular.

.. _g13bb-py2-py-notes:

**Notes**
From a given series :math:y_1,y_2,\ldots,y_n a new series :math:b_1,b_2,\ldots,b_n is calculated using a supplied (filtering) transfer function model according to the equation

.. math::
b_t = \delta_1b_{{t-1}}+\delta_2b_{{t-2}} + \cdots +\delta_pb_{{t-p}}+\omega_0y_{{t-b}}-\omega_1y_{{t-b-1}} - \cdots -\omega_qy_{{t-b-q}}\text{.}

As in the use of :meth:multi_filter_arima, large transient errors may arise in the early values of :math:b_t due to ignorance of :math:y_t for :math:t < 0, and two possibilities are allowed.

(i) The equation (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13bbf.html#eqn1>__ is applied from :math:t = 1+b+q,\ldots,n so all terms in :math:y_t on the right-hand side of (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13bbf.html#eqn1>__ are known, the unknown set of values :math:b_t for :math:t = b+q,\ldots,b+q+1-p being taken as zero.

(#) The unknown values of :math:y_t for :math:t\leq 0 are estimated by backforecasting exactly as for :meth:multi_filter_arima.

.. _g13bb-py2-py-references:

**References**
Box, G E P and Jenkins, G M, 1976, Time Series Analysis: Forecasting and Control, (Revised Edition), Holden--Day
"""
raise NotImplementedError

[docs]def multi_xcorr(x, y, nl):
r"""
multi_xcorr calculates cross-correlations between two time series.

.. _g13bc-py2-py-doc:

For full information please refer to the NAG Library document for g13bc

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13bcf.html

.. _g13bc-py2-py-parameters:

**Parameters**
**x** : float, array-like, shape :math:\left(\textit{nxy}\right)
The :math:n values of the :math:x series.

**y** : float, array-like, shape :math:\left(\textit{nxy}\right)
The :math:n values of the :math:y series.

**nl** : int
:math:L, the maximum lag for calculating cross-correlations.

**Returns**
**s** : float
The ratio of the standard deviation of the :math:y series to the standard deviation of the :math:x series, :math:s_y/s_x.

**r0** : float
The cross-correlation between the :math:x and :math:y series at lag zero.

**r** : float, ndarray, shape :math:\left(\mathrm{nl}\right)
:math:\mathrm{r}[\textit{l}-1] contains the cross-correlations between the :math:x and :math:y series at lags :math:L, :math:r_{{xy}}\left(\textit{l}\right), for :math:\textit{l} = 1,2,\ldots,L.

**stat** : float
The statistic for testing for absence of cross-correlation.

.. _g13bc-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{nxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nxy} > 1.

(errno :math:1)
On entry, :math:\mathrm{nl} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{nxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{nl} < \textit{nxy}.

(errno :math:1)
On entry, :math:\mathrm{nl} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nl}\geq 1.

(errno :math:2)
One or both of the :math:x and :math:y series have zero variance.

.. _g13bc-py2-py-notes:

**Notes**
Given two series :math:x_1,x_2,\ldots,x_n and :math:y_1,y_2,\ldots,y_n the function calculates the cross-correlations between :math:x_t and lagged values of :math:y_t:

.. math::
r_{{xy}}\left(l\right) = \frac{{\sum_{{t = 1}}^{{n-l}}\left(x_t-\bar{x}\right)\left(y_{{t+l}}-\bar{y}\right)}}{{ns_xs_y}}\text{, }\quad l = 0,1,\ldots,L

where

.. math::
\bar{x} = \frac{{\sum_{{t = 1}}^nx_t}}{n}

.. math::
s_x^2 = \frac{{\sum_{{t = 1}}^n\left(x_t-\bar{x}\right)^2}}{n}

and similarly for :math:y.

The ratio of standard deviations :math:s_y/s_x is also returned, and a portmanteau statistic is calculated:

.. math::
\mathrm{stat} = n\sum_{{l = 1}}^Lr_{{xy}}\left(l\right)^2\text{.}

Provided :math:n is large, :math:L much less than :math:n, and both :math:x_t,y_t are samples of series whose true autocorrelation functions are zero, then, under the null hypothesis that the true cross-correlations between the series are zero, :math:\mathrm{stat} has a :math:\chi^2-distribution with :math:L degrees of freedom.
Values of :math:\mathrm{stat} in the upper tail of this distribution provide evidence against the null hypothesis.

.. _g13bc-py2-py-references:

**References**
Box, G E P and Jenkins, G M, 1976, Time Series Analysis: Forecasting and Control, (Revised Edition), Holden--Day
"""
raise NotImplementedError

[docs]def multi_transf_prelim(r0, r, nna, s):
r"""
multi_transf_prelim calculates preliminary estimates of the parameters of a transfer function model.

.. _g13bd-py2-py-doc:

For full information please refer to the NAG Library document for g13bd

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13bdf.html

.. _g13bd-py2-py-parameters:

**Parameters**
**r0** : float
The cross-correlation between the two series at lag :math:0, :math:r_{{xy}}\left(0\right).

**r** : float, array-like, shape :math:\left(\textit{nl}\right)
The cross-correlations between the two series at lags :math:1 to :math:L, :math:r_{{xy}}\left(\textit{l}\right), for :math:\textit{l} = 1,2,\ldots,L.

**nna** : int, array-like, shape :math:\left(3\right)
The transfer function model orders in the standard form :math:b,q,p (i.e., delay time, number of moving-average MA-like followed by number of autoregressive AR-like parameters).

**s** : float
The ratio of the standard deviation of the :math:y series to that of the :math:x series, :math:s_y/s_x.

**Returns**
**wds** : float, ndarray, shape :math:\left(:\right)
The preliminary estimates of the parameters of the transfer function model in the order of :math:q+1 MA-like parameters followed by the :math:p AR-like parameters. If the estimation of either type of parameter fails then these arguments are set to :math:0.0.

**isf** : int, ndarray, shape :math:\left(2\right)
Indicators of the success of the estimation of MA-like and AR-like parameters respectively. A value :math:0 indicates that there are no parameters of that type to be estimated. A value of :math:1 or :math:-1 indicates that there are parameters of that type in the model and the estimation of that type has been successful or unsuccessful respectively. Note that there is always at least one MA-like parameter in the model.

.. _g13bd-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{nwds} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{nna}[1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nna}[2] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nwds} = \mathrm{nna}[1]+\mathrm{nna}[2]+1.

(errno :math:1)
On entry, :math:\mathrm{s} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{s} > 0.0.

(errno :math:1)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{r}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:{-1.0}\leq \mathrm{r}[\textit{i}]\leq 1.0.

(errno :math:1)
On entry, :math:\mathrm{r0} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:{-1.0}\leq \mathrm{r0}\leq 1.0.

(errno :math:1)
On entry, :math:\textit{nl} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{nna}[0] = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{nna}[1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nna}[2] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nl}\geq \mathrm{max}\left({\mathrm{nna}[0]+\mathrm{nna}[1]+\mathrm{nna}[2]}, 1\right).

(errno :math:1)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nna}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nna}[i-1]\geq 0.

.. _g13bd-py2-py-notes:

**Notes**
multi_transf_prelim calculates estimates of parameters :math:\delta_1,\delta_2,\ldots,\delta_p, :math:\omega_0,\omega_1,\ldots,\omega_q in the transfer function model

.. math::
y_t = \delta_1y_{{t-1}}+\delta_2y_{{t-2}} + \cdots +\delta_py_{{t-p}}+\omega_0x_{{t-b}}-\omega_1x_{{t-b-1}} - \cdots -\omega_qx_{{t-b-q}}

given cross-correlations between the series :math:x_t and lagged values of :math:y_t:

.. math::

and the ratio of standard deviations :math:s_y/s_x, as supplied by :meth:multi_xcorr.

It is assumed that the series :math:x_t used to calculate the cross-correlations is a sample from a time series with true autocorrelations of zero.
Otherwise the cross-correlations between the series :math:b_t and :math:a_t, as defined in the description of :meth:multi_filter_arima, should be used in place of those between :math:y_t and :math:x_t.

The estimates are obtained by solving for :math:\delta_1,\delta_2,\ldots,\delta_p the equations

.. math::
r_{{xy}}\left(b+q+j\right) = \delta_1r_{{xy}}\left(b+q+j-1\right)+ \cdots +\delta_pr_{{xy}}\left(b+q+j-p\right)\text{, }\quad j = 1,2,\ldots,p

then calculating

.. math::
\omega_i = \pm \left(s_y/s_x\right)\left[r_{{xy}}\left(b+i\right)-\delta_1r_{{xy}}\left(b+i-1\right)- \cdots -\delta_pr_{{xy}}\left(b+i-p\right)\right]\text{, }\quad i = 0,1,\ldots,q

where the ':math:+' is used for :math:\omega_0 and ':math:-' for :math:\omega_i, :math:i > 0.

Any value of :math:r_{{xy}}\left(l\right) arising in these equations for :math:l < b is taken as zero.
The parameters :math:\delta_1,\delta_2,\ldots,\delta_p are checked as to whether they satisfy the stability criterion.

.. _g13bd-py2-py-references:

**References**
Box, G E P and Jenkins, G M, 1976, Time Series Analysis: Forecasting and Control, (Revised Edition), Holden--Day
"""
raise NotImplementedError

[docs]def multi_inputmod_estim(mr, mt, para, xxy, kfc=1, kef=2, nit=1000, zsp=None, kpriv=0, io_manager=None):
r"""
multi_inputmod_estim 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, multi_inputmod_estim fits a univariate ARIMA model.

.. _g13be-py2-py-doc:

For full information please refer to the NAG Library document for g13be

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13bef.html

.. _g13be-py2-py-parameters:

**Parameters**
**mr** : int, array-like, shape :math:\left(7\right)
The orders vector :math:\left(p, d, q, P, D, Q, s\right) of the ARIMA model for the output noise component.

:math:p, :math:q, :math:P and :math:Q refer respectively to the number of autoregressive :math:\left(\phi \right), moving average :math:\left(\theta \right), seasonal autoregressive :math:\left(\Phi \right) and seasonal moving average :math:\left(\Theta \right) parameters.

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

**mt** : int, array-like, shape :math:\left(4, \textit{nser}\right)
The transfer function model orders :math:b, :math:p and :math:q of each of the input series. The order parameters for input series :math:i are held in column :math:i. Row :math:1 holds the value :math:b_i, row 2 holds the value :math:q_i and row 3 holds the value :math:p_i. For a simple input, :math:b_i = q_i = p_i = 0.

Row 4 holds the value :math:r_i, where :math:r_i = 1 for a simple input, :math:r_i = 2 for a transfer function input for which no allowance is to be made for pre-observation period effects, and :math:r_i = 3 for a transfer function input for which pre-observation period effects will be treated by estimation of appropriate nuisance parameters.

When :math:r_i = 1, any nonzero contents of rows 1, 2, and 3 of column :math:i are ignored.

**para** : float, array-like, shape :math:\left(\textit{npara}\right)
Initial values of the multi-input model parameters. These are in order, firstly the ARIMA model parameters: :math:p values of :math:\phi parameters, :math:q values of :math:\theta parameters, :math:P values of :math:\Phi parameters and :math:Q values of :math:\Theta parameters. These are followed by initial values of the transfer function model parameters :math:\omega_0,\omega_1,\ldots,\omega_{q_1}, :math:\delta_1,\delta_2,\ldots,\delta_{p_1} for the first of any input series and similarly for each subsequent input series. The final component of :math:\mathrm{para} is the initial value of the constant :math:c, whether it is fixed or is to be estimated.

**xxy** : float, array-like, shape :math:\left(\textit{nxxy}, \textit{nser}\right)
The columns of :math:\mathrm{xxy} must contain the :math:\textit{nxxy} original, undifferenced values of each of the input series and the output series :math:x_t in that order.

**kfc** : int, optional
Must be set to :math:0 if the constant :math:c is to remain fixed at its initial value, and :math:1 if it is to be estimated.

**kef** : int, optional
Indicates the likelihood option.

:math:\mathrm{kef} = 1

Gives least squares.

:math:\mathrm{kef} = 2

Gives exact likelihood.

:math:\mathrm{kef} = 3

Gives marginal likelihood.

**nit** : int, optional
The maximum required number of iterations.

:math:\mathrm{nit} = 0

No change is made to any of the model parameters in array :math:\mathrm{para} except that the constant :math:c (if :math:\mathrm{kfc} = 1) and any :math:\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 pre-observation period effects for transfer function inputs.)

**zsp** : None or float, array-like, shape :math:\left(4\right), optional
If :math:\mathrm{zsp}\text{ is not }\mathbf{None}, then :math:\mathrm{zsp} must contain the four values used to control the strategy of the search procedure.

:math:\mathrm{zsp}[0]

Contains :math:\alpha, the value used to constrain the magnitude of the search procedure steps.

:math:\mathrm{zsp}[1]

Contains :math:\beta, the multiplier which regulates the value of :math:\alpha.

:math:\mathrm{zsp}[2]

Contains :math:\delta, the value of the stationarity and invertibility test tolerance factor.

:math:\mathrm{zsp}[3]

Contains :math:\gamma, the value of the convergence criterion.

If :math:\mathrm{zsp}\text{ is }\mathbf{None} before entry, default values of :math:\mathrm{zsp} are supplied by the function.

These are :math:0.01, :math:10.0, :math:1000.0 and :math:\mathrm{max}\left(100\times \text{machine precision},0.0000001\right), respectively.

**kpriv** : int, optional
Must not be set to :math: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 (:math:\mathrm{itc}), the residual sum of squares (:math:\mathrm{s}), the objective function (:math:\mathrm{d}) and a description and value for each of the parameters in the :math:\mathrm{para} array. The descriptions are PHI for :math:\phi, THETA for :math:\theta, SPHI for :math:\Phi, STHETA for :math:\Theta, OMEGA/SI for :math:\omega in a simple input, OMEGA for :math:\omega in a transfer function input, DELTA for :math:\delta and CONSTANT for :math:c. In addition SERIES 1, SERIES 2, etc. indicate the input series relevant to the OMEGA and DELTA parameters.

:math:\mathrm{kpriv} must be set to :math:0 if the print-out of the above information is not required.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**para** : float, ndarray, shape :math:\left(\textit{npara}\right)
The latest values of the estimates of these parameters.

**xxy** : float, ndarray, shape :math:\left(\textit{nxxy}, \textit{nser}\right)
If :math:\textit{kzef} = 0, :math:\mathrm{xxy} remains unchanged on exit.

If :math:\textit{kzef}\neq 0, the columns of :math:\mathrm{xxy} hold the corresponding values of the input component series :math:z_t in place of :math:x_t and the output noise component :math:n_t in place of :math:y_t, in that order.

**zsp** : float, ndarray, shape :math:\left(4\right)
Contains the values, default or otherwise, used by the function.

**itc** : int
The number of iterations carried out.

:math:\mathrm{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 :math:\omega and for the constant :math:c (if :math:\mathrm{kfc} = 1). This value of :math:\mathrm{itc} usually indicates a failure in a consequent step of estimating transfer function input pre-observation period nuisance parameters.

:math:\mathrm{itc} = 0

Indicates that estimates have been obtained up to this point for the constant :math:c (if :math:\mathrm{kfc} = 1), for simple input coefficients :math:\omega and for the nuisance parameters relating to the backforecasts and to transfer function input pre-observation period effects.

**sd** : float, ndarray, shape :math:\left(\textit{npara}\right)
The :math:\textit{npara} values of the standard deviations corresponding to each of the parameters in :math:\mathrm{para}. When the constant is fixed its standard deviation is returned as zero. When the values of :math:\mathrm{para} are valid, the values of :math:\mathrm{sd} are usually also valid. However, if an exit value of :math:\mathrm{errno} = 3, 8 or 10, then the contents of :math:\mathrm{sd} will be indeterminate.

**cm** : float, ndarray, shape :math:\left(\textit{npara}, \textit{npara}\right)
The first :math:\textit{npara} rows and columns of :math:\mathrm{cm} contain the correlation coefficients relating to each pair of parameters in :math:\mathrm{para}. All coefficients relating to the constant will be zero if the constant is fixed. The contents of :math:\mathrm{cm} will be indeterminate under the same conditions as :math:\mathrm{sd}.

**s** : float
The residual sum of squares, :math:S, at the latest set of valid parameter estimates.

**d** : float
The objective function, :math:D, at the latest set of valid parameter estimates.

**ndf** : int
The number of degrees of freedom associated with :math:S.

**res** : float, ndarray, shape :math:\left(\textit{nxxy}\right)
The values of the residuals relating to the differenced values of the output series. The remainder of the first :math:\textit{nxxy} terms in the array will be zero.

**sttf** : float, ndarray, shape :math:\left(\mathrm{nsttf}\right)
The :math:\mathrm{nsttf} values of the state set array.

**nsttf** : int
The number of values in the state set array :math:\mathrm{sttf}.

.. _g13be-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{nser} = 1 and there are no parameters in the model.

(errno :math:1)
On entry, :math:\textit{nser} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nser}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{nit} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nit}\geq 0.

(errno :math:1)
On entry, :math:\mathrm{kef} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{kef} = 1, :math:2 or :math:3.

(errno :math:1)
On entry, :math:\mathrm{kfc} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{kfc} = 0 or :math:1.

(errno :math:2)
On entry, :math:\mathrm{ndf} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ndf} > 0.

(errno :math:2)
On entry, :math:\textit{npara} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{kfc} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npara}, :math:\mathrm{kfc}, :math:\mathrm{mr} and :math:\mathrm{mt} must be consistent.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{mt}[3,i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mt}[3,i-1] = 1, :math:2 or :math:3.

(errno :math:2)
The orders vector :math:\mathrm{mr} is invalid.

(errno :math:3)
On entry, or during execution, one or more sets of delta parameters do not satisfy the stationarity or invertibility conditions.

(errno :math:4)
On entry, :math:\mathrm{zsp}[3] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:0.0\leq \mathrm{zsp}[3] < 1.0.

(errno :math:4)
On entry, :math:\mathrm{zsp}[2] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{zsp}[2]\geq 1.0.

(errno :math:4)
On entry, :math:\mathrm{zsp}[1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{zsp}[1] > 1.0.

(errno :math:4)
On entry, :math:\mathrm{zsp}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{zsp}[0] > 0.0.

(errno :math:8)
Unable to calculate the latest parameter estimates.

(errno :math:9)
Failure in inversion of second derivative matrix.

(errno :math:10)
On entry, or during execution, one or more sets of ARIMA parameters do not satisfy the stationarity or invertibility conditions.

(errno :math:11)
On entry, :math:\textit{isttf} too small.

Constraint: :math:\textit{isttf}\geq \left(P\times s\right)+d+\left(D\times s\right)+q+\mathrm{max}\left(p, {Q\times s}\right)+\textit{ncg}.

(errno :math:12)
The routine has failed to converge after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:13)
On entry, :math:\mathrm{nit} = \langle\mathit{\boldsymbol{value}}\rangle.

:math:\textit{isttf} is too small and the process failed to converge after :math:\mathrm{nit} iterations.

.. _g13be-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

**The Multi-input Model**

The output series :math:y_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,n, is assumed to be the sum of (unobserved) components :math:z_{{i,t}} which are due respectively to the inputs :math:x_{{\textit{i},t}}, for :math:\textit{i} = 1,2,\ldots,m.

Thus :math:y_t = z_{{1,t}} + \cdots +z_{{m,t}}+n_t where :math:n_t is the error, or output noise component.

A typical component :math:z_t may be either

(a) a simple regression component, :math:z_t = \omega x_t (here :math: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 :math:x_t by

.. math::
z_t = \delta_1z_{{t-1}}+\delta_2z_{{t-2}} + \cdots +\delta_pz_{{t-p}}+\omega_0x_{{t-b}}-\omega_1x_{{t-b-1}} - \cdots -\omega_qx_{{t-b-q}}\text{.}

The noise :math:n_t is assumed to follow a (possibly seasonal) ARIMA model, i.e., may be represented in terms of an uncorrelated series, :math:a_t, by the hierarchy of equations

(i) :math:\nabla^d\nabla_s^Dn_t = c+w_t

(#) :math:w_t = \Phi_1w_{{t-s}}+\Phi_2w_{{t-2\times s}} + \cdots +\Phi_Pw_{{t-P\times s}}+e_t-\Theta_1e_{{t-s}}-\Theta_2e_{{t-2\times s}} - \cdots -\Theta_Qe_{{t-Q\times s}}

(#) :math:e_t = \phi_1e_{{t-1}}+\phi_2e_{{t-2}} + \cdots +\phi_pe_{{t-p}}+a_t-\theta_1a_{{t-1}}-\theta_2a_{{t-2}} - \cdots -\theta_qa_{{t-q}}

as outlined in :ref:Notes for uni_arima_estim <g13ae-py2-py-notes>.

**Note:** the orders :math:p,q appearing in each of the transfer function models and the ARIMA model are not necessarily the same; :math:\nabla^d\nabla_s^Dn_t is the result of applying non-seasonal differencing of order :math:d and seasonal differencing of seasonality :math:s and order :math:D to the series :math:n_t: the differenced series is then of length :math:N = n-d-s\times D; the constant term parameter :math: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 :math:a_t is a sequence of independent Normal variates having mean :math:0 and variance :math:\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 pre-period terms :math:z_0,z_{-1},\ldots,z_{{1-p}} and :math:x_0,x_{-1},\ldots,x_{{1-b-q}} which are in theory necessary to re-create the component series :math:z_1,z_2,\ldots,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 :math:z_1,z_2,\ldots \text{}, you are advised first to correct the input series :math:x_t by subtracting from all the terms a suitable constant to make the early values :math:x_1,x_2,\ldots \text{}, close to zero.
The series mean :math:\bar{x} is one possibility, but for a series with strong trend the constant might be simply :math: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 :math:p = 1 and :math:b = q = 0, it is equivalent to fitting to the data a decaying geometric curve of the form :math:A\delta^{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,, along with the other inputs, this being the form of the transient.
If the output :math: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 :math:\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 :math:\mathrm{max}\left(p, {b+q}\right), with a corresponding loss of degrees of freedom in the residuals.
If you align the input :math:x_t with the output by using in its place the shifted series :math:x_{{t-b}}, then setting :math: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.

**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 :math:z_{{1,t}},z_{{2,t}},\ldots,z_{{m,t}} as the responses to the input series :math:x_{{1,t}},x_{{2,t}}\ldots,x_{{m,t}} using the equations \(a) or \(b) above,

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

.. math::
n_t = y_t-\left(z_{{1,t}}+z_{{2,t}} + \cdots +z_{{m,t}}\right)\text{,}

(#) the residual series :math:a_t from :math:n_t 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 :math:n_t and other terms in the equations regenerating :math:a_t. This is identical to the treatment given in :ref:Notes for uni_arima_estim <g13ae-py2-py-notes>, and leads to a criterion which is a sum of squares function :math:S, of the residuals :math:a_t. It may be shown that the finite algorithm presented there is equivalent to taking the infinite set of past values :math:n_0,n_{-1},n_{-2},\ldots, as (linear) nuisance parameters. There is no loss of degrees of freedom however, because the sum of squares function :math:S may be expressed as including the corresponding set of past residuals; see page 273 of Box and Jenkins (1976), who prove that

.. math::
S = \sum_{{-\infty }}^na_t^2\text{.}

The function :math: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 :math: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 :math:n_1,n_2,\ldots,n_n requires theoretical integration over the range of the past set.
Fortunately this yields a criterion of the form :math:D = M\times S (whose minimization is equivalent to maximizing the exact likelihood of the data), where :math:S is exactly as before, and the multiplier :math:M is a function calculated from the ARIMA model parameters.
The value of :math:M is always :math:\text{}\geq 1, and :math:M tends to :math:1 for any fixed parameter set as the sample size :math:n tends to :math:\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 :math:n_0,n_{-1},n_{-2},\ldots \text{}.
These coefficients, together with the constant term :math:c used to represent the mean of :math:w_t, are in effect treated as random variables with highly dispersed distributions.
This leads to the criterion :math:D = M\times S again, but with a different value of :math:M which now depends on the simple input series values :math: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.

multi_inputmod_estim 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 :math: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 :math:\alpha, which is increased or decreased by a factor :math:\beta at successive iterations, depending on the progress of the minimization.
Convergence is deemed to have occurred if the fractional reduction of :math:D in successive iterations is less than a value :math:\gamma, while :math:\alpha < 1.

Certain model parameters (in fact all excluding the :math:\omega\ s) are subject to stability constraints which are checked throughout to within a specified tolerance multiple :math:\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 :math: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 :math: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.

**Further Results**

The residual variance is taken as :math:\textit{erv} = \frac{S}{{\textit{df}}}, where :math:\textit{df} = N-\text{}\ (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 :math:{\textit{df}}, as is the constant if it is estimated.

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

.. math::
\textit{erv}\times H^{-1}

where :math: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 :math:a_t is available upon completion of the iterations over the range :math:t = 1+d+s\times D,\ldots,n corresponding to the differenced noise series :math:w_t.

Because of the algorithm used for backforecasting, these are only true residuals for :math: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 :math:z_{{1,t}},\ldots,z_{{m,t}} and :math: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 :math:t = n+1,n+2,\ldots \text{} using :meth:multi_inputmod_forecast_state, it is not necessary to use the whole set of observations :math:y_t and :math:x_{{1,\textit{t}}},x_{{2,\textit{t}}},\ldots,x_{{m,\textit{t}}}, for :math:\textit{t} = 1,2,\ldots,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 :math:n+1-k for :math:k = 1 up to the maximum lag associated with that series in the equations.
Note that \(i) implicitly includes past values of :math:n_t and intermediate differences of :math:n_t such as :math:\nabla^{{d-1}}\nabla_s^D.

If later observations of the series become available, it is possible to update the state set (without re-estimating the model) using :meth:multi_inputmod_update.
If time series data is supplied with a previously estimated model, it is possible to construct the state set (and forecasts) using :meth:multi_inputmod_forecast.

.. _g13be-py2-py-references:

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

--------
:meth:naginterfaces.library.examples.tsa.multi_inputmod_ex.main
"""
raise NotImplementedError

[docs]def multi_inputmod_update(sttf, mr, mt, para, xxyn, kzef):
r"""
multi_inputmod_update accepts a series of new observations of an output time series and any associated input time series, for which a multi-input model is already fully specified, and updates the 'state set' information for use in constructing further forecasts.

The previous specification of the multi-input model will normally have been obtained by using :meth:multi_inputmod_estim to estimate the relevant transfer function and ARIMA parameters.
The supplied state set will originally have been produced by :meth:multi_inputmod_estim (or possibly :meth:multi_inputmod_forecast), but may since have been updated by multi_inputmod_update.

.. _g13bg-py2-py-doc:

For full information please refer to the NAG Library document for g13bg

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13bgf.html

.. _g13bg-py2-py-parameters:

**Parameters**
**sttf** : float, array-like, shape :math:\left(\textit{nsttf}\right)
The :math:\textit{nsttf} values in the state set before updating as returned by :meth:multi_inputmod_estim or :meth:multi_inputmod_forecast, or a previous call to multi_inputmod_update.

**mr** : int, array-like, shape :math:\left(7\right)
The orders vector :math:\left(p, d, q, P, D, Q, s\right) of the ARIMA model for the output noise component.

:math:p, :math:q, :math:P and :math:Q refer respectively to the number of autoregressive :math:\left(\phi \right), moving average :math:\left(\theta \right), seasonal autoregressive :math:\left(\Phi \right) and seasonal moving average :math:\left(\Theta \right) parameters.

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

**mt** : int, array-like, shape :math:\left(4, \textit{nser}\right)
The transfer function model orders :math:b, :math:p and :math:q of each of the input series. The data for input series :math:i are held in column :math:i. Row 1 holds the value :math:b_i, row 2 holds the value :math:q_i and row 3 holds the value :math:p_i. For a simple input, :math:b_i = q_i = p_i = 0.

Row 4 holds the value :math:r_i, where :math:r_i = 1 for a simple input and :math:r_i = 2 or :math:3 for a transfer function input.

When :math:r_i = 1 any nonzero contents of rows 1, 2 and 3 of column :math:i are ignored.

The choice of :math:r_i = 2 or :math:r_i = 3 is an option for use in model estimation and does not affect the operation of multi_inputmod_update.

**para** : float, array-like, shape :math:\left(\textit{npara}\right)
Estimates of the multi-input model parameters as returned by :meth:multi_inputmod_estim. These are in order, firstly the ARIMA model parameters: :math:p values of :math:\phi parameters, :math:q values of :math:\theta parameters, :math:P values of :math:\Phi parameters and :math:Q values of :math:\Theta parameters. These are followed by the transfer function model parameter values :math:\omega_0,\omega_1,\ldots,\omega_{q_1}, :math:\delta_1,\delta_2,\ldots,\delta_{p_1} for the first of any input series and similarly for each subsequent input series. The final component of :math:\mathrm{para} is the value of the constant :math:c.

**xxyn** : float, array-like, shape :math:\left(\textit{nnv}, \textit{nser}\right)
The :math:\textit{nnv} new observation sets being used to update the state set. Column :math:i-1 contains the values of input series :math:\textit{i}, for :math:\textit{i} = 1,2,\ldots,\textit{nser}-1. Column :math:\textit{nser}-1 contains the values of the output series. Consecutive rows correspond to increasing time sequence.

**kzef** : int
Must not be set to :math:0, if the values of the input component series :math:z_t and the values of the output noise component :math:n_t are to overwrite the contents of :math:\mathrm{xxyn} on exit, and must be set to :math:0 if :math:\mathrm{xxyn} is to remain unchanged on exit.

**Returns**
**sttf** : float, ndarray, shape :math:\left(\textit{nsttf}\right)
The state set values after updating.

**xxyn** : float, ndarray, shape :math:\left(\textit{nnv}, \textit{nser}\right)
If :math:\mathrm{kzef} = 0, :math:\mathrm{xxyn} remains unchanged.

If :math:\mathrm{kzef} \neq 0, the columns of :math:\mathrm{xxyn} hold the corresponding values of the input component series :math:z_t and the output noise component :math:n_t in that order.

**res** : float, ndarray, shape :math:\left(\textit{nnv}\right)
The values of the residual series :math:a_t corresponding to the new observations of the output series.

.. _g13bg-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{nsttf} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nsttf}, :math:\mathrm{mr} and :math:\mathrm{mt} must be consistent.

(errno :math:2)
On entry, :math:\textit{npara} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npara}, :math:\mathrm{mr} and :math:\mathrm{mt} must be consistent.

(errno :math:5)
On entry, the orders vector :math:\mathrm{mr} is invalid.

(errno :math:5)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{mt}[3,i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mt}[3,i-1] = 1, :math:2 or :math:3.

.. _g13bg-py2-py-notes:

**Notes**
The multi-input model is specified in :ref:Notes for multi_inputmod_estim <g13be-py2-py-notes>.
The form of these equations required to update the state set is as follows:

.. math::
z_t = \delta_1z_{{t-1}}+\delta_2z_{{t-2}} + \cdots +\delta_pz_{{t-p}}+\omega_0x_{{t-b}}-\omega_1x_{{t-b-1}} - \cdots -\omega_qx_{{t-b-q}}

the transfer models which generate input component values :math:z_{{i,t}} from one or more inputs :math:x_{{i,t}},

.. math::
n_t = y_t-z_{{1,t}}-z_{{2,t}} - \cdots -z_{{m,t}}

which generates the output noise component from the output :math:y_t and the input components, and

.. math::
\begin{array}{ll}w_t& = \nabla^d\nabla_s^Dn_t-c\\e_t& = w_t-\Phi_1w_{{t-s}}-\Phi_2w_{{t-2\times s}} - \cdots -\Phi_Pw_{{t-P\times s}}+\Theta_1e_{{t-s}}+\Theta_2e_{{t-2\times s}} + \cdots +\Theta_Qe_{{t-Q\times s}}\\a_t& = e_t-\phi_1e_{{t-1}}-\phi_2e_{{t-2}} - \cdots -\phi_pe_{{t-p}}+\theta_1a_{{t-1}}+\theta_2a_{{t-2}} + \cdots +\theta_qa_{{t-q}}\end{array}

the ARIMA model for the output noise which generates the residuals :math:a_t.

The state set (as also given in :ref:Notes for multi_inputmod_estim <g13be-py2-py-notes>) is the collection of terms

.. math::

for :math:k = 1 up to the maximum lag associated with each of these series respectively, in the above model equations. :math:n is the latest time point of the series from which the state set has been generated.

The function accepts further values of the series :math:y_{\textit{t}}, :math:x_{{1,\textit{t}}},x_{{2,\textit{t}}},\ldots,x_{{m,\textit{t}}}, for :math:\textit{t} = n+1,\ldots,n+l, and applies the above model equations over this time range, to generate new values of the various model components, noise series and residuals.
The state set is reconstructed, corresponding to the latest time point :math:n+l, the earlier values being discarded.

The set of residuals corresponding to the new observations may be of use in checking that the new observations conform to the previously fitted model.
The components of the new observations of the output series which are due to the various inputs, and the noise component, are also optionally returned.

The parameters of the model are not changed in this function.

.. _g13bg-py2-py-references:

**References**
Box, G E P and Jenkins, G M, 1976, Time Series Analysis: Forecasting and Control, (Revised Edition), Holden--Day
"""
raise NotImplementedError

[docs]def multi_inputmod_forecast_state(sttf, mr, mt, para, xxyn, mrx, parx, rmsxy, kzef):
r"""
multi_inputmod_forecast_state produces forecasts of a time series (the output series) which depends on one or more other (input) series via a multi-input model which will usually have been fitted using :meth:multi_inputmod_estim.
The future values of the input series must be supplied.
The original observations are not required. multi_inputmod_forecast_state uses as input either the original state set obtained from :meth:multi_inputmod_estim, or the state set updated by a series of new observations from :meth:multi_inputmod_update.
Standard errors of the forecasts are produced.
If future values of some of the input series have been obtained as forecasts using ARIMA models for those series, this may be allowed for in the calculation of the standard errors.

.. _g13bh-py2-py-doc:

For full information please refer to the NAG Library document for g13bh

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13bhf.html

.. _g13bh-py2-py-parameters:

**Parameters**
**sttf** : float, array-like, shape :math:\left(\textit{nsttf}\right)
The :math:\textit{nsttf} values in the state set as returned by :meth:multi_inputmod_estim or :meth:multi_inputmod_update.

**mr** : int, array-like, shape :math:\left(7\right)
The orders vector :math:\left(p, d, q, P, D, Q, s\right) of the ARIMA model for the output noise component.

:math:p, :math:q, :math:P and :math:Q give respectively the number of autoregressive :math:\left(\phi \right), moving average :math:\left(\theta \right), seasonal autoregressive :math:\left(\Phi \right) and seasonal moving average :math:\left(\Theta \right) parameters.

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

**mt** : int, array-like, shape :math:\left(4, \textit{nser}\right)
The transfer function orders :math:b, :math:p and :math:q of each of the input series. The data for input series :math:i are held in column :math:i. Row 1 holds the value :math:b_i, row 2 holds the value :math:q_i and row 3 holds the value :math:p_i. For a simple input, :math:b_i = q_i = p_i = 0.

Row 4 holds the value :math:r_i, where :math:r_i = 1 for a simple input, :math:r_i = 2 or :math:3 for a transfer function input.

When :math:r_i = 1, any nonzero contents of rows 1, 2 and 3 of column :math:i are ignored.

The choice of :math:r_i = 2 or :math:r_i = 3 is an option for use in model estimation and does not affect the operation of multi_inputmod_forecast_state.

**para** : float, array-like, shape :math:\left(\textit{npara}\right)
Estimates of the multi-input model parameters as returned by :meth:multi_inputmod_estim. These are in order, firstly the ARIMA model parameters: :math:p values of :math:\phi parameters, :math:q values of :math:\theta parameters, :math:P values of :math:\Phi parameters and :math:Q values of :math:\Theta parameters. These are followed by the transfer function model parameter values :math:\omega_0,\omega_1,\ldots,\omega_{q_1}, :math:\delta_1,\delta_2,\ldots,\delta_{p_1} for the first of any input series and similar sets of values for any subsequent input series. The final component of :math:\mathrm{para} is the constant :math:c.

**xxyn** : float, array-like, shape :math:\left(\textit{nfv}, \textit{nser}\right)
The supplied :math:\textit{nfv} values for each of the input series required to produce the :math:\textit{nfv} output series forecasts. Column :math:i contains the values for input series :math:i. Column :math:\textit{nser} need not be supplied.

**mrx** : int, array-like, shape :math:\left(7, \textit{nser}\right)
The orders array for each of the input series ARIMA models. Thus, column :math:i contains values of :math:p, :math:d, :math:q, :math:P, :math:D, :math:Q, :math:s for input series :math:i. In the case of those inputs for which no ARIMA model is available, the corresponding orders should be set to :math:0. (The model for any input series only affects the standard errors of the forecast values.)

**parx** : float, array-like, shape :math:\left(:, \textit{nser}\right)
Values of the parameters (:math:\phi, :math:\theta, :math:\Phi and :math:\Theta) for each of the input series ARIMA models. Thus column :math:i contains :math:\mathrm{mrx}[0,i-1] values of :math:\phi parameters, :math:\mathrm{mrx}[2,i-1] values of :math:\theta parameters, :math:\mathrm{mrx}[3,i-1] values of :math:\Phi parameters and :math:\mathrm{mrx}[5,i-1] values of :math:\Theta parameters -- in that order.

Values in the columns relating to those input series for which no ARIMA model is available are ignored. (The model for any input series only affects the standard errors of the forecast values.)

**rmsxy** : float, array-like, shape :math:\left(\textit{nser}\right)
The estimated residual variances for each input series ARIMA model followed by that for the output noise ARIMA model. In the case of those inputs for which no ARIMA model is available, or when its effects are to be excluded in the calculation of forecast standard errors, the corresponding entry of :math:\mathrm{rmsxy} should be set to :math:0.

**kzef** : int
Must not be set to :math:0, if the values of the input component series :math:z_t and the values of the output noise component :math:n_t are to overwrite the contents of :math:\mathrm{xxyn} on exit, and must be set to :math:0 if :math:\mathrm{xxyn} is to remain unchanged on exit, apart from the appearance of the forecast values in column :math:\textit{nser}.

**Returns**
**xxyn** : float, ndarray, shape :math:\left(\textit{nfv}, \textit{nser}\right)
If :math:\mathrm{kzef} = 0, then column :math:\textit{nser} of :math:\mathrm{xxyn} contains the output series forecast values (as does :math:\mathrm{fva}), but :math:\mathrm{xxyn} is otherwise unchanged.

If :math:\mathrm{kzef}\neq 0, then the columns of :math:\mathrm{xxyn} hold the corresponding values of the forecast components :math:z_t for each of the input series and the values of the output noise component :math:n_t in that order.

**mrx** : int, ndarray, shape :math:\left(7, \textit{nser}\right)
Unchanged, apart from column :math:\textit{nser} which is used for workspace.

**fva** : float, ndarray, shape :math:\left(\textit{nfv}\right)
The required forecast values for the output series.

**fsd** : float, ndarray, shape :math:\left(\textit{nfv}\right)
The standard errors for each of the forecast values.

.. _g13bh-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{nsttf} = \langle\mathit{\boldsymbol{value}}\rangle and the expected :math:\text{value} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nsttf}, :math:\mathrm{mr} and :math:\mathrm{mt} must be consistent.

(errno :math:2)
On entry, :math:\textit{npara} = \langle\mathit{\boldsymbol{value}}\rangle and the expected :math:\text{value} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npara}, :math:\mathrm{mr} and :math:\mathrm{mt} must be consistent.

(errno :math:6)
The orders vector :math:\mathrm{mr} is invalid.

(errno :math:6)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{mt}[3,i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mt}[3,i-1] = 1, :math:2 or :math:3.

.. _g13bh-py2-py-notes:

**Notes**
No equivalent traditional C interface for this routine exists in the NAG Library.

The forecasts of the output series :math:y_{\textit{t}} are calculated, for :math:\textit{t} = n+1,\ldots,n+L, where :math:n is the latest time point of the observations used to produce the state set and :math:L is the maximum lead time of the forecasts.

First the new input series values :math:x_t are used to form the input components :math:z_{\textit{t}}, for :math:\textit{t} = n+1,\ldots,n+L, using the transfer function models:

.. rst-class:: nag-rules-none

+---+--------------------------------------------------------------------------------------------------------------------------------------------------+
|(a)|:math:z_t = \delta_1z_{{t-1}}+\delta_2z_{{t-2}} + \cdots +\delta_pz_{{t-p}}+\omega_0x_{{t-b}}-\omega_1x_{{t-b-1}} - \cdots -\omega_qx_{{t-b-q}}.|
+---+--------------------------------------------------------------------------------------------------------------------------------------------------+

The output noise component :math:n_{\textit{t}} is then forecast by setting :math:a_{\textit{t}} = 0, for :math:\textit{t} = n+1,\ldots,n+L, and using the ARIMA model equations:

.. rst-class:: nag-rules-none

+---+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|(b)|:math:e_t = \phi_1e_{{t-1}}+\phi_2e_{{t-2}} + \cdots +\phi_pe_{{t-p}}+a_t-\theta_1a_{{t-1}}-\theta_2a_{{t-2}} - \cdots -\theta_1a_{{t-q}}                                |
+---+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|(c)|:math:w_t = \Phi_1w_{{t-s}}+\Phi_2w_{{t-2\times s}} + \cdots +\Phi_Pw_{{t-P\times s}}+e_t-\Theta_1e_{{t-s}}-\Theta_2e_{{t-2\times s}} - \cdots -\Theta_Qe_{{t-Q\times s}}|
+---+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|(d)|:math:n_t = {\left(\nabla^d\nabla_s^D\right)}^{-1}\left(w_t+c\right).                                                                                                    |
+---+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

This last step of 'integration' reverses the process of differencing.
Finally the output forecasts are calculated as

.. math::
y_t = z_{{1,t}}+z_{{2,t}} + \cdots +z_{{m,t}}+n_t\text{.}

The forecast error variance of :math:y_{{t+l}} (i.e., at lead time :math:l) is :math:S_l^2, which is the sum of parts which arise from the various input series, and the output noise component.
That part due to the output noise is

.. math::
sn_l^2 = V_n\times \left(\psi_0^2+\psi_1^2 + \cdots +\psi_{{l-1}}^2\right)\text{,}

where :math:V_n is the estimated residual variance of the output noise ARIMA model, and :math:\psi_0,\psi_1,\ldots \text{} are the 'psi-weights' of this model as defined in Box and Jenkins (1976).
They are calculated by applying the equations \(b), \(c) and \(d) above, for :math:t = 0,1,\ldots,L, but with artificial values for the various series and with the constant :math:c set to :math:0.
Thus all values of :math:a_t, :math:e_t, :math:w_t and :math:n_t are taken as zero, for :math:t < 0; :math:a_t is taken to be :math:1, for :math:t = 0 and :math:0, for :math:t > 0.
The resulting values of :math:n_{\textit{t}}, for :math:\textit{t} = 0,1,\ldots,L, are precisely :math:\psi_0,\psi_1,\ldots,\psi_L as required.

Further contributions to :math:S_l^2 come only from those input series, for which future values are forecasts which have been obtained by applying input series ARIMA models.
For such a series the contribution is

.. math::
sz_l^2 = V_x\times \left(\nu_0^2+\nu_1^2 + \cdots +\nu_{{l-1}}^2\right)\text{,}

where :math:V_x is the estimated residual variance of the input series ARIMA model.
The coefficients :math:\nu_0,\nu_1,\ldots \text{} are calculated by applying the transfer function model equation \(a) above, for :math:t = 0,1,\ldots,L, but again with artificial values of the series.
Thus all values of :math:z_t and :math:x_t, for :math:t < 0, are taken to be zero, and :math:x_0,x_1,\ldots \text{} are taken to be the psi-weight sequence :math:\psi_0,\psi_1,\ldots \text{} for the **input** **series** ARIMA model.
The resulting values of :math:z_{\textit{t}}, for :math:\textit{t} = 0,1,\ldots,L, are precisely :math:\nu_0,\nu_1,\ldots,\nu_L as required.

In adding such contributions :math:sz_l^2 to :math:sn_l^2 to make up the total forecast error variance :math:S_l^2, it is assumed that the various input series with which these contributions are associated are statistically independent of each other.

When using the function in practice an ARIMA model is required for all the input series.
In the case of those inputs for which no such ARIMA model is available (or its effects are to be excluded), the corresponding orders and parameters and the estimated residual variance should be set to zero.

.. _g13bh-py2-py-references:

**References**
Box, G E P and Jenkins, G M, 1976, Time Series Analysis: Forecasting and Control, (Revised Edition), Holden--Day

--------
:meth:naginterfaces.library.examples.tsa.multi_inputmod_ex.main
"""
raise NotImplementedError

[docs]def multi_inputmod_forecast(mr, mt, para, kfc, nev, nfv, xxy, kzef, rmsxy, mrx, parx, isttf, io_manager=None):
r"""
multi_inputmod_forecast produces forecasts of a time series (the output series) which depends on one or more other (input) series via a previously estimated multi-input model for which the state set information is not available.
The future values of the input series must be supplied.
In contrast with :meth:multi_inputmod_forecast_state the original past values of the input and output series are required.
Standard errors of the forecasts are produced.
If future values of some of the input series have been obtained as forecasts using ARIMA models for those series, this may be allowed for in the calculation of the standard errors.

.. _g13bj-py2-py-doc:

For full information please refer to the NAG Library document for g13bj

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13bjf.html

.. _g13bj-py2-py-parameters:

**Parameters**
**mr** : int, array-like, shape :math:\left(7\right)
The orders vector :math:\left(p, d, q, P, D, Q, s\right) of the ARIMA model for the output noise component.

:math:p, :math:q, :math:P and :math:Q refer respectively to the number of autoregressive :math:\left(\phi \right), moving average :math:\left(\theta \right), seasonal autoregressive :math:\left(\Phi \right) and seasonal moving average :math:\left(\Theta \right) parameters.

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

**mt** : int, array-like, shape :math:\left(4, \textit{nser}\right)
The transfer function model orders :math:b, :math:p and :math:q of each of the input series. The data for input series :math:i is held in column :math:i. Row 1 holds the value :math:b_i, row 2 holds the value :math:q_i and row 3 holds the value :math:p_i.

For a simple input, :math:b_i = q_i = p_i = 0.

Row 4 holds the value :math:r_i, where :math:r_i = 1 for a simple input, and :math:r_i = 2 or :math:3 for a transfer function input.

The choice :math:r_i = 3 leads to estimation of the pre-period input effects as nuisance parameters, and :math:r_i = 2 suppresses this estimation.

This choice may affect the returned forecasts and the state set.

When :math:r_i = 1, any nonzero contents of rows 1, 2 and 3 of column :math:i are ignored.

**para** : float, array-like, shape :math:\left(\textit{npara}\right)
Estimates of the multi-input model parameters. These are in order, firstly the ARIMA model parameters: :math:p values of :math:\phi parameters, :math:q values of :math:\theta parameters, :math:P values of :math:\Phi parameters, :math:Q values of :math:\Theta parameters.

These are followed by the transfer function model parameter values :math:\omega_0,\omega_1,\ldots,\omega_{q_1}, :math:\delta_1,\ldots,\delta_{p_1} for the first of any input series and similarly for each subsequent input series.

The final component of :math:\mathrm{para} is the value of the constant :math:c.

**kfc** : int
Must be set to :math:1 if the constant was estimated when the model was fitted, and :math:0 if it was held at a fixed value. This only affects the degrees of freedom used in calculating the estimated residual variance.

**nev** : int
The number of original (undifferenced) values in each of the input and output time series.

**nfv** : int
The number of forecast values of the output series required.

**xxy** : float, array-like, shape :math:\left(\left(\mathrm{nev}+\mathrm{nfv}\right), \textit{nser}\right)
The columns of :math:\mathrm{xxy} must contain in the first :math:\mathrm{nev} places, the past values of each of the input and output series, in that order. In the next :math:\mathrm{nfv} places, the columns relating to the input series (i.e., columns :math:1 to :math:\textit{nser}-1) contain the future values of the input series which are necessary for construction of the forecasts of the output series :math:y.

**kzef** : int
Must be set to :math:0 if the relevant :math:\mathrm{nfv} values of the forecasts (:math:\mathrm{fva}) are to be held in the output series column (:math:\textit{nser}) of :math:\mathrm{xxy} (which is otherwise unchanged) on exit, and must not be set to :math:0 if the values of the input component series :math:z_t and the values of the output noise component :math:n_t are to overwrite the contents of :math:\mathrm{xxy} on exit.

**rmsxy** : float, array-like, shape :math:\left(\textit{nser}\right)
The first :math:\left(\textit{nser}-1\right) elements of :math:\mathrm{rmsxy} must contain the estimated residual variance of the input series ARIMA models. In the case of those inputs for which no ARIMA model is available or its effects are to be excluded in the calculation of forecast standard errors, the corresponding entry of :math:\mathrm{rmsxy} should be set to :math:0.

**mrx** : int, array-like, shape :math:\left(7, \textit{nser}\right)
The orders array for each of the input series ARIMA models. Thus, column :math:i contains values of :math:p, :math:d, :math:q, :math:P, :math:D, :math:Q, :math:s for input series :math:i. In the case of those inputs for which no ARIMA model is available, the corresponding orders should be set to :math:0.

**parx** : float, array-like, shape :math:\left(:, \textit{nser}\right)
Values of the parameters (:math:\phi, :math:\theta, :math:\Phi, and :math:\Theta) for each of the input series ARIMA models.

Thus column :math:i contains :math:\mathrm{mrx}[0,i-1] values of :math:\phi, :math:\mathrm{mrx}[2,i-1] values of :math:\theta, :math:\mathrm{mrx}[3,i-1] values of :math:\Phi and :math:\mathrm{mrx}[5,i-1] values of :math:\Theta, in that order.

Values in the columns relating to those input series for which no ARIMA model is available are ignored.

**isttf** : int
The dimension of the array :math:\mathrm{sttf}.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**para** : float, ndarray, shape :math:\left(\textit{npara}\right)
The parameter values may be updated using an additional iteration in the estimation process.

**xxy** : float, ndarray, shape :math:\left(\left(\mathrm{nev}+\mathrm{nfv}\right), \textit{nser}\right)
If :math:\mathrm{kzef} = 0 then :math:\mathrm{xxy} is unchanged except that the relevant :math:\mathrm{nfv} values in the column relating to the output series (column :math:\textit{nser}) contain the forecast values (:math:\mathrm{fva}), but if :math:\mathrm{kzef}\neq 0 then the columns of :math:\mathrm{xxy} contain the corresponding values of the input component series :math:z_t and the values of the output noise component :math:n_t, in that order.

**rmsxy** : float, ndarray, shape :math:\left(\textit{nser}\right)
:math:\mathrm{rmsxy}[\textit{nser}-1] contains the estimated residual variance of the output noise ARIMA model which is calculated from the supplied series. Otherwise :math:\mathrm{rmsxy} is unchanged.

**mrx** : int, ndarray, shape :math:\left(7, \textit{nser}\right)
Unchanged, except for column :math:\textit{nser} which is used as workspace.

**fva** : float, ndarray, shape :math:\left(\mathrm{nfv}\right)
The required forecast values for the output series. (Note that these are also output in column :math:\textit{nser} of :math:\mathrm{xxy} if :math:\mathrm{kzef} = 0.)

**fsd** : float, ndarray, shape :math:\left(\mathrm{nfv}\right)
The standard errors for each of the forecast values.

**sttf** : float, ndarray, shape :math:\left(\mathrm{isttf}\right)
The :math:\mathrm{nsttf} values of the state set based on the first :math:\mathrm{nev} sets of (past) values of the input and output series.

**nsttf** : int
The number of values in the state set array :math:\mathrm{sttf}.

.. _g13bj-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{nfv} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nfv} > 0.

(errno :math:1)
On entry, :math:\textit{ldxxy} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{nev} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nfv} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ldxxy}\geq \mathrm{nev}+\mathrm{nfv}.

(errno :math:1)
On entry, :math:\mathrm{kfc} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{kfc} = 0 or :math:1.

(errno :math:2)
The orders vector :math:\mathrm{mr} is invalid.

(errno :math:2)
:math:\textit{npara} is inconsistent with :math:\mathrm{mr} and :math:\mathrm{mt}.

(errno :math:2)
Insufficient degrees of freedom to solve the problem.

(errno :math:2)
On entry, :math:\textit{npara} = \langle\mathit{\boldsymbol{value}}\rangle and the expected :math:\text{value} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npara}, :math:\mathrm{mr} and :math:\mathrm{mt} must be consistent.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{mt}[3,i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mt}[3,i-1] = 1, :math:2 or :math:3.

(errno :math:3)
One or more sets of delta parameters do not satisfy the stationarity or invertibility conditions.

(errno :math:8)
Unable to calculate the latest parameter estimates.

(errno :math:9)
Failure in inversion of second derivative matrix.

(errno :math:10)
One or more sets of ARIMA parameters do not satisfy the stationarity or invertibility conditions.

(errno :math:11)
On entry, :math:\mathrm{isttf} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{isttf}\geq \left(P\times s\right)+d+\left(D\times s\right)+q+\mathrm{max}\left(p, {Q\times s}\right)+\textit{ncf}.

.. _g13bj-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

multi_inputmod_forecast has two stages.
The first stage is essentially the same as a call to the model estimation function :meth:multi_inputmod_estim, with zero iterations.
In particular, all the parameters remain unchanged in the supplied input series transfer function models and output noise series ARIMA model.
The internal nuisance parameters associated with the pre-observation period effects of the input series are estimated where requested, and so are any backforecasts of the output noise series.
The output components :math:z_t and :math:n_t, and residuals :math:a_t are calculated exactly as in :ref:Notes for multi_inputmod_estim <g13be-py2-py-notes>, and the state set for forecasting is constituted.

The second stage is essentially the same as a call to the forecasting function :meth:multi_inputmod_forecast_state.
The same information is required, and the same information is returned.

Use of multi_inputmod_forecast should be confined to situations in which the state set for forecasting is unknown.
Forecasting from the original data is relatively expensive because it requires recalculation of the state set. multi_inputmod_forecast returns the state set for use in producing further forecasts using :meth:multi_inputmod_forecast_state, or for updating the state set using :meth:multi_inputmod_update.

.. _g13bj-py2-py-references:

**References**
Box, G E P and Jenkins, G M, 1976, Time Series Analysis: Forecasting and Control, (Revised Edition), Holden--Day
"""
raise NotImplementedError

[docs]def uni_spectrum_lag(nx, mtx, px, iw, mw, ic, c, kc, l, lg, xg):
r"""
uni_spectrum_lag calculates the smoothed sample spectrum of a univariate time series using one of four lag windows -- rectangular, Bartlett, Tukey or Parzen window.

.. _g13ca-py2-py-doc:

For full information please refer to the NAG Library document for g13ca

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13caf.html

.. _g13ca-py2-py-parameters:

**Parameters**
**nx** : int
:math:n, the length of the time series.

**mtx** : int
If covariances are to be calculated by the function (:math:\mathrm{ic} = 0), :math:\mathrm{mtx} must specify whether the data are to be initially mean or trend corrected.

:math:\mathrm{mtx} = 0

For no correction.

:math:\mathrm{mtx} = 1

For mean correction.

:math:\mathrm{mtx} = 2

For trend correction.

**px** : float
If covariances are to be calculated by the function (:math:\mathrm{ic} = 0), :math:\mathrm{px} must specify the proportion of the data (totalled over both ends) to be initially tapered by the split cosine bell taper.

If covariances are supplied :math:\left(\mathrm{ic}\neq 0\right), :math:\mathrm{px} must specify the proportion of data tapered before the supplied covariances were calculated and after any mean or trend correction. :math:\mathrm{px} is required for the calculation of output statistics.

A value of :math:0.0 implies no tapering.

**iw** : int
The choice of lag window.

:math:\mathrm{iw} = 1

Rectangular.

:math:\mathrm{iw} = 2

Bartlett.

:math:\mathrm{iw} = 3

Tukey.

:math:\mathrm{iw} = 4

Parzen.

**mw** : int
:math:M, the 'cut-off' point of the lag window. Windowed covariances at lag :math:M or greater are zero.

**ic** : int
Indicates whether covariances are to be calculated in the function or supplied in the call to the function.

:math:\mathrm{ic} = 0

Covariances are to be calculated.

:math:\mathrm{ic}\neq 0

Covariances are to be supplied.

**c** : float, array-like, shape :math:\left(\textit{nc}\right)
If :math:\mathrm{ic}\neq 0, :math:\mathrm{c} must contain the :math:\textit{nc} covariances for lags from :math:0 to :math:\left(\textit{nc}-1\right), otherwise :math:\mathrm{c} need not be set.

**kc** : int
If :math:\mathrm{ic} = 0, :math:\mathrm{kc} must specify the order of the fast Fourier transform (FFT) used to calculate the covariances.

If :math:\mathrm{ic}\neq 0, that is covariances are supplied, :math:\mathrm{kc} is not used.

**l** : int
:math:L, the frequency division of the spectral estimates as :math:\frac{{2\pi }}{L}. Therefore, it is also the order of the FFT used to construct the sample spectrum from the covariances.

**lg** : int
Indicates whether unlogged or logged spectral estimates and confidence limits are required.

:math:\mathrm{lg} = 0

Unlogged.

:math:\mathrm{lg} \neq 0

Logged.

**xg** : float, array-like, shape :math:\left(\textit{nxg}\right)
If the covariances are to be calculated, then :math:\mathrm{xg} must contain the :math:\mathrm{nx} data points. If covariances are supplied, :math:\mathrm{xg} may contain any values.

**Returns**
**c** : float, ndarray, shape :math:\left(\textit{nc}\right)
If :math:\mathrm{ic} = 0, :math:\mathrm{c} will contain the :math:\textit{nc} calculated covariances.

If :math:\mathrm{ic}\neq 0, the contents of :math:\mathrm{c} will be unchanged.

**xg** : float, ndarray, shape :math:\left(\textit{nxg}\right)
Contains the :math:\mathrm{ng} spectral estimates, :math:\hat{f}\left(\omega_{\textit{i}}\right), for :math:\textit{i} = 0,1,\ldots,\left[L/2\right] in :math:\mathrm{xg}[0] to :math:\mathrm{xg}[\mathrm{ng}-1] respectively (logged if :math:\mathrm{lg} = 1). The elements :math:\mathrm{xg}[\textit{i}-1], for :math:\textit{i} = \mathrm{ng}+1,\ldots,\textit{nxg} contain :math:0.0.

**ng** : int
The number of spectral estimates, :math:\left[L/2\right]+1, in :math:\mathrm{xg}.

**stats** : float, ndarray, shape :math:\left(4\right)
Four associated statistics. These are the degrees of freedom in :math:\mathrm{stats}[0], the lower and upper :math:95\% confidence limit factors in :math:\mathrm{stats}[1] and :math:\mathrm{stats}[2] respectively (logged if :math:\mathrm{lg} = 1), and the bandwidth in :math:\mathrm{stats}[3].

.. _g13ca-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{nc} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nc}\leq \mathrm{nx}.

(errno :math:1)
On entry, :math:\textit{nc} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nc}\geq \mathrm{mw}.

(errno :math:1)
On entry, :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mw}\leq \mathrm{nx}.

(errno :math:1)
On entry, :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mw}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{iw} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iw} = 1, :math:2, :math:3 or :math:4.

(errno :math:1)
On entry, :math:\mathrm{px} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{px}\leq 1.0.

(errno :math:1)
On entry, :math:\mathrm{px} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{px}\geq 0.0.

(errno :math:1)
On entry, :math:\textit{nxg} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{l} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ic} \neq 0, :math:\textit{nxg}\geq \mathrm{l}.

(errno :math:1)
On entry, :math:\textit{nxg} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{kc} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{l} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ic} = 0, :math:\textit{nxg}\geq \mathrm{max}\left(\mathrm{kc}, \mathrm{l}\right).

(errno :math:1)
On entry, :math:\mathrm{ic} = 0 and :math:\mathrm{mtx} > 2: :math:\mathrm{mtx} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\mathrm{ic} = 0 and :math:\mathrm{mtx} < 0: :math:\mathrm{mtx} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\mathrm{nx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nx}\geq 1.

(errno :math:2)
On entry, :math:\mathrm{kc} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{nx} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{nc} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ic} = 0, :math:\mathrm{kc}\geq \left(\mathrm{nx}+\textit{nc}\right).

(errno :math:3)
On entry, :math:\mathrm{l} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{l} \geq {2\times \mathrm{mw}-1}.

**Warns**
**NagAlgorithmicWarning**
(errno :math:4)
One or more spectral estimates are negative.

Unlogged spectral estimates are returned in :math:\mathrm{xg}, and the degrees of freedom, unloged confidence limit factors and bandwidth in :math:\mathrm{stats}.

(errno :math:5)
The calculation of confidence limit factors has failed.

Spectral estimates (logged if requested) are returned in :math:\mathrm{xg}, and degrees of freedom and bandwidth in :math:\mathrm{stats}.

.. _g13ca-py2-py-notes:

**Notes**
The smoothed sample spectrum is defined as

.. math::
\hat{f}\left(\omega \right) = \frac{1}{{2\pi }}\left(C_0+2\sum_{{k = 1}}^{{M-1}}w_kC_k\cos\left(\omega k\right)\right)\text{,}

where :math:M is the window width, and is calculated for frequency values

.. math::
\omega_i = \frac{{2\pi i}}{L}\text{, }\quad i = 0,1,\ldots,\left[L/2\right]\text{,}

where :math:\left[\right] denotes the integer part.

The autocovariances :math:C_k may be supplied by you, or constructed from a time series :math:x_1,x_2,\ldots,x_n, as

.. math::
C_k = \frac{1}{n}\sum_{{t = 1}}^{{n-k}}x_tx_{{t+k}}\text{,}

the fast Fourier transform (FFT) being used to carry out the convolution in this formula.

The time series may be mean or trend corrected (by classical least squares), and tapered before calculation of the covariances, the tapering factors being those of the split cosine bell:

.. math::
\begin{array}{ll}\frac{1}{2}\left(1-\cos\left(\pi \left(t-\frac{1}{2}\right)/T\right)\right)\text{,}&1\leq t\leq T\\&\\\frac{1}{2}\left(1-\cos\left(\pi \left(n-t+\frac{1}{2}\right)/T\right)\right)\text{,}&n + 1-T\leq t\leq n\\&\\1\text{,}&\text{otherwise,}\end{array}

where :math:T = \left[\frac{{np}}{2}\right] and :math:p is the tapering proportion.

The smoothing window is defined by

.. math::
w_k = W\left(\frac{k}{M}\right)\text{, }\quad k\leq M-1\text{,}

which for the various windows is defined over :math:0\leq \alpha < 1 by

rectangular:

.. math::
W\left(\alpha \right) = 1

Bartlett:

.. math::
W\left(\alpha \right) = 1-\alpha

Tukey:

.. math::
W\left(\alpha \right) = \frac{1}{2}\left(1+\cos\left(\pi \alpha \right)\right)

Parzen:

.. math::
\begin{array}{ll}W\left(\alpha \right) = 1 - 6\alpha^2 + 6\alpha^3\text{,}&0\leq \alpha \leq \frac{1}{2}\\&\\W\left(\alpha \right) = 2\left(1-\alpha \right)^3\text{,}&\frac{1}{2} < \alpha < 1\text{.}\end{array}

The sampling distribution of :math:\hat{f}\left(\omega \right) is approximately that of a scaled :math:\chi_d^2 variate, whose degrees of freedom :math:d is provided by the function, together with multiplying limits :math:mu, :math:ml from which approximate :math:95\% confidence intervals for the true spectrum :math:f\left(\omega \right) may be constructed as :math:\left[{ml\times \hat{ f }\left(\omega \right)}, {mu\times \hat{ f }\left(\omega \right)}\right].
Alternatively, log :math:\hat{f}\left(\omega \right) may be returned, with additive limits.

The bandwidth :math:b of the corresponding smoothing window in the frequency domain is also provided.
Spectrum estimates separated by (angular) frequencies much greater than :math:b may be assumed to be independent.

.. _g13ca-py2-py-references:

**References**
Bloomfield, P, 1976, Fourier Analysis of Time Series: An Introduction, Wiley

Jenkins, G M and Watts, D G, 1968, Spectral Analysis and its Applications, Holden--Day
"""
raise NotImplementedError

[docs]def uni_spectrum_daniell(nx, mtx, px, mw, pw, l, lg, xg):
r"""
uni_spectrum_daniell calculates the smoothed sample spectrum of a univariate time series using spectral smoothing by the trapezium frequency (Daniell) window.

.. _g13cb-py2-py-doc:

For full information please refer to the NAG Library document for g13cb

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13cbf.html

.. _g13cb-py2-py-parameters:

**Parameters**
**nx** : int
:math:n, the length of the time series.

**mtx** : int
Whether the data are to be initially mean or trend corrected.

:math:\mathrm{mtx} = 0

For no correction.

:math:\mathrm{mtx} = 1

For mean correction.

:math:\mathrm{mtx} = 2

For trend correction.

**px** : float
The proportion of the data (totalled over both ends) to be initially tapered by the split cosine bell taper. (A value of :math:0.0 implies no tapering.)

**mw** : int
The value of :math:M which determines the frequency width of the smoothing window as :math:2\pi /M. A value of :math:n implies no smoothing is to be carried out.

**pw** : float
:math:p, the shape parameter of the trapezium frequency window.

A value of :math:0.0 gives a triangular window, and a value of :math:1.0 a rectangular window.

If :math:\mathrm{mw} = \mathrm{nx} (i.e., no smoothing is carried out), :math:\mathrm{pw} is not used.

**l** : int
:math:L, the frequency division of smoothed spectral estimates as :math:2\pi /L.

**lg** : int
Indicates whether unlogged or logged spectral estimates and confidence limits are required.

:math:\mathrm{lg} = 0

For unlogged.

:math:\mathrm{lg}\neq 0

For logged.

**xg** : float, array-like, shape :math:\left(\textit{kc}\right)
The :math:n data points.

**Returns**
**xg** : float, ndarray, shape :math:\left(\textit{kc}\right)
Contains the :math:\mathrm{ng} spectral estimates :math:\hat{f}\left(\omega_{\textit{i}}\right), for :math:\textit{i} = 0,1,\ldots,\left[L/2\right], in :math:\mathrm{xg}[0] to :math:\mathrm{xg}[\mathrm{ng}-1] (logged if :math:\mathrm{lg}\neq 0). The elements :math:\mathrm{xg}[\textit{i}-1], for :math:\textit{i} = \mathrm{ng}+1,\ldots,\textit{kc}, contain :math:0.0.

**ng** : int
The number of spectral estimates, :math:\left[L/2\right]+1, in :math:\mathrm{xg}.

**stats** : float, ndarray, shape :math:\left(4\right)
Four associated statistics. These are the degrees of freedom in :math:\mathrm{stats}[0], the lower and upper :math:95\% confidence limit factors in :math:\mathrm{stats}[1] and :math:\mathrm{stats}[2] respectively (logged if :math:\mathrm{lg}\neq 0), and the bandwidth in :math:\mathrm{stats}[3].

.. _g13cb-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{l} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{l}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{px} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pw} > 1.0, :math:\mathrm{mw} = \mathrm{nx}.

(errno :math:1)
On entry, :math:\mathrm{px} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pw} < 0.0, :math:\mathrm{mw} = \mathrm{nx}.

(errno :math:1)
On entry, :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mw}\leq \mathrm{nx}.

(errno :math:1)
On entry, :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mw}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{px} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{px}\leq 1.0.

(errno :math:1)
On entry, :math:\mathrm{px} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{px}\geq 0.0.

(errno :math:1)
On entry, :math:\mathrm{mtx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mtx} \leq 2.

(errno :math:1)
On entry, :math:\mathrm{mtx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mtx}\geq 0.

(errno :math:1)
On entry, :math:\mathrm{nx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nx}\geq 1.

(errno :math:2)
On entry, :math:\textit{kc} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{l} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{kc} must be a multiple of :math:\mathrm{l}.

(errno :math:2)
On entry, :math:\textit{kc} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{kc} \geq {2\times \mathrm{nx}}.

**Warns**
**NagAlgorithmicWarning**
(errno :math:4)
One or more spectral estimates are negative.

Unlogged spectral estimates are returned in :math:\mathrm{xg}, and the degrees of freedom, unloged confidence limit factors and bandwidth in :math:\mathrm{stats}.

(errno :math:5)
The calculation of confidence limit factors has failed.

Spectral estimates (logged if requested) are returned in :math:\mathrm{xg}, and degrees of freedom and bandwidth in :math:\mathrm{stats}.

.. _g13cb-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

The supplied time series may be mean or trend corrected (by least squares), and tapered, the tapering factors being those of the split cosine bell:

.. math::
\begin{array}{ll}\frac{1}{2} \left(1-\cos\left(\pi \left(t-\frac{1}{2}\right)/T\right)\right) \text{,}&1\leq t\leq T\\&\\\frac{1}{2} \left(1-\cos\left(\pi \left(n-t+\frac{1}{2}\right)/T\right)\right) \text{,}&n+1-T\leq t\leq n\\&\\1\text{,}&\text{otherwise,}\end{array}

where :math:T = \left[\frac{{np}}{2}\right] and :math:p is the tapering proportion.

The unsmoothed sample spectrum

.. math::
f^*\left(\omega \right) = \frac{1}{{2\pi }}\left\lvert \sum_{{t = 1}}^nx_t\mathrm{exp}\left(i\omega t\right)\right\rvert^2

is then calculated for frequency values

.. math::
\omega_k = \frac{{2\pi k}}{K}\text{, }\quad k = 0,1,\ldots,\left[K/2\right]\text{,}

where [ ] denotes the integer part.

The smoothed spectrum is returned as a subset of these frequencies for which :math:k is a multiple of a chosen value :math:r, i.e.,

.. math::
\omega_{{rl}} = \nu_l = \frac{{2\pi l}}{L}\text{, }\quad l = 0,1,\ldots,\left[L/2\right]\text{,}

where :math:K = r\times L.
You will normally fix :math:L first, then choose :math:r so that :math:K is sufficiently large to provide an adequate representation for the unsmoothed spectrum, i.e., :math:K\geq 2\times n.
It is possible to take :math:L = K, i.e., :math:r = 1.

The smoothing is defined by a trapezium window whose shape is supplied by the function

.. math::
\begin{array}{ll}W\left(\alpha \right) = 1\text{,}&\left\lvert \alpha \right\rvert \leq p\\W\left(\alpha \right) = \frac{{1-\left\lvert \alpha \right\rvert }}{{1-p}}\text{,}&p < \left\lvert \alpha \right\rvert \leq 1\end{array}

the proportion :math:p being supplied by you.

The width of the window is fixed as :math:2\pi /M by you supplying :math:M.
A set of averaging weights are constructed:

.. math::
W_k = g\times W\left(\frac{{\omega_kM}}{\pi }\right)\text{, }\quad 0\leq \omega_k\leq \frac{\pi }{M}\text{,}

where :math:g is a normalizing constant, and the smoothed spectrum obtained is

.. math::
\hat{f}\left(\nu_l\right) = \sum_{{\left\lvert \omega_k\right\rvert < \frac{\pi }{M}}}W_kf^*\left(\nu_l+\omega_k\right)\text{.}

If no smoothing is required :math:M should be set to :math:n, in which case the values returned are :math:\hat{f}\left(\nu_l\right) = f^*\left(\nu_l\right).
Otherwise, in order that the smoothing approximates well to an integration, it is essential that :math:K≫M, and preferable, but not essential, that :math:K be a multiple of :math:M.
A choice of :math:L > M would normally be required to supply an adequate description of the smoothed spectrum.
Typical choices of :math:L\simeq n and :math:K\simeq 4n should be adequate for usual smoothing situations when :math:M < n/5.

The sampling distribution of :math:\hat{f}\left(\omega \right) is approximately that of a scaled :math:\chi_d^2 variate, whose degrees of freedom :math:d is provided by the function, together with multiplying limits :math:mu, :math:ml from which approximate 95% confidence intervals for the true spectrum :math:f\left(\omega \right) may be constructed as :math:\left[{ml\times \hat{ f }\left(\omega \right)}{mu\times \hat{ f }\left(\omega \right)}\right].
Alternatively, log :math:\hat{f}\left(\omega \right) may be returned, with additive limits.

The bandwidth :math:b of the corresponding smoothing window in the frequency domain is also provided.
Spectrum estimates separated by (angular) frequencies much greater than :math:b may be assumed to be independent.

.. _g13cb-py2-py-references:

**References**
Bloomfield, P, 1976, Fourier Analysis of Time Series: An Introduction, Wiley

Jenkins, G M and Watts, D G, 1968, Spectral Analysis and its Applications, Holden--Day
"""
raise NotImplementedError

[docs]def multi_spectrum_lag(nxy, mtxy, pxy, iw, mw, ish, ic, cxy, cyx, kc, l, xg=None, yg=None):
r"""
multi_spectrum_lag calculates the smoothed sample cross spectrum of a bivariate time series using one of four lag windows: rectangular, Bartlett, Tukey or Parzen.

.. _g13cc-py2-py-doc:

For full information please refer to the NAG Library document for g13cc

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ccf.html

.. _g13cc-py2-py-parameters:

**Parameters**
**nxy** : int
:math:n, the length of the time series :math:x and :math:y.

**mtxy** : int
If cross-covariances are to be calculated by the function (:math:\mathrm{ic} = 0), :math:\mathrm{mtxy} must specify whether the data is to be initially mean or trend corrected.

:math:\mathrm{mtxy} = 0

For no correction.

:math:\mathrm{mtxy} = 1

For mean correction.

:math:\mathrm{mtxy} = 2

For trend correction.

If cross-covariances are supplied :math:\left(\mathrm{ic}\neq 0\right), :math:\mathrm{mtxy} is not used.

**pxy** : float
If cross-covariances are to be calculated by the function (:math:\mathrm{ic} = 0), :math:\mathrm{pxy} must specify the proportion of the data (totalled over both ends) to be initially tapered by the split cosine bell taper. A value of :math:0.0 implies no tapering.

If cross-covariances are supplied :math:\left(\mathrm{ic}\neq 0\right), :math:\mathrm{pxy} is not used.

**iw** : int
The choice of lag window.

:math:\mathrm{iw} = 1

Rectangular.

:math:\mathrm{iw} = 2

Bartlett.

:math:\mathrm{iw} = 3

Tukey.

:math:\mathrm{iw} = 4

Parzen.

**mw** : int
:math:M, the 'cut-off' point of the lag window, relative to any alignment shift that has been applied. Windowed cross-covariances at lags :math:\left(-\mathrm{mw}+\mathrm{ish}\right) or less, and at lags :math:\left(\mathrm{mw}+\mathrm{ish}\right) or greater are zero.

**ish** : int
:math:S, the alignment shift between the :math:x and :math:y series. If :math:x leads :math:y, the shift is positive.

**ic** : int
Indicates whether cross-covariances are to be calculated in the function or supplied in the call to the function.

:math:\mathrm{ic} = 0

Cross-covariances are to be calculated.

:math:\mathrm{ic}\neq 0

Cross-covariances are to be supplied.

**cxy** : float, array-like, shape :math:\left(\textit{nc}\right)
If :math:\mathrm{ic}\neq 0, :math:\mathrm{cxy} must contain the :math:\textit{nc} cross-covariances between values in the :math:y series and earlier values in time in the :math:x series, for lags from :math:0 to :math:\left(\textit{nc}-1\right).

If :math:\mathrm{ic} = 0, :math:\mathrm{cxy} need not be set.

**cyx** : float, array-like, shape :math:\left(\textit{nc}\right)
If :math:\mathrm{ic}\neq 0, :math:\mathrm{cyx} must contain the :math:\textit{nc} cross-covariances between values in the :math:y series and later values in time in the :math:x series, for lags from :math:0 to :math:\left(\textit{nc}-1\right).

If :math:\mathrm{ic} = 0, :math:\mathrm{cyx} need not be set.

**kc** : int
If :math:\mathrm{ic} = 0, :math:\mathrm{kc} must specify the order of the fast Fourier transform (FFT) used to calculate the cross-covariances.

If :math:\mathrm{ic}\neq 0, that is if covariances are supplied, :math:\mathrm{kc} is not used.

**l** : int
:math:L, the frequency division of the spectral estimates as :math:\frac{{2\pi }}{L}. Therefore, it is also the order of the FFT used to construct the sample spectrum from the cross-covariances.

**xg** : None or float, array-like, shape :math:\left(:\right), optional
Note: the required length for this argument is determined as follows: if :math:\mathrm{ic}=0: :math:\max\left(\mathrm{kc},\mathrm{l}\right); otherwise: :math:\mathrm{l}.

If the cross-covariances are to be calculated, then :math:\mathrm{xg} must contain the :math:\mathrm{nxy} data points of the :math:x series. If covariances are supplied, :math:\mathrm{xg} need not be set.

**yg** : None or float, array-like, shape :math:\left(:\right), optional
Note: the required length for this argument is determined as follows: if :math:\mathrm{ic}=0: :math:\max\left(\mathrm{kc},\mathrm{l}\right); otherwise: :math:\mathrm{l}.

If cross-covariances are to be calculated, :math:\mathrm{yg} must contain the :math:\mathrm{nxy} data points of the :math:y series. If covariances are supplied, :math:\mathrm{yg} need not be set.

**Returns**
**cxy** : float, ndarray, shape :math:\left(\textit{nc}\right)
If :math:\mathrm{ic} = 0, :math:\mathrm{cxy} will contain the :math:\textit{nc} calculated cross-covariances.

If :math:\mathrm{ic}\neq 0, the contents of :math:\mathrm{cxy} will be unchanged.

**cyx** : float, ndarray, shape :math:\left(\textit{nc}\right)
If :math:\mathrm{ic} = 0, :math:\mathrm{cyx} will contain the :math:\textit{nc} calculated cross-covariances.

If :math:\mathrm{ic}\neq 0, the contents of :math:\mathrm{cyx} will be unchanged.

**xg** : float, ndarray, shape :math:\left(:\right)
Contains the real parts of the :math:\mathrm{ng} complex spectral estimates in elements :math:\mathrm{xg}[0] to :math:\mathrm{xg}[\mathrm{ng}-1], and :math:\mathrm{xg}[\mathrm{ng}] to :math:\mathrm{xg}[\textit{nxyg}-1] contain :math:0.0. The :math:y series leads the :math:x series.

**yg** : float, ndarray, shape :math:\left(:\right)
Contains the imaginary parts of the :math:\mathrm{ng} complex spectral estimates in elements :math:\mathrm{yg}[0] to :math:\mathrm{yg}[\mathrm{ng}-1], and :math:\mathrm{yg}[\mathrm{ng}] to :math:\mathrm{yg}[\textit{nxyg}-1] contain :math:0.0. The :math:y series leads the :math:x series.

**ng** : int
The number, :math:\left[\mathrm{l}/2\right]+1, of complex spectral estimates, whose separate parts are held in :math:\mathrm{xg} and :math:\mathrm{yg}.

.. _g13cc-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{ic} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\textit{nxyg} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{l} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ic} \neq 0, :math:\textit{nxyg}\geq \mathrm{l}.

(errno :math:1)
On entry, :math:\textit{nxyg} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{kc} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{l} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ic} = 0, :math:\textit{nxyg}\geq \mathrm{max}\left(\mathrm{kc}, \mathrm{l}\right).

(errno :math:1)
On entry, :math:\mathrm{pxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ic} = 0, :math:\mathrm{pxy}\leq 1.0.

(errno :math:1)
On entry, :math:\mathrm{pxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ic} = 0, :math:\mathrm{pxy}\geq 0.0.

(errno :math:1)
On entry, :math:\mathrm{mtxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ic} = 0 then :math:\mathrm{mtxy} \neq 0, :math:1 or :math:2.

(errno :math:1)
On entry, :math:\textit{nc} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nc}\leq \mathrm{nxy}.

(errno :math:1)
On entry, :math:\textit{nc} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{ish} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nc}\geq \mathrm{mw}+\left\lvert \mathrm{ish}\right\rvert.

(errno :math:1)
On entry, :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{ish} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mw}+\left\lvert \mathrm{ish}\right\rvert \leq \mathrm{nxy}.

(errno :math:1)
On entry, :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mw}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{ish} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\left\lvert \mathrm{ish}\right\rvert \leq \mathrm{mw}.

(errno :math:1)
On entry, :math:\mathrm{iw} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iw} = 1, :math:2, :math:3 or :math:4.

(errno :math:1)
On entry, :math:\mathrm{nxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nxy}\geq 1.

(errno :math:2)
On entry, :math:\mathrm{kc} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{nxy} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{nc} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ic} = 0, :math:\mathrm{kc}\geq \mathrm{nxy}+\textit{nc}.

(errno :math:3)
On entry, :math:\mathrm{l} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{l} \geq {2\times \mathrm{mw}-1}.

.. _g13cc-py2-py-notes:

**Notes**
The smoothed sample cross spectrum is a complex valued function of frequency :math:\omega, :math:f_{{xy}}\left(\omega \right) = cf\left(\omega \right)+iqf\left(\omega \right), defined by its real part or co-spectrum

.. math::
cf\left(\omega \right) = \frac{1}{{2\pi }}\sum_{{k = -M+1}}^{{M-1}}w_kC_{{xy}}\left(k+S\right)\cos\left(\omega k\right)

and imaginary part or quadrature spectrum

.. math::
qf\left(\omega \right) = \frac{1}{{2\pi }}\sum_{{k = -M+1}}^{{M-1}}w_kC_{{xy}}\left(k+S\right)\sin\left(\omega k\right)

where :math:w_{\textit{k}} = w_{{-\textit{k}}}, for :math:\textit{k} = 0,1,\ldots,M-1, is the smoothing lag window as defined in the description of :meth:uni_spectrum_lag.
The alignment shift :math:S is recommended to be chosen as the lag :math:k at which the cross-covariances :math:c_{{xy}}\left(k\right) peak, so as to minimize bias.

The results are calculated for frequency values

.. math::
\omega_j = \frac{{2\pi j}}{L}\text{, }\quad j = 0,1,\ldots,\left[L/2\right]\text{,}

where :math:\left[\right] denotes the integer part.

The cross-covariances :math:c_{{xy}}\left(k\right) may be supplied by you, or constructed from supplied series :math:x_1,x_2,\ldots,x_n; :math:y_1,y_2,\ldots,y_n as

.. math::
c_{{xy}}\left(k\right) = \frac{{\sum_{{t = 1}}^{{n-k}}x_ty_{{t+k}}}}{n}\text{, }\quad k\geq 0

.. math::
c_{{xy}}\left(k\right) = \frac{{\sum_{{t = 1-k}}^nx_ty_{{t+k}}}}{n} = c_{{yx}}\left(-k\right)\text{, }\quad k < 0

this convolution being carried out using the finite Fourier transform.

The supplied series may be mean and trend corrected and tapered before calculation of the cross-covariances, in exactly the manner described in :meth:uni_spectrum_lag for univariate spectrum estimation.
The results are corrected for any bias due to tapering.

The bandwidth associated with the estimates is not returned.
It will normally already have been calculated in previous calls of :meth:uni_spectrum_lag for estimating the univariate spectra of :math:y_t and :math:x_t.

.. _g13cc-py2-py-references:

**References**
Bloomfield, P, 1976, Fourier Analysis of Time Series: An Introduction, Wiley

Jenkins, G M and Watts, D G, 1968, Spectral Analysis and its Applications, Holden--Day
"""
raise NotImplementedError

[docs]def multi_spectrum_daniell(nxy, mtxy, pxy, mw, ish, pw, l, xg, yg):
r"""
multi_spectrum_daniell calculates the smoothed sample cross spectrum of a bivariate time series using spectral smoothing by the trapezium frequency (Daniell) window.

.. _g13cd-py2-py-doc:

For full information please refer to the NAG Library document for g13cd

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13cdf.html

.. _g13cd-py2-py-parameters:

**Parameters**
**nxy** : int
:math:n, the length of the time series :math:x and :math:y.

**mtxy** : int
Whether the data is to be initially mean or trend corrected.

:math:\mathrm{mtxy} = 0

For no correction.

:math:\mathrm{mtxy} = 1

For mean correction.

:math:\mathrm{mtxy} = 2

For trend correction.

**pxy** : float
The proportion of the data (totalled over both ends) to be initially tapered by the split cosine bell taper.

A value of :math:0.0 implies no tapering.

**mw** : int
:math:M, the frequency width of the smoothing window as :math:\frac{{2\pi }}{M}.

A value of :math:n implies that no smoothing is to be carried out.

**ish** : int
:math:S, the alignment shift between the :math:x and :math:y series. If :math:x leads :math:y, the shift is positive.

**pw** : float
:math:p, the shape parameter of the trapezium frequency window.

A value of :math:0.0 gives a triangular window, and a value of :math:1.0 a rectangular window.

If :math:\mathrm{mw} = \mathrm{nxy} (i.e., no smoothing is carried out) then :math:\mathrm{pw} is not used.

**l** : int
:math:L, the frequency division of smoothed cross spectral estimates as :math:\frac{{2\pi }}{L}.

**xg** : float, array-like, shape :math:\left(\textit{kc}\right)
The :math:\mathrm{nxy} data points of the :math:x series.

**yg** : float, array-like, shape :math:\left(\textit{kc}\right)
The :math:\mathrm{nxy} data points of the :math:y series.

**Returns**
**xg** : float, ndarray, shape :math:\left(\textit{kc}\right)
The real parts of the :math:\mathrm{ng} cross spectral estimates in elements :math:\mathrm{xg}[0] to :math:\mathrm{xg}[\mathrm{ng}-1], and :math:\mathrm{xg}[\mathrm{ng}] to :math:\mathrm{xg}[\textit{kc}-1] contain :math:0.0. The :math:y series leads the :math:x series.

**yg** : float, ndarray, shape :math:\left(\textit{kc}\right)
The imaginary parts of the :math:\mathrm{ng} cross spectral estimates in elements :math:\mathrm{yg}[0] to :math:\mathrm{yg}[\mathrm{ng}-1], and :math:\mathrm{yg}[\mathrm{ng}] to :math:\mathrm{yg}[\textit{kc}-1] contain :math:0.0. The :math:y series leads the :math:x series.

**ng** : int
The number of spectral estimates, :math:\left[L/2\right]+1, whose separate parts are held in :math:\mathrm{xg} and :math:\mathrm{yg}.

.. _g13cd-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{ish} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{l} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\left\lvert \mathrm{ish}\right\rvert < \mathrm{l}.

(errno :math:1)
On entry, :math:\mathrm{l} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{l}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{pxy} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pw} > 1.0, :math:\mathrm{mw} = \mathrm{nxy}.

(errno :math:1)
On entry, :math:\mathrm{pxy} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pw} < 0.0, :math:\mathrm{mw} = \mathrm{nxy}.

(errno :math:1)
On entry, :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mw}\leq \mathrm{nxy}.

(errno :math:1)
On entry, :math:\mathrm{mw} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mw}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{pxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{pxy}\leq 1.0.

(errno :math:1)
On entry, :math:\mathrm{pxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{pxy}\geq 0.0.

(errno :math:1)
On entry, :math:\mathrm{mtxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mtxy} \leq 2.

(errno :math:1)
On entry, :math:\mathrm{mtxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mtxy}\geq 0.

(errno :math:1)
On entry, :math:\mathrm{nxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nxy}\geq 1.

(errno :math:2)
On entry, :math:\textit{kc} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{l} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{kc} must be a multiple of :math:\mathrm{l}.

(errno :math:2)
On entry, :math:\textit{kc} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nxy} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{kc} \geq {2\times \mathrm{nxy}}.

.. _g13cd-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

The supplied time series may be mean and trend corrected and tapered as in the description of :meth:uni_spectrum_daniell before calculation of the unsmoothed sample cross-spectrum

.. math::
f_{{xy}}^*\left(\omega \right) = \frac{1}{{2\pi n}}\left\{\sum_{{t = 1}}^ny_t\mathrm{exp}\left(i\omega t\right)\right\}\times \left\{\sum_{{t = 1}}^nx_t\mathrm{exp}\left(-i\omega t\right)\right\}

for frequency values :math:\omega_j = \frac{{2\pi j}}{K}, :math:0\leq \omega_j\leq \pi.

A correction is made for bias due to any tapering.

As in the description of :meth:uni_spectrum_daniell for univariate frequency window smoothing, the smoothed spectrum is returned as a subset of these frequencies,

.. math::
\nu_l = \frac{{2\pi l}}{L}\text{, }\quad l = 0,1,\ldots,\left[L/2\right]

where [ ] denotes the integer part.

Its real part or co-spectrum :math:cf\left(\nu_l\right), and imaginary part or quadrature spectrum :math:qf\left(\nu_l\right) are defined by

.. math::
f_{{xy}}\left(\nu_l\right) = cf\left(\nu_l\right)+iqf\left(\nu_l\right) = \sum_{{\left\lvert \omega_k\right\rvert < \frac{\pi }{M}}}\tilde{w}_kf_{{xy}}^*\left(\nu_l+\omega_k\right)

where the weights :math:\tilde{w}_k are similar to the weights :math:w_k defined for :meth:uni_spectrum_daniell, but allow for an implicit alignment shift :math:S between the series:

.. math::
\tilde{w}_k = w_k\mathrm{exp}\left(-2\pi iSk/L\right)\text{.}

It is recommended that :math:S is chosen as the lag :math:k at which the cross-covariances :math:c_{{xy}}\left(k\right) peak, so as to minimize bias.

If no smoothing is required, the integer :math:M, which determines the frequency window width :math:\frac{{2\pi }}{M}, should be set to :math:n.

The bandwidth of the estimates will normally have been calculated in a previous call of :meth:uni_spectrum_daniell for estimating the univariate spectra of :math:y_t and :math:x_t.

.. _g13cd-py2-py-references:

**References**
Bloomfield, P, 1976, Fourier Analysis of Time Series: An Introduction, Wiley

Jenkins, G M and Watts, D G, 1968, Spectral Analysis and its Applications, Holden--Day
"""
raise NotImplementedError

[docs]def multi_spectrum_bivar(xg, yg, xyrg, xyig, stats):
r"""
For a bivariate time series, multi_spectrum_bivar calculates the cross amplitude spectrum and squared coherency, together with lower and upper bounds from the univariate and bivariate (cross) spectra.

.. _g13ce-py2-py-doc:

For full information please refer to the NAG Library document for g13ce

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13cef.html

.. _g13ce-py2-py-parameters:

**Parameters**
**xg** : float, array-like, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} univariate spectral estimates, :math:f_{{xx}}\left(\omega \right), for the :math:x series.

**yg** : float, array-like, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} univariate spectral estimates, :math:f_{{yy}}\left(\omega \right), for the :math:y series.

**xyrg** : float, array-like, shape :math:\left(\textit{ng}\right)
The real parts, :math:cf\left(\omega \right), of the :math:\textit{ng} bivariate spectral estimates for the :math:x and :math:y series. The :math:x series leads the :math:y series.

**xyig** : float, array-like, shape :math:\left(\textit{ng}\right)
The imaginary parts, :math:qf\left(\omega \right), of the :math:\textit{ng} bivariate spectral estimates for the :math:x and :math:y series. The :math:x series leads the :math:y series.

**Note:** the two univariate and the bivariate spectra must each have been calculated using the same method of smoothing.

For rectangular, Bartlett, Tukey or Parzen smoothing windows, the same cut-off point of lag window and the same frequency division of the spectral estimates must be used.

For the trapezium frequency smoothing window, the frequency width and the shape of the window and the frequency division of the spectral estimates must be the same.

The spectral estimates and statistics must also be unlogged.

**stats** : float, array-like, shape :math:\left(4\right)
The four associated statistics for the univariate spectral estimates for the :math:x and :math:y series. :math:\mathrm{stats}[0] contains the degrees of freedom, :math:\mathrm{stats}[1] and :math:\mathrm{stats}[2] contain the lower and upper bound multiplying factors respectively and :math:\mathrm{stats}[3] contains the bandwidth.

**Returns**
**ca** : float, ndarray, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} cross amplitude spectral estimates :math:\hat{A}\left(\omega \right) at each frequency of :math:\omega.

**calw** : float, ndarray, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} lower bounds for the :math:\textit{ng} cross amplitude spectral estimates.

**caup** : float, ndarray, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} upper bounds for the :math:\textit{ng} cross amplitude spectral estimates.

**t** : float
The critical value for the significance of the squared coherency, :math:T.

**sc** : float, ndarray, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} squared coherency estimates, :math:\hat{W}\left(\omega \right) at each frequency :math:\omega.

**sclw** : float, ndarray, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} lower bounds for the :math:\textit{ng} squared coherency estimates.

**scup** : float, ndarray, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} upper bounds for the :math:\textit{ng} squared coherency estimates.

.. _g13ce-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{stats}[2] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{stats}[2]\geq 1.0.

(errno :math:1)
On entry, :math:\mathrm{stats}[1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{stats}[1]\leq 1.0.

(errno :math:1)
On entry, :math:\mathrm{stats}[1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{stats}[1] > 0.0.

(errno :math:1)
On entry, :math:\mathrm{stats}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{stats}[0]\geq 3.0.

(errno :math:1)
On entry, :math:\textit{ng} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ng}\geq 1.

**Warns**
**NagAlgorithmicWarning**
(errno :math:2)
A bivariate spectral estimate is zero.

(errno :math:3)
A univariate spectral estimate is negative.

(errno :math:4)
A univariate spectral estimate is zero.

(errno :math:5)
A calculated value of the squared coherency exceeds :math:1.0.

.. _g13ce-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

Estimates of the cross amplitude spectrum :math:A\left(\omega \right) and squared coherency :math:W\left(\omega \right) are calculated for each frequency :math:\omega as

.. math::
\begin{array}{l}A\left(\omega \right) = \left\lvert f_{{xy}}\left(\omega \right)\right\rvert = \sqrt{cf\left(\omega \right)^2+qf\left(\omega \right)^2}\quad \text{ and}\\\\W\left(\omega \right) = \frac{\left\lvert f_{{xy}}\left(\omega \right)\right\rvert^2}{{f_{{xx}}\left(\omega \right)f_{{yy}}\left(\omega \right)}}\text{,}\end{array}

where

:math:cf\left(\omega \right) and :math:qf\left(\omega \right) are the co-spectrum and quadrature spectrum estimates between the series, i.e., the real and imaginary parts of the cross spectrum :math:f_{{xy}}\left(\omega \right) as obtained using :meth:multi_spectrum_lag or :meth:multi_spectrum_daniell;

:math:f_{{xx}}\left(\omega \right) and :math:f_{{yy}}\left(\omega \right) are the univariate spectrum estimates for the two series as obtained using :meth:uni_spectrum_lag or :meth:uni_spectrum_daniell.

The same type and amount of smoothing should be used for these estimates, and this is specified by the degrees of freedom and bandwidth values which are passed from the calls of :meth:uni_spectrum_lag or :meth:uni_spectrum_daniell.

Upper and lower :math:95\% confidence limits for the cross amplitude are given approximately by

.. math::
A\left(\omega \right)\left[1\pm \left(1.96/\sqrt{d}\right)\sqrt{W\left(\omega \right)^{-1}+1}\right]\text{,}

except that a negative lower limit is reset to :math:0.0, in which case the approximation is rather poor.
You are, therefore, particularly recommended to compare the coherency estimate :math:W\left(\omega \right) with the critical value :math:T derived from the upper :math:5\% point of the :math:F-distribution on :math:\left(2, {d-2}\right) degrees of freedom:

.. math::
T = \frac{{2F}}{{d-2+2F}}\text{,}

where :math:d is the degrees of freedom associated with the univariate spectrum estimates.
The value of :math:T is returned by the function.

The hypothesis that the series are unrelated at frequency :math:\omega, i.e., that both the true cross amplitude and coherency are zero, may be rejected at the :math:5\% level if :math:W\left(\omega \right) > T.
Tests at two frequencies separated by more than the bandwidth may be taken to be independent.

The confidence limits on :math:A\left(\omega \right) are strictly appropriate only at frequencies for which the coherency is significant.
The same applies to the confidence limits on :math:W\left(\omega \right) which are however calculated at all frequencies using the approximation that :math:\mathrm{arctanh}\left(\sqrt{W\left(l\right)}\right) is Normal with variance :math:1/d.

.. _g13ce-py2-py-references:

**References**
Bloomfield, P, 1976, Fourier Analysis of Time Series: An Introduction, Wiley

Jenkins, G M and Watts, D G, 1968, Spectral Analysis and its Applications, Holden--Day
"""
raise NotImplementedError

[docs]def multi_gain_bivar(xg, yg, xyrg, xyig, stats):
r"""
For a bivariate time series, multi_gain_bivar calculates the gain and phase together with lower and upper bounds from the univariate and bivariate spectra.

.. _g13cf-py2-py-doc:

For full information please refer to the NAG Library document for g13cf

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13cff.html

.. _g13cf-py2-py-parameters:

**Parameters**
**xg** : float, array-like, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} univariate spectral estimates, :math:f_{{xx}}\left(\omega \right), for the :math:x series.

**yg** : float, array-like, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} univariate spectral estimates, :math:f_{{yy}}\left(\omega \right), for the :math:y series.

**xyrg** : float, array-like, shape :math:\left(\textit{ng}\right)
The real parts, :math:cf\left(\omega \right), of the :math:\textit{ng} bivariate spectral estimates for the :math:x and :math:y series. The :math:x series leads the :math:y series.

**xyig** : float, array-like, shape :math:\left(\textit{ng}\right)
The imaginary parts, :math:qf\left(\omega \right), of the :math:\textit{ng} bivariate spectral estimates for the :math:x and :math:y series. The :math:x series leads the :math:y series.

**Note:** the two univariate and the bivariate spectra must each have been calculated using the same method of smoothing.

For rectangular, Bartlett, Tukey or Parzen smoothing windows, the same cut-off point of lag window and the same frequency division of the spectral estimates must be used.

For the trapezium frequency smoothing window, the frequency width and the shape of the window and the frequency division of the spectral estimates must be the same.

The spectral estimates and statistics must also be unlogged.

**stats** : float, array-like, shape :math:\left(4\right)
The four associated statistics for the univariate spectral estimates for the :math:x and :math:y series. :math:\mathrm{stats}[0] contains the degrees of freedom, :math:\mathrm{stats}[1] and :math:\mathrm{stats}[2] contain the lower and upper bound multiplying factors respectively and :math:\mathrm{stats}[3] holds the bandwidth.

**Returns**
**gn** : float, ndarray, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} gain estimates, :math:\hat{G}\left(\omega \right), at each frequency :math:\omega.

**gnlw** : float, ndarray, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} lower bounds for the :math:\textit{ng} gain estimates.

**gnup** : float, ndarray, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} upper bounds for the :math:\textit{ng} gain estimates.

**ph** : float, ndarray, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} phase estimates, :math:\hat{\phi }\left(\omega \right), at each frequency :math:\omega.

**phlw** : float, ndarray, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} lower bounds for the :math:\textit{ng} phase estimates.

**phup** : float, ndarray, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} upper bounds for the :math:\textit{ng} phase estimates.

.. _g13cf-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{stats}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{stats}[0]\geq 3.0.

(errno :math:1)
On entry, :math:\textit{ng} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ng}\geq 1.

**Warns**
**NagAlgorithmicWarning**
(errno :math:2)
A bivariate spectral estimate is zero.

(errno :math:3)
A univariate spectral estimate is negative.

(errno :math:4)
A univariate spectral estimate is zero.

(errno :math:5)
A calculated value of the squared coherency exceeds :math:1.0.

.. _g13cf-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

Estimates of the gain :math:G\left(\omega \right) and phase :math:\phi \left(\omega \right) of the dependency of series :math:y on series :math:x at frequency :math:\omega are given by

.. math::
\begin{array}{ll}\hat{G}\left(\omega \right) = \frac{{A\left(\omega \right)}}{{f_{{xx}}\left(\omega \right)}}&\\&\\\hat{\phi }\left(\omega \right) = \arccos\left(\frac{{cf\left(\omega \right)}}{{A\left(\omega \right)}}\right)\text{,}&\text{if }qf\left(\omega \right)\geq 0\\&\\\hat{\phi }\left(\omega \right) = 2\pi -\arccos\left(\frac{{cf\left(\omega \right)}}{{A\left(\omega \right)}}\right)\text{,}&\text{if }qf\left(\omega \right) < 0\text{.}\end{array}

The quantities used in these definitions are obtained as in :ref:Notes for multi_spectrum_bivar <g13ce-py2-py-notes>.

Confidence limits are returned for both gain and phase, but should again be taken as very approximate when the coherency :math:W\left(\omega \right), as calculated by :meth:multi_spectrum_bivar, is not significant.
These are based on the assumption that both :math:\left(\hat{G}\left(\omega \right)/G\left(\omega \right)\right)-1 and :math:\hat{\phi }\left(\omega \right) are Normal with variance

.. math::
\frac{1}{d}\left(\frac{1}{{W\left(\omega \right)}}-1\right)\text{.}

Although the estimate of :math:\phi \left(\omega \right) is always given in the range :math:\left[0, {2\pi }\right), no attempt is made to restrict its confidence limits to this range.

.. _g13cf-py2-py-references:

**References**
Bloomfield, P, 1976, Fourier Analysis of Time Series: An Introduction, Wiley

Jenkins, G M and Watts, D G, 1968, Spectral Analysis and its Applications, Holden--Day
"""
raise NotImplementedError

[docs]def multi_noise_bivar(xg, yg, xyrg, xyig, stats, l, n):
r"""
For a bivariate time series, multi_noise_bivar calculates the noise spectrum together with multiplying factors for the bounds and the impulse response function and its standard error, from the univariate and bivariate spectra.

.. _g13cg-py2-py-doc:

For full information please refer to the NAG Library document for g13cg

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13cgf.html

.. _g13cg-py2-py-parameters:

**Parameters**
**xg** : float, array-like, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} univariate spectral estimates, :math:f_{{xx}}\left(\omega \right), for the :math:x series.

**yg** : float, array-like, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} univariate spectral estimates, :math:f_{{yy}}\left(\omega \right), for the :math:y series.

**xyrg** : float, array-like, shape :math:\left(\textit{ng}\right)
The real parts, :math:cf\left(\omega \right), of the :math:\textit{ng} bivariate spectral estimates for the :math:x and :math:y series. The :math:x series leads the :math:y series.

**xyig** : float, array-like, shape :math:\left(\textit{ng}\right)
The imaginary parts, :math:qf\left(\omega \right), of the :math:\textit{ng} bivariate spectral estimates for the :math:x and :math:y series. The :math:x series leads the :math:y series.

**Note:** the two univariate and the bivariate spectra must each have been calculated using the same method of smoothing.

For rectangular, Bartlett, Tukey or Parzen smoothing windows, the same cut-off point of lag window and the same frequency division of the spectral estimates must be used.

For the trapezium frequency smoothing window, the frequency width and the shape of the window and the frequency division of the spectral estimates must be the same.

The spectral estimates and statistics must also be unlogged.

**stats** : float, array-like, shape :math:\left(4\right)
The four associated statistics for the univariate spectral estimates for the :math:x and :math:y series. :math:\mathrm{stats}[0] contains the degree of freedom, :math:\mathrm{stats}[1] and :math:\mathrm{stats}[2] contain the lower and upper bound multiplying factors respectively and :math:\mathrm{stats}[3] contains the bandwidth.

**l** : int
:math:L, the frequency division of the spectral estimates as :math:\frac{{2\pi }}{L}. It is also the order of the FFT used to calculate the impulse response function. :math:\mathrm{l} must relate to the parameter :math:\textit{ng} by the relationship.

**n** : int
The number of points in each of the time series :math:x and :math:y. :math:\mathrm{n} should have the same value as :math:\textit{nxy} in the call of :meth:multi_spectrum_lag or :meth:multi_spectrum_daniell which calculated the smoothed sample cross spectrum. :math:\mathrm{n} is used in calculating the impulse response function standard error (:math:\mathrm{rfse}).

**Returns**
**er** : float, ndarray, shape :math:\left(\textit{ng}\right)
The :math:\textit{ng} estimates of the noise spectrum, :math:\hat{f}_{{y | x}}\left(\omega \right) at each frequency.

**erlw** : float
The noise spectrum lower limit multiplying factor.

**erup** : float
The noise spectrum upper limit multiplying factor.

**rf** : float, ndarray, shape :math:\left(\mathrm{l}\right)
The impulse response function. Causal responses are stored in ascending frequency in :math:\mathrm{rf}[0] to :math:\mathrm{rf}[\textit{ng}-1] and anticipatory responses are stored in descending frequency in :math:\mathrm{rf}[\textit{ng}] to :math:\mathrm{rf}[\mathrm{l}-1].

**rfse** : float
The impulse response function standard error.

.. _g13cg-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n} \geq 1.

(errno :math:1)
On entry, :math:\mathrm{stats}[2] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{stats}[2]\geq 1.0.

(errno :math:1)
On entry, :math:\mathrm{stats}[1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{stats}[1]\leq 1.0.

(errno :math:1)
On entry, :math:\mathrm{stats}[1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{stats}[1] > 0.0.

(errno :math:1)
On entry, :math:\mathrm{stats}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{stats}[0]\geq 3.0.

(errno :math:1)
On entry, :math:\textit{ng} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ng}\geq 1.

(errno :math:6)
On entry, :math:\textit{ng} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{l} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ng} = \mathrm{l}/2+1.

**Warns**
**NagAlgorithmicWarning**
(errno :math:2)
A bivariate spectral estimate is zero.

For this frequency the noise spectrum is set to zero, and the contribution to the impulse response function and its standard error is set to zero.

(errno :math:3)
A univariate spectral estimate is negative.

For this frequency the noise spectrum is set to zero, and the contributions to the impulse response function and its standard error are set to zero.

(errno :math:4)
A univariate spectral estimate is zero.

For this frequency the noise spectrum is set to zero and the contributions to the impulse response function and its standard error are set to zero.

(errno :math:5)
A calculated value of the squared coherency exceeds :math:1.0.

For this frequency the squared coherency is reset to :math:1.0 with the consequence that the noise spectrum is zero and the contribution to the impulse response function at this frequency is zero.

.. _g13cg-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

An estimate of the noise spectrum in the dependence of series :math:y on series :math:x at frequency :math:\omega is given by

.. math::
f_{{y | x}}\left(\omega \right) = f_{{yy}}\left(\omega \right)\left(1-W\left(\omega \right)\right)\text{,}

where :math:W\left(\omega \right) is the squared coherency described in :meth:multi_spectrum_bivar and :math:f_{{yy}}\left(\omega \right) is the univariate spectrum estimate for series :math:y.
Confidence limits on the true spectrum are obtained using multipliers as described for :meth:uni_spectrum_lag, but based on :math:\left(d-2\right) degrees of freedom.

If the dependence of :math:y_t on :math:x_t can be assumed to be represented in the time domain by the one sided relationship

.. math::
y_t = v_0x_t+v_1x_{{t-1}} + \cdots +n_t\text{,}

where the noise :math:n_t is independent of :math:x_t, then it is the spectrum of this noise which is estimated by :math:f_{{y | x}}\left(\omega \right).

Estimates of the impulse response function :math:v_0,v_1,v_2,\ldots \text{} may also be obtained as

.. math::
v_k = \frac{1}{\pi }\int_0^{\pi }\mathrm{Re}\left(\frac{{\mathrm{exp}\left(ik\omega \right)f_{{xy}}\left(\omega \right)}}{{f_{{xx}}\left(\omega \right)}}\right)\text{,}

where :math:\textit{Re} indicates the real part of the expression.
For this purpose it is essential that the univariate spectrum for :math:x, :math:f_{{xx}}\left(\omega \right), and the cross spectrum, :math:f_{{xy}}\left(\omega \right), be supplied to this function for a frequency range

.. math::
\omega_l = \left[\frac{{2\pi l}}{L}\right]\text{, }\quad 0\leq l\leq \left[L/2\right]\text{,}

where :math:\left[\right] denotes the integer part, the integral being approximated by a finite Fourier transform.

An approximate standard error is calculated for the estimates :math:v_k.
Significant values of :math:v_k in the locations described as anticipatory responses in the argument array :math:\mathrm{rf} indicate that feedback exists from :math:y_t to :math:x_t.
This will bias the estimates of :math:v_k in any causal dependence of :math:y_t on :math:x_t,x_{{t-1}},\ldots \text{}.

.. _g13cg-py2-py-references:

**References**
Bloomfield, P, 1976, Fourier Analysis of Time Series: An Introduction, Wiley

Jenkins, G M and Watts, D G, 1968, Spectral Analysis and its Applications, Holden--Day
"""
raise NotImplementedError

[docs]def multi_autocorr_part(c0, c, nk):
r"""
multi_autocorr_part calculates the multivariate partial autocorrelation function of a multivariate time series.

.. _g13db-py2-py-doc:

For full information please refer to the NAG Library document for g13db

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dbf.html

.. _g13db-py2-py-parameters:

**Parameters**
**c0** : float, array-like, shape :math:\left(\textit{ns}, \textit{ns}\right)
Contains the zero lag cross-covariances between the :math:\textit{ns} series as returned by :meth:multi_corrmat_cross. (:math:\mathrm{c0} is assumed to be symmetric, upper triangle only is used.)

**c** : float, array-like, shape :math:\left(\textit{ns}, \textit{ns}, \textit{nl}\right)
Contains the cross-covariances at lags :math:1 to :math:\textit{nl}. :math:\mathrm{c}[i-1,j-1,k-1] must contain the cross-covariance, :math:c_{{ijk}}, of series :math:i and series :math:j at lag :math:k. Series :math:j leads series :math:i.

**nk** : int
The number of lags to which partial auto-correlations are to be calculated.

**Returns**
**p** : float, ndarray, shape :math:\left(\mathrm{nvp}\right)
The multiple squared partial autocorrelations from lags :math:1 to :math:\mathrm{nvp}; that is, :math:\mathrm{p}[l-1] contains :math:p_{\textit{l}}^2, for :math:\textit{l} = 1,2,\ldots,\mathrm{nvp}. For lags :math:\mathrm{nvp}+1 to :math:\mathrm{nk} the elements of :math:\mathrm{p} are set to zero.

**v0** : float
The lag zero prediction error variance (equal to the determinant of :math:\mathrm{c0}).

**v** : float, ndarray, shape :math:\left(\mathrm{nvp}\right)
The prediction error variance ratios from lags :math:1 to :math:\mathrm{nvp}; that is, :math:\mathrm{v}[\textit{l}-1] contains :math:v_{\textit{l}}, for :math:\textit{l} = 1,2,\ldots,\mathrm{nvp}. For lags :math:\mathrm{nvp}+1 to :math:\mathrm{nk} the elements of :math:\mathrm{v} are set to zero.

**d** : float, ndarray, shape :math:\left(\textit{ns}, \textit{ns}, \mathrm{nk}\right)
The prediction error variance matrices at lags :math:1 to :math:\mathrm{nvp}.

Element :math:\left(i, j, \textit{k}\right) of :math:\mathrm{d} contains the prediction error covariance of series :math:i and series :math:j at lag :math:\textit{k}, for :math:\textit{k} = 1,2,\ldots,\mathrm{nvp}.

Series :math:j leads series :math:i; that is, the :math:\left(i, j\right)\ th element of :math:D_k.

For lags :math:\mathrm{nvp}+1 to :math:\mathrm{nk} the elements of :math:\mathrm{d} are set to zero.

**db** : float, ndarray, shape :math:\left(\textit{ns}, \textit{ns}\right)
The backward prediction error variance matrix at lag :math:\mathrm{nvp}.

:math:\mathrm{db}[i-1,j-1] contains the backward prediction error covariance of series :math:i and series :math:j; that is, the :math:\left(i, j\right)\ th element of the :math:G_k, where :math:k = \mathrm{nvp}.

**w** : float, ndarray, shape :math:\left(\textit{ns}, \textit{ns}, \mathrm{nk}\right)
The prediction coefficient matrices at lags :math:1 to :math:\mathrm{nvp}.

:math:\mathrm{w}[i-1,j-1,\textit{l}-1] contains the :math:j\ th prediction coefficient of series :math:i at lag :math:\textit{l}; that is, the :math:\left(i, j\right)\ th element of :math:\Phi_{{k\textit{l}}}, where :math:k = \mathrm{nvp}, for :math:\textit{l} = 1,2,\ldots,\mathrm{nvp}.

For lags :math:\mathrm{nvp}+1 to :math:\mathrm{nk} the elements of :math:\mathrm{w} are set to zero.

**wb** : float, ndarray, shape :math:\left(\textit{ns}, \textit{ns}, \mathrm{nk}\right)
The backward prediction coefficient matrices at lags :math:1 to :math:\mathrm{nvp}.

:math:\mathrm{wb}[i-1,j-1,\textit{l}-1] contains the :math:j\ th backward prediction coefficient of series :math:i at lag :math:\textit{l}; that is, the :math:\left(i, j\right)\ th element of :math:\Psi_{{k\textit{l}}}, where :math:k = \mathrm{nvp}, for :math:\textit{l} = 1,2,\ldots,\mathrm{nvp}.

For lags :math:\mathrm{nvp}+1 to :math:\mathrm{nk} the elements of :math:\mathrm{wb} are set to zero.

**nvp** : int
The maximum lag, :math:L, for which calculation of :math:\mathrm{p}, :math:\mathrm{v}, :math:\mathrm{d}, :math:\mathrm{db}, :math:\mathrm{w} and :math:\mathrm{wb} was successful. If the function completes successfully :math:\mathrm{nvp} will equal :math:\mathrm{nk}.

.. _g13db-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{nk} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{nl} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nk}\leq \textit{nl}.

(errno :math:1)
On entry, :math:\mathrm{nk} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nk}\geq 1.

(errno :math:1)
On entry, :math:\textit{nl} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nl}\geq 1.

(errno :math:1)
On entry, :math:\textit{ns} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{ldc0} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ns}\leq \textit{ldc0}.

(errno :math:1)
On entry, :math:\textit{ns} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ns}\geq 1.

(errno :math:2)
:math:\mathrm{c0} is not positive definite.

**Warns**
**NagAlgorithmicWarning**
(errno :math:3)
For :math:\mathrm{nvp} = \langle\mathit{\boldsymbol{value}}\rangle, at lag :math:k = \mathrm{nvp}+1, :math:D_k was found not to be positive definite.

.. _g13db-py2-py-notes:

**Notes**
The input is a set of lagged autocovariance matrices :math:C_0,C_1,C_2,\ldots,C_m.
These will generally be sample values such as are obtained from a multivariate time series using :meth:multi_corrmat_cross.

The main calculation is the recursive determination of the coefficients in the finite lag (forward) prediction equation

.. math::
x_t = \Phi_{{l,1}}x_{{t-1}} + \cdots +\Phi_{{l,l}}x_{{t-l}}+e_{{l,t}}

and the associated backward prediction equation

.. math::
x_{{t-l-1}} = \Psi_{{l,1}}x_{{t-l}} + \cdots +\Psi_{{l,l}}x_{{t-1}}+f_{{l,t}}

together with the covariance matrices :math:D_l of :math:e_{{l,t}} and :math:G_l of :math:f_{{l,t}}.

The recursive cycle, by which the order of the prediction equation is extended from :math:l to :math:l+1, is to calculate

.. math::
M_{{l+1}} = C_{{l+1}}^\mathrm{T}-\Phi_{{l,1}}C_l^\mathrm{T} - \cdots -\Phi_{{l,l}} C_1^\mathrm{T}

then :math:\Phi_{{l+1,l+1}} = M_{{l+1}}D_l^{-1}, :math:\quad \text{ }\quad \Psi_{{l+1,l+1}} = M^\mathrm{T}_{{l+1}}G_l^{-1}

from which

.. math::
\Phi_{{l+1,j}} = \Phi_{{l,j}}-\Phi_{{l+1,l+1}}\Psi_{{l,l+1-j}}\text{, }\quad j = 1,2,\ldots,l

and

.. math::
\Psi_{{l+1,j}} = \Psi_{{l,j}}-\Psi_{{l+1,l+1}}\Phi_{{l,l+1-j}}\text{, }\quad j = 1,2,\ldots,l\text{.}

Finally, :math:D_{{l+1}} = D_l-M_{{l+1}}\Phi^\mathrm{T}_{{l+1,l+1}} and :math:G_{{l+1}} = G_l-M^\mathrm{T}_{{l+1}}\Psi^\mathrm{T}_{{l+1,l+1}}.

(Here :math:\mathrm{T} denotes the transpose of a matrix.)

The cycle is initialized by taking (for :math:l = 0)

.. math::
D_0 = G_0 = C_0\text{.}

In the step from :math:l = 0 to :math:1, the above equations contain redundant terms and simplify.
Thus (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dbf.html#eqn1>__ becomes :math:M_1 = C^\mathrm{T}_1 and neither (2) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dbf.html#eqn2>__ and (3) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dbf.html#eqn2>__ are needed.

Quantities useful in assessing the effectiveness of the prediction equation are generalized variance ratios

.. math::
v_l = \mathrm{det}\left(D_l\right)/\mathrm{det}\left(C_0\right)\text{, }\quad l = 1,2,\ldots

and multiple squared partial autocorrelations

.. math::
p_l^2 = 1-v_l/v_{{l-1}}\text{.}

.. _g13db-py2-py-references:

**References**
Akaike, H, 1971, Autoregressive model fitting for control, Ann. Inst. Statist. Math. (23), 163--180

Whittle, P, 1963, On the fitting of multivariate autoregressions and the approximate canonical factorization of a spectral density matrix, Biometrika (50), 129--134
"""
raise NotImplementedError

[docs]def multi_varma_estimate(ip, iq, mean, par, qq, w, parhld, exact, iprint, cgetol, ishow, maxcal=None, io_manager=None):
r"""
multi_varma_estimate fits a vector autoregressive moving average (VARMA) model to an observed vector of time series using the method of Maximum Likelihood (ML).
Standard errors of parameter estimates are computed along with their appropriate correlation matrix.
The function also calculates estimates of the residual series.

.. _g13dd-py2-py-doc:

For full information please refer to the NAG Library document for g13dd

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ddf.html

.. _g13dd-py2-py-parameters:

**Parameters**
**ip** : int
:math:p, the number of AR parameter matrices.

**iq** : int
:math:q, the number of MA parameter matrices.

**mean** : bool
:math:\mathrm{mean} = \mathbf{True}, if components of :math:\mu have been estimated and :math:\mathrm{mean} = \mathbf{False}, if all elements of :math:\mu are to be taken as zero.

**par** : float, array-like, shape :math:\left(\textit{npar}\right)
Initial parameter estimates read in row by row in the order :math:\phi_1,\phi_2,\ldots,\phi_p, :math:\theta_1,\theta_2,\ldots,\theta_q,\mu.

Thus,

if :math:\mathrm{ip} > 0, :math:\mathrm{par}[\left(\textit{l}-1\right)\times k\times k+\left(\textit{i}-1\right)\times k+\textit{j}-1] must be set equal to an initial estimate of the :math:\left(\textit{i}, \textit{j}\right)\ th element of :math:\phi_{\textit{l}}, for :math:\textit{j} = 1,2,\ldots,k, for :math:\textit{i} = 1,2,\ldots,k, for :math:\textit{l} = 1,2,\ldots,p;

if :math:\mathrm{iq} > 0, :math:\mathrm{par}[p\times k\times k+\left(l-1\right)\times k\times k+\left(i-1\right)\times k+j-1] must be set equal to an initial estimate of the :math:\left(i, j\right)\ th element of :math:\theta_l, :math:l = 1,2,\ldots,q and :math:i,j = 1,2,\ldots,k;

if :math:\mathrm{mean} = \mathbf{True}, :math:\mathrm{par}[\left(p+q\right)\times k\times k+i-1] should be set equal to an initial estimate of the :math:i\ th component of :math:\mu (:math:\mu \left(i\right)). (If you set :math:\mathrm{par}[\left(p+q\right)\times k\times k+i-1] to :math:0.0 then multi_varma_estimate will calculate the mean of the :math:i\ th series and use this as an initial estimate of :math:\mu \left(i\right).)

The first :math:p\times k\times k elements of :math:\mathrm{par} must satisfy the stationarity condition and the next :math:q\times k\times k elements of :math:\mathrm{par} must satisfy the invertibility condition.

If in doubt set all elements of :math:\mathrm{par} to :math:0.0.

**qq** : float, array-like, shape :math:\left(k, k\right)
:math:\mathrm{qq}[\textit{i}-1,\textit{j}-1] must be set equal to an initial estimate of the :math:\left(\textit{i}, \textit{j}\right)\ th element of :math:\Sigma. The lower triangle only is needed. :math:\mathrm{qq} must be positive definite. It is strongly recommended that on entry the elements of :math:\mathrm{qq} are of the same order of magnitude as at the solution point. If you set :math:\mathrm{qq}[\textit{i}-1,\textit{j}-1] = 0.0, for :math:\textit{j} = 1,2,\ldots,i, for :math:\textit{i} = 1,2,\ldots,k, then multi_varma_estimate will calculate the covariance matrix between the :math:k time series and use this as an initial estimate of :math:\Sigma.

**w** : float, array-like, shape :math:\left(k, n\right)
:math:\mathrm{w}[\textit{i}-1,\textit{t}-1] must be set equal to the :math:\textit{i}\ th component of :math:W_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,n, for :math:\textit{i} = 1,2,\ldots,k.

**parhld** : bool, array-like, shape :math:\left(\textit{npar}\right)
:math:\mathrm{parhld}[\textit{i}-1] must be set to :math:\mathbf{True} if :math:\mathrm{par}[\textit{i}-1] is to be held constant at its input value and :math:\mathbf{False} if :math:\mathrm{par}[\textit{i}-1] is a free parameter, for :math:\textit{i} = 1,2,\ldots,\textit{npar}.

If in doubt try setting all elements of :math:\mathrm{parhld} to :math:\mathbf{False}.

**exact** : bool
Must be set equal to :math:\mathbf{True} if you wish multi_varma_estimate to compute exact maximum likelihood estimates. :math:\mathrm{exact} must be set equal to :math:\mathbf{False} if only conditional likelihood estimates are required.

**iprint** : int
The frequency with which the automatic monitoring function is to be called.

:math:\mathrm{iprint} > 0

The ML search procedure is monitored once every :math:\mathrm{iprint} iterations and just before exit from the search function.

:math:\mathrm{iprint} = 0

The search function is monitored once at the final point.

:math:\mathrm{iprint} < 0

The search function is not monitored at all.

**cgetol** : float
The accuracy to which the solution in :math:\mathrm{par} and :math:\mathrm{qq} is required.

If :math:\mathrm{cgetol} is set to :math:10^{{-l}} and on exit no exception or warning is raised or :math:\mathrm{errno} >= 6, then all the elements in :math:\mathrm{par} and :math:\mathrm{qq} should be accurate to approximately :math:l decimal places.

For most practical purposes the value :math:10^{-4} should suffice.

You should be wary of setting :math:\mathrm{cgetol} too small since the convergence criteria may then have become too strict for the machine to handle.

If :math:\mathrm{cgetol} has been set to a value which is less than the machine precision, :math:\epsilon, then multi_varma_estimate will use the value :math:10.0\times \sqrt{\epsilon } instead.

**ishow** : int
Specifies which of the following two quantities are to be printed.

(i) table of maximum likelihood estimates and their standard errors (as returned in the output arrays :math:\mathrm{par}, :math:\mathrm{qq} and :math:\mathrm{cm});

(#) table of residual series (as returned in the output array :math:\mathrm{v}).

:math:\mathrm{ishow} = 0

None of the above are printed.

:math:\mathrm{ishow} = 1

\(i) only is printed.

:math:\mathrm{ishow} = 2

\(i) and (ii) are printed.

**maxcal** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:40\times \textit{npar}\times \left(\textit{npar}+5\right).

The maximum number of likelihood evaluations to be permitted by the search procedure.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**par** : float, ndarray, shape :math:\left(\textit{npar}\right)
If no exception or warning is raised or :math:\mathrm{errno} >= 4 then all the elements of :math:\mathrm{par} will be overwritten by the latest estimates of the corresponding ARMA parameters.

**qq** : float, ndarray, shape :math:\left(k, k\right)
If no exception or warning is raised or :math:\mathrm{errno} >= 4 then :math:\mathrm{qq}[i-1,j-1] will contain the latest estimate of the :math:\left(i, j\right)\ th element of :math:\Sigma. The lower triangle only is returned.

**niter** : int
If no exception or warning is raised or :math:\mathrm{errno} >= 4 then :math:\mathrm{niter} contains the number of iterations performed by the search function.

**rlogl** : float
If no exception or warning is raised or :math:\mathrm{errno} >= 4 then :math:\mathrm{rlogl} contains the value of the log-likelihood function corresponding to the final point held in :math:\mathrm{par} and :math:\mathrm{qq}.

**v** : float, ndarray, shape :math:\left(k, n\right)
If no exception or warning is raised or :math:\mathrm{errno} >= 4 then :math:\mathrm{v}[\textit{i}-1,\textit{t}-1] will contain an estimate of the :math:\textit{i}\ th component of :math:\epsilon_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,n, for :math:\textit{i} = 1,2,\ldots,k, corresponding to the final point held in :math:\mathrm{par} and :math:\mathrm{qq}.

**g** : float, ndarray, shape :math:\left(\textit{npar}\right)
If no exception or warning is raised or :math:\mathrm{errno} >= 4 then :math:\mathrm{g}[i-1] will contain the estimated first derivative of the log-likelihood function with respect to the :math:i\ th element in the array :math:\mathrm{par}. If the gradient cannot be computed then all the elements of :math:\mathrm{g} are returned as zero.

**cm** : float, ndarray, shape :math:\left(\textit{npar}, \textit{npar}\right)
If no exception or warning is raised or :math:\mathrm{errno} >= 4 then :math:\mathrm{cm}[i-1,j-1] will contain an estimate of the correlation coefficient between the :math:i\ th and :math:j\ th elements in the :math:\mathrm{par} array for :math:1\leq i\leq \textit{npar}, :math:1\leq j\leq \textit{npar}. If :math:i = j, then :math:\mathrm{cm}[i-1,j-1] will contain the estimated standard error of :math:\mathrm{par}[i-1]. If the :math:l\ th component of :math:\mathrm{par} has been held constant, i.e., :math:\mathrm{parhld}[l-1] was set to :math:\mathbf{True}, then the :math:l\ th row and column of :math:\mathrm{cm} will be set to zero. If the second derivative matrix cannot be computed then all the elements of :math:\mathrm{cm} are returned as zero.

.. _g13dd-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:k = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:k\geq 1.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npar}\geq 0.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle, :math:k = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\times k > \textit{npar}+k\times \left(k+1\right)/2.

(errno :math:1)
On entry, :math:\mathrm{ip} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ip}\geq 0.

(errno :math:1)
On entry, :math:\mathrm{iq} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iq}\geq 0.

(errno :math:1)
On entry, :math:\mathrm{ip} = 0 and :math:\mathrm{iq} = 0.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\mathrm{maxcal} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxcal}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{ishow} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:0\leq \mathrm{ishow}\leq 2.

(errno :math:2)
The initial estimate of :math:\Sigma is not positive definite.

(errno :math:2)
The initial AR parameter estimates are outside the stationarity region.

(errno :math:2)
The initial MA parameter estimates are outside the invertibility region.

(errno :math:2)
The starting point is too close to the boundary of the admissibility region.

(errno :math:3)
The function cannot compute a sufficiently accurate estimate of the gradient vector at the user-supplied starting point.

(errno :math:4)
There have been :math:\mathrm{maxcal} log-likelihood evaluations made in the function.

See the function document for further details.

**Warns**
**NagAlgorithmicWarning**
(errno :math:5)
The conditions for a solution have not all been met, but a point at which the log-likelihood took a larger value could not be found.

See the function document for further details.

(errno :math:6)
The ML solution is so close to the boundary of either the stationarity region or the invertibility region that multi_varma_estimate cannot evaluate the Hessian matrix. The elements of :math:\mathrm{cm} are set to zero, as are the elements of :math:\mathrm{g}. All other output quantities are correct.

(errno :math:7)
An estimate of the second derivative matrix and the gradient vector at the solution point was computed. Either the Hessian matrix was found to be too ill-conditioned to be evaluated accurately or the gradient vector could not be computed to an acceptable degree of accuracy. The elements of :math:\mathrm{cm} are set to zero, as are the elements of :math:\mathrm{g}. All other output quantities are correct.

(errno :math:8)
The second-derivative matrix at the solution point is not positive definite. The elements of :math:\mathrm{cm} are set to zero. All other output quantities are correct.

.. _g13dd-py2-py-notes:

**Notes**
Let :math:W_{\textit{t}} = \left(w_{{1\textit{t}}}, w_{{2\textit{t}}}, \ldots, w_{{\textit{k}\textit{t}}}\right)^\mathrm{T}, for :math:\textit{t} = 1,2,\ldots,n, denote a vector of :math:k time series which is assumed to follow a multivariate ARMA model of the form

.. math::
\begin{array}{ll}W_t-\mu = &\phi_1\left(W_{{t-1}}-\mu \right)+\phi_2\left(W_{{t-2}}-\mu \right)+ \cdots +\phi_p\left(W_{{t-p}}-\mu \right)\\&+\epsilon_t-\theta_1\epsilon_{{t-1}}-\theta_2\epsilon_{{t-2}} - \cdots -\theta_q\epsilon_{{t-q}}\end{array}

where :math:\epsilon_{\textit{t}} = \left(\epsilon_{{1\textit{t}}}, \epsilon_{{2\textit{t}}}, \ldots, \epsilon_{{k\textit{t}}}\right)^\mathrm{T}, for :math:\textit{t} = 1,2,\ldots,n, is a vector of :math:k residual series assumed to be Normally distributed with zero mean and positive definite covariance matrix :math:\Sigma.
The components of :math:\epsilon_t are assumed to be uncorrelated at non-simultaneous lags.
The :math:\phi_i and :math:\theta_j are :math:k\times k matrices of parameters. :math:\left\{\phi_{\textit{i}}\right\}, for :math:\textit{i} = 1,2,\ldots,p, are called the autoregressive (AR) parameter matrices, and :math:\left\{\theta_{\textit{i}}\right\}, for :math:\textit{i} = 1,2,\ldots,q, the moving average (MA) parameter matrices.
The parameters in the model are thus the :math:p (:math:k\times k) :math:\phi-matrices, the :math:q (:math:k\times k) :math:\theta-matrices, the mean vector, :math:\mu, and the residual error covariance matrix :math:\Sigma.
Let

.. math::
A\left(\phi \right) = \left[\begin{array}{lllllll}\phi_1&I&0&.&.&.&0\\\phi_2&0&I&0&.&.&0\\.&&&.&&&\\.&&&&.&&\\.&&&&&.&\\\phi_{{p-1}}&0&.&.&.&0&I\\\phi_p&0&.&.&.&0&0\end{array}\right]_{{pk\times pk}}\quad \text{ and }\quad B\left(\theta \right) = \left[\begin{array}{lllllll}\theta_1&I&0&.&.&.&0\\\theta_2&0&I&0&.&.&0\\.&&&.&&&\\.&&&&.&&\\.&&&&&.&\\\theta_{{q-1}}&0&.&.&.&.&I\\\theta_q&0&.&.&.&.&0\end{array}\right]_{{qk\times qk}}

where :math:I denotes the :math:k\times k identity matrix.

The ARMA model (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ddf.html#eqn1>__ is said to be stationary if the eigenvalues of :math:A\left(\phi \right) lie inside the unit circle.
Similarly, the ARMA model (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ddf.html#eqn1>__ is said to be invertible if the eigenvalues of :math:B\left(\theta \right) lie inside the unit circle.

The method of computing the exact likelihood function (using a Kalman filter algorithm) is discussed in Shea (1987).
A quasi-Newton algorithm (see Gill and Murray (1972)) is then used to search for the maximum of the log-likelihood function.
Stationarity and invertibility are enforced on the model using the reparameterisation discussed in Ansley and Kohn (1986).
Conditional on the maximum likelihood estimates being equal to their true values the estimates of the residual series are uncorrelated with zero mean and constant variance :math:\Sigma.

You have the option of setting an argument (:math:\mathrm{exact} to :math:\mathbf{False}) so that multi_varma_estimate calculates conditional maximum likelihood estimates (conditional on :math:W_0 = W_{-1} = \cdots = W_{{1-p}} = \epsilon_0 = \epsilon_{-1} = \cdots = \epsilon_{{1-q}} = 0).
This may be useful if the exact maximum likelihood estimates are close to the boundary of the invertibility region.

You also have the option (see :ref:Parameters <g13dd-py2-py-parameters>) of requesting multi_varma_estimate to constrain elements of the :math:\phi and :math:\theta matrices and :math:\mu vector to have pre-specified values.

.. _g13dd-py2-py-references:

**References**
Ansley, C F and Kohn, R, 1986, A note on reparameterising a vector autoregressive moving average model to enforce stationarity, J. Statist. Comput. Simulation (24), 99--106

Gill, P E and Murray, W, 1972, Quasi-Newton methods for unconstrained optimization, J. Inst. Math. Appl. (9), 91--108

Shea, B L, 1987, Estimation of multivariate time series, J. Time Ser. Anal. (8), 95--110
"""
raise NotImplementedError

[docs]def multi_varma_forecast(z, tr, dord, delta, ip, iq, mean, par, qq, v, lmax, lref):
r"""
multi_varma_forecast computes forecasts of a multivariate time series.
It is assumed that a vector ARMA model has already been fitted to the appropriately differenced/transformed time series using :meth:multi_varma_estimate.
The standard deviations of the forecast errors are also returned.
A reference vector is set up so that, should future series values become available, the forecasts and their standard errors may be updated by calling :meth:multi_varma_update.

.. _g13dj-py2-py-doc:

For full information please refer to the NAG Library document for g13dj

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13djf.html

.. _g13dj-py2-py-parameters:

**Parameters**
**z** : float, array-like, shape :math:\left(k, n\right)
:math:\mathrm{z}[\textit{i},\textit{t}] must contain, :math:z_{{\textit{i}\textit{t}}}, the :math:\textit{i}\ th component of :math:Z_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,n, for :math:\textit{i} = 1,2,\ldots,k.

**tr** : str, length 1, array-like, shape :math:\left(k\right)
:math:\mathrm{tr}[\textit{i}-1] indicates whether the :math:\textit{i}\ th time series is to be transformed, for :math:\textit{i} = 1,2,\ldots,k.

:math:\mathrm{tr}[i-1] = \texttt{'N'}

No transformation is used.

:math:\mathrm{tr}[i-1] = \texttt{'L'}

A log transformation is used.

:math:\mathrm{tr}[i-1] = \texttt{'S'}

A square root transformation is used.

**dord** : int, array-like, shape :math:\left(k\right)
:math:\mathrm{dord}[i-1] must specify, :math:\textit{d}_i, the order of differencing required for the :math:i\ th series.

**delta** : float, array-like, shape :math:\left(k, \textit{d}\right)
If :math:\mathrm{dord}[i-1] > 0, then :math:\mathrm{delta}[\textit{i}-1,\textit{j}-1] must be set equal to :math:\delta_{{\textit{i}\textit{j}}}, for :math:\textit{i} = 1,2,\ldots,k, for :math:\textit{j} = 1,2,\ldots,\textit{d}_{\textit{i}}.

If :math:\textit{d} = 0, :math:\mathrm{delta} is not referenced.

**ip** : int
:math:p, the number of AR parameter matrices.

**iq** : int
:math:q, the number of MA parameter matrices.

**mean** : str, length 1
:math:\mathrm{mean} = \texttt{'M'}, if components of :math:\mu have been estimated and :math:\mathrm{mean} = \texttt{'Z'}, if all elements of :math:\mu are to be taken as zero.

**par** : float, array-like, shape :math:\left(\textit{lpar}\right)
Must contain the parameter estimates read in row by row in the order :math:\phi_1,\phi_2,\ldots,\phi_p, :math:\theta_1,\theta_2,\ldots,\theta_q, :math:\mu.

Thus,

if :math:\mathrm{ip} > 0, :math:\mathrm{par}[\left(\textit{l}-1\right)\times k\times k+\left(\textit{i}-1\right)\times k+\textit{j}-1] must be set equal to an estimate of the :math:\left(\textit{i}, \textit{j}\right)\ th element of :math:\phi_{\textit{l}}, for :math:\textit{j} = 1,2,\ldots,k, for :math:\textit{i} = 1,2,\ldots,k, for :math:\textit{l} = 1,2,\ldots,p;

if :math:\mathrm{iq} > 0, :math:\mathrm{par}[p\times k\times k+\left(\textit{l}-1\right)\times k\times k+\left(\textit{i}-1\right)\times k+\textit{j}-1] must be set equal to an estimate of the :math:\left(\textit{i}, \textit{j}\right)\ th element of :math:\theta_{\textit{l}}, for :math:\textit{j} = 1,2,\ldots,k, for :math:\textit{i} = 1,2,\ldots,k, for :math:\textit{l} = 1,2,\ldots,q;

if :math:\mathrm{mean} = \texttt{'M'}, :math:\mathrm{par}[\left(p+q\right)\times k\times k+\textit{i}-1] must be set equal to an estimate of the :math:\textit{i}\ th component of :math:\mu, for :math:\textit{i} = 1,2,\ldots,k.

**qq** : float, array-like, shape :math:\left(k, k\right)
:math:\mathrm{qq}[i-1,j-1] must contain an estimate of the :math:\left(i, j\right)\ th element of :math:\Sigma. The lower triangle only is needed.

**v** : float, array-like, shape :math:\left(k, n-\textit{d}\right)
:math:\mathrm{v}[\textit{i}-1,\textit{t}-1] must contain an estimate of the :math:\textit{i}\ th component of :math:\epsilon_{{\textit{t}+\textit{d}}}, for :math:\textit{t} = 1,2,\ldots,n-\textit{d}, for :math:\textit{i} = 1,2,\ldots,k.

If :math:q = 0, :math:\mathrm{v} is not used.

**lmax** : int
The number, :math:l_{\mathrm{max}}, of forecasts required.

**lref** : int
The dimension of the array :math:\mathrm{ref}.

**Returns**
**qq** : float, ndarray, shape :math:\left(k, k\right)
If :math:\mathrm{errno} != 1, then the upper triangle is set equal to the lower triangle.

**predz** : float, ndarray, shape :math:\left(k, \mathrm{lmax}\right)
:math:\mathrm{predz}[\textit{i}-1,\textit{l}-1] contains the forecast of :math:z_{{\textit{i},n+\textit{l}}}, for :math:\textit{l} = 1,2,\ldots,\textit{l}_{\mathrm{max}}, for :math:\textit{i} = 1,2,\ldots,k.

**sefz** : float, ndarray, shape :math:\left(k, \mathrm{lmax}\right)
:math:\mathrm{sefz}[\textit{i}-1,\textit{l}-1] contains an estimate of the standard error of the forecast of :math:z_{{\textit{i},n+\textit{l}}}, for :math:\textit{l} = 1,2,\ldots,\textit{l}_{\mathrm{max}}, for :math:\textit{i} = 1,2,\ldots,k.

**ref** : float, ndarray, shape :math:\left(\mathrm{lref}\right)
The reference vector which may be used to update forecasts using :meth:multi_varma_update. The first :math:\left(\mathrm{lmax}-1\right)\times k\times k elements contain the :math:\psi weight matrices, :math:\psi_1,\psi_2,\ldots,\psi_{{l_{\mathrm{max}}-1}}. The next :math:k\times \mathrm{lmax} elements contain the forecasts of the transformed series :math:\hat{Z}_{{n+1}}^*,\hat{Z}_{{n+2}}^*,\ldots,\hat{Z}_{{n+l_{\mathrm{max}}}}^* and the next :math:k\times \mathrm{lmax} contain the variances of the forecasts of the transformed variables. The last :math:\textit{k} elements are used to store the transformations for the series.

.. _g13dj-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{lref} = \langle\mathit{\boldsymbol{value}}\rangle and the minimum size :math:\text{required} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{lref}\geq \left(\mathrm{lmax}-1\right)\times k\times k+2\times k\times \mathrm{lmax}+k.

(errno :math:1)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{dord}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n-\mathrm{max}\left(\mathrm{ip}, \mathrm{iq}\right) = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:0\leq \mathrm{dord}[\textit{i}-1] < n-\mathrm{max}\left(\mathrm{ip}, \mathrm{iq}\right).

(errno :math:1)
On entry, :math:\mathrm{lmax} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{lmax} \geq 1.

(errno :math:1)
On entry, number of observations :math:\text{} = \langle\mathit{\boldsymbol{value}}\rangle and number of parameters :math:\text{} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: number of :math:\text{observations}\geq \text{number} of parameters.

(errno :math:1)
On entry, :math:\textit{lpar} is too small: :math:\textit{lpar} = \langle\mathit{\boldsymbol{value}}\rangle and the minimum size :math:\text{required} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\mathrm{mean} is an invalid character.

Constraint: :math:\mathrm{mean} = \texttt{'M'} or :math:\texttt{'Z'}.

(errno :math:1)
On entry, :math:\mathrm{iq} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iq} \geq 0.

(errno :math:1)
On entry, :math:\mathrm{ip} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ip} \geq 0.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n \geq 3.

(errno :math:1)
On entry, :math:k = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:k \geq 1.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{tr}[i-1] is invalid.

Constraint: :math:\mathrm{tr}[i-1] = \texttt{'N'}, :math:\texttt{'L'} or :math:\texttt{'S'}.

(errno :math:3)
On entry, one (or more) of the transformations requested is invalid.

(errno :math:4)
On entry, the MA parameter matrices are outside the invertibility region.

(errno :math:4)
On entry, the AR parameter matrices are outside the stationarity region.

(errno :math:4)
On entry, the covariance matrix :math:\mathrm{qq} is not positive definite.

(errno :math:5)
An excessive number of iterations were needed to evaluate the eigenvalues of the matrices used to test for stationarity and invertibility.

(errno :math:6)
The covariance matrix may be nearly non-positive definite.

(errno :math:7)
The forecasts will overflow if computed.

.. _g13dj-py2-py-notes:

**Notes**
Let the vector :math:Z_{\textit{t}} = \left(z_{{1\textit{t}}}, z_{{2\textit{t}}}, \ldots, z_{{k\textit{t}}}\right)^\mathrm{T}, for :math:\textit{t} = 1,2,\ldots,n, denote a :math:k-dimensional time series for which forecasts of :math:Z_{{n+1}},Z_{{n+2}},\ldots,Z_{{n+l_{\mathrm{max}}}} are required.
Let :math:W_t = \left(w_{{1t}}, w_{{2t}}, \ldots, w_{{kt}}\right)^\mathrm{T} be defined as follows:

.. math::
w_{{it}} = \delta_i\left(B\right)z_{{it}}^*\text{, }\quad i = 1,2,\ldots,k\text{,}

where :math:\delta_i\left(B\right) is the differencing operator applied to the :math:i\ th series and where :math:z_{{it}}^* is equal to either :math:z_{{it}}, :math:\sqrt{z_{{it}}} or :math:\mathrm{loge}\left(z_{{it}}\right) depending on whether or not a transformation was required to stabilize the variance before fitting the model.

If the order of differencing required for the :math:i\ th series is :math:\textit{d}_i, then the differencing operator for the :math:i\ th series is defined by :math:\delta_i\left(B\right) = 1-\delta_{{i1}}B-\delta_{{i2}}B^2 - \cdots -\delta_{{i\textit{d}_i}}B^{\textit{d}_i} where :math:B is the backward shift operator; that is, :math:BZ_t = Z_{{t-1}}.
The differencing parameters :math:\delta_{{\textit{i}\textit{j}}}, for :math:\textit{j} = 1,2,\ldots,\textit{d}_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k, must be supplied by you.
If the :math:i\ th series does not require differencing, then :math:\textit{d}_i = 0.

:math:W_t is assumed to follow a multivariate ARMA model of the form:

.. math::
W_t-\mu = \phi_1\left(W_{{t-1}}-\mu \right)+\phi_2\left(W_{{t-2}}-\mu \right)+ \cdots +\phi_p\left(W_{{t-p}}-\mu \right)+\epsilon_t-\theta_1\epsilon_{{t-1}} - \cdots -\theta_q\epsilon_{{t-q}}\text{,}

where :math:\epsilon_{\textit{t}} = \left(\epsilon_{{1\textit{t}}}, \epsilon_{{2\textit{t}}}, \ldots, \epsilon_{{k\textit{t}}}\right)^\mathrm{T}, for :math:\textit{t} = 1,2,\ldots,n, is a vector of :math:k residual series assumed to be Normally distributed with zero mean and positive definite covariance matrix :math:\Sigma.
The components of :math:\epsilon_t are assumed to be uncorrelated at non-simultaneous lags.
The :math:\phi_i and :math:\theta_j are :math:k\times k matrices of parameters.
The matrices :math:\phi_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,p, are the autoregressive (AR) parameter matrices, and the matrices :math:\theta_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q, the moving average (MA) parameter matrices.
The parameters in the model are thus the :math:p (:math:k\times k) :math:\phi-matrices, the :math:q (:math:k\times k) :math:\theta-matrices, the mean vector :math:\mu and the residual error covariance matrix :math:\Sigma.
The ARMA model (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13djf.html#eqn1>__ must be both stationary and invertible; see :meth:uni_arma_roots for a method of checking these conditions.

The ARMA model (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13djf.html#eqn1>__ may be rewritten as

.. math::
\phi \left(B\right)\left(\delta \left(B\right)Z_t^*-\mu \right) = \theta \left(B\right)\epsilon_t\text{,}

where :math:\phi \left(B\right) and :math:\theta \left(B\right) are the autoregressive and moving average polynomials and :math:\delta \left(B\right) denotes the :math:k\times k diagonal matrix whose :math:i\ th diagonal elements is :math:\delta_i\left(B\right) and :math:Z_t^* = \left(z_{{1t}}^*, {z_{{2t}}^*\ldots z_{{kt}}^*}\right)^\mathrm{T}.

This may be rewritten as

.. math::
\phi \left(B\right)\delta \left(B\right)Z_t^* = \phi \left(B\right)\mu +\theta \left(B\right)\epsilon_t

or

.. math::
Z_t^* = \tau +\psi \left(B\right)\epsilon_t = \tau +\epsilon_t+\psi_1\epsilon_{{t-1}}+\psi_2\epsilon_{{t-2}} + \cdots

where :math:\psi \left(B\right) = \delta^{-1}\left(B\right)\phi^{-1}\left(B\right)\theta \left(B\right) and :math:\tau = \delta^{-1}\left(B\right)\mu is a vector of length :math:k.

Forecasts are computed using a multivariate version of the procedure described in Box and Jenkins (1976).
If :math:\hat{Z}_n^*\left(l\right) denotes the forecast of :math:Z_{{n+l}}^*, then :math:\hat{Z}_n^*\left(l\right) is taken to be that linear function of :math:Z_n^*,Z_{{n-1}}^*,\ldots \text{} which minimizes the elements of :math:E\left\{e_n\left(l\right)e_n^{\prime }\left(l\right)\right\} where :math:e_n\left(l\right) = Z_{{n+l}}^*-\hat{Z}_n^*\left(l\right) is the forecast error. :math:\hat{Z}_n^*\left(l\right) is referred to as the linear minimum mean square error forecast of :math:Z_{{n+l}}^*.

The linear predictor which minimizes the mean square error may be expressed as

.. math::
\hat{Z}_n^*\left(l\right) = \tau +\psi_l\epsilon_n+\psi_{{l+1}}\epsilon_{{n-1}}+\psi_{{l+2}}\epsilon_{{n-2}} + \cdots \text{.}

The forecast error at :math:t for lead :math:l is then

.. math::
e_n\left(l\right) = Z_{{n+l}}^*-\hat{Z}_n^*\left(l\right) = \epsilon_{{n+l}}+\psi_1\epsilon_{{n+l-1}}+\psi_2\epsilon_{{n+l-2}} + \cdots +\psi_{{l-1}}\epsilon_{{n+1}}\text{.}

Let :math:\textit{d} = \mathrm{max}\left(\textit{d}_{\textit{i}}\right), for :math:\textit{i} = 1,2,\ldots,k.
Unless :math:q = 0 the function requires estimates of :math:\epsilon_{\textit{t}}, for :math:\textit{t} = \textit{d}+1,\ldots,n, which are obtainable from :meth:multi_varma_estimate.
The terms :math:\epsilon_{\textit{t}} are assumed to be zero, for :math:\textit{t} = n+1,\ldots,n+l_{\mathrm{max}}.
You may use :meth:multi_varma_update to update these :math:l_{\mathrm{max}} forecasts should further observations, :math:Z_{{n+1}},Z_{{n+2}},\ldots \text{}, become available.
Note that when :math:l_{\mathrm{max}} or more further observations are available then multi_varma_forecast must be used to produce new forecasts for :math:Z_{{n+l_{\mathrm{max}}+1}},Z_{{n+l_{\mathrm{max}}+2}},\ldots \text{}, should they be required.

When a transformation has been used the forecasts and their standard errors are suitably modified to give results in terms of the original series, :math:Z_t; see Granger and Newbold (1976).

.. _g13dj-py2-py-references:

**References**
Box, G E P and Jenkins, G M, 1976, Time Series Analysis: Forecasting and Control, (Revised Edition), Holden--Day

Granger, C W J and Newbold, P, 1976, Forecasting transformed series, J. Roy. Statist. Soc. Ser. B (38), 189--203

Wei, W W S, 1990, Time Series Analysis: Univariate and Multivariate Methods, Addison--Wesley
"""
raise NotImplementedError

[docs]def multi_varma_update(mlast, z, ref, predz, sefz):
r"""
multi_varma_update accepts a sequence of new observations in a multivariate time series and updates both the forecasts and the standard deviations of the forecast errors.
A call to :meth:multi_varma_forecast must be made prior to calling this function in order to calculate the elements of a reference vector together with a set of forecasts and their standard errors.
On a successful exit from multi_varma_update the reference vector is updated so that should future series values become available these forecasts may be updated by recalling multi_varma_update.

.. _g13dk-py2-py-doc:

For full information please refer to the NAG Library document for g13dk

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dkf.html

.. _g13dk-py2-py-parameters:

**Parameters**
**mlast** : int
On the first call to multi_varma_update, since calling :meth:multi_varma_forecast, :math:\mathrm{mlast} must be set to :math:0 to indicate that no new observations have yet been used to update the forecasts; on subsequent calls :math:\mathrm{mlast} must contain the value of :math:\mathrm{mlast} as output on the previous call to multi_varma_update.

**z** : float, array-like, shape :math:\left(k, m\right)
:math:\mathrm{z}[\textit{i}-1,\textit{j}-1] must contain the value of :math:z_{{\textit{i},n+\mathrm{mlast}+\textit{j}}}, for :math:\textit{j} = 1,2,\ldots,m, for :math:\textit{i} = 1,2,\ldots,k, and where :math:n is the number of observations in the time series in the last call made to :meth:multi_varma_forecast.

**ref** : float, array-like, shape :math:\left(\textit{lref}\right)
Must contain the first :math:\left(\textit{lmax}-1\right)\times k\times k+2\times k\times \textit{lmax}+k elements of the reference vector as returned on a successful exit from :meth:multi_varma_forecast (or a previous call to multi_varma_update).

**predz** : float, array-like, shape :math:\left(k, \textit{lmax}\right)
Nonupdated values are kept intact.

**sefz** : float, array-like, shape :math:\left(k, \textit{lmax}\right)
Nonupdated values are kept intact.

**Returns**
**mlast** : int
Is incremented by :math:m to indicate that :math:\mathrm{mlast}+m observations have now been used to update the forecasts since the last call to :meth:multi_varma_forecast.

:math:\mathrm{mlast} must not be changed between calls to multi_varma_update, unless a call to :meth:multi_varma_forecast has been made between the calls in which case :math:\mathrm{mlast} should be reset to :math:0.

**ref** : float, ndarray, shape :math:\left(\textit{lref}\right)
The elements of :math:\mathrm{ref} are updated. The first :math:\left(\textit{lmax}-1\right)\times k\times k elements store the :math:\psi weights :math:\psi_1,\psi_2,\ldots,\psi_{{l_{\mathrm{max}}-1}}. The next :math:k\times \textit{lmax} elements contain the forecasts of the transformed series and the next :math:k\times \textit{lmax} elements contain the variances of the forecasts of the transformed variables; see :meth:multi_varma_forecast. The last :math:\textit{k} elements are not updated.

**v** : float, ndarray, shape :math:\left(k, m\right)
:math:\mathrm{v}[\textit{i}-1,\textit{j}-1] contains an estimate of the :math:\textit{i}\ th component of :math:\epsilon_{{n+\mathrm{mlast}+\textit{j}}}, for :math:\textit{j} = 1,2,\ldots,m, for :math:\textit{i} = 1,2,\ldots,k.

**predz** : float, ndarray, shape :math:\left(k, \textit{lmax}\right)
:math:\mathrm{predz}[\textit{i}-1,\textit{j}-1] contains the updated forecast of :math:z_{{\textit{i},n+\textit{j}}}, for :math:\textit{j} = \mathrm{mlast}+m+1,\ldots,l_{\mathrm{max}}, for :math:\textit{i} = 1,2,\ldots,k.

The columns of :math:\mathrm{predz} corresponding to the new observations since the last call to either :meth:multi_varma_forecast or multi_varma_update are set equal to the corresponding columns of :math:\mathrm{z}.

**sefz** : float, ndarray, shape :math:\left(k, \textit{lmax}\right)
:math:\mathrm{sefz}[\textit{i}-1,\textit{j}-1] contains an estimate of the standard error of the corresponding element of :math:\mathrm{predz}, for :math:\textit{j} = \mathrm{mlast}+m+1,\ldots,l_{\mathrm{max}}, for :math:\textit{i} = 1,2,\ldots,k.

The columns of :math:\mathrm{sefz} corresponding to the new observations since the last call to either :meth:multi_varma_forecast or multi_varma_update are set equal to zero.

.. _g13dk-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{lref} = \langle\mathit{\boldsymbol{value}}\rangle and the minimum size :math:\text{required} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{lref}\geq \left(\textit{lmax}-1\right)\times k\times k+2\times k\times \textit{lmax}+k.

(errno :math:1)
On entry, :math:\mathrm{mlast} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mlast} \geq 0.

(errno :math:1)
On entry, :math:m = \langle\mathit{\boldsymbol{value}}\rangle, :math:\textit{lmax} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{mlast} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:m < \textit{lmax}-\mathrm{mlast}.

(errno :math:1)
On entry, :math:m = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:m > 0.

(errno :math:1)
On entry, :math:\textit{lmax} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{lmax} \geq 2.

(errno :math:1)
On entry, :math:k = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:k \geq 1.

(errno :math:2)
On entry, some of the elements of the array :math:\mathrm{ref} have been corrupted.

(errno :math:3)
On entry, one (or more) of the transformations requested is invalid.

(errno :math:4)
The updated forecasts will overflow if computed.

.. _g13dk-py2-py-notes:

**Notes**
Let :math:Z_{\textit{t}} = \left(z_{{1\textit{t}}}, z_{{2\textit{t}}}, \ldots, z_{{k\textit{t}}}\right)^\mathrm{T}, for :math:\textit{t} = 1,2,\ldots,n, denote a :math:k-dimensional time series for which forecasts of :math:\hat{Z}_{{n+1}},\hat{Z}_{{n+2}},\ldots,\hat{Z}_{{n+l_{\mathrm{max}}}} have been computed using :meth:multi_varma_forecast.
Given :math:m further observations :math:Z_{{n+1}},Z_{{n+2}},\ldots,Z_{{n+m}}, where :math:m < l_{\mathrm{max}}, multi_varma_update updates the forecasts of :math:Z_{{n+m+1}},Z_{{n+m+2}},\ldots,Z_{{n+l_{\mathrm{max}}}} and their corresponding standard errors.

multi_varma_update uses a multivariate version of the procedure described in Box and Jenkins (1976).
The forecasts are updated using the :math:\psi weights, computed in :meth:multi_varma_forecast.
If :math:Z_t^* denotes the transformed value of :math:Z_t and :math:\hat{Z}_t^*\left(l\right) denotes the forecast of :math:Z_{{t+l}}^* from time :math:t with a lead of :math:l (that is the forecast of :math:Z_{{t+l}}^* given observations :math:Z_t^*,Z_{{t-1}}^*,\ldots \text{}), then

.. math::
\hat{Z}_{{t+1}}^*\left(l\right) = \tau +\psi_l\epsilon_{{t+1}}+\psi_{{l+1}}\epsilon_t+\psi_{{l+2}}\epsilon_{{t-1}} + \cdots

and

.. math::
\hat{Z}_t^*\left(l+1\right) = \tau +\psi_{{l+1}}\epsilon_t+\psi_{{l+2}}\epsilon_{{t-1}} + \cdots

where :math:\tau is a constant vector of length :math:k involving the differencing parameters and the mean vector :math:\mu.
By subtraction we obtain

.. math::
\hat{Z}_{{t+1}}^*\left(l\right) = \hat{Z}_t^*\left(l+1\right)+\psi_l\epsilon_{{t+1}}\text{.}

Estimates of the residuals corresponding to the new observations are also computed as :math:\epsilon_{{n+\textit{l}}} = Z_{{n+\textit{l}}}^*-\hat{Z}_n^*\left(\textit{l}\right), for :math:\textit{l} = 1,2,\ldots,m.
These may be of use in checking that the new observations conform to the previously fitted model.

On a successful exit, the reference array is updated so that multi_varma_update may be called again should future series values become available, see Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dkf.html#fcomments>__.

When a transformation has been used the forecasts and their standard errors are suitably modified to give results in terms of the original series :math:Z_t; see Granger and Newbold (1976).

.. _g13dk-py2-py-references:

**References**
Box, G E P and Jenkins, G M, 1976, Time Series Analysis: Forecasting and Control, (Revised Edition), Holden--Day

Granger, C W J and Newbold, P, 1976, Forecasting transformed series, J. Roy. Statist. Soc. Ser. B (38), 189--203

Wei, W W S, 1990, Time Series Analysis: Univariate and Multivariate Methods, Addison--Wesley
"""
raise NotImplementedError

[docs]def multi_diff(z, tr, dord, delta):
r"""
multi_diff differences and/or transforms a multivariate time series. It is intended to be used prior to :meth:multi_varma_estimate to fit a vector autoregressive moving average (VARMA) model to the differenced/transformed series.

.. _g13dl-py2-py-doc:

For full information please refer to the NAG Library document for g13dl

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dlf.html

.. _g13dl-py2-py-parameters:

**Parameters**
**z** : float, array-like, shape :math:\left(k, n\right)
:math:\mathrm{z}[\textit{i},\textit{t}] must contain, :math:z_{{\textit{i}\textit{t}}}, the :math:\textit{i}\ th component of :math:Z_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,n, for :math:\textit{i} = 1,2,\ldots,k.

**tr** : str, length 1, array-like, shape :math:\left(k\right)
:math:\mathrm{tr}[\textit{i}-1] indicates whether the :math:\textit{i}\ th time series is to be transformed, for :math:\textit{i} = 1,2,\ldots,k.

:math:\mathrm{tr}[i-1] = \texttt{'N'}

No transformation is used.

:math:\mathrm{tr}[i-1] = \texttt{'L'}

A log transformation is used.

:math:\mathrm{tr}[i-1] = \texttt{'S'}

A square root transformation is used.

**dord** : int, array-like, shape :math:\left(k\right)
The order of differencing for each series, :math:\textit{d}_1,\textit{d}_2,\ldots,\textit{d}_k.

**delta** : float, array-like, shape :math:\left(k, \textit{d}\right)
If :math:\mathrm{dord}[i-1] > 0, then :math:\mathrm{delta}[\textit{i}-1,\textit{j}-1] must be set equal to :math:\delta_{{\textit{i}\textit{j}}}, for :math:\textit{i} = 1,2,\ldots,k, for :math:\textit{j} = 1,2,\ldots,\textit{d}_i.

If :math:\textit{d} = 0, :math:\mathrm{delta} is not referenced.

**Returns**
**w** : float, ndarray, shape :math:\left(k, \mathrm{nd}\right)
:math:\mathrm{w}[\textit{i}-1,\textit{t}-1] contains the value of :math:w_{{\textit{i},\textit{t}+\textit{d}}}, for :math:\textit{t} = 1,2,\ldots,n-\textit{d}, for :math:\textit{i} = 1,2,\ldots,k.

**nd** : int
The number of differenced values, :math:n-\textit{d}, in the series, where :math:\textit{d} = \mathrm{max}\left(\mathrm{dord}[i-1]\right).

.. _g13dl-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n \geq 1.

(errno :math:1)
On entry, :math:k = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:k \geq 1.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{dord}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dord} < n.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{dord}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dord}[i-1] \geq 0.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{tr}[i-1] is invalid.

Constraint: :math:\mathrm{tr}[i-1] = \texttt{'N'}, :math:\texttt{'L'} or :math:\texttt{'S'}.

(errno :math:4)
On entry, one (or more) of the transformations requested is invalid.

.. _g13dl-py2-py-notes:

**Notes**
For certain time series it may first be necessary to difference the original data to obtain a stationary series before calculating autocorrelations, etc.
This function also allows you to apply either a square root or a log transformation to the original time series to stabilize the variance if required.

If the order of differencing required for the :math:i\ th series is :math:\textit{d}_i, then the differencing operator is defined by :math:\delta_i\left(B\right) = 1-\delta_{{i1}}B-\delta_{{i2}}B^2 - \cdots -\delta_{{i\textit{d}_i}}B^{\textit{d}_i}, where :math:B is the backward shift operator; that is, :math:BZ_t = Z_{{t-1}}.
Let :math:\textit{d} denote the maximum of the orders of differencing, :math:\textit{d}_i, over the :math:k series.
The function computes values of the differenced/transformed series :math:W_{\textit{t}} = \left(w_{{1\textit{t}}}, w_{{2\textit{t}}}, \ldots, w_{{\textit{k}\textit{t}}}\right)^\mathrm{T}, for :math:\textit{t} = \textit{d}+1,\ldots,n, as follows:

.. math::
w_{{it}} = \delta_i\left(B\right)z_{{it}}^*\text{, }\quad i = 1,2,\ldots,k

where :math:z_{{it}}^* are the transformed values of the original :math:k-dimensional time series :math:Z_t = \left(z_{{1t}}, z_{{2t}}, \ldots, z_{{kt}}\right)^\mathrm{T}.

The differencing parameters :math:\delta_{{ij}}, for :math:i = 1,2,\ldots,k and :math:j = 1,2,\ldots,\textit{d}_i, must be supplied by you.
If the :math:i\ th series does not require differencing, then :math:\textit{d}_i = 0.

.. _g13dl-py2-py-references:

**References**
Box, G E P and Jenkins, G M, 1976, Time Series Analysis: Forecasting and Control, (Revised Edition), Holden--Day

Wei, W W S, 1990, Time Series Analysis: Univariate and Multivariate Methods, Addison--Wesley
"""
raise NotImplementedError

[docs]def multi_corrmat_cross(matrix, m, w):
r"""
multi_corrmat_cross calculates the sample cross-correlation (or cross-covariance) matrices of a multivariate time series.

.. _g13dm-py2-py-doc:

For full information please refer to the NAG Library document for g13dm

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dmf.html

.. _g13dm-py2-py-parameters:

**Parameters**
**matrix** : str, length 1
Indicates whether the cross-covariance or cross-correlation matrices are to be computed.

:math:\mathrm{matrix} = \texttt{'V'}

The cross-covariance matrices are computed.

:math:\mathrm{matrix} = \texttt{'R'}

The cross-correlation matrices are computed.

**m** : int
:math:m, the number of cross-correlation (or cross-covariance) matrices to be computed. If in doubt set :math:\mathrm{m} = 10. However it should be noted that :math:\mathrm{m} is usually taken to be at most :math:n/4.

**w** : float, array-like, shape :math:\left(k, n\right)
:math:\mathrm{w}[\textit{i}-1,\textit{t}-1] must contain the observation :math:w_{{\textit{i}\textit{t}}}, for :math:\textit{t} = 1,2,\ldots,n, for :math:\textit{i} = 1,2,\ldots,k.

**Returns**
**wmean** : float, ndarray, shape :math:\left(k\right)
The means, :math:\bar{w}_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k.

**r0** : float, ndarray, shape :math:\left(k, k\right)
If :math:i\neq j, then :math:\mathrm{r0}[i-1,j-1] contains an estimate of the :math:\left(i, j\right)\ th element of the cross-correlation (or cross-covariance) matrix at lag zero, :math:\hat{R}_{{ij}}\left(0\right); if :math:i = j, then if :math:\mathrm{matrix} = \texttt{'V'}, :math:\mathrm{r0}[i-1,i-1] contains the variance of the :math:i\ th series, :math:\hat{C}_{{ii}}\left(0\right), and if :math:\mathrm{matrix} = \texttt{'R'}, :math:\mathrm{r0}[i-1,i-1] contains the standard deviation of the :math:i\ th series, :math:\sqrt{\hat{C}_{{ii}}\left(0\right)}.

If :math:\mathrm{errno} = 2 and :math:\mathrm{matrix} = \texttt{'R'}, then on exit all the elements in :math:\mathrm{r0} whose computation involves the zero variance are set to zero.

**r** : float, ndarray, shape :math:\left(k, k, \mathrm{m}\right)
:math:\mathrm{r}[\textit{i}-1,\textit{j}-1,\textit{l}-1] contains an estimate of the (:math:\textit{i},\textit{j})th element of the cross-correlation (or cross-covariance) at lag :math:\textit{l}, :math:\hat{R}_{{\textit{i}\textit{j}}}\left(\textit{l}\right), for :math:\textit{j} = 1,2,\ldots,k, for :math:\textit{i} = 1,2,\ldots,k, for :math:\textit{l} = 1,2,\ldots,m.

If :math:\mathrm{errno} = 2 and :math:\mathrm{matrix} = \texttt{'R'}, then on exit all the elements in :math:\mathrm{r} whose computation involves the zero variance are set to zero.

.. _g13dm-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{m} \geq 1 and :math:\mathrm{m} < n.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n \geq 2.

(errno :math:1)
On entry, :math:k = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:k \geq 1.

(errno :math:1)
On entry, :math:\mathrm{matrix} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{matrix} = \texttt{'V'} or :math:\texttt{'R'}.

**Warns**
**NagAlgorithmicWarning**
(errno :math:2)
On entry, at least one of the series is such that all its elements are practically identical giving zero (or near zero) variance.

.. _g13dm-py2-py-notes:

**Notes**
Let :math:W_t = \left(w_{{1t}}, w_{{2t}}, \ldots, w_{{kt}}\right)^\mathrm{T}, for :math:t = 1,2,\ldots,n, denote :math:n observations of a vector of :math:k time series.
The sample cross-covariance matrix at lag :math:l is defined to be the :math:k\times k matrix :math:\hat{C}\left(l\right), whose (:math:i,j)th element is given by

.. math::
\hat{C}_{{ij}}\left(l\right) = \frac{1}{n}\sum_{{t = l+1}}^n\left(w_{{i\left(t-l\right)}}-\bar{w}_i\right)\left(w_{{jt}}-\bar{w}_j\right)\text{, }\quad l = 0,1,2,\ldots,m\text{, }i = 1,2,\ldots,k\text{ and }j = 1,2,\ldots,k\text{,}

where :math:\bar{w}_i and :math:\bar{w}_j denote the sample means for the :math:i\ th and :math:j\ th series respectively.
The sample cross-correlation matrix at lag :math:l is defined to be the :math:k\times k matrix :math:\hat{R}\left(l\right), whose :math:\left(i, j\right)\ th element is given by

.. math::
\hat{R}_{{ij}}\left(l\right) = \frac{{\hat{C}_{{ij}}\left(l\right)}}{{\sqrt{\hat{C}_{{ii}}\left(0\right)\hat{C}_{{jj}}\left(0\right)}}}\text{, }\quad l = 0,1,2,\ldots,m\text{, }i = 1,2,\ldots,k\text{ and }j = 1,2,\ldots,k\text{.}

The number of lags, :math:m, is usually taken to be at most :math:n/4.

If :math:W_t follows a vector moving average model of order :math:q, then it can be shown that the theoretical cross-correlation matrices :math:\left(R\left(l\right)\right) are zero beyond lag :math:q.
In order to help spot a possible cut-off point, the elements of :math:\hat{R}\left(l\right) are usually compared to their approximate standard error of 1/:math:\sqrt{n}.
For further details see, for example, Wei (1990).

The function uses a single pass through the data to compute the means and the cross-covariance matrix at lag zero.
The cross-covariance matrices at further lags are then computed on a second pass through the data.

.. _g13dm-py2-py-references:

**References**
Wei, W W S, 1990, Time Series Analysis: Univariate and Multivariate Methods, Addison--Wesley

West, D H D, 1979, Updating mean and variance estimates: An improved method, Comm. ACM (22), 532--555
"""
raise NotImplementedError

[docs]def multi_corrmat_partlag(n, r0, r):
r"""
multi_corrmat_partlag calculates the sample partial lag correlation matrices of a multivariate time series.
A set of :math:\chi^2-statistics and their significance levels are also returned.
A call to :meth:multi_corrmat_cross is usually made prior to calling this function in order to calculate the sample cross-correlation matrices.

.. _g13dn-py2-py-doc:

For full information please refer to the NAG Library document for g13dn

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dnf.html

.. _g13dn-py2-py-parameters:

**Parameters**
**n** : int
:math:n, the number of observations in each series.

**r0** : float, array-like, shape :math:\left(k, k\right)
If :math:i\neq j, then :math:\mathrm{r0}[i-1,j-1] must contain the :math:\left(i, j\right)\ th element of the sample cross-correlation matrix at lag zero, :math:\hat{R}_{{ij}}\left(0\right). If :math:i = j, then :math:\mathrm{r0}[i-1,i-1] must contain the standard deviation of the :math:i\ th series.

**r** : float, array-like, shape :math:\left(k, k, m\right)
:math:\mathrm{r}[i-1,j-1,l-1] must contain the :math:\left(i, j\right)\ th element of the sample cross-correlation at lag :math:l, :math:\hat{R}_{{\textit{i}\textit{j}}}\left(\textit{l}\right), for :math:\textit{j} = 1,2,\ldots,k, for :math:\textit{i} = 1,2,\ldots,k, for :math:\textit{l} = 1,2,\ldots,m, where series :math:\textit{j} leads series :math:\textit{i} (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dnf.html#fcomments>__).

**Returns**
**maxlag** : int
The maximum lag up to which partial lag correlation matrices (along with :math:\chi^2-statistics and their significance levels) have been successfully computed. On a successful exit :math:\mathrm{maxlag} will equal :math:\textit{m}. If :math:\mathrm{errno} = 2 on exit, :math:\mathrm{maxlag} will be less than :math:\textit{m}.

**parlag** : float, ndarray, shape :math:\left(k, k, m\right)
:math:\mathrm{parlag}[i-1,j-1,l-1] contains the :math:\left(i, j\right)\ th element of the sample partial lag correlation matrix at lag :math:l, :math:\hat{P}_{{\textit{i}\textit{j}}}\left(\textit{l}\right), for :math:\textit{j} = 1,2,\ldots,k, for :math:\textit{i} = 1,2,\ldots,k, for :math:\textit{l} = 1,2,\ldots,\mathrm{maxlag}.

**x** : float, ndarray, shape :math:\left(m\right)
:math:\mathrm{x}[\textit{l}-1] contains the :math:\chi^2-statistic at lag :math:\textit{l}, for :math:\textit{l} = 1,2,\ldots,\mathrm{maxlag}.

**pvalue** : float, ndarray, shape :math:\left(m\right)
:math:\mathrm{pvalue}[\textit{l}-1] contains the significance level of the corresponding :math:\chi^2-statistic in :math:\mathrm{x}, for :math:\textit{l} = 1,2,\ldots,\mathrm{maxlag}.

.. _g13dn-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:m = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:m < \mathrm{n}.

(errno :math:1)
On entry, :math:m = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:m \geq 1.

(errno :math:1)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n} \geq 2.

(errno :math:1)
On entry, :math:k = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:k \geq 1.

**Warns**
**NagAlgorithmicWarning**
(errno :math:2)
The recursive equations used to compute the partial lag correlation matrices are ill-conditioned (they have been computed up to lag :math:\langle\mathit{\boldsymbol{value}}\rangle).

.. _g13dn-py2-py-notes:

**Notes**
Let :math:W_{\textit{t}} = \left(w_{{1\textit{t}}}, w_{{2\textit{t}}}, \ldots, w_{{\textit{k}\textit{t}}}\right)^\mathrm{T}, for :math:\textit{t} = 1,2,\ldots,n, denote :math:n observations of a vector of :math:k time series.
The partial lag correlation matrix at lag :math:l, :math:P\left(l\right), is defined to be the correlation matrix between :math:W_t and :math:W_{{t+l}}, after removing the linear dependence on each of the intervening vectors :math:W_{{t+1}},W_{{t+2}},\ldots,W_{{t+l-1}}.
It is the correlation matrix between the residual vectors resulting from the regression of :math:W_{{t+l}} on the carriers :math:W_{{t+l-1}},\ldots,W_{{t+1}} and the regression of :math:W_t on the same set of carriers; see Heyse and Wei (1985).

:math:P\left(l\right) has the following properties.

(i) If :math:W_t follows a vector autoregressive model of order :math:p, then :math:P\left(l\right) = 0 for :math:l > p;

(#) When :math:k = 1, :math:P\left(l\right) reduces to the univariate partial autocorrelation at lag :math:l;

(#) Each element of :math:P\left(l\right) is a properly normalized correlation coefficient;

(#) When :math:l = 1, :math:P\left(l\right) is equal to the cross-correlation matrix at lag :math:1 (a natural property which also holds for the univariate partial autocorrelation function).

Sample estimates of the partial lag correlation matrices may be obtained using the recursive algorithm described in Wei (1990).
They are calculated up to lag :math:m, which is usually taken to be at most :math:n/4.
Only the sample cross-correlation matrices ( :math:\hat{R}\left(\textit{l}\right), for :math:\textit{l} = 0,1,\ldots,m) and the standard deviations of the series are required as input to multi_corrmat_partlag.
These may be computed by :meth:multi_corrmat_cross.
Under the hypothesis that :math:W_t follows an autoregressive model of order :math:s-1, the elements of the sample partial lag matrix :math:\hat{P}\left(s\right), denoted by :math:\hat{P}_{{ij}}\left(s\right), are asymptotically Normally distributed with mean zero and variance :math:1/n.

.. math::
X\left(s\right) = n\sum_{{i = 1}}^k\sum_{{j = 1}}^k\hat{P}_{{ij}}\left(s\right)^2

has an asymptotic :math:\chi^2-distribution with :math:k^2 degrees of freedom.
These quantities, :math:X\left(l\right), are useful as a diagnostic aid for determining whether the series follows an autoregressive model and, if so, of what order.

.. _g13dn-py2-py-references:

**References**
Heyse, J F and Wei, W W S, 1985, The partial lag autocorrelation function, Technical Report No. 32, Department of Statistics, Temple University, Philadelphia

Wei, W W S, 1990, Time Series Analysis: Univariate and Multivariate Methods, Addison--Wesley
"""
raise NotImplementedError

[docs]def multi_regmat_partial(z, m):
r"""
multi_regmat_partial calculates the sample partial autoregression matrices of a multivariate time series.
A set of likelihood ratio statistics and their significance levels are also returned.
These quantities are useful for determining whether the series follows an autoregressive model and, if so, of what order.

.. _g13dp-py2-py-doc:

For full information please refer to the NAG Library document for g13dp

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dpf.html

.. _g13dp-py2-py-parameters:

**Parameters**
**z** : float, array-like, shape :math:\left(k, n\right)
:math:\mathrm{z}[\textit{i}-1,\textit{t}-1] must contain the observation :math:w_{{\textit{i}\textit{t}}}, for :math:\textit{t} = 1,2,\ldots,n, for :math:\textit{i} = 1,2,\ldots,k.

**m** : int
:math:m, the number of partial autoregression matrices to be computed. If in doubt set :math:\mathrm{m} = 10.

**Returns**
**maxlag** : int
The maximum lag up to which partial autoregression matrices (along with their likelihood ratio statistics and their significance levels) have been successfully computed. On a successful exit :math:\mathrm{maxlag} will equal :math:\mathrm{m}. If :math:\mathrm{errno} = 2 on exit then :math:\mathrm{maxlag} will be less than :math:\mathrm{m}.

**parlag** : float, ndarray, shape :math:\left(k, k, \mathrm{m}\right)
:math:\mathrm{parlag}[i-1,j-1,l-1] contains an estimate of the :math:\left(i, j\right)\ th element of the partial autoregression matrix at lag :math:l, :math:\hat{P}_l\left(ij\right), for :math:l = 1,2,\ldots,\mathrm{maxlag}, :math:i = 1,2,\ldots,k and :math:j = 1,2,\ldots,k.

**se** : float, ndarray, shape :math:\left(k, k, \mathrm{m}\right)
:math:\mathrm{se}[i-1,j-1,l-1] contains an estimate of the standard error of the corresponding element in the array :math:\mathrm{parlag}.

**qq** : float, ndarray, shape :math:\left(k, k, \mathrm{m}\right)
:math:\mathrm{qq}[\textit{i}-1,\textit{j}-1,\textit{l}-1] contains an estimate of the :math:\left(\textit{i}, \textit{j}\right)\ th element of the corresponding variance-covariance matrix :math:\hat{\Sigma }_{\textit{l}}, for :math:\textit{j} = 1,2,\ldots,k, for :math:\textit{i} = 1,2,\ldots,k, for :math:\textit{l} = 1,2,\ldots,\mathrm{maxlag}.

**x** : float, ndarray, shape :math:\left(\mathrm{m}\right)
:math:\mathrm{x}[\textit{l}-1] contains :math:X_{\textit{l}}, the likelihood ratio statistic at lag :math:\textit{l}, for :math:\textit{l} = 1,2,\ldots,\mathrm{maxlag}.

**pvalue** : float, ndarray, shape :math:\left(\mathrm{m}\right)
:math:\mathrm{pvalue}[l-1] contains the significance level of the statistic in the corresponding element of :math:\mathrm{x}.

**loglhd** : float, ndarray, shape :math:\left(\mathrm{m}\right)
:math:\mathrm{loglhd}[\textit{l}-1] contains an estimate of the maximum of the log-likelihood function when an :math:\text{AR}\left(\textit{l}-1\right) model has been fitted to the series, for :math:\textit{l} = 1,2,\ldots,\mathrm{maxlag}.

.. _g13dp-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:k = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n-\mathrm{m}-\left(k\times \mathrm{m}+1\right)\geq k.

(errno :math:1)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{m} \geq 1.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n \geq 4.

(errno :math:1)
On entry, :math:k = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:k \geq 1.

**Warns**
**NagAlgorithmicWarning**
(errno :math:2)
The recursive equations used to compute the partial autoregression matrices are ill-conditioned. They have been computed up to lag :math:\langle\mathit{\boldsymbol{value}}\rangle.

.. _g13dp-py2-py-notes:

**Notes**
Let :math:W_{\textit{t}} = \left(w_{{1\textit{t}}}, w_{{2\textit{t}}}, \ldots, w_{{\textit{k}\textit{t}}}\right)^\mathrm{T}, for :math:\textit{t} = 1,2,\ldots,n, denote a vector of :math:k time series.
The partial autoregression matrix at lag :math:l, :math:P_l, is defined to be the last matrix coefficient when a vector autoregressive model of order :math:l is fitted to the series. :math:P_l has the property that if :math:W_t follows a vector autoregressive model of order :math:p then :math:P_l = 0 for :math:l > p.

Sample estimates of the partial autoregression matrices may be obtained by fitting autoregressive models of successively higher orders by multivariate least squares; see Tiao and Box (1981) and Wei (1990).
These models are fitted using a :math:QR algorithm based on the functions :meth:correg.linregm_obs_edit <naginterfaces.library.correg.linregm_obs_edit> and :meth:correg.linregm_var_del <naginterfaces.library.correg.linregm_var_del>.
They are calculated up to lag :math:m, which is usually taken to be at most :math:n/4.

The function also returns the asymptotic standard errors of the elements of :math:\hat{P}_l and an estimate of the residual variance-covariance matrix :math:\hat{\Sigma }_l, for :math:l = 1,2,\ldots,m.
If :math:S_l denotes the residual sum of squares and cross-products matrix after fitting an :math:\text{AR}\left(l\right) model to the series then under the null hypothesis :math:H_0:P_l = 0 the test statistic

.. math::
X_l = -\left(\left(n-m-1\right)-\frac{1}{2}-lk\right)\log\left(\frac{{\left\lvert S_l\right\rvert }}{{\left\lvert S_{{l-1}}\right\rvert }}\right)

is asymptotically distributed as :math:\chi^2 with :math:k^2 degrees of freedom. :math:X_l provides a useful diagnostic aid in determining the order of an autoregressive model. (Note that :math:\hat{\Sigma }_l = S_l/\left(n-l\right).) The function also returns an estimate of the maximum of the log-likelihood function for each AR model that has been fitted.

.. _g13dp-py2-py-references:

**References**
Tiao, G C and Box, G E P, 1981, Modelling multiple time series with applications, J. Am. Stat. Assoc. (76), 802--816

Wei, W W S, 1990, Time Series Analysis: Univariate and Multivariate Methods, Addison--Wesley
"""
raise NotImplementedError

[docs]def multi_varma_diag(v, ip, iq, m, par, parhld, qq, ishow, io_manager=None):
r"""
multi_varma_diag is a diagnostic checking function suitable for use after fitting a vector ARMA model to a multivariate time series using :meth:multi_varma_estimate.
The residual cross-correlation matrices are returned along with an estimate of their asymptotic standard errors and correlations.
Also, multi_varma_diag calculates the modified Li--McLeod portmanteau statistic and its significance level for testing model adequacy.

.. _g13ds-py2-py-doc:

For full information please refer to the NAG Library document for g13ds

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dsf.html

.. _g13ds-py2-py-parameters:

**Parameters**
**v** : float, array-like, shape :math:\left(k, n\right)
:math:\mathrm{v}[\textit{i}-1,\textit{t}-1] must contain an estimate of the :math:\textit{i}\ th component of :math:\epsilon_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,n, for :math:\textit{i} = 1,2,\ldots,k.

**ip** : int
:math:p, the number of AR parameter matrices.

**iq** : int
:math:q, the number of MA parameter matrices.

**m** : int
The value of :math:m, the number of residual cross-correlation matrices to be computed. See Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dsf.html#fcomments2>__ for advice on the choice of :math:\mathrm{m}.

**par** : float, array-like, shape :math:\left(\left(\mathrm{ip}+\mathrm{iq}\right)\times k\times k\right)
The parameter estimates read in row by row in the order :math:\phi_1,\phi_2,\ldots,\phi_p, :math:\theta_1,\theta_2,\ldots,\theta_q.

Thus,

if :math:\mathrm{ip} > 0, :math:\mathrm{par}[\left(\textit{l}-1\right)\times k\times k+\left(\textit{i}-1\right)\times k+j-1] must be set equal to an estimate of the :math:\left(\textit{i}, j\right)\ th element of :math:\phi_{\textit{l}}, for :math:\textit{i} = 1,2,\ldots,k, for :math:\textit{l} = 1,2,\ldots,p;

if :math:\mathrm{iq}\geq 0, :math:\mathrm{par}[p\times k\times k+\left(\textit{l}-1\right)\times k\times k+\left(\textit{i}-1\right)\times k+j-1] must be set equal to an estimate of the :math:\left(\textit{i}, j\right)\ th element of :math:\theta_{\textit{l}}, for :math:\textit{i} = 1,2,\ldots,k, for :math:\textit{l} = 1,2,\ldots,q.

The first :math:p\times k\times k elements of :math:\mathrm{par} must satisfy the stationarity condition and the next :math:q\times k\times k elements of :math:\mathrm{par} must satisfy the invertibility condition.

**parhld** : bool, array-like, shape :math:\left(\left(\mathrm{ip}+\mathrm{iq}\right)\times k\times k\right)
:math:\mathrm{parhld}[\textit{i}-1] must be set to :math:\mathbf{True} if :math:\mathrm{par}[\textit{i}-1] has been held constant at a pre-specified value and :math:\mathbf{False} if :math:\mathrm{par}[\textit{i}-1] is a free parameter, for :math:\textit{i} = 1,2,\ldots,\left(p+q\right)\times k\times k.

**qq** : float, array-like, shape :math:\left(k, k\right)
:math:\mathrm{qq}[i-1,j-1] is an efficient estimate of the :math:\left(i, j\right)\ th element of :math:\Sigma. The lower triangle only is needed.

**ishow** : int
Must be nonzero if the residual cross-correlation matrices :math:\left\{\hat{r}_{{ij}}\left(l\right)\right\} and their standard errors :math:\left\{\mathrm{se}\left(\hat{r}_{{ij}}\left(l\right)\right)\right\}, the modified portmanteau statistic with its significance and a summary table are to be printed. The summary table indicates which elements of the residual correlation matrices are significant at the :math:5\% level in either a positive or negative direction; i.e., if :math:\hat{r}_{{ij}}\left(l\right) > 1.96\times \mathrm{se}\left(\hat{r}_{{ij}}\left(l\right)\right) then a ':math:+' is printed, if :math:\hat{r}_{{ij}}\left(l\right) < {-1.96}\times \mathrm{se}\left(\hat{r}_{{ij}}\left(l\right)\right) then a ':math:-' is printed, otherwise a fullstop (.) is printed. The summary table is only printed if :math:k\leq 6 on entry.

The residual cross-correlation matrices, their standard errors and the modified portmanteau statistic with its significance are available also as output variables in :math:\mathrm{r}, :math:\mathrm{rcm}, :math:\mathrm{chi}, :math:\mathrm{idf} and :math:\mathrm{siglev}.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**qq** : float, ndarray, shape :math:\left(k, k\right)
If :math:\mathrm{errno} != 1, then the upper triangle is set equal to the lower triangle.

**r0** : float, ndarray, shape :math:\left(k, k\right)
If :math:i\neq j, then :math:\mathrm{r0}[i-1,j-1] contains an estimate of the :math:\left(i, j\right)\ th element of the residual cross-correlation matrix at lag zero, :math:\hat{R}_0. When :math:i = j, :math:\mathrm{r0}[i-1,j-1] contains the standard deviation of the :math:i\ th residual series. If :math:\mathrm{errno} = 3 on exit then the first :math:\textit{k} rows and columns of :math:\mathrm{r0} are set to zero.

**r** : float, ndarray, shape :math:\left(k, k, \mathrm{m}\right)
:math:\mathrm{r}[\textit{l}-1,\textit{i}-1,\textit{j}-1] is an estimate of the :math:\left(\textit{i}, \textit{j}\right)\ th element of the residual cross-correlation matrix at lag :math:\textit{l}, for :math:\textit{l} = 1,2,\ldots,m, for :math:\textit{j} = 1,2,\ldots,k, for :math:\textit{i} = 1,2,\ldots,k. If :math:\mathrm{errno} = 3 on exit then all elements of :math:\mathrm{r} are set to zero.

**rcm** : float, ndarray, shape :math:\left(\mathrm{m}\times k\times k, \mathrm{m}\times k\times k\right)
The estimated standard errors and correlations of the elements in the array :math:\mathrm{r}. The correlation between :math:\mathrm{r}[l-1,i-1,j-1] and :math:\mathrm{r}[l_2-1,i_2-1,j_2-1] is returned as :math:\mathrm{rcm}[s,t] where :math:s = \left(l-1\right)\times k\times k+\left(j-1\right)\times k+i and :math:t = \left(l_2-1\right)\times k\times k+\left(j_2-1\right)\times k+i_2 except that if :math:s = t, then :math:\mathrm{rcm}[s,t] contains the standard error of :math:\mathrm{r}[l-1,i-1,j-1]. If on exit, :math:\mathrm{errno} >= 5, then all off-diagonal elements of :math:\mathrm{rcm} are set to zero and all diagonal elements are set to :math:1/\sqrt{n}.

**chi** : float
The value of the modified portmanteau statistic, :math:Q_{\left(m\right)}^*. If :math:\mathrm{errno} = 3 on exit then :math:\mathrm{chi} is returned as zero.

**idf** : int
The number of degrees of freedom of :math:\mathrm{chi}.

**siglev** : float
The significance level of :math:\mathrm{chi} based on :math:\mathrm{idf} degrees of freedom. If :math:\mathrm{errno} = 3 on exit, :math:\mathrm{siglev} is returned as one.

.. _g13ds-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{ldrcm} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:k = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ldrcm}\geq \mathrm{m}\times k\times k.

(errno :math:1)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{m} < n.

(errno :math:1)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{ip} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{iq} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{m} > \mathrm{ip}+\mathrm{iq}.

(errno :math:1)
On entry, :math:\mathrm{ip} = 0 and :math:\mathrm{iq} = 0.

Constraint: :math:\mathrm{ip} = \mathrm{iq} = 0 must not hold.

(errno :math:1)
On entry, :math:\mathrm{iq} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iq} \geq 0.

(errno :math:1)
On entry, :math:\mathrm{ip} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ip} \geq 0.

(errno :math:1)
On entry, :math:k = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:k \geq 1.

(errno :math:2)
On entry, the MA parameter matrices are outside the invertibility region.

(errno :math:2)
On entry, the AR parameter matrices are outside the stationarity region.

(errno :math:2)
On entry, the covariance matrix :math:\mathrm{qq} is not positive definite.

(errno :math:4)
Excessive iterations needed to find zeros of determinental polynomials.

(errno :math:5)
On entry, the AR operator has a factor in common with the MA operator.

(errno :math:6)
The matrix :math:\mathrm{rcm} could not be computed because one of its diagonal elements was found to be non-positive.

**Warns**
**NagAlgorithmicWarning**
(errno :math:3)
On entry, at least one of the residual series in the array :math:\mathrm{v} has near-zero variance.

(errno :math:3)
On entry, at least two of the residual series are identical.

.. _g13ds-py2-py-notes:

**Notes**
Let :math:W_{\textit{t}} = \left(w_{{1\textit{t}}}, w_{{2\textit{t}}}, \ldots, w_{{\textit{k}\textit{t}}}\right)^\mathrm{T}, for :math:\textit{t} = 1,2,\ldots,n, denote a vector of :math:k time series which is assumed to follow a multivariate ARMA model of the form

.. math::
\begin{array}{ll}W_t-\mu = &\phi_1\left(W_{{t-1}}-\mu \right)+\phi_2\left(W_{{t-2}}-\mu \right)+ \cdots +\phi_p\left(W_{{t-p}}-\mu \right)\\&+\epsilon_t-\theta_1\epsilon_{{t-1}}-\theta_2\epsilon_{{t-2}} - \cdots -\theta_q\epsilon_{{t-q}}\text{,}\end{array}

where :math:\epsilon_{\textit{t}} = \left(\epsilon_{{1\textit{t}}}, \epsilon_{{2\textit{t}}}, \ldots, \epsilon_{{k\textit{t}}}\right)^\mathrm{T}, for :math:\textit{t} = 1,2,\ldots,n, is a vector of :math:k residual series assumed to be Normally distributed with zero mean and positive definite covariance matrix :math:\Sigma.
The components of :math:\epsilon_t are assumed to be uncorrelated at non-simultaneous lags.
The :math:\phi_i and :math:\theta_j are :math:k\times k matrices of parameters. :math:\left\{\phi_{\textit{i}}\right\}, for :math:\textit{i} = 1,2,\ldots,p, are called the autoregressive (AR) parameter matrices, and :math:\left\{\theta_{\textit{i}}\right\}, for :math:\textit{i} = 1,2,\ldots,q, the moving average (MA) parameter matrices.
The parameters in the model are thus the :math:p (:math:k\times k) :math:\phi-matrices, the :math:q (:math:k\times k) :math:\theta-matrices, the mean vector :math:\mu and the residual error covariance matrix :math:\Sigma.
Let

.. math::
A\left(\phi \right) = \left[\begin{array}{lllllll}\phi_1&I&0&.&.&.&0\\\phi_2&0&I&0&.&.&0\\.&&&.&&&\\.&&&&.&&\\.&&&&&.&\\\phi_{{p-1}}&0&.&.&.&0&I\\\phi_p&0&.&.&.&0&0\end{array}\right]_{{pk\times pk}}\quad \text{ and }\quad B\left(\theta \right) = \left[\begin{array}{lllllll}\theta_1&I&0&.&.&.&0\\\theta_2&0&I&0&.&.&0\\.&&&.&&&\\.&&&&.&&\\.&&&&&.&\\\theta_{{q-1}}&0&.&.&.&&I\\\theta_q&0&.&.&.&.&0\end{array}\right]_{{qk\times qk}}

where :math:I denotes the :math:k\times k identity matrix.

The ARMA model (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dsf.html#eqn1>__ is said to be stationary if the eigenvalues of :math:A\left(\phi \right) lie inside the unit circle, and invertible if the eigenvalues of :math:B\left(\theta \right) lie inside the unit circle.
The ARMA model is assumed to be both stationary and invertible.
Note that some of the elements of the :math:\phi- and/or :math:\theta-matrices may have been fixed at pre-specified values (for example by calling :meth:multi_varma_estimate).

The estimated residual cross-correlation matrix at lag :math:l is defined to the :math:k\times k matrix :math:\hat{R}_l whose :math:\left(i, j\right)\ th element is computed as

.. math::
\hat{ r }_{{ij}}\left(l\right) = \frac{{\sum_{{t = l+1}}^n\left(\hat{ \epsilon }_{{it-l}}-\bar{ \epsilon }_i\right)\left(\hat{ \epsilon }_{{jt}}-\bar{ \epsilon }_j\right)}}{\sqrt{\sum_{{t = 1}}^n\left(\hat{ \epsilon }_{{it}}-\bar{ \epsilon }_i\right)^2\sum_{{t = 1}}^n\left(\hat{ \epsilon }_{{jt}}-\bar{ \epsilon }_j\right)^2}}\text{, }\quad l = 0,1,\ldots,i\text{ and }j = 1,2,\ldots,k\text{,}

where :math:\hat{\epsilon }_{{it}} denotes an estimate of the :math:t\ th residual for the :math:i\ th series :math:\epsilon_{{it}} and :math:\bar{\epsilon }_i = \sum_{{t = 1}}^n\hat{\epsilon }_{{it}}/n. (Note that :math:\hat{R}_l is an estimate of :math:E\left(\epsilon_{{t-l}}\epsilon_t^\mathrm{T}\right), where :math:E is the expected value.)

A modified portmanteau statistic, :math:Q_{\left(m\right)}^*, is calculated from the formula (see Li and McLeod (1981))

.. math::
Q_{\left(m\right)}^* = \frac{{k^2m\left(m+1\right)}}{{2n}}+n\sum_{{l = 1}}^m\hat{r}\left(l\right)^\mathrm{T}\left(\hat{R}_0^{-1}⊗\hat{R}_0^{-1}\right)\hat{r}\left(l\right)\text{,}

where :math:⊗ denotes Kronecker product, :math:\hat{R}_0 is the estimated residual cross-correlation matrix at lag zero and :math:\hat{r}\left(l\right) = \mathrm{vec}\left(\hat{R}_l^\mathrm{T}\right), where :math:\text{vec} of a :math:k\times k matrix is a vector with the :math:\left(i, j\right)\ th element in position :math:\left(i-1\right)k+j. :math:m denotes the number of residual cross-correlation matrices computed. (Advice on the choice of :math:m is given in Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dsf.html#fcomments2>__.) Let :math:l_C denote the total number of 'free' parameters in the ARMA model excluding the mean, :math:\mu, and the residual error covariance matrix :math:\Sigma.
Then, under the hypothesis of model adequacy, :math:Q_{\left(m\right)}^*, has an asymptotic :math:\chi^2-distribution on :math:mk^2-l_C degrees of freedom.

Let :math:\underline{\hat{r}} = \left({\mathrm{vec}\left(R_1^\mathrm{T}\right)}, {\mathrm{vec}\left(R_2^\mathrm{T}\right)}, \ldots, {\mathrm{vec}\left(R_m^\mathrm{T}\right)}\right) then the covariance matrix of :math:\underline{\hat{r}} is given by

.. math::
\mathrm{Var}\left(\hat{\underline{r}}\right) = \left[Y-X\left(X^\mathrm{T}GG^\mathrm{T}X\right)^{-1}X^\mathrm{T}\right]/n\text{,}

where :math:Y = I_m⊗\left(\Delta ⊗\Delta \right) and :math:G = I_m\left(GG^\mathrm{T}\right). :math:\Delta is the dispersion matrix :math:\Sigma in correlation form and :math:G a nonsingular :math:k\times k matrix such that :math:GG^\mathrm{T} = \Delta^{-1} and :math:G\Delta G^\mathrm{T} = I_k.
The construction of the matrix :math:X is discussed in Li and McLeod (1981). (Note that the mean, :math:\mu, plays no part in calculating :math:\mathrm{Var}\left(\hat{\underline{r}}\right) and, therefore, is not required as input to multi_varma_diag.)

.. _g13ds-py2-py-references:

**References**
Li, W K and McLeod, A I, 1981, Distribution of the residual autocorrelations in multivariate ARMA time series models, J. Roy. Statist. Soc. Ser. B (43), 231--239
"""
raise NotImplementedError

[docs]def uni_arma_roots(k, ip, par):
r"""
uni_arma_roots calculates the zeros of a vector autoregressive (or moving average) operator. This function is likely to be used in conjunction with :meth:rand.times_mv_varma <naginterfaces.library.rand.times_mv_varma>, :meth:uni_arima_resid, :meth:multi_varma_estimate or :meth:multi_varma_diag.

.. _g13dx-py2-py-doc:

For full information please refer to the NAG Library document for g13dx

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dxf.html

.. _g13dx-py2-py-parameters:

**Parameters**
**k** : int
:math:k, the dimension of the multivariate time series.

**ip** : int
The number of AR (or MA) parameter matrices, :math:p (or :math:q).

**par** : float, array-like, shape :math:\left(\mathrm{ip}\times \mathrm{k}\times \mathrm{k}\right)
The AR (or MA) parameter matrices read in row by row in the order :math:\phi_1,\phi_2,\ldots,\phi_p (or :math:\theta_1,\theta_2,\ldots,\theta_q). That is, :math:\mathrm{par}[\left(\textit{l}-1\right)\times k\times k+\left(i-1\right)\times k+j-1] must be set equal to the :math:\left(i, j\right)\ th element of :math:\phi_l, for :math:\textit{l} = 1,2,\ldots,p (or the :math:\left(i, j\right)\ th element of :math:\theta_{\textit{l}}, for :math:\textit{l} = 1,2,\ldots,q).

**Returns**
**rr** : float, ndarray, shape :math:\left(\mathrm{k}\times \mathrm{ip}\right)
The real parts of the eigenvalues.

**ri** : float, ndarray, shape :math:\left(\mathrm{k}\times \mathrm{ip}\right)
The imaginary parts of the eigenvalues.

**rmod** : float, ndarray, shape :math:\left(\mathrm{k}\times \mathrm{ip}\right)
The moduli of the eigenvalues.

.. _g13dx-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{ip} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ip} \geq 1.

(errno :math:1)
On entry, :math:\mathrm{k} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{k} \geq 1.

(errno :math:2)
An excessive number of iterations have been required to calculate the eigenvalues.

.. _g13dx-py2-py-notes:

**Notes**
Consider the vector autoregressive moving average (VARMA) model

.. math::
W_t-\mu = \phi_1\left(W_{{t-1}}-\mu \right)+\phi_2\left(W_{{t-2}}-\mu \right)+ \cdots +\phi_p\left(W_{{t-p}}-\mu \right)+\epsilon_t-\theta_1\epsilon_{{t-1}}-\theta_2\epsilon_{{t-2}} - \cdots -\theta_q\epsilon_{{t-q}}\text{,}

where :math:W_t denotes a vector of :math:k time series and :math:\epsilon_t is a vector of :math:k residual series having zero mean and a constant variance-covariance matrix.
The components of :math:\epsilon_t are also assumed to be uncorrelated at non-simultaneous lags. :math:\phi_1,\phi_2,\ldots,\phi_p denotes a sequence of :math:k\times k matrices of autoregressive (AR) parameters and :math:\theta_1,\theta_2,\ldots,\theta_q denotes a sequence of :math:k\times k matrices of moving average (MA) parameters. :math:\mu is a vector of length :math:k containing the series means.
Let

.. math::
A\left(\phi \right) = \left[\begin{array}{rrrrrrr}\phi_1&I&0&.&.&.&0\\\phi_2&0&I&0&.&.&0\\.&&&.&&&\\.&&&&.&&\\.&&&&&.&\\\phi_{{p-1}}&0&.&.&.&0&I\\\phi_p&0&.&.&.&0&0\end{array}\right]_{{pk\times pk}}

where :math:I denotes the :math:k\times k identity matrix.

The model (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13dxf.html#eqn1>__ is said to be stationary if the eigenvalues of :math:A\left(\phi \right) lie inside the unit circle.
Similarly let

.. math::
B\left(\theta \right) = \left[\begin{array}{rrrrrrr}\theta_1&I&0&.&.&.&0\\\theta_2&0&I&0&.&.&0\\.&&&.&&&\\.&&&&.&&\\.&&&&&.&\\\theta_{{q-1}}&0&.&.&.&0&I\\\theta_q&0&.&.&.&0&0\end{array}\right]_{{qk\times qk}}\text{.}

Then the model is said to be invertible if the eigenvalues of :math:B\left(\theta \right) lie inside the unit circle.

uni_arma_roots returns the :math:pk eigenvalues of :math:A\left(\phi \right) (or the :math:qk eigenvalues of :math:B\left(\theta \right)) along with their moduli, in descending order of magnitude.
Thus to check for stationarity or invertibility you should check whether the modulus of the largest eigenvalue is less than :math:1.

.. _g13dx-py2-py-references:

**References**
Wei, W W S, 1990, Time Series Analysis: Univariate and Multivariate Methods, Addison--Wesley
"""
raise NotImplementedError

[docs]def multi_kalman_sqrt_var(a, b, stq, q, c, r, s, tol=0.0):
r"""
multi_kalman_sqrt_var performs a combined measurement and time update of one iteration of the time-varying Kalman filter using a square root covariance filter.

.. _g13ea-py2-py-doc:

For full information please refer to the NAG Library document for g13ea

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13eaf.html

.. _g13ea-py2-py-parameters:

**Parameters**
**a** : float, array-like, shape :math:\left(n, n\right)
The state transition matrix, :math:A_i.

**b** : float, array-like, shape :math:\left(n, l\right)
The noise coefficient matrix :math:B_i.

**stq** : bool
If :math:\mathrm{stq} = \mathbf{True}, the state noise covariance matrix :math:Q_i is assumed to be the identity matrix. Otherwise the lower triangular Cholesky factor, :math:Q_i^{{1/2}}, must be provided in :math:\mathrm{q}.

**q** : float, array-like, shape :math:\left(:, :\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{not}\left(\mathrm{stq}\right): :math:l; otherwise: :math:1.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{not}\left(\mathrm{stq}\right): :math:l; otherwise: :math:0.

If :math:\mathrm{stq} = \mathbf{False}, :math:\mathrm{q} must contain the lower triangular Cholesky factor of the state noise covariance matrix, :math:Q_i^{{1/2}}. Otherwise :math:\mathrm{q} is not referenced.

**c** : float, array-like, shape :math:\left(m, n\right)
The measurement coefficient matrix, :math:C_i.

**r** : float, array-like, shape :math:\left(m, m\right)
The lower triangular Cholesky factor of the measurement noise covariance matrix :math:R_i^{{1/2}}.

**s** : float, array-like, shape :math:\left(n, n\right)
The lower triangular Cholesky factor of the state covariance matrix, :math:S_i.

**tol** : float, optional
The tolerance used to test for the singularity of :math:H_i^{{1/2}}. If :math:0.0\leq \mathrm{tol} < m^2\times \text{machine precision}, then :math:m^2\times \text{machine precision} is used instead. The inverse of the condition number of :math:H^{{1/2}} is estimated by a call to :meth:lapacklin.dtrcon <naginterfaces.library.lapacklin.dtrcon>. If this estimate is less than :math:\mathrm{tol} then :math:H^{{1/2}} is assumed to be singular.

**Returns**
**s** : float, ndarray, shape :math:\left(n, n\right)
The lower triangular Cholesky factor of the state covariance matrix, :math:S_{{i+1}}.

**k** : float, ndarray, shape :math:\left(n, m\right)
The Kalman gain matrix, :math:K_i, premultiplied by the state transition matrix, :math:A_i, :math:A_iK_i.

**h** : float, ndarray, shape :math:\left(m, m\right)
The lower triangular matrix :math:H_i^{{1/2}}.

.. _g13ea-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{tol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tol}\geq 0.0.

(errno :math:1)
On entry, :math:l = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:l \geq 1.

(errno :math:1)
On entry, :math:m = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:m \geq 1.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n \geq 1.

(errno :math:2)
The matrix :math:H_i^{{1/2}} is singular.

.. _g13ea-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

The Kalman filter arises from the state space model given by:

.. math::
\begin{array}{ll}X_{{i+1}} = A_iX_i+B_iW_i\text{,}&\mathrm{Var}\left(W_i\right) = Q_i\\&\\Y_i = C_iX_i+V_i\text{,}&\mathrm{Var}\left(V_i\right) = R_i\end{array}

where :math:X_i is the state vector of length :math:n at time :math:i, :math:Y_i is the observation vector of length :math:m at time :math:i, and :math:W_i of length :math:l and :math:V_i of length :math:m are the independent state noise and measurement noise respectively.

The estimate of :math:X_i given observations :math:Y_1 to :math:Y_{{i-1}} is denoted by :math:\hat{X}_{{i | i-1}} with state covariance matrix :math:\mathrm{Var}\left(\hat{X}_{{i | i-1}}\right) = P_{{i | i-1}} = S_iS_i^\mathrm{T}, while the estimate of :math:X_i given observations :math:Y_1 to :math:Y_i is denoted by :math:\hat{X}_{{i | i}} with covariance matrix :math:\mathrm{Var}\left(\hat{X}_{{i | i}}\right) = P_{{i | i}}.
The update of the estimate, :math:\hat{X}_{{i | i-1}}, from time :math:i to time :math:\left(i+1\right), is computed in two stages.
First, the measurement-update is given by

.. math::
\hat{X}_{{i | i}} = \hat{X}_{{i | i-1}}+K_i\left[Y_i-C_i\hat{X}_{{i | i-1}}\right]

and

.. math::
P_{{i | i}} = \left[I-K_iC_i\right]P_{{i | i-1}}

where :math:K_i = P_{{i | i-1}}C_i^\mathrm{T}{\left[C_iP_{{i | i-1}}C_i^\mathrm{T}+R_i\right]}^{-1} is the Kalman gain matrix.
The second stage is the time-update for :math:X which is given by

.. math::
\hat{X}_{{i+1 | i}} = A_i\hat{X}_{{i | i}}+D_iU_i

and

.. math::
P_{{i+1 | i}} = A_iP_{{i | i}}A_i^\mathrm{T}+B_iQ_iB_i^\mathrm{T}

where :math:D_iU_i represents any deterministic control used.

The square root covariance filter algorithm provides a stable method for computing the Kalman gain matrix and the state covariance matrix.
The algorithm can be summarised as

.. math::
\begin{pmatrix}R_i^{{1/2}}&C_iS_i&0\\&&\\0&A_iS_i&B_iQ_i^{{1/2}}\end{pmatrix}U = \begin{pmatrix}H_i^{{1/2}}&0&0\\&&\\G_i&S_{{i+1}}&0\end{pmatrix}

where :math:U is an orthogonal transformation triangularizing the left-hand pre-array to produce the right-hand post-array.
The relationship between the Kalman gain matrix, :math:K_i, and :math:G_i is given by

.. math::
A_iK_i = G_i\left(H_i^{{1/2}}\right)^{-1}\text{.}

multi_kalman_sqrt_var requires the input of the lower triangular Cholesky factors of the noise covariance matrices :math:R_i^{{1/2}} and, optionally, :math:Q_i^{{1/2}} and the lower triangular Cholesky factor of the current state covariance matrix, :math:S_i, and returns the product of the matrices :math:A_i and :math:K_i, :math:A_iK_i, the Cholesky factor of the updated state covariance matrix :math:S_{{i+1}} and the matrix :math:H_i^{{1/2}} used in the computation of the likelihood for the model.

.. _g13ea-py2-py-references:

**References**
Vanbegin, M, van Dooren, P and Verhaegen, M H G, 1989, Algorithm 675: FORTRAN subroutines for computing the square root covariance filter and square root information filter in dense or Hessenberg forms, ACM Trans. Math. Software (15), 243--256

Verhaegen, M H G and van Dooren, P, 1986, Numerical aspects of different Kalman filter implementations, IEEE Trans. Auto. Contr. (AC-31), 907--917
"""
raise NotImplementedError

[docs]def multi_kalman_sqrt_invar(transf, a, b, stq, q, c, r, s, tol=0.0):
r"""
multi_kalman_sqrt_invar performs a combined measurement and time update of one iteration of the time-invariant Kalman filter using a square root covariance filter.

.. _g13eb-py2-py-doc:

For full information please refer to the NAG Library document for g13eb

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ebf.html

.. _g13eb-py2-py-parameters:

**Parameters**
**transf** : str, length 1
Indicates whether to transform the input matrix pair :math:\left(A, C\right) to lower observer Hessenberg form. The transformation will only be required on the first call to multi_kalman_sqrt_invar.

:math:\mathrm{transf} = \texttt{'T'}

The matrices in arrays :math:\mathrm{a} and :math:\mathrm{c} are transformed to lower observer Hessenberg form and the matrices in :math:\mathrm{b} and :math:\mathrm{s} are transformed as described in :ref:Notes <g13eb-py2-py-notes>.

:math:\mathrm{transf} = \texttt{'H'}

The matrices in arrays :math:\mathrm{a}, :math:\mathrm{c} and :math:\mathrm{b} should be as returned from a previous call to multi_kalman_sqrt_invar with :math:\mathrm{transf} = \texttt{'T'}.

**a** : float, array-like, shape :math:\left(n, n\right)
If :math:\mathrm{transf} = \texttt{'T'}, the state transition matrix, :math:A.

If :math:\mathrm{transf} = \texttt{'H'}, the transformed matrix as returned by a previous call to multi_kalman_sqrt_invar with :math:\mathrm{transf} = \texttt{'T'}.

**b** : float, array-like, shape :math:\left(n, l\right)
If :math:\mathrm{transf} = \texttt{'T'}, the noise coefficient matrix :math:B.

If :math:\mathrm{transf} = \texttt{'H'}, the transformed matrix as returned by a previous call to multi_kalman_sqrt_invar with :math:\mathrm{transf} = \texttt{'T'}.

**stq** : bool
If :math:\mathrm{stq} = \mathbf{True}, the state noise covariance matrix :math:Q_i is assumed to be the identity matrix. Otherwise the lower triangular Cholesky factor, :math:Q_i^{{1/2}}, must be provided in :math:\mathrm{q}.

**q** : float, array-like, shape :math:\left(:, :\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{not}\left(\mathrm{stq}\right): :math:l; otherwise: :math:1.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{not}\left(\mathrm{stq}\right): :math:l; otherwise: :math:0.

If :math:\mathrm{stq} = \mathbf{False}, :math:\mathrm{q} must contain the lower triangular Cholesky factor of the state noise covariance matrix, :math:Q_i^{{1/2}}. Otherwise :math:\mathrm{q} is not referenced.

**c** : float, array-like, shape :math:\left(m, n\right)
If :math:\mathrm{transf} = \texttt{'T'}, the measurement coefficient matrix, :math:C.

If :math:\mathrm{transf} = \texttt{'H'}, the transformed matrix as returned by a previous call to multi_kalman_sqrt_invar with :math:\mathrm{transf} = \texttt{'T'}.

**r** : float, array-like, shape :math:\left(m, m\right)
The lower triangular Cholesky factor of the measurement noise covariance matrix :math:R_i^{{1/2}}.

**s** : float, array-like, shape :math:\left(n, n\right)
If :math:\mathrm{transf} = \texttt{'T'} the lower triangular Cholesky factor of the state covariance matrix, :math:S_i.

If :math:\mathrm{transf} = \texttt{'H'} the lower triangular Cholesky factor of the covariance matrix of the transformed state vector :math:S_i^* as returned from a previous call to multi_kalman_sqrt_invar with :math:\mathrm{transf} = \texttt{'T'}.

**tol** : float, optional
The tolerance used to test for the singularity of :math:H_i^{{1/2}}. If :math:0.0\leq \mathrm{tol} < m^2\times \text{machine precision}, then :math:m^2\times \text{machine precision} is used instead. The inverse of the condition number of :math:H^{{1/2}} is estimated by a call to :meth:lapacklin.dtrcon <naginterfaces.library.lapacklin.dtrcon>. If this estimate is less than :math:\mathrm{tol} then :math:H^{{1/2}} is assumed to be singular.

**Returns**
**a** : float, ndarray, shape :math:\left(n, n\right)
If :math:\mathrm{transf} = \texttt{'T'}, the transformed matrix, :math:U^*AU^{{*T}}, otherwise :math:\mathrm{a} is unchanged.

**b** : float, ndarray, shape :math:\left(n, l\right)
If :math:\mathrm{transf} = \texttt{'T'}, the transformed matrix, :math:U^*B, otherwise :math:\mathrm{b} is unchanged.

**c** : float, ndarray, shape :math:\left(m, n\right)
If :math:\mathrm{transf} = \texttt{'T'}, the transformed matrix, :math:CU^{{*T}}, otherwise :math:\mathrm{c} is unchanged.

**s** : float, ndarray, shape :math:\left(n, n\right)
The lower triangular Cholesky factor of the transformed state covariance matrix, :math:S_{{i+1}}^*.

**k** : float, ndarray, shape :math:\left(n, m\right)
The Kalman gain matrix for the transformed state vector premultiplied by the state transformed transition matrix, :math:U^*AK_i.

**h** : float, ndarray, shape :math:\left(m, m\right)
The lower triangular matrix :math:H_i^{{1/2}}.

**u** : float, ndarray, shape :math:\left(n, :\right)
If :math:\mathrm{transf} = \texttt{'T'} the :math:n\times n transformation matrix :math:U^*, otherwise :math:\mathrm{u} is not referenced.

.. _g13eb-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{transf} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{transf} = \texttt{'T'} or :math:\texttt{'H'}.

(errno :math:1)
On entry, :math:\mathrm{tol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tol} \geq 0.0.

(errno :math:1)
On entry, :math:l = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:l \geq 1.

(errno :math:1)
On entry, :math:m = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:m \geq 1.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n \geq 1.

(errno :math:2)
The matrix :math:H_i^{{1/2}} is singular.

.. _g13eb-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

The Kalman filter arises from the state space model given by

.. math::
\begin{array}{ll}X_{{i+1}} = AX_i+BW_i\text{,}&\mathrm{Var}\left(W_i\right) = Q_i\\&\\Y_i = CX_i+V_i\text{,}&\mathrm{Var}\left(V_i\right) = R_i\end{array}

where :math:X_i is the state vector of length :math:n at time :math:i, :math:Y_i is the observation vector of length :math:m at time :math:i and :math:W_i of length :math:l and :math:V_i of length :math:m are the independent state noise and measurement noise respectively.
The matrices :math:A,B and :math:C are time invariant.

The estimate of :math:X_i given observations :math:Y_1 to :math:Y_{{i-1}} is denoted by :math:\hat{X}_{{i | i-1}} with state covariance matrix :math:\mathrm{Var}\left(\hat{X}_{{i | i-1}}\right) = P_{{i | i-1}} = S_iS_i^\mathrm{T} while the estimate of :math:X_i given observations :math:Y_1 to :math:Y_i is denoted by :math:\hat{X}_{{i | i}} with covariance matrix :math:\mathrm{Var}\left(\hat{X}_{{i | i}}\right) = P_{{i | i}}.
The update of the estimate, :math:\hat{X}_{{i | i-1}}, from time :math:i to time :math:\left(i+1\right) is computed in two stages.
First, the measurement-update is given by

.. math::
\hat{X}_{{i | i}} = \hat{X}_{{i | i-1}}+K_i\left[Y_i-C\hat{X}_{{i | i-1}}\right]

where :math:K_i = P_{{i | i}}C^\mathrm{T}{\left[CP_{{i | i}}C^\mathrm{T}+R_i\right]}^{-1} is the Kalman gain matrix.
The second stage is the time-update for :math:X, which is given by

.. math::
\hat{X}_{{i+1 | i}} = A\hat{X}_{{i | i}}+D_iU_i

where :math:D_iU_i represents any deterministic control used.

The square root covariance filter algorithm provides a stable method for computing the Kalman gain matrix and the state covariance matrix.
The algorithm can be summarised as

.. math::
\begin{pmatrix}R_i^{{1/2}}&0&CS_i\\&&\\0&BQ_i^{{1/2}}&AS_i\end{pmatrix}U = \begin{pmatrix}H_i^{{1/2}}&0&0\\&&\\G_i&S_{{i+1}}&0\end{pmatrix}

where :math:U is an orthogonal transformation triangularizing the left-hand pre-array to produce the right-hand post-array.
The triangularization is carried out via Householder transformations exploiting the zero pattern of the pre-array.
The relationship between the Kalman gain matrix :math:K_i and :math:G_i is given by

.. math::
AK_i = G_i\left(H_i^{{1/2}}\right)^{-1}\text{.}

In order to exploit the invariant parts of the model to simplify the computation of :math:U the results for the transformed state space :math:U^*X are computed where :math:U^* is the transformation that reduces the matrix pair :math:\left(A, C\right) to lower observer Hessenberg form.
That is, the matrix :math:U^* is computed such that the compound matrix

.. math::
\left[\begin{array}{c}CU^{{*T}}\\U^*AU^{{*T}}\end{array}\right]

is a lower trapezoidal matrix.
Further the matrix :math:B is transformed to :math:U^*B.
These transformations need only be computed once at the start of a series, and multi_kalman_sqrt_invar will, optionally, compute them. multi_kalman_sqrt_invar returns transformed matrices :math:U^*AU^{{*T}}, :math:U^*B, :math:CU^{{*T}} and :math:U^*AK_i, the Cholesky factor of the updated transformed state covariance matrix :math:S_{{i+1}}^* (where :math:U^*P_{{i+1 | i}}U^{{*T}} = S_{{i+1}}^*S_{{i+1}}^{{*T}}) and the matrix :math:H_i^{{1/2}}, valid for both transformed and original models, which is used in the computation of the likelihood for the model.
Note that the covariance matrices :math:Q_i and :math:R_i can be time-varying.

.. _g13eb-py2-py-references:

**References**
Vanbegin, M, van Dooren, P and Verhaegen, M H G, 1989, Algorithm 675: FORTRAN subroutines for computing the square root covariance filter and square root information filter in dense or Hessenberg forms, ACM Trans. Math. Software (15), 243--256

Verhaegen, M H G and van Dooren, P, 1986, Numerical aspects of different Kalman filter implementations, IEEE Trans. Auto. Contr. (AC-31), 907--917
"""
raise NotImplementedError

[docs]def kalman_unscented_state_revcom(irevcm, y, ly, x, st, xt, fxt, comm, lx=None, ropt=None):
r"""
kalman_unscented_state_revcom applies the Unscented Kalman Filter to a nonlinear state space model, with additive noise.

kalman_unscented_state_revcom uses reverse communication for evaluating the nonlinear functionals of the state space model.

.. _g13ej-py2-py-doc:

For full information please refer to the NAG Library document for g13ej

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ejf.html

.. _g13ej-py2-py-parameters:

**Parameters**
**irevcm** : int
On initial entry: must be set to :math:0 or :math:3.

If :math:\mathrm{irevcm} = 0, it is assumed that :math:t = 0, otherwise it is assumed that :math:t\neq 0 and that kalman_unscented_state_revcom has been called at least once before at an earlier time step.

On intermediate entry: :math:\mathrm{irevcm} must remain unchanged.

**y** : float, array-like, shape :math:\left(\textit{my}\right)
:math:y_t, the observed data at the current time point.

**ly** : float, array-like, shape :math:\left(\textit{my}, \textit{my}\right)
:math:L_y, such that :math:L_yL_y^\mathrm{T} = \Sigma_y, i.e., the lower triangular part of a Cholesky decomposition of the observation noise covariance structure. Only the lower triangular part of :math:\mathrm{ly} is referenced.

If :math:\Sigma_y is time dependent, the value supplied should be for time :math:t.

**x** : float, ndarray, shape :math:\left(\textit{mx}\right), modified in place
On initial entry: :math:\hat{x}_{{t-1}} the state vector for the previous time point.

On intermediate exit: when

:math:\mathrm{irevcm} = 1

:math:\mathrm{x} is unchanged.

:math:\mathrm{irevcm} = 2

:math:\hat{x}_{\bar{t}}.

On intermediate entry: :math:\mathrm{x} must remain unchanged.

On final exit: :math:\hat{x}_t the updated state vector.

**st** : float, ndarray, shape :math:\left(\textit{mx}, \textit{mx}\right), modified in place
On initial entry: :math:S_t, such that :math:S_{{t-1}}S_{{t-1}}^\mathrm{T} = P_{{t-1}}, i.e., the lower triangular part of a Cholesky decomposition of the state covariance matrix at the previous time point. Only the lower triangular part of :math:\mathrm{st} is referenced.

On intermediate exit: when

:math:\mathrm{irevcm} = 1

:math:\mathrm{st} is unchanged.

:math:\mathrm{irevcm} = 2

:math:S_{\bar{t}}, the lower triangular part of a Cholesky factorization of :math:P_{\bar{t}}.

On intermediate entry: :math:\mathrm{st} must remain unchanged.

On final exit: :math:S_t, the lower triangular part of a Cholesky factorization of the updated state covariance matrix.

**xt** : float, ndarray, shape :math:\left(\textit{mx}, :\right), modified in place
Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{irevcm}=0: :math:\max\left(\textit{my},n\right); if :math:\mathrm{irevcm}\text{ in } (1, 2, 3)\text{ and }\textit{licomm}\geq 10: :math:\max\left(\textit{my},\mathrm{comm}\ ['icomm'][9]\right); otherwise: :math:0.

On initial entry: need not be set.

On intermediate exit: :math:\mathcal{X}_t when :math:\mathrm{irevcm} = 1, otherwise :math:\mathcal{Y}_t.

For the :math:j\ th sigma point, the value for the :math:i\ th parameter is held in :math:\mathrm{xt}[\textit{i}-1,\textit{j}-1], for :math:\textit{j} = 1,2,\ldots,n, for :math:\textit{i} = 1,2,\ldots,\textit{mx}.

On intermediate entry: :math:\mathrm{xt} must remain unchanged.

On final exit: the contents of :math:\mathrm{xt} are undefined.

**fxt** : float, ndarray, shape :math:\left(:, :\right), modified in place
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{irevcm}\text{ in } (1, 2): :math:\max\left(\textit{mx},\textit{my}\right); otherwise: :math:0.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{irevcm}=1: :math:{ n+\textit{mx} }; if :math:\mathrm{irevcm}=2: :math:{ n+\textit{my} }; otherwise: :math:0.

On initial entry: need not be set.

On intermediate exit: the contents of :math:\mathrm{fxt} are undefined.

On intermediate entry: :math:F\left(\mathcal{X}_t\right) when :math:\mathrm{irevcm} = 1, otherwise :math:H\left(\mathcal{Y}_t\right) for the values of :math:\mathcal{X}_t and :math:\mathcal{Y}_t held in :math:\mathrm{xt}.

For the :math:j\ th sigma point the value for the :math:i\ th parameter should be held in :math:\mathrm{fxt}[i-1,\textit{j}-1], for :math:\textit{j} = 1,2,\ldots,n.

When :math:\mathrm{irevcm} = 1, :math:i = 1,2,\ldots,\textit{mx} and when :math:\mathrm{irevcm} = 2, :math:i = 1,2,\ldots,\textit{my}.

On final exit: the contents of :math:\mathrm{fxt} are undefined.

**comm** : dict, communication object, modified in place
Communication structure.

On initial entry: need not be set.

**lx** : None or float, array-like, shape :math:\left(:, \textit{mx}\right), optional
:math:L_x, such that :math:L_xL_x^\mathrm{T} = \Sigma_x, i.e., the lower triangular part of a Cholesky decomposition of the process noise covariance structure. Only the lower triangular part of :math:\mathrm{lx} is referenced.

If :math:\textit{ldlx} = 0, there is no process noise (:math:v_t = 0 for all :math:t) and :math:\mathrm{lx} is not referenced.

If :math:\Sigma_x is time dependent, the value supplied should be for time :math:t.

**ropt** : None or float, array-like, shape :math:\left(\textit{lropt}\right), optional
Options. The default value will be used for :math:\mathrm{ropt}[i-1] if :math:\textit{lropt} < i. Setting :math:\textit{lropt} = 0 will use the default values for all options and :math:\mathrm{ropt} need not be set.

:math:\mathrm{ropt}[0]

If set to :math:1 then the second set of sigma points are redrawn, as given by equation [equation] <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ejf.html#eqn_ukf_5>__. If set to :math:2 then the second set of sigma points are generated via augmentation, as given by equation [equation] <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ejf.html#eqn_ukf_5alt>__.

Default is for the sigma points to be redrawn (i.e., :math:\mathrm{ropt}[0] = 1)

:math:\mathrm{ropt}[1]

:math:\kappa_x, value of :math:\kappa used when constructing the first set of sigma points, :math:\mathcal{X}_t.

Defaults to :math:3-\textit{mx}.

:math:\mathrm{ropt}[2]

:math:\alpha_x, value of :math:\alpha used when constructing the first set of sigma points, :math:\mathcal{X}_t.

Defaults to :math:1.

:math:\mathrm{ropt}[3]

:math:\beta_x, value of :math:\beta used when constructing the first set of sigma points, :math:\mathcal{X}_t.

Defaults to :math:2.

:math:\mathrm{ropt}[4]

Value of :math:\kappa used when constructing the second set of sigma points, :math:\mathcal{Y}_t.

Defaults to :math:3-2\times \textit{mx} when :math:\textit{ldlx} \neq 0 and the second set of sigma points are augmented and :math:\kappa_x otherwise.

:math:\mathrm{ropt}[5]

Value of :math:\alpha used when constructing the second set of sigma points, :math:\mathcal{Y}_t.

Defaults to :math:\alpha_x.

:math:\mathrm{ropt}[6]

Value of :math:\beta used when constructing the second set of sigma points, :math:\mathcal{Y}_t.

Defaults to :math:\beta_x.

**Returns**
**irevcm** : int
On intermediate exit: :math:\mathrm{irevcm} = 1 or :math:2. The value of :math:\mathrm{irevcm} specifies what intermediate values are returned by this function and what values the calling program must assign to arguments of kalman_unscented_state_revcom before re-entering the routine. Details of the output and required input are given in the individual argument descriptions.

On final exit: :math:\mathrm{irevcm} = 3

.. _g13ej-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:11)
On entry, :math:\mathrm{irevcm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irevcm} = 0, :math:1, :math:2 or :math:3.

(errno :math:21)
On entry, :math:\textit{mx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{mx}\geq 1.

(errno :math:22)
:math:\textit{mx} has changed between calls.

On intermediate entry, :math:\textit{mx} = \langle\mathit{\boldsymbol{value}}\rangle.

On initial entry, :math:\textit{mx} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:31)
On entry, :math:\textit{my} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{my}\geq 1.

(errno :math:32)
:math:\textit{my} has changed between calls.

On intermediate entry, :math:\textit{my} = \langle\mathit{\boldsymbol{value}}\rangle.

On initial entry, :math:\textit{my} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:121)
On entry, augmented sigma points requested, :math:n = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{mx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:122)
On entry, redrawn sigma points requested, :math:n = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{mx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:123)
:math:\textit{n} has changed between calls.

On intermediate entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

On intermediate exit, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:171)
On entry, :math:\mathrm{ropt}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ropt}[0] = 1 or :math:2.

(errno :math:172)
On entry, :math:\mathrm{ropt}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\kappa > \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:173)
On entry, :math:\mathrm{ropt}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\alpha > 0.

(errno :math:181)
On entry, :math:\textit{lropt} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:0\leq \textit{lropt}\leq 7.

(errno :math:191)
:math:\mathrm{comm}\ ['icomm'] has been corrupted between calls.

(errno :math:211)
:math:\mathrm{comm}\ ['rcomm'] has been corrupted between calls.

(errno :math:301)
A weight was negative and it was not possible to downdate the Cholesky factorization.

(errno :math:302)
Unable to calculate the Kalman gain matrix.

(errno :math:303)
Unable to calculate the Cholesky factorization of the updated state covariance matrix.

**Warns**
**NagAlgorithmicWarning**
(errno :math:202)
On entry, :math:\textit{licomm} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{lrcomm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{licomm}\geq 30 and :math:\textit{lrcomm}\geq 30+\textit{my}+\textit{mx}\times \textit{my}+2\times \mathrm{max}\left(\textit{mx}, \textit{my}\right).

The minimum required values for :math:\textit{licomm} and :math:\textit{lrcomm} are returned in :math:\mathrm{comm}\ ['icomm'][0] and :math:\mathrm{comm}\ ['icomm'][1] respectively.

.. _g13ej-py2-py-notes:

**Notes**
kalman_unscented_state_revcom applies the Unscented Kalman Filter (UKF), as described in Julier and Uhlmann (1997b) to a nonlinear state space model, with additive noise, which, at time :math:t, can be described by:

.. math::
\begin{array}{cc}x_{{t+1}}&{} = F\left(x_t\right)+v_t\\y_{{t}}&{} = H\left(x_t\right)+u_t\end{array}

where :math:x_t represents the unobserved state vector of length :math:m_x and :math:y_t the observed measurement vector of length :math:m_y.
The process noise is denoted :math:v_t, which is assumed to have mean zero and covariance structure :math:\Sigma_x, and the measurement noise by :math:u_t, which is assumed to have mean zero and covariance structure :math:\Sigma_y.

**Unscented Kalman Filter Algorithm**

Given :math:\hat{x}_0, an initial estimate of the state and :math:P_0 and initial estimate of the state covariance matrix, the UKF can be described as follows:

(a) Generate a set of sigma points (see Sigma Points <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ejf.html#ukf_sigmapoints>__):

.. math::
\begin{array}{cc}\mathcal{X}_t&{} = \left[\hat{ x }_{{t-1}} \hat{ x }_{{t-1}}+γ\sqrt{P_{{t-1}}} \hat{ x }_{{t-1}}-γ\sqrt{P_{{t-1}}}\right] \end{array}

(#) Evaluate the known model function :math:F:

.. math::
\begin{array}{cc}\mathcal{F}_t&{} = F\left(\mathcal{X}_t\right)\end{array}

The function :math:F is assumed to accept the :math:m_x\times n matrix, :math:\mathcal{X}_t and return an :math:m_x\times n matrix, :math:\mathcal{F}_t. The columns of both :math:\mathcal{X}_t and :math:\mathcal{F}_t correspond to different possible states. The notation :math:\mathcal{F}_{{t,i}} is used to denote the :math:i\ th column of :math:\mathcal{F}_t, hence the result of applying :math:F to the :math:i\ th possible state.

(#) Time Update:

.. math::
\begin{array}{cc} \hat{x}_{\bar{t}} &{} = \sum_{{i = 1}}^{{n}} W_i^m \mathcal{F}_{{t,i}} \\ P_{\bar{t}} &{} = \sum_{{i = 1}}^{{n}} W_i^c \left(\mathcal{F}_{{t,i}}-\hat{x}_{\hat{t}}\right) \left(\mathcal{F}_{{t,i}}-\hat{x}_{\hat{t}}\right)^\mathrm{T} + \Sigma_x \end{array}

(#) Redraw another set of sigma points (see Sigma Points <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ejf.html#ukf_sigmapoints>__):

.. math::
\begin{array}{cc} \mathcal{Y}_t &{} = \left[\hat{x}_{\hat{t}} \hat{x}_{\hat{t}}+γ\sqrt{P_{\bar{t}}} \hat{x}_{\hat{t}}-γ\sqrt{P_{\bar{t}}}\right] \end{array}

(#) Evaluate the known model function :math:H:

.. math::
\begin{array}{cc}\mathcal{H}_t&{} = H\left(\mathcal{Y}_t\right)\end{array}

The function :math:H is assumed to accept the :math:m_x\times n matrix, :math:\mathcal{Y}_t and return an :math:m_y\times n matrix, :math:\mathcal{H}_t. The columns of both :math:\mathcal{Y}_t and :math:\mathcal{H}_t correspond to different possible states. As above :math:\mathcal{H}_{{t,i}} is used to denote the :math:i\ th column of :math:\mathcal{H}_t.

(#) Measurement Update:

.. math::
\begin{array}{cc} \hat{ y }_t &{} = \sum_{{i = 1}}^{{n}} W_i^m \mathcal{H}_{{t,i}} \\ P_{{yy_t}} &{} = \sum_{{i = 1}}^{{n}} W_i^c \left(\mathcal{H}_{{t,i}}-\hat{ y }_t\right) \left(\mathcal{H}_{{t,i}}-\hat{ y }_t\right)^\mathrm{T} + \Sigma_y \\ P_{{xy_t}} &{} = \sum_{{i = 1}}^{{n}} W_i^c \left(\mathcal{F}_{{t,i}}-\hat{x}_{\hat{t}}\right) \left(\mathcal{H}_{{t,i}}-\hat{ y }_t\right)^\mathrm{T} \\ \mathcal{K}_t &{} = P_{{xy_t}} P_{{yy_t}}^{-1} \\ \hat{x}_t &{} = \hat{x}_{\hat{t}} + \mathcal{K}_t \left(y_t-\hat{y}_t\right) \\ P_t &{} = P_{\bar{t}} - \mathcal{K}_t P_{{yy_t}} \mathcal{K}_t^\mathrm{T} \end{array}

Here :math:\mathcal{K}_t is the Kalman gain matrix, :math:\hat{x}_t is the estimated state vector at time :math:t and :math:P_t the corresponding covariance matrix.
Rather than implementing the standard UKF as stated above kalman_unscented_state_revcom uses the square-root form described in the Haykin (2001).

**Sigma Points**

A nonlinear state space model involves propagating a vector of random variables through a nonlinear system and we are interested in what happens to the mean and covariance matrix of those variables.
Rather than trying to directly propagate the mean and covariance matrix, the UKF uses a set of carefully chosen sample points, referred to as sigma points, and propagates these through the system of interest.
An estimate of the propagated mean and covariance matrix is then obtained via the weighted sample mean and covariance matrix.

For a vector of :math:m random variables, :math:x, with mean :math:\mu and covariance matrix :math:\Sigma, the sigma points are usually constructed as:

.. math::
\mathcal{X}_t = \left[\mu \mu +γ\sqrt{\Sigma } \mu -γ\sqrt{\Sigma }\right]

When calculating the weighted sample mean and covariance matrix two sets of weights are required, one used when calculating the weighted sample mean, denoted :math:W^m and one used when calculating the weighted sample covariance matrix, denoted :math:W^c.
The weights and multiplier, :math:\gamma, are constructed as follows:

.. math::
\begin{array}{cc}\lambda &{} = \alpha^2\left(L+\kappa \right)-L\\\gamma &{} = \sqrt{L+\lambda }\\W_i^m&{} = \left\{\begin{array}{cc}\frac{\lambda }{{L+\lambda }}&i = 1\\ \frac{1}{{2\left(L+\lambda \right)}} &i = 2,3,\ldots,2L+1\end{array}\right. \\W_i^c&{} = \left\{\begin{array}{cc} \frac{\lambda }{{L+\lambda }} +1-\alpha^2+\beta &i = 1\\ \frac{1}{{2\left(L+\lambda \right)}} &i = 2,3,\ldots,2L+1\end{array}\right. \end{array}

where, usually :math:L = m and :math:\alpha,\beta and :math:\kappa are constants.
The total number of sigma points, :math:n, is given by :math:2L+1.
The constant :math:\alpha is usually set to somewhere in the range :math:10^{-4}\leq \alpha \leq 1 and for a Gaussian distribution, the optimal values of :math:\kappa and :math:\beta are :math:3-L and :math:2 respectively.

Rather than redrawing another set of sigma points in \(d) of the UKF an alternative method can be used where the sigma points used in \(a) are augmented to take into account the process noise.
This involves replacing equation [equation] <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ejf.html#eqn_ukf_5>__ with:

.. math::
\begin{array}{cc} \mathcal{Y}_t &{} = \left[\mathcal{X}_t \mathcal{X}_{{t,1}}+γ\sqrt{\Sigma_x} \mathcal{X}_{{t,1}}-γ\sqrt{\Sigma_x}\right] \end{array}

Augmenting the sigma points in this manner requires setting :math:L to :math:2L (and hence :math:n to :math:2n-1) and recalculating the weights.
These new values are then used for the rest of the algorithm.
The advantage of augmenting the sigma points is that it keeps any odd-moments information captured by the original propagated sigma points, at the cost of using a larger number of points.

.. _g13ej-py2-py-references:

**References**
Haykin, S, 2001, Kalman Filtering and Neural Networks, John Wiley and Sons

Julier, S J, 2002, The scaled unscented transformation, Proceedings of the 2002 American Control Conference (Volume 6), 4555--4559

Julier, S J and Uhlmann, J K, 1997, A consistent, debiased method for converting between polar and Cartesian coordinate systems, Proceedings of AeroSense '97, International Society for Optics and Phonotonics, 110--121

Julier, S J and Uhlmann, J K, 1997, A new extension of the Kalman Filter to nonlinear systems, International Symposium for Aerospace/Defense, Sensing, Simulation and Controls (Volume 3) (26)
"""
raise NotImplementedError

[docs]def kalman_unscented_state(y, lx, ly, f, h, x, st, data=None, spiked_sorder='C'):
r"""
kalman_unscented_state applies the Unscented Kalman Filter (UKF) to a nonlinear state space model, with additive noise.

kalman_unscented_state uses direct communication for evaluating the nonlinear functionals of the state space model.

.. _g13ek-py2-py-doc:

For full information please refer to the NAG Library document for g13ek

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ekf.html

.. _g13ek-py2-py-parameters:

**Parameters**
**y** : float, array-like, shape :math:\left(\textit{my}\right)
:math:y_t, the observed data at the current time point.

**lx** : float, array-like, shape :math:\left(\textit{mx}, \textit{mx}\right)
:math:L_x, such that :math:L_xL_x^\mathrm{T} = \Sigma_x, i.e., the lower triangular part of a Cholesky decomposition of the process noise covariance structure. Only the lower triangular part of :math:\mathrm{lx} is referenced.

If :math:\Sigma_x is time dependent, the value supplied should be for time :math:t.

**ly** : float, array-like, shape :math:\left(\textit{my}, \textit{my}\right)
:math:L_y, such that :math:L_yL_y^\mathrm{T} = \Sigma_y, i.e., the lower triangular part of a Cholesky decomposition of the observation noise covariance structure. Only the lower triangular part of :math:\mathrm{ly} is referenced.

If :math:\Sigma_y is time dependent, the value supplied should be for time :math:t.

**f** : callable fxt = f(xt, data=None)
The state function, :math:F.

**Parameters**
**xt** : float, ndarray, shape :math:\left(\textit{mx}, n\right)
:math:\mathcal{X}_t, the sigma points generated in \(a). For the :math:j\ th sigma point, the value for the :math:i\ th parameter is held in :math:\mathrm{xt}[\textit{i}-1,\textit{j}-1], for :math:\textit{j} = 1,2,\ldots,n, for :math:\textit{i} = 1,2,\ldots,m_x.

**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.

**Returns**
**fxt** : float, array-like, shape :math:\left(\textit{mx}, n\right)
:math:F\left(\mathcal{X}_t\right).

For the :math:j\ th sigma point the value for the :math:i\ th parameter should be held in :math:\mathrm{fxt}[\textit{i}-1,\textit{j}-1], for :math:\textit{j} = 1,2,\ldots,n, for :math:\textit{i} = 1,2,\ldots,m_x.

**h** : callable hyt = h(my, yt, data=None)
The measurement function, :math:H as described in \(e).

**Parameters**
**my** : int
:math:m_y, the number of observed variables.

**yt** : float, ndarray, shape :math:\left(\textit{mx}, n\right)
:math:\mathcal{Y}_t, the sigma points generated in \(d). For the :math:j\ th sigma point, the value for the :math:i\ th parameter is held in :math:\mathrm{yt}[\textit{i}-1,\textit{j}-1], for :math:\textit{j} = 1,2,\ldots,n, for :math:\textit{i} = 1,2,\ldots,m_x, where :math:m_x is the number of state variables and :math:n is the number of sigma points.

**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.

**Returns**
**hyt** : float, array-like, shape :math:\left(\mathrm{my}, n\right)
:math:H\left(\mathcal{Y}_t\right).

For the :math:j\ th sigma point the value for the :math:i\ th parameter should be held in :math:\mathrm{hyt}[\textit{i}-1,\textit{j}-1], for :math:\textit{j} = 1,2,\ldots,n, for :math:\textit{i} = 1,2,\ldots,m_y.

**x** : float, array-like, shape :math:\left(\textit{mx}\right)
:math:\hat{x}_{{t-1}} the state vector for the previous time point.

**st** : float, array-like, shape :math:\left(\textit{mx}, \textit{mx}\right)
:math:S_t, such that :math:S_{{t-1}}S_{{t-1}}^\mathrm{T} = P_{{t-1}}, i.e., the lower triangular part of a Cholesky decomposition of the state covariance matrix at the previous time point. Only the lower triangular part of :math:\mathrm{st} is referenced.

**data** : arbitrary, optional
User-communication data for callback functions.

**spiked_sorder** : str, optional
If :math:\mathrm{lx} and :math:\mathrm{st} are spiked (i.e., have unit extent in all but one dimension, or have size :math:1), :math:\mathrm{spiked\_sorder} selects the storage order to associate with them in the NAG Engine:

spiked_sorder = :math:\texttt{'C'}
row-major storage will be used;

spiked_sorder = :math:\texttt{'F'}
column-major storage will be used.

Two-dimensional arrays returned from callback functions in this routine must then use the same storage order.

**Returns**
**x** : float, ndarray, shape :math:\left(\textit{mx}\right)
:math:\hat{x}_t the updated state vector.

**st** : float, ndarray, shape :math:\left(\textit{mx}, \textit{mx}\right)
:math:S_t, the lower triangular part of a Cholesky factorization of the updated state covariance matrix.

.. _g13ek-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:11)
On entry, :math:\textit{mx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{mx}\geq 1.

(errno :math:21)
On entry, :math:\textit{my} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{my}\geq 1.

(errno :math:301)
A weight was negative and it was not possible to downdate the Cholesky factorization.

(errno :math:302)
Unable to calculate the Kalman gain matrix.

(errno :math:303)
Unable to calculate the Cholesky factorization of the updated state covariance matrix.

**Warns**
**NagCallbackTerminateWarning**
(errno :math:61)
User requested termination in :math:\mathrm{f}.

(errno :math:71)
User requested termination in :math:\mathrm{h}.

.. _g13ek-py2-py-notes:

**Notes**
kalman_unscented_state applies the Unscented Kalman Filter (UKF), as described in Julier and Uhlmann (1997b) to a nonlinear state space model, with additive noise, which, at time :math:t, can be described by:

.. math::
\begin{array}{cc}x_{{t+1}}&{} = F\left(x_t\right)+v_t\\y_{{t}}&{} = H\left(x_t\right)+u_t\end{array}

where :math:x_t represents the unobserved state vector of length :math:m_x and :math:y_t the observed measurement vector of length :math:m_y.
The process noise is denoted :math:v_t, which is assumed to have mean zero and covariance structure :math:\Sigma_x, and the measurement noise by :math:u_t, which is assumed to have mean zero and covariance structure :math:\Sigma_y.

**Unscented Kalman Filter Algorithm**

Given :math:\hat{x}_0, an initial estimate of the state and :math:P_0 and initial estimate of the state covariance matrix, the UKF can be described as follows:

(a) Generate a set of sigma points (see Sigma Points <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ekf.html#ukf_sigmapoints>__):

.. math::
\begin{array}{cc}\mathcal{X}_t&{} = \left[\hat{ x }_{{t-1}} \hat{ x }_{{t-1}}+γ\sqrt{P_{{t-1}}} \hat{ x }_{{t-1}}-γ\sqrt{P_{{t-1}}}\right] \end{array}

(#) Evaluate the known model function :math:F:

.. math::
\begin{array}{cc}\mathcal{F}_t&{} = F\left(\mathcal{X}_t\right)\end{array}

The function :math:F is assumed to accept the :math:m_x\times n matrix, :math:\mathcal{X}_t and return an :math:m_x\times n matrix, :math:\mathcal{F}_t. The columns of both :math:\mathcal{X}_t and :math:\mathcal{F}_t correspond to different possible states. The notation :math:\mathcal{F}_{{t,i}} is used to denote the :math:i\ th column of :math:\mathcal{F}_t, hence the result of applying :math:F to the :math:i\ th possible state.

(#) Time Update:

.. math::
\begin{array}{cc} \hat{x}_{\bar{t}} &{} = \sum_{{i = 1}}^{{n}} W_i^m \mathcal{F}_{{t,i}} \\ P_{\bar{t}} &{} = \sum_{{i = 1}}^{{n}} W_i^c \left(\mathcal{F}_{{t,i}}-\hat{x}_{\hat{t}}\right) \left(\mathcal{F}_{{t,i}}-\hat{x}_{\hat{t}}\right)^\mathrm{T} + \Sigma_x \end{array}

(#) Redraw another set of sigma points (see Sigma Points <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ekf.html#ukf_sigmapoints>__):

.. math::
\begin{array}{cc} \mathcal{Y}_t &{} = \left[\hat{x}_{\hat{t}} \hat{x}_{\hat{t}}+γ\sqrt{P_{\bar{t}}} \hat{x}_{\hat{t}}-γ\sqrt{P_{\bar{t}}}\right] \end{array}

(#) Evaluate the known model function :math:H:

.. math::
\begin{array}{cc}\mathcal{H}_t&{} = H\left(\mathcal{Y}_t\right)\end{array}

The function :math:H is assumed to accept the :math:m_x\times n matrix, :math:\mathcal{Y}_t and return an :math:m_y\times n matrix, :math:\mathcal{H}_t. The columns of both :math:\mathcal{Y}_t and :math:\mathcal{H}_t correspond to different possible states. As above :math:\mathcal{H}_{{t,i}} is used to denote the :math:i\ th column of :math:\mathcal{H}_t.

(#) Measurement Update:

.. math::
\begin{array}{cc} \hat{ y }_t &{} = \sum_{{i = 1}}^{{n}} W_i^m \mathcal{H}_{{t,i}} \\ P_{{yy_t}} &{} = \sum_{{i = 1}}^{{n}} W_i^c \left(\mathcal{H}_{{t,i}}-\hat{ y }_t\right) \left(\mathcal{H}_{{t,i}}-\hat{ y }_t\right)^\mathrm{T} + \Sigma_y \\ P_{{xy_t}} &{} = \sum_{{i = 1}}^{{n}} W_i^c \left(\mathcal{F}_{{t,i}}-\hat{x}_{\hat{t}}\right) \left(\mathcal{H}_{{t,i}}-\hat{y}_t\right)^\mathrm{T} \\ \mathcal{K}_t &{} = P_{{xy_t}} P_{{yy_t}}^{-1} \\ \hat{x}_t &{} = \hat{x}_{\hat{t}} + \mathcal{K}_t \left(y_t-\hat{y}_t\right) \\ P_t &{} = P_{\bar{t}} - \mathcal{K}_t P_{{yy_t}} \mathcal{K}_t^\mathrm{T} \end{array}

Here :math:\mathcal{K}_t is the Kalman gain matrix, :math:\hat{x}_t is the estimated state vector at time :math:t and :math:P_t the corresponding covariance matrix.
Rather than implementing the standard UKF as stated above kalman_unscented_state uses the square-root form described in the Haykin (2001).

**Sigma Points**

A nonlinear state space model involves propagating a vector of random variables through a nonlinear system and we are interested in what happens to the mean and covariance matrix of those variables.
Rather than trying to directly propagate the mean and covariance matrix, the UKF uses a set of carefully chosen sample points, referred to as sigma points, and propagates these through the system of interest.
An estimate of the propagated mean and covariance matrix is then obtained via the weighted sample mean and covariance matrix.

For a vector of :math:m random variables, :math:x, with mean :math:\mu and covariance matrix :math:\Sigma, the sigma points are usually constructed as:

.. math::
\mathcal{X}_t = \left[\mu \mu +γ\sqrt{\Sigma } \mu -γ\sqrt{\Sigma }\right]

When calculating the weighted sample mean and covariance matrix two sets of weights are required, one used when calculating the weighted sample mean, denoted :math:W^m and one used when calculating the weighted sample covariance matrix, denoted :math:W^c.
The weights and multiplier, :math:\gamma, are constructed as follows:

.. math::
\begin{array}{cc}\lambda &{} = \alpha^2\left(L+\kappa \right)-L\\\gamma &{} = \sqrt{L+\lambda }\\W_i^m&{} = \left\{\begin{array}{cc}\frac{\lambda }{{L+\lambda }}&\quad \text{ }\quad i = 1\\ \frac{1}{{2\left(L+\lambda \right)}} &\quad \text{ }\quad i = 2,3,\ldots,2L+1\end{array}\right. \\W_i^c&{} = \left\{\begin{array}{cc} \frac{\lambda }{{L+\lambda }} +1-\alpha^2+\beta &i = 1\\ \frac{1}{{2\left(L+\lambda \right)}} &i = 2,3,\ldots,2L+1\end{array}\right. \end{array}

where, usually :math:L = m and :math:\alpha,\beta and :math:\kappa are constants.
The total number of sigma points, :math:n, is given by :math:2L+1.
The constant :math:\alpha is usually set to somewhere in the range :math:10^{-4}\leq \alpha \leq 1 and for a Gaussian distribution, the optimal values of :math:\kappa and :math:\beta are :math:3-L and :math:2 respectively.

The constants, :math:\kappa, :math:\alpha and :math:\beta are given by :math:\kappa = 3-m_x, :math:\alpha = 1.0 and :math:\beta = 2.
If more control is required over the construction of the sigma points then the reverse communication function, :meth:kalman_unscented_state_revcom, can be used instead.

.. _g13ek-py2-py-references:

**References**
Haykin, S, 2001, Kalman Filtering and Neural Networks, John Wiley and Sons

Julier, S J, 2002, The scaled unscented transformation, Proceedings of the 2002 American Control Conference (Volume 6), 4555--4559

Julier, S J and Uhlmann, J K, 1997, A consistent, debiased method for converting between polar and Cartesian coordinate systems, Proceedings of AeroSense '97, International Society for Optics and Phonotonics, 110--121

Julier, S J and Uhlmann, J K, 1997, A new extension of the Kalman Filter to nonlinear systems, International Symposium for Aerospace/Defense, Sensing, Simulation and Controls (Volume 3) (26)

--------
:meth:naginterfaces.library.examples.tsa.kalman_unscented_state_ex.main
"""
raise NotImplementedError

[docs]def uni_garch_asym1_estim(dist, yt, x, ip, iq, mn, isym, theta, pht, copts, maxit, tol, io_manager=None):
r"""
uni_garch_asym1_estim estimates the parameters of either a standard univariate regression GARCH process, or a univariate regression-type I :math:\text{AGARCH}\left(p, q\right) process (see Engle and Ng (1993)).

.. _g13fa-py2-py-doc:

For full information please refer to the NAG Library document for g13fa

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13faf.html

.. _g13fa-py2-py-parameters:

**Parameters**
**dist** : str, length 1
The type of distribution to use for :math:e_t.

:math:\mathrm{dist} = \texttt{'N'}

A Normal distribution is used.

:math:\mathrm{dist} = \texttt{'T'}

A Student's :math:t-distribution is used.

**yt** : float, array-like, shape :math:\left(\textit{num}\right)
The sequence of observations, :math:y_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**x** : float, array-like, shape :math:\left(\textit{num}, \textit{nreg}\right)
Row :math:\textit{t} of :math:\mathrm{x} must contain the time dependent exogenous vector :math:x_{\textit{t}}, where :math:x_{\textit{t}}^\mathrm{T} = \left(x_{\textit{t}}^1, \ldots, x_{\textit{t}}^k\right), for :math:\textit{t} = 1,2,\ldots,T.

**ip** : int
The number of coefficients, :math:\beta_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,p.

**iq** : int
The number of coefficients, :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

**mn** : int
If :math:\mathrm{mn} = 1, the mean term :math:b_0 will be included in the model.

**isym** : int
If :math:\mathrm{isym} = 1, the asymmetry term :math:\gamma will be included in the model.

**theta** : float, array-like, shape :math:\left(\textit{npar}\right)
The initial parameter estimates for the vector :math:\theta.

The first element must contain the coefficient :math:\alpha_o and the next :math:\mathrm{iq} elements must contain the coefficients :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{ip} elements must contain the coefficients :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

If :math:\mathrm{isym} = 1, the next element must contain the asymmetry parameter :math:\gamma.

If :math:\mathrm{dist} = \texttt{'T'}, the next element must contain :math:{\textit{df}}, the number of degrees of freedom of the Student's :math:t-distribution.

If :math:\mathrm{mn} = 1, the next element must contain the mean term :math:b_o.

If :math:\mathrm{copts}[1] = \mathbf{False}, the remaining :math:\textit{nreg} elements are taken as initial estimates of the linear regression coefficients :math:b_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k.

**pht** : float
If :math:\mathrm{copts}[1] = \mathbf{False}, :math:\mathrm{pht} is the value to be used for the pre-observed conditional variance; otherwise :math:\mathrm{pht} is not referenced.

**copts** : bool, array-like, shape :math:\left(2\right)
The options to be used by uni_garch_asym1_estim.

:math:\mathrm{copts}[0] = \mathbf{True}

Stationary conditions are enforced, otherwise they are not.

:math:\mathrm{copts}[1] = \mathbf{True}

The function provides initial parameter estimates of the regression terms, otherwise these are to be provided by you.

**maxit** : int
The maximum number of iterations to be used by the optimization function when estimating the :math:\text{GARCH}\left(p, q\right) parameters. If :math:\mathrm{maxit} is set to :math:0, the standard errors, score vector and variance-covariance are calculated for the input value of :math:\theta in :math:\mathrm{theta} when :math:\mathrm{dist} = \texttt{'N'}; however the value of :math:\theta is not updated.

**tol** : float
The tolerance to be used by the optimization function when estimating the :math:\text{GARCH}\left(p, q\right) parameters.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**theta** : float, ndarray, shape :math:\left(\textit{npar}\right)
The estimated values :math:\hat{\theta } for the vector :math:\theta.

The first element contains the coefficient :math:\alpha_o, the next :math:\mathrm{iq} elements contain the coefficients :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{ip} elements are the coefficients :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

If :math:\mathrm{isym} = 1, the next element contains the estimate for the asymmetry parameter :math:\gamma.

If :math:\mathrm{dist} = \texttt{'T'}, the next element contains an estimate for :math:{\textit{df}}, the number of degrees of freedom of the Student's :math:t-distribution.

If :math:\mathrm{mn} = 1, the next element contains an estimate for the mean term :math:b_o.

The final :math:\textit{nreg} elements are the estimated linear regression coefficients :math:b_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k.

**se** : float, ndarray, shape :math:\left(\textit{npar}\right)
The standard errors for :math:\hat{\theta }.

The first element contains the standard error for :math:\alpha_o.

The next :math:\mathrm{iq} elements contain the standard errors for :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{ip} elements are the standard errors for :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

If :math:\mathrm{isym} = 1, the next element contains the standard error for :math:\gamma.

If :math:\mathrm{dist} = \texttt{'T'}, the next element contains the standard error for :math:{\textit{df}}, the number of degrees of freedom of the Student's :math:t-distribution.

If :math:\mathrm{mn} = 1, the next element contains the standard error for :math:b_o.

The final :math:\textit{nreg} elements are the standard errors for :math:b_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,k.

**sc** : float, ndarray, shape :math:\left(\textit{npar}\right)
The scores for :math:\hat{\theta }.

The first element contains the score for :math:\alpha_o.

The next :math:\mathrm{iq} elements contain the score for :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{ip} elements are the scores for :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

If :math:\mathrm{isym} = 1, the next element contains the score for :math:\gamma.

If :math:\mathrm{dist} = \texttt{'T'}, the next element contains the score for :math:{\textit{df}}, the number of degrees of freedom of the Student's :math:t-distribution.

If :math:\mathrm{mn} = 1, the next element contains the score for :math:b_o.

The final :math:\textit{nreg} elements are the scores for :math:b_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,k.

**covr** : float, ndarray, shape :math:\left(\textit{npar}, \textit{npar}\right)
The covariance matrix of the parameter estimates :math:\hat{\theta }, that is the inverse of the Fisher Information Matrix.

**pht** : float
If :math:\mathrm{copts}[1] = \mathbf{True}, :math:\mathrm{pht} is the estimated value of the pre-observed conditional variance.

**et** : float, ndarray, shape :math:\left(\textit{num}\right)
The estimated residuals, :math:\epsilon_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**ht** : float, ndarray, shape :math:\left(\textit{num}\right)
The estimated conditional variances, :math:h_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**lgf** : float
The value of the log-likelihood function at :math:\hat{\theta }.

.. _g13fa-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{num} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{num}\geq \textit{nreg}+\mathrm{mn}.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npar} < 20.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{dist} = \texttt{'N'} then :math:\textit{npar} = 1+\mathrm{iq}+\mathrm{ip}+\mathrm{isym}+\mathrm{mn}+\textit{nreg}, else :math:\textit{npar} = 2+\mathrm{iq}+\mathrm{ip}+\mathrm{isym}+\mathrm{mn}+\textit{nreg}.

(errno :math:1)
On entry, :math:\textit{num} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{max}\left(\mathrm{ip}, \mathrm{iq}\right)\leq \textit{num}.

(errno :math:1)
On entry, :math:\mathrm{maxit} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxit} \geq 0.

(errno :math:1)
On entry, :math:\mathrm{dist} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dist} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:1)
On entry, :math:\mathrm{iq} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iq} \geq 1.

(errno :math:1)
On entry, :math:\mathrm{ip} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ip} \geq 0.

(errno :math:1)
On entry, :math:\mathrm{mn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mn} = 0 or :math:1.

(errno :math:1)
On entry, :math:\mathrm{isym} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{isym} = 0 or :math:1.

(errno :math:1)
On entry, :math:\textit{nreg} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nreg} \geq 0.

(errno :math:3)
On entry, the matrix :math:X is not full rank.

(errno :math:4)
The information matrix is not positive definite.

(errno :math:5)
The maximum number of iterations has been reached.

(errno :math:7)
No feasible model parameters could be found.

**Warns**
**NagAlgorithmicWarning**
(errno :math:6)
The log-likelihood cannot be optimized any further.

.. _g13fa-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

A univariate regression-type I :math:\text{AGARCH}\left(p, q\right) process, with :math:q coefficients :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q, :math:p coefficients :math:\beta_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,p, and :math:k linear regression coefficients :math:b_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k, can be represented by:

.. math::
y_t = b_o+x_t^\mathrm{T}b+\epsilon_t

.. math::
h_t = \alpha_0+\sum_{{i = 1}}^q\alpha_i\left(\epsilon_{{t-i}}+\gamma \right)^2+\sum_{{i = 1}}^p\beta_ih_{{t-i}}\text{, }\quad t = 1,2,\ldots,T

where :math:\epsilon_t | \psi_{{t-1}} = N\left(0, h_t\right) or :math:\epsilon_t | \psi_{{t-1}} = S_t\left({\textit{df}}, h_t\right).
Here :math:S_t is a standardized Student's :math:t-distribution with :math:{\textit{df}} degrees of freedom and variance :math:h_t, :math:T is the number of terms in the sequence, :math:y_t denotes the endogenous variables, :math:x_t the exogenous variables, :math:b_o the regression mean, :math:b the regression coefficients, :math:\epsilon_t the residuals, :math:h_t the conditional variance, :math:{\textit{df}} the number of degrees of freedom of the Student's :math:t-distribution, and :math:\psi_t the set of all information up to time :math:t.

uni_garch_asym1_estim provides an estimate for :math:\hat{\theta }, the parameter vector :math:\theta = \left({b_o}, {b^\mathrm{T}}, \omega^\mathrm{T}\right) where :math:b^\mathrm{T} = \left({b_1}, \ldots, {b_k}\right), :math:\omega^\mathrm{T} = \left(\alpha_0, \alpha_1, \ldots, \alpha_q, {\beta_1}, \ldots, {\beta_p}, \gamma \right) when :math:\mathrm{dist} = \texttt{'N'} and :math:\omega^\mathrm{T} = \left(\alpha_0, \alpha_1, \ldots, \alpha_q, {\beta_1}, \ldots, {\beta_p}, \gamma, {\textit{df}}\right) when :math:\mathrm{dist} = \texttt{'T'}.

:math:\mathrm{isym}, :math:\mathrm{mn} and :math:\textit{nreg} can be used to simplify the :math:\text{GARCH}\left(p, q\right) expression in (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13faf.html#eqn1>__ as follows:

**No Regression and No Mean**

:math:y_t = \epsilon_t,

:math:\mathrm{isym} = 0,

:math:\mathrm{mn} = 0,

:math:\textit{nreg} = 0 and

:math:\theta is a :math:\left(p+q+1\right) vector when :math:\mathrm{dist} = \texttt{'N'} and a :math:\left(p+q+2\right) vector when :math:\mathrm{dist} = \texttt{'T'}.

**No Regression**

:math:y_t = b_o+\epsilon_t,

:math:\mathrm{isym} = 0,

:math:\mathrm{mn} = 1,

:math:\textit{nreg} = 0 and

:math:\theta is a :math:\left(p+q+2\right) vector when :math:\mathrm{dist} = \texttt{'N'} and a :math:\left(p+q+3\right) vector when :math:\mathrm{dist} = \texttt{'T'}.

**Note:** if the :math:y_t = \mu +\epsilon_t, where :math:\mu is known (not to be estimated by uni_garch_asym1_estim) then (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13faf.html#eqn1>__ can be written as :math:y_t^{\mu } = \epsilon_t, where :math:y_t^{\mu } = y_t-\mu.
This corresponds to the case **No Regression and No Mean**, with :math:y_t replaced by :math:y_t-\mu.

**No Mean**

:math:y_t = x_t^\mathrm{T}b+\epsilon_t,

:math:\mathrm{isym} = 0,

:math:\mathrm{mn} = 0,

:math:\textit{nreg} = k and

:math:\theta is a :math:\left(p+q+k+1\right) vector when :math:\mathrm{dist} = \texttt{'N'} and a :math:\left(p+q+k+2\right) vector when :math:\mathrm{dist} = \texttt{'T'}.

.. _g13fa-py2-py-references:

**References**
Bollerslev, T, 1986, Generalised autoregressive conditional heteroskedasticity, Journal of Econometrics (31), 307--327

Engle, R, 1982, Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation, Econometrica (50), 987--1008

Engle, R and Ng, V, 1993, Measuring and testing the impact of news on volatility, Journal of Finance (48), 1749--1777

Hamilton, J, 1994, Time Series Analysis, Princeton University Press

--------
:meth:naginterfaces.library.examples.tsa.uni_garch_asym1_ex.main
"""
raise NotImplementedError

[docs]def uni_garch_asym1_forecast(nt, ip, iq, theta, gamma, ht, et):
r"""
uni_garch_asym1_forecast forecasts the conditional variances :math:h_t, for :math:\textit{t} = T+1,\ldots,T+\xi, from a type I :math:\text{AGARCH}\left(p, q\right) sequence, where :math:\xi is the forecast horizon and :math:T is the current time (see Engle and Ng (1993)).

.. _g13fb-py2-py-doc:

For full information please refer to the NAG Library document for g13fb

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13fbf.html

.. _g13fb-py2-py-parameters:

**Parameters**
**nt** : int
:math:\xi, the forecast horizon.

**ip** : int
The number of coefficients, :math:\beta_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,p.

**iq** : int
The number of coefficients, :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

**theta** : float, array-like, shape :math:\left(\mathrm{iq}+\mathrm{ip}+1\right)
The first element must contain the coefficient :math:\alpha_o and the next :math:\mathrm{iq} elements must contain the coefficients :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q. The remaining :math:\mathrm{ip} elements must contain the coefficients :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

**gamma** : float
The asymmetry parameter :math:\gamma for the :math:\text{GARCH}\left(p, q\right) sequence.

**ht** : float, array-like, shape :math:\left(\textit{num}\right)
The sequence of past conditional variances for the :math:\text{GARCH}\left(p, q\right) process, :math:h_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**et** : float, array-like, shape :math:\left(\textit{num}\right)
The sequence of past residuals for the :math:\text{GARCH}\left(p, q\right) process, :math:\epsilon_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**Returns**
**fht** : float, ndarray, shape :math:\left(\mathrm{nt}\right)
The forecast values of the conditional variance, :math:h_t, for :math:\textit{t} = T+1,\ldots,T+\xi.

.. _g13fb-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{max}\left({\mathrm{ip}-1}, {\mathrm{iq}-1}\right) = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{max}\left({\mathrm{ip}-1}, {\mathrm{iq}-1}\right)\leq 20.

(errno :math:1)
On entry, :math:\textit{num} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{max}\left(\mathrm{ip}, \mathrm{iq}\right)\leq \textit{num}.

(errno :math:1)
On entry, :math:\mathrm{nt} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nt} > 0.

(errno :math:1)
On entry, :math:\mathrm{iq} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iq} \geq 1.

(errno :math:1)
On entry, :math:\mathrm{ip} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ip} \geq 0.

.. _g13fb-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

Assume the :math:\text{GARCH}\left(p, q\right) process can be represented by:

.. math::
h_t = \alpha_0+\sum_{{i = 1}}^q\alpha_i\left(\epsilon_{{t-i}}+\gamma \right)^2+\sum_{{i = 1}}^p\beta_ih_{{t-i}}\text{, }\quad t = 1,2,\ldots,T

where :math:\epsilon_t | \psi_{{t-1}} = N\left(0, h_t\right) or :math:\epsilon_t | \psi_{{t-1}} = S_t\left({\textit{df}}, h_t\right), has been modelled by :meth:uni_garch_asym1_estim and the estimated conditional variances and residuals are contained in the arrays :math:\mathrm{ht} and :math:\mathrm{et} respectively.

uni_garch_asym1_forecast will then use the last :math:\mathrm{max}\left(p, q\right) elements of the arrays :math:\mathrm{ht} and :math:\mathrm{et} to estimate the conditional variance forecasts, :math:h_t | \psi_T, where :math:t = T+1,\ldots,T+\xi and :math:\xi is the forecast horizon.

.. _g13fb-py2-py-references:

**References**
Bollerslev, T, 1986, Generalised autoregressive conditional heteroskedasticity, Journal of Econometrics (31), 307--327

Engle, R, 1982, Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation, Econometrica (50), 987--1008

Engle, R and Ng, V, 1993, Measuring and testing the impact of news on volatility, Journal of Finance (48), 1749--1777

Hamilton, J, 1994, Time Series Analysis, Princeton University Press

--------
:meth:naginterfaces.library.examples.tsa.uni_garch_asym1_ex.main
"""
raise NotImplementedError

[docs]def uni_garch_asym2_estim(dist, yt, x, ip, iq, mn, theta, pht, copts, maxit, tol, io_manager=None):
r"""
uni_garch_asym2_estim estimates the parameters of a univariate regression-type II :math:\text{AGARCH}\left(p, q\right) process.

.. _g13fc-py2-py-doc:

For full information please refer to the NAG Library document for g13fc

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13fcf.html

.. _g13fc-py2-py-parameters:

**Parameters**
**dist** : str, length 1
The type of distribution to use for :math:e_t.

:math:\mathrm{dist} = \texttt{'N'}

A Normal distribution is used.

:math:\mathrm{dist} = \texttt{'T'}

A Student's :math:t-distribution is used.

**yt** : float, array-like, shape :math:\left(\textit{num}\right)
The sequence of observations, :math:y_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**x** : float, array-like, shape :math:\left(\textit{num}, \textit{nreg}\right)
Row :math:\textit{t} of :math:\mathrm{x} must contain the time dependent exogenous vector :math:x_{\textit{t}}, where :math:x_{\textit{t}}^\mathrm{T} = \left(x_{\textit{t}}^1, \ldots, x_{\textit{t}}^k\right), for :math:\textit{t} = 1,2,\ldots,T.

**ip** : int
The number of coefficients, :math:\beta_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,p.

**iq** : int
The number of coefficients, :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

**mn** : int
If :math:\mathrm{mn} = 1, the mean term :math:b_0 will be included in the model.

**theta** : float, array-like, shape :math:\left(\textit{npar}\right)
The initial parameter estimates for the vector :math:\theta.

The first element must contain the coefficient :math:\alpha_o and the next :math:\mathrm{iq} elements must contain the coefficients :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{ip} elements must contain the coefficients :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

The next element must contain the asymmetry parameter :math:\gamma.

If :math:\mathrm{dist} = \texttt{'T'}, the next element must contain :math:{\textit{df}}, the number of degrees of freedom of the Student's :math:t-distribution.

If :math:\mathrm{mn} = 1, the next element contains the mean term :math:b_o.

If :math:\mathrm{copts}[1] = \mathbf{False}, the remaining :math:\textit{nreg} elements are taken as initial estimates of the linear regression coefficients :math:b_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k.

**pht** : float
If :math:\mathrm{copts}[1] = \mathbf{False}, :math:\mathrm{pht} is the value to be used for the pre-observed conditional variance; otherwise :math:\mathrm{pht} is not referenced.

**copts** : bool, array-like, shape :math:\left(2\right)
The options to be used by uni_garch_asym2_estim.

:math:\mathrm{copts}[0] = \mathbf{True}

Stationary conditions are enforced, otherwise they are not.

:math:\mathrm{copts}[1] = \mathbf{True}

The function provides initial parameter estimates of the regression terms, otherwise these are to be provided by you.

**maxit** : int
The maximum number of iterations to be used by the optimization function when estimating the :math:\text{GARCH}\left(p, q\right) parameters. If :math:\mathrm{maxit} is set to :math:0, the standard errors, score vector and variance-covariance are calculated for the input value of :math:\theta in :math:\mathrm{theta} when :math:\mathrm{dist} = \texttt{'N'}; however the value of :math:\theta is not updated.

**tol** : float
The tolerance to be used by the optimization function when estimating the :math:\text{GARCH}\left(p, q\right) parameters.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**theta** : float, ndarray, shape :math:\left(\textit{npar}\right)
The estimated values :math:\hat{\theta } for the vector :math:\theta.

The first element contains the coefficient :math:\alpha_o, the next :math:\mathrm{iq} elements contain the coefficients :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{ip} elements are the coefficients :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

The next element contains the estimate for the asymmetry parameter :math:\gamma.

If :math:\mathrm{dist} = \texttt{'T'}, the next element contains an estimate for :math:{\textit{df}}, the number of degrees of freedom of the Student's :math:t-distribution.

If :math:\mathrm{mn} = 1, the next element contains an estimate for the mean term :math:b_o.

The final :math:\textit{nreg} elements are the estimated linear regression coefficients :math:b_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k.

**se** : float, ndarray, shape :math:\left(\textit{npar}\right)
The standard errors for :math:\hat{\theta }.

The first element contains the standard error for :math:\alpha_o and the next :math:\mathrm{iq} elements contain the standard errors for :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{ip} elements are the standard errors for :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

The next element contains the standard error for :math:\gamma.

If :math:\mathrm{dist} = \texttt{'T'}, the next element contains the standard error for :math:{\textit{df}}, the number of degrees of freedom of the Student's :math:t-distribution.

If :math:\mathrm{mn} = 1, the next element contains the standard error for :math:b_o.

The final :math:\textit{nreg} elements are the standard errors for :math:b_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,k.

**sc** : float, ndarray, shape :math:\left(\textit{npar}\right)
The scores for :math:\hat{\theta }.

The first element contains the score for :math:\alpha_o and the next :math:\mathrm{iq} elements contain the score for :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{ip} elements are the scores for :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

The next element contains the score for :math:\gamma.

If :math:\mathrm{dist} = \texttt{'T'}, the next element contains the score for :math:{\textit{df}}, the number of degrees of freedom of the Student's :math:t-distribution.

If :math:\mathrm{mn} = 1, the next element contains the score for :math:b_o.

The final :math:\textit{nreg} elements are the scores for :math:b_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,k.

**covr** : float, ndarray, shape :math:\left(\textit{npar}, \textit{npar}\right)
The covariance matrix of the parameter estimates :math:\hat{\theta }, that is the inverse of the Fisher Information Matrix.

**pht** : float
If :math:\mathrm{copts}[1] = \mathbf{True}, :math:\mathrm{pht} is the estimated value of the pre-observed conditional variance.

**et** : float, ndarray, shape :math:\left(\textit{num}\right)
The estimated residuals, :math:\epsilon_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**ht** : float, ndarray, shape :math:\left(\textit{num}\right)
The estimated conditional variances, :math:h_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**lgf** : float
The value of the log-likelihood function at :math:\hat{\theta }.

.. _g13fc-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{num} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{num}\geq \textit{nreg}+\mathrm{mn}.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npar} < 20.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{dist} = \texttt{'N'} then :math:\textit{npar} = 2+\mathrm{iq}+\mathrm{ip}+\mathrm{mn}+\textit{nreg}, else :math:\textit{npar} = 3+\mathrm{iq}+\mathrm{ip}+\mathrm{mn}+\textit{nreg}.

(errno :math:1)
On entry, :math:\textit{num} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{max}\left(\mathrm{ip}, \mathrm{iq}\right)\leq \textit{num}.

(errno :math:1)
On entry, :math:\mathrm{maxit} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxit} \geq 0.

(errno :math:1)
On entry, :math:\mathrm{dist} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dist} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:1)
On entry, :math:\mathrm{iq} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iq} \geq 1.

(errno :math:1)
On entry, :math:\mathrm{ip} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ip} \geq 0.

(errno :math:1)
On entry, :math:\mathrm{mn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mn} = 0 or :math:1.

(errno :math:1)
On entry, :math:\textit{nreg} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nreg} \geq 0.

(errno :math:3)
On entry, the matrix :math:X is not full rank.

(errno :math:4)
The information matrix is not positive definite.

(errno :math:7)
No feasible model parameters could be found.

**Warns**
**NagAlgorithmicWarning**
(errno :math:5)
The maximum number of iterations has been reached.

(errno :math:6)
The log-likelihood cannot be optimized any further.

.. _g13fc-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

A univariate regression-type II :math:\text{AGARCH}\left(p, q\right) process, with :math:q coefficients :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q, :math:p coefficients, :math:\beta_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,p, and :math:k linear regression coefficients :math:b_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k, can be represented by:

.. math::
y_t = b_o+x_t^\mathrm{T}b+\epsilon_t

.. math::
h_t = \alpha_0+\sum_{{i = 1}}^q\alpha_i\left(\left\lvert \epsilon_{{t-i}}\right\rvert +\gamma \epsilon_{{t-i}}\right)^2+\sum_{{i = 1}}^p\beta_ih_{{t-i}}\text{, }\quad t = 1,2,\ldots,T\text{.}

where :math:\epsilon_t | \psi_{{t-1}} = N\left(0, h_t\right) or :math:\epsilon_t | \psi_{{t-1}} = S_t\left({\textit{df}}, h_t\right).
Here :math:S_t is a standardized Student's :math:t-distribution with :math:{\textit{df}} degrees of freedom and variance :math:h_t, :math:T is the number of terms in the sequence, :math:y_t denotes the endogenous variables, :math:x_t the exogenous variables, :math:b_o the regression mean, :math:b the regression coefficients, :math:\epsilon_t the residuals, :math:h_t the conditional variance, and :math:\psi_t the set of all information up to time :math:t.

uni_garch_asym2_estim provides an estimate for the parameter vector :math:\theta = \left({b_o}, {b^\mathrm{T}}, \omega^\mathrm{T}\right) where :math:b^\mathrm{T} = \left({b_1}, \ldots, {b_k}\right), :math:\omega^\mathrm{T} = \left(\alpha_0, \alpha_1, \ldots, \alpha_q, {\beta_1}, \ldots, {\beta_p}, \gamma \right) when :math:\mathrm{dist} = \texttt{'N'} and :math:\omega^\mathrm{T} = \left(\alpha_0, \alpha_1, \ldots, \alpha_q, {\beta_1}, \ldots, {\beta_p}, \gamma, {\textit{df}}\right) when :math:\mathrm{dist} = \texttt{'T'}.

:math:\mathrm{mn} and :math:\textit{nreg} can be used to simplify the :math:\text{GARCH}\left(p, q\right) expression in (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13fcf.html#eqn1>__ as follows:

**No Regression and No Mean**

:math:y_t = \epsilon_t,

:math:\mathrm{mn} = 0,

:math:\textit{nreg} = 0 and

:math:\theta is a :math:\left(p+q+2\right) vector when :math:\mathrm{dist} = \texttt{'N'} and a :math:\left(p+q+3\right) vector when :math:\mathrm{dist} = \texttt{'T'}.

**No Regression**

:math:y_t = b_o+\epsilon_t,

:math:\mathrm{mn} = 1,

:math:\textit{nreg} = 0 and

:math:\theta is a :math:\left(p+q+3\right) vector when :math:\mathrm{dist} = \texttt{'N'} and a :math:\left(p+q+4\right)\times 1 vector when :math:\mathrm{dist} = \texttt{'T'}.

**Note:** if the :math:y_t = \mu +\epsilon_t, where :math:\mu is known (not to be estimated by uni_garch_asym2_estim) then (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13fcf.html#eqn1>__ can be written as :math:y_t^{\mu } = \epsilon_t, where :math:y_t^{\mu } = y_t-\mu.
This corresponds to the case **No Regression and No Mean**, with :math:y_t replaced by :math:y_t-\mu.

**No Mean**

:math:y_t = x_t^\mathrm{T}b+\epsilon_t,

:math:\mathrm{mn} = 0,

:math:\textit{nreg} = k and

:math:\theta is a :math:\left(p+q+k+2\right) vector when :math:\mathrm{dist} = \texttt{'N'} and a :math:\left(p+q+k+3\right) vector when :math:\mathrm{dist} = \texttt{'T'}.

.. _g13fc-py2-py-references:

**References**
Bollerslev, T, 1986, Generalised autoregressive conditional heteroskedasticity, Journal of Econometrics (31), 307--327

Engle, R, 1982, Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation, Econometrica (50), 987--1008

Engle, R and Ng, V, 1993, Measuring and testing the impact of news on volatility, Journal of Finance (48), 1749--1777

Hamilton, J, 1994, Time Series Analysis, Princeton University Press
"""
raise NotImplementedError

[docs]def uni_garch_asym2_forecast(nt, ip, iq, theta, gamma, ht, et):
r"""
uni_garch_asym2_forecast forecasts the conditional variances, :math:h_t,t = T+1,\ldots,T+\xi from a type II :math:\text{AGARCH}\left(p, q\right) sequence, where :math:\xi is the forecast horizon and :math:T is the current time (see Engle and Ng (1993)).

.. _g13fd-py2-py-doc:

For full information please refer to the NAG Library document for g13fd

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13fdf.html

.. _g13fd-py2-py-parameters:

**Parameters**
**nt** : int
:math:\xi, the forecast horizon.

**ip** : int
The number of coefficients, :math:\beta_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,p.

**iq** : int
The number of coefficients, :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

**theta** : float, array-like, shape :math:\left(\mathrm{iq}+\mathrm{ip}+1\right)
The first element must contain the coefficient :math:\alpha_o and the next :math:\mathrm{iq} elements must contain the coefficients :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q. The remaining :math:\mathrm{ip} elements must contain the coefficients :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

**gamma** : float
The asymmetry parameter :math:\gamma for the :math:\text{GARCH}\left(p, q\right) sequence.

**ht** : float, array-like, shape :math:\left(\textit{num}\right)
The sequence of past conditional variances for the :math:\text{GARCH}\left(p, q\right) process, :math:h_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**et** : float, array-like, shape :math:\left(\textit{num}\right)
The sequence of past residuals for the :math:\text{GARCH}\left(p, q\right) process, :math:\epsilon_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**Returns**
**fht** : float, ndarray, shape :math:\left(\mathrm{nt}\right)
The forecast values of the conditional variance, :math:h_t, for :math:\textit{t} = T+1,\ldots,T+\xi.

.. _g13fd-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{max}\left({\mathrm{ip}-1}, {\mathrm{iq}-1}\right) = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{max}\left({\mathrm{ip}-1}, {\mathrm{iq}-1}\right)\leq 20.

(errno :math:1)
On entry, :math:\textit{num} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{max}\left(\mathrm{ip}, \mathrm{iq}\right)\leq \textit{num}.

(errno :math:1)
On entry, :math:\mathrm{nt} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nt} > 0.

(errno :math:1)
On entry, :math:\mathrm{iq} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iq} \geq 1.

(errno :math:1)
On entry, :math:\mathrm{ip} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ip} \geq 0.

.. _g13fd-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

Assume the :math:\text{GARCH}\left(p, q\right) process can be represented by:

.. math::
h_t = \alpha_0+\sum_{{i = 1}}^q\alpha_i\left(\left\lvert \epsilon_{{t-i}}\right\rvert +\gamma \epsilon_{{t-i}}\right)^2+\sum_{{i = 1}}^p\beta_ih_{{t-i}}\text{, }\quad t = 1,2,\ldots,T\text{.}

where :math:\epsilon_t | \psi_{{t-1}} = N\left(0, h_t\right) or :math:\epsilon_t | \psi_{{t-1}} = S_t\left({\textit{df}}, h_t\right), has been modelled by :meth:uni_garch_asym2_estim and the estimated conditional variances and residuals are contained in the arrays :math:\mathrm{ht} and :math:\mathrm{et} respectively.

uni_garch_asym2_forecast will then use the last :math:\mathrm{max}\left(p, q\right) elements of the arrays :math:\mathrm{ht} and :math:\mathrm{et} to estimate the conditional variance forecasts, :math:h_t | \psi_T, where :math:t = T+1,\ldots,T+\xi and :math:\xi is the forecast horizon.

.. _g13fd-py2-py-references:

**References**
Bollerslev, T, 1986, Generalised autoregressive conditional heteroskedasticity, Journal of Econometrics (31), 307--327

Engle, R, 1982, Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation, Econometrica (50), 987--1008

Engle, R and Ng, V, 1993, Measuring and testing the impact of news on volatility, Journal of Finance (48), 1749--1777

Hamilton, J, 1994, Time Series Analysis, Princeton University Press
"""
raise NotImplementedError

[docs]def uni_garch_gjr_estim(dist, yt, x, ip, iq, mn, theta, pht, copts, maxit, tol, io_manager=None):
r"""
uni_garch_gjr_estim estimates the parameters of a univariate regression-GJR :math:\text{GARCH}\left(p, q\right) process (see Glosten et al. (1993)).

.. _g13fe-py2-py-doc:

For full information please refer to the NAG Library document for g13fe

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13fef.html

.. _g13fe-py2-py-parameters:

**Parameters**
**dist** : str, length 1
The type of distribution to use for :math:e_t.

:math:\mathrm{dist} = \texttt{'N'}

A Normal distribution is used.

:math:\mathrm{dist} = \texttt{'T'}

A Student's :math:t-distribution is used.

**yt** : float, array-like, shape :math:\left(\textit{num}\right)
The sequence of observations, :math:y_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**x** : float, array-like, shape :math:\left(\textit{num}, \textit{nreg}\right)
Row :math:\textit{t} of :math:\mathrm{x} must contain the time dependent exogenous vector :math:x_{\textit{t}}, where :math:x_{\textit{t}}^\mathrm{T} = \left(x_{\textit{t}}^1, \ldots, x_{\textit{t}}^k\right), for :math:\textit{t} = 1,2,\ldots,T.

**ip** : int
The number of coefficients, :math:\beta_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,p.

**iq** : int
The number of coefficients, :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

**mn** : int
If :math:\mathrm{mn} = 1, the mean term :math:b_0 will be included in the model.

**theta** : float, array-like, shape :math:\left(\textit{npar}\right)
The initial parameter estimates for the vector :math:\theta.

The first element must contain the coefficient :math:\alpha_o and the next :math:\mathrm{iq} elements contain the coefficients :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{ip} elements must contain the coefficients :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

The next element must contain the asymmetry parameter :math:\gamma.

If :math:\mathrm{dist} = \texttt{'T'}, the next element contains :math:{\textit{df}}, the number of degrees of freedom of the Student's :math:t-distribution.

If :math:\mathrm{mn} = 1, the next element must contain the mean term :math:b_o.

If :math:\mathrm{copts}[1] = \mathbf{False}, the remaining :math:\textit{nreg} elements are taken as initial estimates of the linear regression coefficients :math:b_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k.

**pht** : float
If :math:\mathrm{copts}[1] = \mathbf{False}, :math:\mathrm{pht} is the value to be used for the pre-observed conditional variance; otherwise :math:\mathrm{pht} is not referenced.

**copts** : bool, array-like, shape :math:\left(2\right)
The options to be used by uni_garch_gjr_estim.

:math:\mathrm{copts}[0] = \mathbf{True}

Stationary conditions are enforced, otherwise they are not.

:math:\mathrm{copts}[1] = \mathbf{True}

The function provides initial parameter estimates of the regression terms, otherwise these are to be provided by you.

**maxit** : int
The maximum number of iterations to be used by the optimization function when estimating the :math:\text{GARCH}\left(p, q\right) parameters. If :math:\mathrm{maxit} is set to :math:0, the standard errors, score vector and variance-covariance are calculated for the input value of :math:\theta in :math:\mathrm{theta} when :math:\mathrm{dist} = \texttt{'N'}; however the value of :math:\theta is not updated.

**tol** : float
The tolerance to be used by the optimization function when estimating the :math:\text{GARCH}\left(p, q\right) parameters.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**theta** : float, ndarray, shape :math:\left(\textit{npar}\right)
The estimated values :math:\hat{\theta } for the vector :math:\theta.

The first element contains the coefficient :math:\alpha_o, the next :math:\mathrm{iq} elements contain the coefficients :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{ip} elements are the moving average coefficients :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

The next element contains the estimate for the asymmetry parameter :math:\gamma.

If :math:\mathrm{dist} = \texttt{'T'}, the next element contains an estimate for :math:{\textit{df}}, the number of degrees of freedom of the Student's :math:t-distribution.

If :math:\mathrm{mn} = 1, the next element contains an estimate for the mean term :math:b_o.

The final :math:\textit{nreg} elements are the estimated linear regression coefficients :math:b_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k.

**se** : float, ndarray, shape :math:\left(\textit{npar}\right)
The standard errors for :math:\hat{\theta }.

The first element contains the standard error for :math:\alpha_o and the next :math:\mathrm{iq} elements contain the standard errors for :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{ip} elements are the standard errors for :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

The next element contains the standard error for :math:\gamma.

If :math:\mathrm{dist} = \texttt{'T'}, the next element contains the standard error for :math:{\textit{df}}, the number of degrees of freedom of the Student's :math:t-distribution.

If :math:\mathrm{mn} = 1, the next element contains the standard error for :math:b_o.

The final :math:\textit{nreg} elements are the standard errors for :math:b_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,k.

**sc** : float, ndarray, shape :math:\left(\textit{npar}\right)
The scores for :math:\hat{\theta }.

The first element contains the score for :math:\alpha_o, the next :math:\mathrm{iq} elements contain the scores for :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{ip} elements are the score for :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

The next element contains the score for :math:\gamma.

If :math:\mathrm{dist} = \texttt{'T'}, the next element contains the score for :math:{\textit{df}}, the number of degrees of freedom of the Student's :math:t-distribution.

If :math:\mathrm{mn} = 1, the next element contains the score for :math:b_o.

The final :math:\textit{nreg} elements are the scores for :math:b_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,k.

**covr** : float, ndarray, shape :math:\left(\textit{npar}, \textit{npar}\right)
The covariance matrix of the parameter estimates :math:\hat{\theta }, that is the inverse of the Fisher Information Matrix.

**pht** : float
If :math:\mathrm{copts}[1] = \mathbf{True}, :math:\mathrm{pht} is the estimated value of the pre-observed conditional variance.

**et** : float, ndarray, shape :math:\left(\textit{num}\right)
The estimated residuals, :math:\epsilon_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**ht** : float, ndarray, shape :math:\left(\textit{num}\right)
The estimated conditional variances, :math:h_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**lgf** : float
The value of the log-likelihood function at :math:\hat{\theta }.

.. _g13fe-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{num} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{num}\geq \textit{nreg}+\mathrm{mn}.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npar} < 20.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{dist} = \texttt{'N'} then :math:\textit{npar} = 2+\mathrm{iq}+\mathrm{ip}+\mathrm{mn}+\textit{nreg}, else :math:\textit{npar} = 3+\mathrm{iq}+\mathrm{ip}+\mathrm{mn}+\textit{nreg}.

(errno :math:1)
On entry, :math:\textit{num} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{max}\left(\mathrm{ip}, \mathrm{iq}\right)\leq \textit{num}.

(errno :math:1)
On entry, :math:\mathrm{maxit} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxit} \geq 0.

(errno :math:1)
On entry, :math:\mathrm{dist} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dist} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:1)
On entry, :math:\mathrm{iq} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iq} \geq 1.

(errno :math:1)
On entry, :math:\mathrm{ip} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ip} \geq 0.

(errno :math:1)
On entry, :math:\mathrm{mn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mn} = 0 or :math:1.

(errno :math:1)
On entry, :math:\textit{nreg} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nreg} \geq 0.

(errno :math:3)
On entry, the matrix :math:X is not full rank.

(errno :math:4)
The information matrix is not positive definite.

(errno :math:7)
No feasible model parameters could be found.

**Warns**
**NagAlgorithmicWarning**
(errno :math:5)
The maximum number of iterations has been reached.

(errno :math:6)
The log-likelihood cannot be optimized any further.

.. _g13fe-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

A univariate regression-GJR :math:\text{GARCH}\left(p, q\right) process, with :math:q coefficients :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q, :math:p coefficients :math:\beta_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,p, and :math:k linear regression coefficients :math:b_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k, can be represented by:

.. math::
y_t = b_o+x_t^\mathrm{T}b+\epsilon_t

.. math::
h_t = \alpha_0+\sum_{{i = 1}}^q\left(\alpha_i+\gamma I_{{t-i}}\right)\epsilon_{{t-i}}^2+\sum_{{i = 1}}^p\beta_ih_{{t-i}}\text{, }\quad t = 1,2,\ldots,T

where :math:I_t = 1, if :math:\epsilon_t < 0, :math:I_t = 0, if :math:\epsilon_t\geq 0, and :math:\epsilon_t | \psi_{{t-1}} = N\left(0, h_t\right) or :math:\epsilon_t | \psi_{{t-1}} = S_t\left({\textit{df}}, h_t\right).
Here :math:S_t is a standardized Student's :math:t-distribution with :math:{\textit{df}} degrees of freedom and variance :math:h_t, :math:T is the number of terms in the sequence, :math:y_t denotes the endogenous variables, :math:x_t the exogenous variables, :math:b_o the regression mean, :math:b the regression coefficients, :math:\epsilon_t the residuals, :math:h_t is the conditional variance, and :math:\psi_t the set of all information up to time :math:t.

uni_garch_gjr_estim provides an estimate for :math:\hat{\theta }, the parameter vector :math:\theta = \left({b_o}, {b^\mathrm{T}}, \omega^\mathrm{T}\right) where :math:b^\mathrm{T} = \left({b_1}, \ldots, {b_k}\right), :math:\omega^\mathrm{T} = \left(\alpha_0, \alpha_1, \ldots, \alpha_q, {\beta_1}, \ldots, {\beta_p}, \gamma \right) when :math:\mathrm{dist} = \texttt{'N'} and :math:\omega^\mathrm{T} = \left(\alpha_0, \alpha_1, \ldots, \alpha_q, {\beta_1}, \ldots, {\beta_p}, \gamma, {\textit{df}}\right) when :math:\mathrm{dist} = \texttt{'T'}.

:math:\mathrm{mn}, :math:\textit{nreg} can be used to simplify the :math:\text{GARCH}\left(p, q\right) expression in (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13fef.html#eqn1>__ as follows:

**No Regression and No Mean**

:math:y_t = \epsilon_t,

:math:\mathrm{mn} = 0,

:math:\textit{nreg} = 0 and

:math:\theta is a :math:\left(p+q+2\right) vector when :math:\mathrm{dist} = \texttt{'N'}, and a :math:\left(p+q+3\right) vector when :math:\mathrm{dist} = \texttt{'T'}.

**No Regression**

:math:y_t = b_o+\epsilon_t,

:math:\mathrm{mn} = 1,

:math:\textit{nreg} = 0 and

:math:\theta is a :math:\left(p+q+3\right) vector when :math:\mathrm{dist} = \texttt{'N'}, and a :math:\left(p+q+4\right) vector when :math:\mathrm{dist} = \texttt{'T'}.

**Note:** if the :math:y_t = \mu +\epsilon_t, where :math:\mu is known (not to be estimated by uni_garch_gjr_estim) then (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13fef.html#eqn1>__ can be written as :math:y_t^{\mu } = \epsilon_t, where :math:y_t^{\mu } = y_t-\mu.
This corresponds to the case **No Regression and No Mean**, with :math:y_t replaced by :math:y_t-\mu.

**No Mean**

:math:y_t = x_t^\mathrm{T}b+\epsilon_t,

:math:\mathrm{mn} = 0,

:math:\textit{nreg} = k and

:math:\theta is a :math:\left(p+q+k+2\right) vector when :math:\mathrm{dist} = \texttt{'N'}, and a :math:\left(p+q+k+3\right) vector when :math:\mathrm{dist} = \texttt{'T'}.

.. _g13fe-py2-py-references:

**References**
Bollerslev, T, 1986, Generalised autoregressive conditional heteroskedasticity, Journal of Econometrics (31), 307--327

Engle, R, 1982, Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation, Econometrica (50), 987--1008

Engle, R and Ng, V, 1993, Measuring and testing the impact of news on volatility, Journal of Finance (48), 1749--1777

Glosten, L, Jagannathan, R and Runkle, D, 1993, Relationship between the expected value and the volatility of nominal excess return on stocks, Journal of Finance (48), 1779--1801

Hamilton, J, 1994, Time Series Analysis, Princeton University Press
"""
raise NotImplementedError

[docs]def uni_garch_gjr_forecast(nt, ip, iq, theta, gamma, ht, et):
r"""
uni_garch_gjr_forecast forecasts the conditional variances, :math:h_t, for :math:\textit{t} = T+1,\ldots,T+\xi from a GJR :math:\text{GARCH}\left(p, q\right) sequence, where :math:\xi is the forecast horizon and :math:T is the current time (see Glosten et al. (1993)).

.. _g13ff-py2-py-doc:

For full information please refer to the NAG Library document for g13ff

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13fff.html

.. _g13ff-py2-py-parameters:

**Parameters**
**nt** : int
:math:\xi, the forecast horizon.

**ip** : int
The number of coefficients, :math:\beta_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,p.

**iq** : int
The number of coefficients, :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

**theta** : float, array-like, shape :math:\left(\mathrm{iq}+\mathrm{ip}+1\right)
The first element must contain the coefficient :math:\alpha_o and the next :math:\mathrm{iq} elements must contain the coefficients :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q. The remaining :math:\mathrm{ip} elements must contain the coefficients :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

**gamma** : float
The asymmetry parameter :math:\gamma for the :math:\text{GARCH}\left(p, q\right) sequence.

**ht** : float, array-like, shape :math:\left(\textit{num}\right)
The sequence of past conditional variances for the :math:\text{GARCH}\left(p, q\right) process, :math:h_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**et** : float, array-like, shape :math:\left(\textit{num}\right)
The sequence of past residuals for the :math:\text{GARCH}\left(p, q\right) process, :math:\epsilon_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**Returns**
**fht** : float, ndarray, shape :math:\left(\mathrm{nt}\right)
The forecast values of the conditional variance, :math:h_t, for :math:\textit{t} = T+1,\ldots,T+\xi.

.. _g13ff-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{max}\left({\mathrm{ip}-1}, {\mathrm{iq}-1}\right) = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{max}\left({\mathrm{ip}-1}, {\mathrm{iq}-1}\right)\leq 20.

(errno :math:1)
On entry, :math:\textit{num} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{max}\left(\mathrm{ip}, \mathrm{iq}\right)\leq \textit{num}.

(errno :math:1)
On entry, :math:\mathrm{nt} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nt} > 0.

(errno :math:1)
On entry, :math:\mathrm{iq} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iq} \geq 1.

(errno :math:1)
On entry, :math:\mathrm{ip} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ip} \geq 0.

.. _g13ff-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

Assume the :math:\text{GARCH}\left(p, q\right) process can be represented by:

.. math::
h_t = \alpha_0+\sum_{{i = 1}}^q\left(\alpha_i+\gamma I_{{t-i}}\right)\epsilon_{{t-i}}^2+\sum_{{i = 1}}^p\beta_ih_{{t-i}}\text{, }\quad t = 1,2,\ldots,T\text{.}

where :math:\epsilon_t | \psi_{{t-1}} = N\left(0, h_t\right) or :math:\epsilon_t | \psi_{{t-1}} = S_t\left({\textit{df}}, h_t\right), and :math:I_t = 1, if :math:\epsilon_t < 0, or :math:I_t = 0, if :math:\epsilon_t\geq 0, has been modelled by :meth:uni_garch_gjr_estim, and the estimated conditional variances and residuals are contained in the arrays :math:\mathrm{ht} and :math:\mathrm{et} respectively.

uni_garch_gjr_forecast will then use the last :math:\mathrm{max}\left(p, q\right) elements of the arrays :math:\mathrm{ht} and :math:\mathrm{et} to estimate the conditional variance forecasts, :math:h_t | \psi_T, where :math:t = T+1,\ldots,T+\xi and :math:\xi is the forecast horizon.

.. _g13ff-py2-py-references:

**References**
Bollerslev, T, 1986, Generalised autoregressive conditional heteroskedasticity, Journal of Econometrics (31), 307--327

Engle, R, 1982, Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation, Econometrica (50), 987--1008

Engle, R and Ng, V, 1993, Measuring and testing the impact of news on volatility, Journal of Finance (48), 1749--1777

Glosten, L, Jagannathan, R and Runkle, D, 1993, Relationship between the expected value and the volatility of nominal excess return on stocks, Journal of Finance (48), 1779--1801

Hamilton, J, 1994, Time Series Analysis, Princeton University Press
"""
raise NotImplementedError

[docs]def uni_garch_exp_estim(dist, yt, x, ip, iq, mn, theta, pht, copts, maxit, tol, io_manager=None):
r"""
uni_garch_exp_estim estimates the parameters of a univariate regression-exponential :math:\text{GARCH}\left(p, q\right) process (see Engle and Ng (1993)).

.. _g13fg-py2-py-doc:

For full information please refer to the NAG Library document for g13fg

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13fgf.html

.. _g13fg-py2-py-parameters:

**Parameters**
**dist** : str, length 1
The type of distribution to use for :math:e_t.

:math:\mathrm{dist} = \texttt{'N'}

A Normal distribution is used.

:math:\mathrm{dist} = \texttt{'T'}

A Student's :math:t-distribution is used.

**yt** : float, array-like, shape :math:\left(\textit{num}\right)
The sequence of observations, :math:y_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**x** : float, array-like, shape :math:\left(\textit{num}, \textit{nreg}\right)
Row :math:\textit{t} of :math:\mathrm{x} must contain the time dependent exogenous vector :math:x_{\textit{t}}, where :math:x_{\textit{t}}^\mathrm{T} = \left(x_{\textit{t}}^1, \ldots, x_{\textit{t}}^k\right), for :math:\textit{t} = 1,2,\ldots,T.

**ip** : int
The number of coefficients, :math:\beta_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,p.

**iq** : int
The number of coefficients, :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

**mn** : int
If :math:\mathrm{mn} = 1, the mean term :math:b_0 will be included in the model.

**theta** : float, array-like, shape :math:\left(\textit{npar}\right)
The initial parameter estimates for the vector :math:\theta.

The first element must contain the coefficient :math:\alpha_o and the next :math:\mathrm{iq} elements must contain the autoregressive coefficients :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{iq} elements contain the coefficients :math:\phi_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{ip} elements must contain the moving average coefficients :math:\beta_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,p.

If :math:\mathrm{dist} = \texttt{'T'}, the next element must contain an estimate for :math:{\textit{df}}, the number of degrees of freedom of the Student's :math:t-distribution.

If :math:\mathrm{mn} = 1, the next element must contain the mean term :math:b_o.

If :math:\mathrm{copts} = \mathbf{False}, the remaining :math:\textit{nreg} elements are taken as initial estimates of the linear regression coefficients :math:b_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k.

**pht** : float
If :math:\mathrm{copts} = \mathbf{False} then :math:\mathrm{pht} is the value to be used for the pre-observed conditional variance, otherwise :math:\mathrm{pht} is not referenced.

**copts** : bool
If :math:\mathrm{copts} = \mathbf{True}, the function provides initial parameter estimates of the regression terms, otherwise these are provided by you.

**maxit** : int
The maximum number of iterations to be used by the optimization function when estimating the :math:\text{GARCH}\left(p, q\right) parameters.

**tol** : float
The tolerance to be used by the optimization function when estimating the :math:\text{GARCH}\left(p, q\right) parameters.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**theta** : float, ndarray, shape :math:\left(\textit{npar}\right)
The estimated values :math:\hat{\theta } for the vector :math:\theta.

The first element contains the coefficient :math:\alpha_o and the next :math:\mathrm{iq} elements contain the coefficients :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{iq} elements contain the coefficients :math:\phi_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{ip} elements are the moving average coefficients :math:\beta_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,p.

If :math:\mathrm{dist} = \texttt{'T'}, the next element contains an estimate for :math:{\textit{df}} then the number of degrees of freedom of the Student's :math:t-distribution.

If :math:\mathrm{mn} = 1, the next element contains an estimate for the mean term :math:b_o.

The final :math:\textit{nreg} elements are the estimated linear regression coefficients :math:b_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k.

**se** : float, ndarray, shape :math:\left(\textit{npar}\right)
The standard errors for :math:\hat{\theta }.

The first element contains the standard error for :math:\alpha_o and the next :math:\mathrm{iq} elements contain the standard errors for :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{iq} elements contain the standard errors for :math:\phi_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

The next :math:\mathrm{ip} elements are the standard errors for :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

If :math:\mathrm{dist} = \texttt{'T'}, the next element contains the standard error for :math:{\textit{df}}, the number of degrees of freedom of the Student's :math:t-distribution.

If :math:\mathrm{mn} = 1, the next element contains the standard error for :math:b_o.

The final :math:\textit{nreg} elements are the standard errors for :math:b_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,k.

**sc** : float, ndarray, shape :math:\left(\textit{npar}\right)
The scores for :math:\hat{\theta }.

The first element contains the scores for :math:\alpha_o, the next :math:\mathrm{iq} elements contain the scores for :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q, the next :math:\mathrm{iq} elements contain the scores for :math:\phi_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q, the next :math:\mathrm{ip} elements are the scores for :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

If :math:\mathrm{dist} = \texttt{'T'}, the next element contains the scores for :math:{\textit{df}}, the number of degrees of freedom of the Student's :math:t-distribution.

If :math:\mathrm{mn} = 1, the next element contains the score for :math:b_o.

The final :math:\textit{nreg} elements are the scores for :math:b_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,k.

**covr** : float, ndarray, shape :math:\left(\textit{npar}, \textit{npar}\right)
The covariance matrix of the parameter estimates :math:\hat{\theta }, that is the inverse of the Fisher Information Matrix.

**pht** : float
If :math:\mathrm{copts} = \mathbf{True} then :math:\mathrm{pht} is the estimated value of the pre-observed conditional variance.

**et** : float, ndarray, shape :math:\left(\textit{num}\right)
The estimated residuals, :math:\epsilon_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**ht** : float, ndarray, shape :math:\left(\textit{num}\right)
The estimated conditional variances, :math:h_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**lgf** : float
The value of the log-likelihood function at :math:\hat{\theta }.

.. _g13fg-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{num} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{num}\geq \textit{nreg}+\mathrm{mn}.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{npar} < 20.

(errno :math:1)
On entry, :math:\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{dist} = \texttt{'N'} then :math:\textit{npar} = 1+2\times \mathrm{iq}+\mathrm{ip}+\mathrm{mn}+\textit{nreg}, else :math:\textit{npar} = 2+2\times \mathrm{iq}+\mathrm{ip}+\mathrm{mn}+\textit{nreg}.

(errno :math:1)
On entry, :math:\textit{num} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{max}\left(\mathrm{ip}, \mathrm{iq}\right)\leq \textit{num}.

(errno :math:1)
On entry, :math:\mathrm{maxit} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxit} > 0.

(errno :math:1)
On entry, :math:\mathrm{dist} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dist} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:1)
On entry, :math:\mathrm{iq} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iq} \geq 1.

(errno :math:1)
On entry, :math:\mathrm{ip} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ip} \geq 0.

(errno :math:1)
On entry, :math:\mathrm{mn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{mn} = 0 or :math:1.

(errno :math:1)
On entry, :math:\textit{nreg} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nreg} \geq 0.

(errno :math:3)
On entry, the matrix :math:X is not full rank.

(errno :math:4)
The information matrix is not positive definite.

(errno :math:7)
No feasible model parameters could be found.

**Warns**
**NagAlgorithmicWarning**
(errno :math:5)
The maximum number of iterations has been reached.

(errno :math:6)
The log-likelihood cannot be optimized any further.

.. _g13fg-py2-py-notes:

**Notes**
No equivalent traditional C interface for this routine exists in the NAG Library.

A univariate regression-exponential :math:\text{GARCH}\left(p, q\right) process, with :math:q coefficients :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q, :math:q coefficients :math:\phi_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q, :math:p coefficients, :math:\beta_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,p, and :math:k linear regression coefficients :math:b_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k, can be represented by:

.. math::
\begin{array}{c} y_t = b_o + x_t^\mathrm{T} b + \epsilon_t \\ ln\left(h_t\right) = \alpha_0 + \sum_{{i = 1}}^q \alpha_i z_{{t-i}} + \sum_{{i = 1}}^q \phi_i {\left(\left\lvert z_{{t-i}}\right\rvert -E\left[\left\lvert z_{{t-i}}\right\rvert \right]\right)} + \sum_{{i = 1}}^p \beta_i ln \left(h_{{t-i}}\right) \text{, }\quad t = 1,2,\ldots,T \end{array}

where :math:z_t = \frac{\epsilon_t}{{\sqrt{h_t}}}, :math:E\left[\left\lvert z_{{t-i}}\right\rvert \right] denotes the expected value of :math:\left\lvert z_{{t-i}}\right\rvert and :math:\epsilon_t | \psi_{{t-1}} = N\left(0, h_t\right) or :math:\epsilon_t | \psi_{{t-1}} = S_t\left({\textit{df}}, h_t\right).
Here :math:S_t is a standardized Student's :math:t-distribution with :math:{\textit{df}} degrees of freedom and variance :math:h_t, :math:T is the number of terms in the sequence, :math:y_t denotes the endogenous variables, :math:x_t the exogenous variables, :math:b_o the regression mean, :math:b the regression coefficients, :math:\epsilon_t the residuals, :math:h_t the conditional variance, :math:{\textit{df}} the number of degrees of freedom of the Student's :math:t-distribution, and :math:\psi_t the set of all information up to time :math:t.

uni_garch_exp_estim provides an estimate :math:\hat{\theta }, for the vector :math:\theta = \left({b_o}, {b^\mathrm{T}}, \omega^\mathrm{T}\right) where :math:b^\mathrm{T} = \left({b_1}, \ldots, {b_k}\right), :math:\omega^\mathrm{T} = \left(\alpha_0, \alpha_1, \ldots, \alpha_q, \phi_1, \ldots, \phi_q, \beta_1, \ldots, \beta_p, \gamma \right) when :math:\mathrm{dist} = \texttt{'N'}, and :math:\omega^\mathrm{T} = \left(\alpha_0, \alpha_1, \ldots, \alpha_q, \phi_1, \ldots, \phi_q, \beta_1, \ldots, \beta_p, \gamma, {\textit{df}}\right) when :math:\mathrm{dist} = \texttt{'T'}.

:math:\mathrm{mn}, :math:\textit{nreg} can be used to simplify the :math:\text{GARCH}\left(p, q\right) expression in (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13fgf.html#eqn1>__ as follows:

**No Regression and No Mean**

:math:y_t = \epsilon_t,

:math:\mathrm{mn} = 0,

:math:\textit{nreg} = 0 and

:math:\theta is a :math:\left(2\times q+p+1\right) vector when :math:\mathrm{dist} = \texttt{'N'}, and a :math:\left(2\times q+p+2\right) vector, when :math:\mathrm{dist} = \texttt{'T'}.

**No Regression**

:math:y_t = b_o+\epsilon_t,

:math:\mathrm{mn} = 1,

:math:\textit{nreg} = 0 and

:math:\theta is a :math:\left(2\times q+p+2\right) vector when :math:\mathrm{dist} = \texttt{'N'} and a :math:\left(2\times q+p+3\right) vector, when :math:\mathrm{dist} = \texttt{'T'}.

**Note:** if the :math:y_t = \mu +\epsilon_t, where :math:\mu is known (not to be estimated by uni_garch_exp_estim) then (1) <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13fgf.html#eqn1>__ can be written as :math:y_t^{\mu } = \epsilon_t, where :math:y_t^{\mu } = y_t-\mu.
This corresponds to the case **No Regression and No Mean**, with :math:y_t replaced by :math:y_t-\mu.

**No Mean**

:math:y_t = x_t^\mathrm{T}b+\epsilon_t,

:math:\mathrm{mn} = 0,

:math:\textit{nreg} = k and

:math:\theta is a :math:\left(2\times q+p+1+k\right) vector when :math:\mathrm{dist} = \texttt{'N'} and a :math:\left(2\times q+p+2+k\right) vector, when :math:\mathrm{dist} = \texttt{'T'}.

.. _g13fg-py2-py-references:

**References**
Bollerslev, T, 1986, Generalised autoregressive conditional heteroskedasticity, Journal of Econometrics (31), 307--327

Engle, R, 1982, Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation, Econometrica (50), 987--1008

Engle, R and Ng, V, 1993, Measuring and testing the impact of news on volatility, Journal of Finance (48), 1749--1777

Glosten, L, Jagannathan, R and Runkle, D, 1993, Relationship between the expected value and the volatility of nominal excess return on stocks, Journal of Finance (48), 1779--1801

Hamilton, J, 1994, Time Series Analysis, Princeton University Press
"""
raise NotImplementedError

[docs]def uni_garch_exp_forecast(nt, ip, iq, theta, ht, et):
r"""
uni_garch_exp_forecast forecasts the conditional variances, :math:h_t,t = T+1,\ldots,T+\xi from an exponential :math:\text{GARCH}\left(p, q\right) sequence, where :math:\xi is the forecast horizon and :math:T is the current time (see Engle and Ng (1993)).

.. _g13fh-py2-py-doc:

For full information please refer to the NAG Library document for g13fh

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13fhf.html

.. _g13fh-py2-py-parameters:

**Parameters**
**nt** : int
:math:\xi, the forecast horizon.

**ip** : int
The number of coefficients, :math:\beta_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,p.

**iq** : int
The number of coefficients, :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q.

**theta** : float, array-like, shape :math:\left(2\times \mathrm{iq}+\mathrm{ip}+1\right)
The initial parameter estimates for the vector :math:\theta. The first element must contain the coefficient :math:\alpha_o and the next :math:\mathrm{iq} elements must contain the autoregressive coefficients :math:\alpha_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q. The next :math:\mathrm{iq} elements must contain the coefficients :math:\phi_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,q. The next :math:\mathrm{ip} elements must contain the moving average coefficients :math:\beta_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,p.

**ht** : float, array-like, shape :math:\left(\textit{num}\right)
The sequence of past conditional variances for the :math:\text{GARCH}\left(p, q\right) process, :math:h_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**et** : float, array-like, shape :math:\left(\textit{num}\right)
The sequence of past residuals for the :math:\text{GARCH}\left(p, q\right) process, :math:\epsilon_{\textit{t}}, for :math:\textit{t} = 1,2,\ldots,T.

**Returns**
**fht** : float, ndarray, shape :math:\left(\mathrm{nt}\right)
The forecast values of the conditional variance, :math:h_t, for :math:\textit{t} = T+1,\ldots,T+\xi.

.. _g13fh-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{max}\left({\mathrm{ip}-1}, {\mathrm{iq}-1}\right) = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{max}\left({\mathrm{ip}-1}, {\mathrm{iq}-1}\right)\leq 20.

(errno :math:1)
On entry, :math:\textit{num} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{max}\left(\mathrm{ip}, \mathrm{iq}\right)\leq \textit{num}.

(errno :math:1)
On entry, :math:\mathrm{nt} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nt} > 0.

(errno :math:1)
On entry, :math:\mathrm{iq} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iq} \geq 1.

(errno :math:1)
On entry, :math:\mathrm{ip} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ip} \geq 0.

.. _g13fh-py2-py-notes:

**Notes**
No equivalent traditional C interface for this routine exists in the NAG Library.

Assume the :math:\text{GARCH}\left(p, q\right) process represented by:

.. math::
{ln\left(h_t\right)} = \alpha_0+\sum_{{i = 1}}^q\alpha_iz_{{t-i}}+\sum_{{j = 1}}^q\phi_i{\left(\left\lvert z_{{t-j}}\right\rvert -E\left[\left\lvert z_{{t-i}}\right\rvert \right]\right)}+\sum_{{j = 1}}^p\beta_iln\left(h_{{t-j}}\right)\text{, }\quad t = 1,2,\ldots,T\text{.}

where :math:\epsilon_t | \psi_{{t-1}} = N\left(0, h_t\right) or :math:\epsilon_t | \psi_{{t-1}} = S_t\left({\textit{df}}, h_t\right), and :math:z_t = \frac{\epsilon_t}{{\sqrt{h_t}}}, :math:E\left[\left\lvert z_{{t-i}}\right\rvert \right] denotes the expected value of :math:\left\lvert z_{{t-i}}\right\rvert, has been modelled by :meth:uni_garch_exp_estim, and the estimated conditional variances and residuals are contained in the arrays :math:\mathrm{ht} and :math:\mathrm{et} respectively.

uni_garch_exp_forecast will then use the last :math:\mathrm{max}\left(p, q\right) elements of the arrays :math:\mathrm{ht} and :math:\mathrm{et} to estimate the conditional variance forecasts, :math:h_t | \psi_T, where :math:t = T+1,\ldots,T+\xi and :math:\xi is the forecast horizon.

.. _g13fh-py2-py-references:

**References**
Bollerslev, T, 1986, Generalised autoregressive conditional heteroskedasticity, Journal of Econometrics (31), 307--327

Engle, R, 1982, Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation, Econometrica (50), 987--1008

Engle, R and Ng, V, 1993, Measuring and testing the impact of news on volatility, Journal of Finance (48), 1749--1777

Glosten, L, Jagannathan, R and Runkle, D, 1993, Relationship between the expected value and the volatility of nominal excess return on stocks, Journal of Finance (48), 1779--1801

Hamilton, J, 1994, Time Series Analysis, Princeton University Press
"""
raise NotImplementedError

[docs]def inhom_iema(iema, t, tau, inter, sinit=None, pn=0, comm=None):
r"""
inhom_iema calculates the iterated exponential moving average for an inhomogeneous time series.

.. _g13me-py2-py-doc:

For full information please refer to the NAG Library document for g13me

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13mef.html

.. _g13me-py2-py-parameters:

**Parameters**
**iema** : float, array-like, shape :math:\left(\textit{nb}\right)
:math:z_{\textit{i}}, the current block of observations, for :math:\textit{i} = k+1,\ldots,k+b, where :math:k is the number of observations processed so far, i.e., the value supplied in :math:\mathrm{pn} on entry.

**t** : float, array-like, shape :math:\left(\textit{nb}\right)
:math:t_i, the times for the current block of observations, for :math:\textit{i} = k+1,\ldots,k+b, where :math:k is the number of observations processed so far, i.e., the value supplied in :math:\mathrm{pn} on entry.

If :math:t_i\leq t_{{i-1}}, :math:\mathrm{errno} = 31 will be returned, but inhom_iema will continue as if :math:t was strictly increasing by using the absolute value.

**tau** : float
:math:\tau, the parameter controlling the rate of decay, which must be sufficiently large that :math:e^{{-\alpha }}, :math:\alpha = \left(t_i-t_{{i-1}}\right)/\tau can be calculated without overflowing, for all :math:i.

**inter** : int, array-like, shape :math:\left(2\right)
The type of interpolation used with :math:\mathrm{inter}[0] indicating the interpolation method to use when calculating :math:\text{EMA}\left[\tau,1;z\right] and :math:\mathrm{inter}[1] the interpolation method to use when calculating :math:\text{EMA}\left[\tau,j;z\right], :math:j > 1.

Three types of interpolation are possible:

:math:\mathrm{inter}[i] = 1

Previous point, with :math:\nu = 1.

:math:\mathrm{inter}[i] = 2

Linear, with :math:\nu = \left(1-\mu \right)/\alpha.

:math:\mathrm{inter}[i] = 3

Next point, :math:\nu = \mu.

Zumbach and Müller (2001) recommend that linear interpolation is used in second and subsequent iterations, i.e., :math:\mathrm{inter}[1] = 2, irrespective of the interpolation method used at the first iteration, i.e., the value of :math:\mathrm{inter}[0].

**sinit** : None or float, array-like, shape :math:\left(m+2\right), optional
If :math:\mathrm{pn} = 0, the values used to start the iterative process, with

:math:\mathrm{sinit}[0] = t_0,

:math:\mathrm{sinit}[1] = z_0,

:math:\mathrm{sinit}[\textit{j}+1] = \text{EMA}\left[\tau,\textit{j};z\right]\left(t_0\right), for :math:\textit{j} = 1,2,\ldots,m.

If :math:\mathrm{pn}\neq 0, :math:\mathrm{sinit} is not referenced.

**pn** : int, optional
:math:k, the number of observations processed so far. On the first call to inhom_iema, or when starting to summarise a new dataset, :math:\mathrm{pn} must be set to :math:0. On subsequent calls it must be the same value as returned by the last call to inhom_iema.

**comm** : None or dict, communication object, optional, modified in place
Communication structure.

On initial entry: need not be set.

**Returns**
**iema** : float, ndarray, shape :math:\left(\textit{nb}\right)
The iterated EMA, with :math:\mathrm{iema}[i-1] = \text{EMA}\left[\tau,m;z\right]\left(t_i\right).

**pn** : int
:math:k+b, the updated number of observations processed so far.

.. _g13me-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:11)
On entry, :math:\textit{nb} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nb}\geq 0.

(errno :math:32)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{t}[i-2] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{t}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{t}[i-1]\neq \mathrm{t}[i-2] if linear interpolation is being used.

(errno :math:41)
On entry, :math:\mathrm{tau} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tau} > 0.0.

(errno :math:42)
On entry, :math:\mathrm{tau} = \langle\mathit{\boldsymbol{value}}\rangle.

On entry at previous call, :math:\mathrm{tau} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} > 0 then :math:\mathrm{tau} must be unchanged since previous call.

(errno :math:51)
On entry, :math:m = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:m\geq 1.

(errno :math:52)
On entry, :math:m = \langle\mathit{\boldsymbol{value}}\rangle.

On entry at previous call, :math:m = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} > 0 then :math:\textit{m} must be unchanged since previous call.

(errno :math:71)
On entry, :math:\mathrm{inter}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{inter}[0] = 1, :math:2 or :math:3.

(errno :math:72)
On entry, :math:\mathrm{inter}[1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{inter}[1] = 1, :math:2 or :math:3.

(errno :math:73)
On entry, :math:\mathrm{inter}[0] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{inter}[1] = \langle\mathit{\boldsymbol{value}}\rangle.

On entry at previous call, :math:\mathrm{inter}[0] = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{inter}[1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} \neq 0, :math:\mathrm{inter} must be unchanged since the previous call.

(errno :math:81)
On entry, :math:\mathrm{pn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{pn}\geq 0.

(errno :math:82)
On entry, :math:\mathrm{pn} = \langle\mathit{\boldsymbol{value}}\rangle.

On exit from previous call, :math:\mathrm{pn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} > 0 then :math:\mathrm{pn} must be unchanged since previous call.

(errno :math:91)
:math:\mathrm{comm}\ ['rcomm'] has been corrupted between calls.

(errno :math:101)
On entry, :math:\mathrm{pn} = 0, :math:\textit{lrcomm} = \langle\mathit{\boldsymbol{value}}\rangle and :math:m = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} = 0, :math:\textit{lrcomm} = 0 or :math:\textit{lrcomm}\geq m+20.

(errno :math:102)
On entry, :math:\mathrm{pn}\neq 0, :math:\textit{lrcomm} = \langle\mathit{\boldsymbol{value}}\rangle and :math:m = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn}\neq 0, :math:\textit{lrcomm}\geq m+20.

**Warns**
**NagAlgorithmicWarning**
(errno :math:31)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{t}[i-2] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{t}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{t} should be strictly increasing.

(errno :math:301)
Truncation occurred to avoid overflow, check for extreme values in :math:\mathrm{t}, :math:\mathrm{iema} or for :math:\mathrm{tau}.

.. _g13me-py2-py-notes:

**Notes**
inhom_iema calculates the iterated exponential moving average for an inhomogeneous time series.
The time series is represented by two vectors of length :math:n; a vector of times, :math:t; and a vector of values, :math:z.
Each element of the time series is, therefore, composed of the pair of scalar values :math:\left(t_{\textit{i}},z_i\right), for :math:\textit{i} = 1,2,\ldots,n.
Time can be measured in any arbitrary units, as long as all elements of :math:t use the same units.

The exponential moving average (EMA), with parameter :math:\tau, is an average operator, with the exponentially decaying kernel given by

.. math::
\frac{e^{{-t_i/\tau }}}{\tau }\text{.}

The exponential form of this kernel gives rise to the following iterative formula for the EMA operator (see Zumbach and Müller (2001)):

.. math::
\text{EMA}\left[\tau ;z\right]\left(t_i\right) = \mu \text{EMA}\left[\tau ;z\right]\left(t_{{i-1}}\right)+\left(\nu -\mu \right)z_{{i-1}}+\left(1-\nu \right)z_i

where

.. math::

The value of :math:\nu depends on the method of interpolation chosen. inhom_iema gives the option of three interpolation methods:

.. rst-class:: nag-rules-none nag-align-left

+--+---------------+-----------------------------------------+
|1.|Previous point:|:math:\nu = 1;                         |
+--+---------------+-----------------------------------------+
|2.|Linear:        |:math:\nu = \left(1-\mu \right)/\alpha;|
+--+---------------+-----------------------------------------+
|3.|Next point:    |:math:\nu = \mu.                       |
+--+---------------+-----------------------------------------+

The :math:m-iterated exponential moving average, :math:\text{EMA}\left[\tau,m;z\right]\left(t_i\right), :math:m > 1, is defined using the recursive formula:

.. math::
\text{EMA}\left[\tau,m;z\right] = \text{EMA}\left[\tau ;\text{EMA}\left[\tau,m-1;z\right]\right]

with

.. math::
\text{EMA}\left[\tau,1;z\right] = \text{EMA}\left[\tau ;z\right]\text{.}

For large datasets or where all the data is not available at the same time, :math:z and :math:t can be split into arbitrary sized blocks and inhom_iema called multiple times.

.. _g13me-py2-py-references:

**References**
Dacorogna, M M, Gencay, R, Müller, U, Olsen, R B and Pictet, O V, 2001, An Introduction to High-frequency Finance, Academic Press

Zumbach, G O and Müller, U A, 2001, Operators on inhomogeneous time series, International Journal of Theoretical and Applied Finance (4(1)), 147--178

--------
:meth:naginterfaces.library.examples.tsa.inhom_iema_ex.main
"""
raise NotImplementedError

[docs]def inhom_iema_all(z, t, tau, m1, inter, ftype, p, sorder=1, sinit=None, x=None, pn=0, comm=None):
r"""
inhom_iema_all calculates the iterated exponential moving average for an inhomogeneous time series, returning the intermediate results.

.. _g13mf-py2-py-doc:

For full information please refer to the NAG Library document for g13mf

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13mff.html

.. _g13mf-py2-py-parameters:

**Parameters**
**z** : float, array-like, shape :math:\left(\textit{nb}\right)
:math:z_{\textit{i}}, the current block of observations, for :math:\textit{i} = k+1,\ldots,k+b, where :math:k is the number of observations processed so far, i.e., the value supplied in :math:\mathrm{pn} on entry.

**t** : float, array-like, shape :math:\left(\textit{nb}\right)
:math:t_{\textit{i}}, the times for the current block of observations, for :math:\textit{i} = k+1,\ldots,k+b, where :math:k is the number of observations processed so far, i.e., the value supplied in :math:\mathrm{pn} on entry.

If :math:t_i\leq t_{{i-1}}, :math:\mathrm{errno} = 61 will be returned, but inhom_iema_all will continue as if :math:t was strictly increasing by using the absolute value.

**tau** : float
:math:\tau, the parameter controlling the rate of decay. :math:\tau must be sufficiently large that :math:e^{{-\alpha }}, :math:\alpha = \left(t_i-t_{{i-1}}\right)/\tau can be calculated without overflowing, for all :math:i.

**m1** : int
The minimum number of times the EMA operator is to be iterated.

**inter** : int, array-like, shape :math:\left(2\right)
The type of interpolation used with :math:\mathrm{inter}[0] indicating the interpolation method to use when calculating :math:\text{EMA}\left[\tau,1;z\right] and :math:\mathrm{inter}[1] the interpolation method to use when calculating :math:\text{EMA}\left[\tau,j;z\right], :math:j > 1.

Three types of interpolation are possible:

:math:\mathrm{inter}[i] = 1

Previous point, with :math:\nu = 1.

:math:\mathrm{inter}[i] = 2

Linear, with :math:\nu = \left(1-\mu \right)/\alpha.

:math:\mathrm{inter}[i] = 3

Next point, :math:\nu = \mu.

Zumbach and Müller (2001) recommend that linear interpolation is used in second and subsequent iterations, i.e., :math:\mathrm{inter}[1] = 2, irrespective of the interpolation method used at the first iteration, i.e., the value of :math:\mathrm{inter}[0].

**ftype** : int
The function type used to define the relationship between :math:y and :math:z when calculating :math:\text{EMA}\left[\tau,1;y\right]. Three functions are provided:

:math:\mathrm{ftype} = 1

The identity function, with :math:y_i = z_i^{\left[p\right]}.

:math:\mathrm{ftype} = 2

The absolute value, with :math:y_i = \left|z_i\right|^p.

:math:\mathrm{ftype} = 3

The absolute difference, with :math:y_i = \left|z_i-x_i\right|^p, where the vector :math:x is supplied in :math:\mathrm{x}.

**p** : float
:math:p, the power used in the transformation function.

**sorder** : int, optional
Determines the storage order of output returned in :math:\mathrm{iema}.

**sinit** : None or float, array-like, shape :math:\left(\textit{m2}+2\right), optional
If :math:\mathrm{pn} = 0, the values used to start the iterative process, with

:math:\mathrm{sinit}[0] = t_0,

:math:\mathrm{sinit}[1] = y_0,

:math:\mathrm{sinit}[j+1] = \text{EMA}\left[\tau,j;y\right]\left(t_0\right), :math:j = 1,2,\ldots,\textit{m2}.

If :math:\mathrm{pn}\neq 0 then :math:\mathrm{sinit} is not referenced.

**x** : None or float, array-like, shape :math:\left(:\right), optional
Note: the required length for this argument is determined as follows: if :math:\mathrm{ftype}=3: :math:\textit{nb}; otherwise: :math:0.

If :math:\mathrm{ftype} = 3, :math:x_i, the vector used to shift the current block of observations, for :math:\textit{i} = k+1,\ldots,k+b, where :math:k is the number of observations processed so far, i.e., the value supplied in :math:\mathrm{pn} on entry.

If :math:\mathrm{ftype} \neq 3 then :math:\mathrm{x} is not referenced.

**pn** : int, optional
:math:k, the number of observations processed so far. On the first call to inhom_iema_all, or when starting to summarise a new dataset, :math:\mathrm{pn} must be set to :math:0. On subsequent calls it must be the same value as returned by the last call to inhom_iema_all.

**comm** : None or dict, communication object, optional, modified in place
Communication structure.

On initial entry: need not be set.

**Returns**
**iema** : float, ndarray, shape :math:\left(:, :\right)
The iterated exponential moving average.

If :math:\mathrm{sorder} = 1, :math:\mathrm{iema}[i-1,j-1] = \text{EMA}\left[\tau,j+\mathrm{m1}-1;y\right]\left(t_{{i+k}}\right).

If :math:\mathrm{sorder} = 2, :math:\mathrm{iema}[j-1,i-1] = \text{EMA}\left[\tau,j+\mathrm{m1}-1;y\right]\left(t_{{i+k}}\right).

For :math:i = 1,2,\ldots,\textit{nb}, :math:j = 1,2,\ldots,\textit{m2}-\mathrm{m1}+1 and :math:k is the number of observations processed so far, i.e., the value supplied in :math:\mathrm{pn} on entry.

**p** : float
If :math:\mathrm{ftype} = 1, then :math:\left[p\right], the actual power used in the transformation function is returned, otherwise :math:\mathrm{p} is unchanged.

**pn** : int
:math:k+b, the updated number of observations processed so far.

.. _g13mf-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:11)
On entry, :math:\mathrm{sorder} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{sorder} = 1 or :math:2.

(errno :math:21)
On entry, :math:\textit{nb} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nb}\geq 0.

(errno :math:51)
On entry, :math:\mathrm{sorder} = 1, :math:\textit{ldiema} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{nb} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ldiema}\geq \textit{nb}.

(errno :math:51)
On entry, :math:\mathrm{sorder} = 2, :math:\textit{ldiema} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{m2}-\mathrm{m1}+1 = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ldiema}\geq \textit{m2}-\mathrm{m1}+1.

(errno :math:62)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{t}[i-2] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{t}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{t}[i-1]\neq \mathrm{t}[i-2] if linear interpolation is being used.

(errno :math:71)
On entry, :math:\mathrm{tau} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tau} > 0.0.

(errno :math:72)
On entry, :math:\mathrm{tau} = \langle\mathit{\boldsymbol{value}}\rangle.

On entry at previous call, :math:\mathrm{tau} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} > 0 then :math:\mathrm{tau} must be unchanged since previous call.

(errno :math:81)
On entry, :math:\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{m1}\geq 1.

(errno :math:82)
On entry, :math:\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle.

On entry at previous call, :math:\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} > 0 then :math:\mathrm{m1} must be unchanged since previous call.

(errno :math:91)
On entry, :math:\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{m2}\geq \mathrm{m1}.

(errno :math:92)
On entry, :math:\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle.

On entry at previous call, :math:\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} > 0 then :math:\textit{m2} must be unchanged since previous call.

(errno :math:101)
On entry, :math:\mathrm{ftype} \neq 1, :math:j = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{sinit}[j-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ftype} \neq 1, :math:\mathrm{sinit}[\textit{j}-1]\geq 0.0, for :math:\textit{j} = 2,3,\ldots,\textit{m2}+2.

(errno :math:111)
On entry, :math:\mathrm{inter}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{inter}[0] = 1, :math:2 or :math:3.

(errno :math:112)
On entry, :math:\mathrm{inter}[1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{inter}[1] = 1, :math:2 or :math:3.

(errno :math:113)
On entry, :math:\mathrm{inter}[0] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{inter}[1] = \langle\mathit{\boldsymbol{value}}\rangle.

On entry at previous call, :math:\mathrm{inter}[0] = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{inter}[1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} \neq 0, :math:\mathrm{inter} must be unchanged since the last call.

(errno :math:121)
On entry, :math:\mathrm{ftype} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ftype} = 1, :math:2 or :math:3.

(errno :math:122)
On entry, :math:\mathrm{ftype} = \langle\mathit{\boldsymbol{value}}\rangle, On entry at previous call, :math:\mathrm{ftype} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} \neq 0, :math:\mathrm{ftype} must be unchanged since the previous call.

(errno :math:131)
On entry, :math:\mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: absolute value of :math:\mathrm{p} must be representable as an integer.

(errno :math:132)
On entry, :math:\mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ftype} \neq 1, :math:\mathrm{p}\neq 0.0. If :math:\mathrm{ftype} = 1, the nearest integer to :math:\mathrm{p} must not be :math:0.

(errno :math:133)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{z}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ftype} = 1 or :math:2 and :math:\mathrm{z}[i] = 0 for any :math:i then :math:\mathrm{p} > 0.0.

(errno :math:134)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{z}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{x}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ftype} = 3 and :math:\mathrm{z}[i] = \mathrm{x}[i] for any :math:i then :math:\mathrm{p} > 0.0.

(errno :math:135)
On entry, :math:\mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle.

On exit from previous call, :math:\mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} > 0 then :math:\mathrm{p} must be unchanged since previous call.

(errno :math:151)
On entry, :math:\mathrm{pn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{pn}\geq 0.

(errno :math:152)
On entry, :math:\mathrm{pn} = \langle\mathit{\boldsymbol{value}}\rangle.

On exit from previous call, :math:\mathrm{pn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} > 0 then :math:\mathrm{pn} must be unchanged since previous call.

(errno :math:161)
:math:\mathrm{comm}\ ['rcomm'] has been corrupted between calls.

(errno :math:171)
On entry, :math:\mathrm{pn} = 0, :math:\textit{lrcomm} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} = 0, :math:\textit{lrcomm} = 0 or :math:\textit{lrcomm}\geq \textit{m2}+20.

(errno :math:172)
On entry, :math:\mathrm{pn} \neq 0, :math:\textit{lrcomm} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn}\neq 0 then :math:\textit{lrcomm}\geq \textit{m2}+20.

**Warns**
**NagAlgorithmicWarning**
(errno :math:61)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{t}[i-2] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{t}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{t} should be strictly increasing.

(errno :math:301)
Truncation occurred to avoid overflow, check for extreme values in :math:\mathrm{t}, :math:\mathrm{z}, :math:\mathrm{x} or for :math:\mathrm{tau}.

.. _g13mf-py2-py-notes:

**Notes**
inhom_iema_all calculates the iterated exponential moving average for an inhomogeneous time series.
The time series is represented by two vectors of length :math:n: a vector of times, :math:t; and a vector of values, :math:z.
Each element of the time series is, therefore, composed of the pair of scalar values :math:\left(t_{\textit{i}},z_{\textit{i}}\right), for :math:\textit{i} = 1,2,\ldots,n.
Time can be measured in any arbitrary units, as long as all elements of :math:t use the same units.

The exponential moving average (EMA), with parameter :math:\tau, is an average operator, with the exponentially decaying kernel given by

.. math::
\frac{e^{{-t_i/\tau }}}{\tau }\text{.}

The exponential form of this kernel gives rise to the following iterative formula (Zumbach and Müller (2001)) for the EMA operator:

.. math::
\text{EMA}\left[\tau ;y\right]\left(t_i\right) = \mu \text{EMA}\left[\tau ;y\right]\left(t_{{i-1}}\right)+\left(\nu -\mu \right)y_{{i-1}}+\left(1-\nu \right)y_i

where

.. math::

The value of :math:\nu depends on the method of interpolation chosen and the relationship between :math:y and the input series :math:z depends on the transformation function chosen. inhom_iema_all gives the option of three interpolation methods:

.. rst-class:: nag-rules-none nag-align-left

+--+---------------+-----------------------------------------+
|1.|Previous point:|:math:\nu = 1;                         |
+--+---------------+-----------------------------------------+
|2.|Linear:        |:math:\nu = \left(1-\mu \right)/\alpha;|
+--+---------------+-----------------------------------------+
|3.|Next point:    |:math:\nu = \mu.                       |
+--+---------------+-----------------------------------------+

and three transformation functions:

.. rst-class:: nag-rules-none nag-align-left

+--+--------------------+-------------------------------------+
|1.|Identity:           |:math:y_i = z_i^{\left[p\right]};  |
+--+--------------------+-------------------------------------+
|2.|Absolute value:     |:math:y_i = \left|z_i\right|^p;    |
+--+--------------------+-------------------------------------+
|3.|Absolute difference:|:math:y_i = \left|z_i-x_i\right|^p;|
+--+--------------------+-------------------------------------+

where the notation :math:\left[p\right] is used to denote the integer nearest to :math:p.
In the case of the absolute difference :math:x is a user-supplied vector of length :math:n and, therefore, each element of the time series is composed of the triplet of scalar values, :math:\left(t_i,z_i,x_i\right).

The :math:m-iterated exponential moving average, :math:\text{EMA}\left[\tau,m;y\right]\left(t_i\right), is defined using the recursive formula:

.. math::
\text{EMA}\left[\tau,m;y\right]\left(t_i\right) = \text{EMA}\left[\tau ;\text{EMA}\left[\tau,m-1;y\right]\left(t_i\right)\right]\left(t_i\right)

with

.. math::
\text{EMA}\left[\tau,1;y\right]\left(t_i\right) = \text{EMA}\left[\tau ;y\right]\left(t_i\right)\text{.}

For large datasets or where all the data is not available at the same time, :math:z,t and, where required, :math:x can be split into arbitrary sized blocks and inhom_iema_all called multiple times.

.. _g13mf-py2-py-references:

**References**
Dacorogna, M M, Gencay, R, Müller, U, Olsen, R B and Pictet, O V, 2001, An Introduction to High-frequency Finance, Academic Press

Zumbach, G O and Müller, U A, 2001, Operators on inhomogeneous time series, International Journal of Theoretical and Applied Finance (4(1)), 147--178
"""
raise NotImplementedError

[docs]def inhom_ma(ma, t, tau, m1, m2, inter, ftype, p, sinit=None, pn=0, comm=None):
r"""
inhom_ma provides a moving average, moving norm, moving variance and moving standard deviation operator for an inhomogeneous time series.

.. _g13mg-py2-py-doc:

For full information please refer to the NAG Library document for g13mg

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13mgf.html

.. _g13mg-py2-py-parameters:

**Parameters**
**ma** : float, array-like, shape :math:\left(\textit{nb}\right)
:math:z_{\textit{i}}, the current block of observations, for :math:\textit{i} = k+1,\ldots,k+b, where :math:k is the number of observations processed so far, i.e., the value supplied in :math:\mathrm{pn} on entry.

**t** : float, array-like, shape :math:\left(\textit{nb}\right)
:math:t_{\textit{i}}, the times for the current block of observations, for :math:\textit{i} = k+1,\ldots,k+b, where :math:k is the number of observations processed so far, i.e., the value supplied in :math:\mathrm{pn} on entry.

If :math:t_i\leq t_{{i-1}}, :math:\mathrm{errno} = 31 will be returned, but inhom_ma will continue as if :math:t was strictly increasing by using the absolute value.

The lagged difference, :math:t_i-t_{{i-1}} must be sufficiently small that :math:e^{{-\alpha }}, :math:\alpha = \left(t_i-t_{{i-1}}\right)/\tilde{\tau } can be calculated without overflowing, for all :math:i.

**tau** : float
:math:\tau, the parameter controlling the rate of decay. :math:\tau must be sufficiently large that :math:e^{{-\alpha }}, :math:\alpha = \left(t_i-t_{{i-1}}\right)/\tilde{\tau } can be calculated without overflowing, for all :math:i, where :math:\tilde{\tau } = \frac{{2\tau }}{{m_2+m_1}}.

**m1** : int
:math:m_1, the iteration of the EMA operator at which the sum is started.

**m2** : int
:math:m_2, the iteration of the EMA operator at which the sum is ended.

**inter** : int, array-like, shape :math:\left(2\right)
The type of interpolation used with :math:\mathrm{inter}[0] indicating the interpolation method to use when calculating :math:\text{EMA}\left[\tau,1;z\right] and :math:\mathrm{inter}[1] the interpolation method to use when calculating :math:\text{EMA}\left[\tau,j;z\right], :math:j > 1.

Three types of interpolation are possible:

:math:\mathrm{inter}[i] = 1

Previous point, with :math:\nu = 1.

:math:\mathrm{inter}[i] = 2

Linear, with :math:\nu = \left(1-\mu \right)/\alpha.

:math:\mathrm{inter}[i] = 3

Next point, :math:\nu = \mu.

Zumbach and Müller (2001) recommend that linear interpolation is used in second and subsequent iterations, i.e., :math:\mathrm{inter}[1] = 2, irrespective of the interpolation method used at the first iteration, i.e., the value of :math:\mathrm{inter}[0].

**ftype** : int
The function type used to define the relationship between :math:y and :math:z when calculating :math:\text{EMA}\left[\tau,1;y\right]. Three functions are provided:

:math:\mathrm{ftype} = 1

The identity function, with :math:y_i = z_i^{\left[p\right]}.

:math:\mathrm{ftype} = 2 or :math:4

The absolute value, with :math:y_i = \left|z_i\right|^p.

:math:\mathrm{ftype} = 3 or :math:5

The absolute difference, with :math:y_i = \left|z_i-\text{MA}\left[\tau,m;y\right]\left(t_i\right)\right|^p.

If :math:\mathrm{ftype} = 4 or :math:5 then the resulting vector of averages is scaled by :math:p^{-1} as described in :math:\mathrm{ma}.

**p** : float
:math:p, the power used in the transformation function.

**sinit** : None or float, array-like, shape :math:\left(:\right), optional
Note: the required length for this argument is determined as follows: if :math:\mathrm{ftype}\text{ in } (3, 5): :math:{ 2 \times \mathrm{m2} + 3 }; otherwise: :math:{ \mathrm{m2}+2 }.

If :math:\mathrm{pn} = 0, the values used to start the iterative process, with

:math:\mathrm{sinit}[0] = t_0,

:math:\mathrm{sinit}[1] = y_0,

:math:\mathrm{sinit}[\textit{j}+1] = \text{EMA}\left[\tau,\textit{j};y\right]\left(t_0\right), for :math:\textit{i} = 1,2,\ldots,\mathrm{m2}.

In addition, if :math:\mathrm{ftype} = 3 or :math:5 then

:math:\mathrm{sinit}[\mathrm{m2}+2] = z_0,

:math:\mathrm{sinit}[\mathrm{m2}+\textit{j}+1] = \text{EMA}\left[\tau,\textit{j};z\right]\left(t_0\right), for :math:\textit{j} = 1,2,\ldots,\mathrm{m2}.

i.e., initial values based on the original data :math:z as opposed to the transformed data :math:y.

If :math:\mathrm{pn}\neq 0, :math:\mathrm{sinit} is not referenced.

**pn** : int, optional
:math:k, the number of observations processed so far. On the first call to inhom_ma, or when starting to summarise a new dataset, :math:\mathrm{pn} must be set to :math:0. On subsequent calls it must be the same value as returned by the last call to inhom_ma.

**comm** : None or dict, communication object, optional, modified in place
Communication structure.

On initial entry: need not be set.

**Returns**
**ma** : float, ndarray, shape :math:\left(\textit{nb}\right)
The moving average:

if :math:\mathrm{ftype} = 4 or :math:5

:math:\mathrm{ma}[i-1] = \left\{\text{MA}\left[\tau,m_1,m_2;y\right]\left(t_i\right)\right\}^{{1/p}},

otherwise

:math:\mathrm{ma}[i-1] = \text{MA}\left[\tau,m_1,m_2;y\right]\left(t_i\right).

**p** : float
If :math:\mathrm{ftype} = 1, then :math:\left[p\right], the actual power used in the transformation function is returned, otherwise :math:\mathrm{p} is unchanged.

**pn** : int
:math:k+b, the updated number of observations processed so far.

**wma** : float, ndarray, shape :math:\left(\textit{nb}\right)
Either the moving average or exponential moving average, depending on the value of :math:\mathrm{ftype}.

if :math:\mathrm{ftype} = 3 or :math:5

:math:\mathrm{wma}[i-1] = \text{MA}\left[\tau ;y\right]\left(t_i\right)

otherwise

:math:\mathrm{wma}[i-1] = \text{EMA}\left[\tilde{\tau };y\right]\left(t_i\right).

.. _g13mg-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:11)
On entry, :math:\textit{nb} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nb}\geq 0.

(errno :math:32)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{t}[i-2] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{t}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{t}[i-1]\neq \mathrm{t}[i-2] if linear interpolation is being used.

(errno :math:41)
On entry, :math:\mathrm{tau} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tau} > 0.0.

(errno :math:42)
On entry, :math:\mathrm{tau} = \langle\mathit{\boldsymbol{value}}\rangle.

On entry at previous call, :math:\mathrm{tau} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} > 0 then :math:\mathrm{tau} must be unchanged since previous call.

(errno :math:51)
On entry, :math:\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{m1}\geq 1.

(errno :math:52)
On entry, :math:\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle.

On entry at previous call, :math:\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} > 0 then :math:\mathrm{m1} must be unchanged since previous call.

(errno :math:61)
On entry, :math:\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{m2} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{m2}\geq \mathrm{m1}.

(errno :math:62)
On entry, :math:\mathrm{m2} = \langle\mathit{\boldsymbol{value}}\rangle.

On entry at previous call, :math:\mathrm{m2} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} > 0 then :math:\mathrm{m2} must be unchanged since previous call.

(errno :math:71)
On entry, :math:\mathrm{ftype} \neq 1, :math:j = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{sinit}[j-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ftype} \neq 1, :math:\mathrm{sinit}[\textit{j}-1]\geq 0.0, for :math:\textit{j} = 2,3,\ldots,\mathrm{m2}+2.

(errno :math:81)
On entry, :math:\mathrm{inter}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{inter}[0] = 1, :math:2 or :math:3.

(errno :math:82)
On entry, :math:\mathrm{inter}[1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{inter}[1] = 1, :math:2 or :math:3.

(errno :math:83)
On entry, :math:\mathrm{inter}[0] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{inter}[1] = \langle\mathit{\boldsymbol{value}}\rangle.

On entry at previous call, :math:\mathrm{inter}[0] = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{inter}[1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} \neq 0, :math:\mathrm{inter} must be unchanged since the last call.

(errno :math:91)
On entry, :math:\mathrm{ftype} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ftype} = 1, :math:2, :math:3, :math:4 or :math:5.

(errno :math:92)
On entry, :math:\mathrm{ftype} = \langle\mathit{\boldsymbol{value}}\rangle, On entry at previous call, :math:\mathrm{ftype} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} \neq 0, :math:\mathrm{ftype} must be unchanged since the previous call.

(errno :math:101)
On entry, :math:\mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: absolute value of :math:\mathrm{p} must be representable as an integer.

(errno :math:102)
On entry, :math:\mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ftype} \neq 1, :math:\mathrm{p}\neq 0.0. If :math:\mathrm{ftype} = 1, the nearest integer to :math:\mathrm{p} must not be :math:0.

(errno :math:103)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{ma}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ftype} = 1, :math:2 or :math:4 and :math:\mathrm{ma}[i-1] = 0 for any :math:i then :math:\mathrm{p} > 0.0.

(errno :math:104)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{ma}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{wma}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{p} < 0.0, :math:\mathrm{ma}[i-1]-\mathrm{wma}[i-1]\neq 0.0, for any :math:i.

(errno :math:105)
On entry, :math:\mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle.

On exit from previous call, :math:\mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} > 0 then :math:\mathrm{p} must be unchanged since previous call.

(errno :math:111)
On entry, :math:\mathrm{pn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{pn}\geq 0.

(errno :math:112)
On entry, :math:\mathrm{pn} = \langle\mathit{\boldsymbol{value}}\rangle.

On exit from previous call, :math:\mathrm{pn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} > 0 then :math:\mathrm{pn} must be unchanged since previous call.

(errno :math:131)
:math:\mathrm{comm}\ ['rcomm'] has been corrupted between calls.

(errno :math:141)
On entry, :math:\mathrm{pn} = 0, :math:\textit{lrcomm} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{m2} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn} = 0, :math:\textit{lrcomm} = 0 or :math:\textit{lrcomm}\geq 2\mathrm{m2}+20.

(errno :math:142)
On entry, :math:\mathrm{pn} \neq 0, :math:\textit{lrcomm} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{m2} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{pn}\neq 0, :math:\textit{lrcomm}\geq 2\mathrm{m2}+20.

**Warns**
**NagAlgorithmicWarning**
(errno :math:31)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{t}[i-2] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{t}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{t} should be strictly increasing.

(errno :math:301)
Truncation occurred to avoid overflow, check for extreme values in :math:\mathrm{t}, :math:\mathrm{ma} or for :math:\mathrm{tau}.

.. _g13mg-py2-py-notes:

**Notes**
inhom_ma provides a number of operators for an inhomogeneous time series.
The time series is represented by two vectors of length :math:n; a vector of times, :math:t; and a vector of values, :math:z.
Each element of the time series is, therefore, composed of the pair of scalar values :math:\left(t_{\textit{i}},z_i\right), for :math:\textit{i} = 1,2,\ldots,n.
Time :math:t can be measured in any arbitrary units, as long as all elements of :math:t use the same units.

The main operator available, the moving average (MA), with parameter :math:\tau is defined as

.. math::
\text{MA}\left[\tau,m_1,m_2;y\right]\left(t_i\right) = \frac{1}{{m_2-m_1+1}}\sum_{{j = m_1}}^{m_2}\text{EMA}\left[\tilde{\tau },j;y\right]\left(t_i\right)

where :math:\tilde{\tau } = \frac{{2\tau }}{{m_2+m_1}}, :math:m_1 and :math:m_2 are user-supplied integers controlling the amount of lag and smoothing respectively, with :math:m_2\geq m_1 and :math:\text{EMA}\left[·\right] is the iterated exponential moving average operator.

The iterated exponential moving average, :math:\text{EMA}\left[\tilde{\tau },m;y\right]\left(t_i\right), is defined using the recursive formula:

.. math::
\text{EMA}\left[\tilde{\tau },m;y\right]\left(t_i\right) = \text{EMA}\left[\tilde{\tau };\text{EMA}\left[\tilde{\tau },m-1;y\right]\left(t_i\right)\right]\left(t_i\right)

with

.. math::
\text{EMA}\left[\tilde{\tau },1;y\right]\left(t_i\right) = \text{EMA}\left[\tilde{\tau };y\right]\left(t_i\right)

and

.. math::
\text{EMA}\left[\tilde{\tau };y\right]\left(t_i\right) = \mu \text{EMA}\left[\tilde{\tau };y\right]\left(t_{{i-1}}\right)+\left(\nu -\mu \right)y_{{i-1}}+\left(1-\nu \right)y_i

where

.. math::

The value of :math:\nu depends on the method of interpolation chosen and the relationship between :math:y and the input series :math:z depends on the transformation function chosen. inhom_ma gives the option of three interpolation methods:

.. rst-class:: nag-rules-none nag-align-left

+--+---------------+-----------------------------------------+
|1.|Previous point:|:math:\nu = 1.                         |
+--+---------------+-----------------------------------------+
|2.|Linear:        |:math:\nu = \left(1-\mu \right)/\alpha.|
+--+---------------+-----------------------------------------+
|3.|Next point:    |:math:\nu = \mu.                       |
+--+---------------+-----------------------------------------+

and three transformation functions:

.. rst-class:: nag-rules-none nag-align-left

+--+--------------------+--------------------------------------------------------------------------------------+
|1.|Identity:           |:math:y_i = z_i^{\left[p\right]}.                                                   |
+--+--------------------+--------------------------------------------------------------------------------------+
|2.|Absolute value:     |:math:y_i = \left|z_i\right|^p.                                                     |
+--+--------------------+--------------------------------------------------------------------------------------+
|3.|Absolute difference:|:math:y_i = \left|z_i-\text{MA}\left[\tau,m_1,m_2;z\right]\left(t_i\right)\right|^p.|
+--+--------------------+--------------------------------------------------------------------------------------+

where the notation :math:\left[p\right] is used to denote the integer nearest to :math:p.
In addition, if either the absolute value or absolute difference transformation are used then the resulting moving average can be scaled by :math:p^{-1}.

The various parameter options allow a number of different operators to be applied by inhom_ma, a few of which are:

(i) **Moving Average (MA)**, as defined in [equation] <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13mgf.html#mairregular>__ (obtained by setting :math:\mathrm{ftype} = 1 and :math:\mathrm{p} = 1).

(#) **Moving Norm (MNorm)**, defined as

.. math::
\text{MNorm}\left(\tau,m,p;z\right) = {\text{MA}\left[\tau,1,m;\left|z\right|^p\right]}^{{1/p}}

(obtained by setting :math:\mathrm{ftype} = 4, :math:\mathrm{m1} = 1 and :math:\mathrm{m2} = m).

(#) **Moving Variance (MVar)**, defined as

.. math::
\text{MVar}\left(\tau,m,p;z\right) = \text{MA}\left[\tau,1,m;\left|z-\text{MA}\left[\tau,1,m;z\right]\right|^p\right]

(obtained by setting :math:\mathrm{ftype} = 3, :math:\mathrm{m1} = 1 and :math:\mathrm{m2} = m).

(#) **Moving Standard Deviation (MSD)**, defined as

.. math::
\text{MSD}\left(\tau,m,p;z\right) = {\text{MA}\left[\tau,1,m;\left|z-\text{MA}\left[\tau,1,m;z\right]\right|^p\right]}^{{1/p}}

(obtained by setting :math:\mathrm{ftype} = 5, :math:\mathrm{m1} = 1 and :math:\mathrm{m2} = m).

For large datasets or where all the data is not available at the same time, :math:z and :math:t can be split into arbitrary sized blocks and inhom_ma called multiple times.

.. _g13mg-py2-py-references:

**References**
Dacorogna, M M, Gencay, R, Müller, U, Olsen, R B and Pictet, O V, 2001, An Introduction to High-frequency Finance, Academic Press

Zumbach, G O and Müller, U A, 2001, Operators on inhomogeneous time series, International Journal of Theoretical and Applied Finance (4(1)), 147--178
"""
raise NotImplementedError

[docs]def cp_pelt(ctype, y, beta=None, minss=2, param=None):
r"""
cp_pelt detects change points in a univariate time series, that is, the time points at which some feature of the data, for example the mean, changes.
Change points are detected using the PELT (Pruned Exact Linear Time) algorithm using one of a provided set of cost functions.

.. _g13na-py2-py-doc:

For full information please refer to the NAG Library document for g13na

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13naf.html

.. _g13na-py2-py-parameters:

**Parameters**
**ctype** : int
A flag indicating the assumed distribution of the data and the type of change point being looked for.

:math:\mathrm{ctype} = 1

Data from a Normal distribution, looking for changes in the mean, :math:\mu.

:math:\mathrm{ctype} = 2

Data from a Normal distribution, looking for changes in the standard deviation :math:\sigma.

:math:\mathrm{ctype} = 3

Data from a Normal distribution, looking for changes in the mean, :math:\mu and standard deviation :math:\sigma.

:math:\mathrm{ctype} = 4

Data from a Gamma distribution, looking for changes in the scale parameter :math:b.

:math:\mathrm{ctype} = 5

Data from an exponential distribution, looking for changes in :math:\lambda.

:math:\mathrm{ctype} = 6

Data from a Poisson distribution, looking for changes in :math:\lambda.

**y** : float, array-like, shape :math:\left(n\right)
:math:y, the time series.

If :math:\mathrm{ctype} = 6, that is the data is assumed to come from a Poisson distribution, :math:\mathrm{floor}\left({y+0.5}\right) is used in all calculations.

**beta** : None or float, optional
Note: if this argument is **None** then a default value will be used, determined as follows: if :math:\mathrm{ctype} = 3: :math:{ 2\times \log n }; otherwise: :math:{ \log n }.

:math:\beta, the penalty term.

There are a number of standard ways of setting :math:\beta, including:

SIC or BIC

:math:\beta = p\times \log\left(n\right)

AIC

:math:\beta = 2p

Hannan-Quinn

:math:\beta = 2p\times \log\left(\log\left(n\right)\right)

where :math:p is the number of parameters being treated as estimated in each segment.

This is usually set to :math:2 when :math:\mathrm{ctype} = 3 and :math:1 otherwise.

If no penalty is required then set :math:\beta = 0.

Generally, the smaller the value of :math:\beta the larger the number of suggested change points.

**minss** : int, optional
The minimum distance between two change points, that is :math:\tau_i-\tau_{{i-1}}\geq \mathrm{minss}.

**param** : None or float, array-like, shape :math:\left(1\right), optional
:math:\phi, values for the parameters that will be treated as fixed. If :math:\mathrm{ctype} = 4 then :math:\mathrm{param} must be supplied.

If supplied, then when

:math:\mathrm{ctype} = 1

:math:\mathrm{param}[0] = \sigma, the standard deviation of the normal distribution. If not supplied then :math:\sigma is estimated from the full input data,

:math:\mathrm{ctype} = 2

:math:\mathrm{param}[0] = \mu, the mean of the normal distribution. If not supplied then :math:\mu is estimated from the full input data,

:math:\mathrm{ctype} = 4

:math:\mathrm{param}[0] must hold the shape, :math:a, for the gamma distribution,

otherwise

:math:\mathrm{param} is not referenced.

**Returns**
**ntau** : int
:math:m, the number of change points detected.

**tau** : int, ndarray, shape :math:\left(\mathrm{ntau}\right)
The first :math:m elements of :math:\mathrm{tau} hold the location of the change points. The :math:i\ th segment is defined by :math:y_{\left(\tau_{{i-1}}+1\right)} to :math:y_{\tau_i}, where :math:\tau_0 = 0 and :math:\tau_i = \mathrm{tau}[i-1],1\leq i\leq m.

**sparam** : float, ndarray, shape :math:\left(:\right) or :math:\left(:, :\right)
The estimated values of the distribution parameters in each segment

:math:\mathrm{ctype} = 1, :math:2 or :math:3

:math:\mathrm{sparam}[0,i-1] = \mu_i and :math:\mathrm{sparam}[1,i-1] = \sigma_i for :math:i = 1,2,\ldots,m, where :math:\mu_i and :math:\sigma_i is the mean and standard deviation, respectively, of the values of :math:y in the :math:i\ th segment.

It should be noted that :math:\sigma_i = \sigma_j when :math:\mathrm{ctype} = 1 and :math:\mu_i = \mu_j when :math:\mathrm{ctype} = 2, for all :math:i and :math:j.

:math:\mathrm{ctype} = 4

:math:\mathrm{sparam}[0,i-1] = a_i and :math:\mathrm{sparam}[1,i-1] = b_i for :math:i = 1,2,\ldots,m, where :math:a_i and :math:b_i are the shape and scale parameters, respectively, for the values of :math:y in the :math:i\ th segment. It should be noted that :math:a_i = \mathrm{param}[0] for all :math:i.

:math:\mathrm{ctype} = 5 or :math:6

:math:\mathrm{sparam}[i-1] = \lambda_i for :math:i = 1,2,\ldots,m, where :math:\lambda_i is the mean of the values of :math:y in the :math:i\ th segment.

.. _g13na-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:11)
On entry, :math:\mathrm{ctype} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ctype} = 1, :math:2, :math:3, :math:4, :math:5 or :math:6.

(errno :math:21)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 2.

(errno :math:31)
On entry, :math:\mathrm{ctype} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{y}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ctype} = 4, :math:5 or :math:6 then :math:\mathrm{y}[\textit{i}-1]\geq 0.0, for :math:\textit{i} = 1,2,\ldots,n.

(errno :math:32)
On entry, :math:\mathrm{y}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle, is too large.

(errno :math:51)
On entry, :math:\mathrm{minss} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{minss}\geq 2.

(errno :math:71)
On entry, :math:\mathrm{ctype} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{param}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ctype} = 1 or :math:4 and :math:\mathrm{param} has been supplied, then :math:\mathrm{param}[0] > 0.0.

**Warns**
**NagAlgorithmicWarning**
(errno :math:200)
To avoid overflow some truncation occurred when calculating the cost function, :math:C. All output is returned as normal.

(errno :math:201)
To avoid overflow some truncation occurred when calculating the parameter estimates returned in :math:\mathrm{sparam}. All output is returned as normal.

.. _g13na-py2-py-notes:

**Notes**
Let :math:y_{{1:n}} = \left\{y_j:j = 1,2,\ldots,n\right\} denote a series of data and :math:\tau = \left\{\tau_i:i = 1,2,\ldots,m\right\} denote a set of :math:m ordered (strictly monotonic increasing) indices known as change points with :math:1\leq \tau_i\leq n and :math:\tau_m = n.
For ease of notation we also define :math:\tau_0 = 0.
The :math:m change points, :math:\tau, split the data into :math:m segments, with the :math:i\ th segment being of length :math:n_i and containing :math:y_{{\tau_{{i-1}}+1:\tau_i}}.

Given a cost function, :math:C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right) cp_pelt solves

.. math::
\textit{minimize}_{{m,\tau }}\sum_{{i = 1}}^m\left(C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right)+\beta \right)

where :math:\beta is a penalty term used to control the number of change points.
This minimization is performed using the PELT algorithm of Killick et al. (2012).
The PELT algorithm is guaranteed to return the optimal solution to [equation] <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13naf.html#eqn_g13na_objfun>__ if there exists a constant :math:K such that

.. math::
C\left(y_{{\left(u+1\right):v}}\right)+C\left(y_{{\left(v+1\right):w}}\right)+K\leq C\left(y_{{\left(u+1\right):w}}\right)

for all :math:u < v < w.

cp_pelt supplies four families of cost function.
Each cost function assumes that the series, :math:y, comes from some distribution, :math:D\left(\Theta \right).
The parameter space, :math:\Theta = \left\{\theta,\phi \right\} is subdivided into :math:\theta containing those parameters allowed to differ in each segment and :math:\phi those parameters treated as constant across all segments.
All four cost functions can then be described in terms of the likelihood function, :math:L and are given by:

.. math::
C\left(y_{{\left(\tau_{{i-1}}+1\right):\tau_i}}\right) = -2\log\left({L\left(\hat{\theta }_i,\phi |y_{{\left(\tau_{{i-1}}+1\right):\tau_i}}\right)}\right)

where :math:\hat{\theta }_i is the maximum likelihood estimate of :math:\theta within the :math:i\ th segment.
In all four cases setting :math:K = 0 satisfies equation [equation] <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13naf.html#eqn_g13na_condition>__.
Four distributions are available: Normal, Gamma, Exponential and Poisson.
Letting

.. math::
S_i = \sum_{{j = \tau_{{i-1}}}}^{\tau_i}y_j

the log-likelihoods and cost functions for the four distributions, and the available subdivisions of the parameter space are:

**Normal distribution:** :math:\Theta = \left\{\mu,\sigma^2\right\}

.. math::
-2\log\left(L\right) = \sum_{{i = 1}}^m\sum_{{j = \tau_{{i-1}}}}^{\tau_i}\log\left(2\pi \right)+\log\left(\sigma_i^2\right)+\frac{\left(y_j-\mu_i\right)^2}{\sigma_i^2}

Mean changes: :math:\theta = \left\{\mu \right\}

.. math::
C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right) = \sum_{{j = \tau_{{i-1}}}}^{\tau_i}\frac{\left(y_j-n_i^{-1}S_i\right)^2}{\sigma^2}

Variance changes: :math:\theta = \left\{\sigma^2\right\}

.. math::
C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right) = n_i\left(\log\left(\sum_{{j = \tau_{{i-1}}}}^{\tau_i}\left(y_j-\mu \right)^2\right)-\log\left(n_i\right)\right)

Both mean and variance change: :math:\theta = \left\{\mu,\sigma^2\right\}

.. math::
C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right) = n_i\left(\log\left(\sum_{{j = \tau_{{i-1}}}}^{\tau_i}\left(y_j-n_i^{-1}S_i\right)^2\right)-\log\left(n_i\right)\right)

**Gamma distribution:** :math:\Theta = \left\{a,b\right\}

.. math::
-2\log\left(L\right) = 2\times \sum_{{i = 1}}^m\sum_{{j = \tau_{{i-1}}}}^{\tau_i}\log\left({\Gamma \left(a_i\right)}\right)+a_i\log\left(b_i\right)+\left(1-a_i\right)\log\left(y_j\right)+\frac{y_j}{b_i}

Scale changes: :math:\theta = \left\{b\right\}

.. math::
C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right) = 2an_i\left(\log\left(S_i\right)-\log\left(an_i\right)\right)

**Exponential Distribution:** :math:\Theta = \left\{\lambda \right\}

.. math::
-2\log\left(L\right) = 2\times \sum_{{i = 1}}^m\sum_{{j = \tau_{{i-1}}}}^{\tau_i}\log\left(\lambda_i\right)+\frac{y_j}{\lambda_i}

Mean changes: :math:\theta = \left\{\lambda \right\}

.. math::
C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right) = 2n_i\left(\log\left(S_i\right)-\log\left(n_i\right)\right)

**Poisson distribution:** :math:\Theta = \left\{\lambda \right\}

.. math::
-2\log\left(L\right) = 2\times \sum_{{i = 1}}^m\sum_{{j = \tau_{{i-1}}}}^{\tau_i}\lambda_i-\mathrm{floor}\left({y_j+0.5}\right)\log\left(\lambda_i\right)+\log\left({\Gamma \left(\mathrm{floor}\left({y_j+0.5}\right)+1\right)}\right)

Mean changes: :math:\theta = \left\{\lambda \right\}

.. math::
C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right) = 2S_i\left(\log\left(n_i\right)-\log\left(S_i\right)\right)

when calculating :math:S_i for the Poisson distribution, the sum is calculated for :math:\mathrm{floor}\left({y_i+0.5}\right) rather than :math:y_i.

.. _g13na-py2-py-references:

**References**
Chen, J and Gupta, A K, 2010, Parametric Statistical Change Point Analysis With Applications to Genetics, Medicine and Finance (Second Edition), Birkhäuser

Killick, R, Fearnhead, P and Eckely, I A, 2012, Optimal detection of changepoints with a linear computational cost, Journal of the American Statistical Association (107:500), 1590--1598

--------
:meth:naginterfaces.library.examples.tsa.cp_pelt_ex.main
"""
raise NotImplementedError

[docs]def cp_pelt_user(n, beta, k, costfn, minss=2, data=None):
r"""
cp_pelt_user detects change points in a univariate time series, that is, the time points at which some feature of the data, for example the mean, changes.
Change points are detected using the PELT (Pruned Exact Linear Time) algorithm and a user-supplied cost function.

.. _g13nb-py2-py-doc:

For full information please refer to the NAG Library document for g13nb

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13nbf.html

.. _g13nb-py2-py-parameters:

**Parameters**
**n** : int
:math:n, the length of the time series.

**beta** : float
:math:\beta, the penalty term.

There are a number of standard ways of setting :math:\beta, including:

SIC or BIC

:math:\beta = p\times \log\left(n\right)

AIC

:math:\beta = 2p

Hannan-Quinn

:math:\beta = 2p\times \log\left(\log\left(n\right)\right)

where :math:p is the number of parameters being treated as estimated in each segment.

The value of :math:p will depend on the cost function being used.

If no penalty is required then set :math:\beta = 0.

Generally, the smaller the value of :math:\beta the larger the number of suggested change points.

**k** : float
:math:K, the constant value that satisfies equation [equation] <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13nbf.html#eqn_g13nb_condition>__. If :math:K exists, it is unlikely to be unique in such cases, it is recommened that the largest value of :math:K, that satisfies equation [equation] <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13nbf.html#eqn_g13nb_condition>__, is chosen. No check is made that :math:K is the correct value for the supplied cost function.

**costfn** : callable c = costfn(ts, r, data=None)
The cost function, :math:C. :math:\mathrm{costfn} must calculate a vector of costs for a number of segments.

**Parameters**
**ts** : int
A reference time point.

**r** : int, ndarray, shape :math:\left(\textit{nr}\right)
Time points which, along with :math:\mathrm{ts}, define the segments being considered, :math:0\leq \mathrm{r}[i-1]\leq n for :math:i = 1,2,\ldots \textit{nr}.

**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.

**Returns**
**c** : float, array-like, shape :math:\left(\textit{nr}\right)
On exit, the cost function, :math:C.

**minss** : int, optional
The minimum distance between two change points, that is :math:\tau_i-\tau_{{i-1}}\geq \mathrm{minss}.

**data** : arbitrary, optional
User-communication data for callback functions.

**Returns**
**ntau** : int
:math:m, the number of change points detected.

**tau** : int, ndarray, shape :math:\left(\mathrm{ntau}\right)
The first :math:m elements of :math:\mathrm{tau} hold the location of the change points. The :math:i\ th segment is defined by :math:y_{\left(\tau_{{i-1}}+1\right)} to :math:y_{\tau_i}, where :math:\tau_0 = 0 and :math:\tau_i = \mathrm{tau}[i-1],1\leq i\leq m.

.. _g13nb-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:11)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n}\geq 2.

(errno :math:31)
On entry, :math:\mathrm{minss} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{minss}\geq 2.

**Warns**
**NagCallbackTerminateWarning**
(errno :math:51)
User requested termination.

.. _g13nb-py2-py-notes:

**Notes**
Let :math:y_{{1:n}} = \left\{y_j:j = 1,2,\ldots,n\right\} denote a series of data and :math:\tau = \left\{\tau_i:i = 1,2,\ldots,m\right\} denote a set of :math:m ordered (strictly monotonic increasing) indices known as change points with :math:1\leq \tau_i\leq n and :math:\tau_m = n.
For ease of notation we also define :math:\tau_0 = 0.
The :math:m change points, :math:\tau, split the data into :math:m segments, with the :math:i\ th segment being of length :math:n_i and containing :math:y_{{\tau_{{i-1}}+1:\tau_i}}.

Given a user-supplied cost function, :math:C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right) cp_pelt_user solves

.. math::
\textit{minimize}_{{m,\tau }}\sum_{{i = 1}}^m\left(C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right)+\beta \right)

where :math:\beta is a penalty term used to control the number of change points.
This minimization is performed using the PELT algorithm of Killick et al. (2012).
The PELT algorithm is guaranteed to return the optimal solution to [equation] <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13nbf.html#eqn_g13nb_objfun>__ if there exists a constant :math:K such that

.. math::
C\left(y_{{\left(u+1\right):v}}\right)+C\left(y_{{\left(v+1\right):w}}\right)+K\leq C\left(y_{{\left(u+1\right):w}}\right)

for all :math:u < v < w

.. _g13nb-py2-py-references:

**References**
Chen, J and Gupta, A K, 2010, Parametric Statistical Change Point Analysis With Applications to Genetics, Medicine and Finance (Second Edition), Birkhäuser

Killick, R, Fearnhead, P and Eckely, I A, 2012, Optimal detection of changepoints with a linear computational cost, Journal of the American Statistical Association (107:500), 1590--1598
"""
raise NotImplementedError

[docs]def cp_binary(ctype, y, beta=None, minss=2, param=None, mdepth=0):
r"""
cp_binary detects change points in a univariate time series, that is, the time points at which some feature of the data, for example the mean, changes.
Change points are detected using binary segmentation using one of a provided set of cost functions.

.. _g13nd-py2-py-doc:

For full information please refer to the NAG Library document for g13nd

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ndf.html

.. _g13nd-py2-py-parameters:

**Parameters**
**ctype** : int
A flag indicating the assumed distribution of the data and the type of change point being looked for.

:math:\mathrm{ctype} = 1

Data from a Normal distribution, looking for changes in the mean, :math:\mu.

:math:\mathrm{ctype} = 2

Data from a Normal distribution, looking for changes in the standard deviation :math:\sigma.

:math:\mathrm{ctype} = 3

Data from a Normal distribution, looking for changes in the mean, :math:\mu and standard deviation :math:\sigma.

:math:\mathrm{ctype} = 4

Data from a Gamma distribution, looking for changes in the scale parameter :math:b.

:math:\mathrm{ctype} = 5

Data from an exponential distribution, looking for changes in :math:\lambda.

:math:\mathrm{ctype} = 6

Data from a Poisson distribution, looking for changes in :math:\lambda.

**y** : float, array-like, shape :math:\left(n\right)
:math:y, the time series.

If :math:\mathrm{ctype} = 6, that is the data is assumed to come from a Poisson distribution, :math:\mathrm{floor}\left({y+0.5}\right) is used in all calculations.

**beta** : None or float, optional
Note: if this argument is **None** then a default value will be used, determined as follows: if :math:\mathrm{ctype} = 3: :math:{ 2\times \log n }; otherwise: :math:{ \log n }.

:math:\beta, the penalty term.

There are a number of standard ways of setting :math:\beta, including:

SIC or BIC

:math:\beta = p\times \log\left(n\right)

AIC

:math:\beta = 2p

Hannan-Quinn

:math:\beta = 2p\times \log\left(\log\left(n\right)\right)

where :math:p is the number of parameters being treated as estimated in each segment.

This is usually set to :math:2 when :math:\mathrm{ctype} = 3 and :math:1 otherwise.

If no penalty is required then set :math:\beta = 0.

Generally, the smaller the value of :math:\beta the larger the number of suggested change points.

**minss** : int, optional
The minimum distance between two change points, that is :math:\tau_i-\tau_{{i-1}}\geq \mathrm{minss}.

**param** : None or float, array-like, shape :math:\left(1\right), optional
:math:\phi, values for the parameters that will be treated as fixed. If :math:\mathrm{ctype} = 4 then :math:\mathrm{param} must be supplied.

If supplied, then when

:math:\mathrm{ctype} = 1

:math:\mathrm{param}[0] = \sigma, the standard deviation of the normal distribution. If not supplied then :math:\sigma is estimated from the full input data,

:math:\mathrm{ctype} = 2

:math:\mathrm{param}[0] = \mu, the mean of the normal distribution. If not supplied then :math:\mu is estimated from the full input data,

:math:\mathrm{ctype} = 4

:math:\mathrm{param}[0] must hold the shape, :math:a, for the gamma distribution,

otherwise

:math:\mathrm{param} is not referenced.

**mdepth** : int, optional
:math:K, the maximum depth for the iterative process, which in turn puts an upper limit on the number of change points with :math:m\leq 2^K.

If :math:K\leq 0 then no limit is put on the depth of the iterative process and no upper limit is put on the number of change points, other than that inherent in the length of the series and the value of :math:\mathrm{minss}.

**Returns**
**ntau** : int
:math:m, the number of change points detected.

**tau** : int, ndarray, shape :math:\left(\mathrm{ntau}\right)
The first :math:m elements of :math:\mathrm{tau} hold the location of the change points. The :math:i\ th segment is defined by :math:y_{\left(\tau_{{i-1}}+1\right)} to :math:y_{\tau_i}, where :math:\tau_0 = 0 and :math:\tau_i = \mathrm{tau}[i-1],1\leq i\leq m.

**sparam** : float, ndarray, shape :math:\left(:\right) or :math:\left(:, :\right)
The estimated values of the distribution parameters in each segment

:math:\mathrm{ctype} = 1, :math:2 or :math:3

:math:\mathrm{sparam}[0,i-1] = \mu_i and :math:\mathrm{sparam}[1,i-1] = \sigma_i for :math:i = 1,2,\ldots,m, where :math:\mu_i and :math:\sigma_i is the mean and standard deviation, respectively, of the values of :math:y in the :math:i\ th segment.

It should be noted that :math:\sigma_i = \sigma_j when :math:\mathrm{ctype} = 1 and :math:\mu_i = \mu_j when :math:\mathrm{ctype} = 2, for all :math:i and :math:j.

:math:\mathrm{ctype} = 4

:math:\mathrm{sparam}[0,i-1] = a_i and :math:\mathrm{sparam}[1,i-1] = b_i for :math:i = 1,2,\ldots,m, where :math:a_i and :math:b_i are the shape and scale parameters, respectively, for the values of :math:y in the :math:i\ th segment. It should be noted that :math:a_i = \mathrm{param}[0] for all :math:i.

:math:\mathrm{ctype} = 5 or :math:6

:math:\mathrm{sparam}[i-1] = \lambda_i for :math:i = 1,2,\ldots,m, where :math:\lambda_i is the mean of the values of :math:y in the :math:i\ th segment.

.. _g13nd-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:11)
On entry, :math:\mathrm{ctype} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ctype} = 1, :math:2, :math:3, :math:4, :math:5 or :math:6.

(errno :math:21)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 2.

(errno :math:31)
On entry, :math:\mathrm{ctype} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{y}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ctype} = 4, :math:5 or :math:6 then :math:\mathrm{y}[\textit{i}-1]\geq 0.0, for :math:\textit{i} = 1,2,\ldots,n.

(errno :math:32)
On entry, :math:\mathrm{y}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle, is too large.

(errno :math:51)
On entry, :math:\mathrm{minss} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{minss}\geq 2.

(errno :math:71)
On entry, :math:\mathrm{ctype} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{param}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{ctype} = 1 or :math:4 and :math:\mathrm{param} has been supplied, then :math:\mathrm{param}[0] > 0.0.

**Warns**
**NagAlgorithmicWarning**
(errno :math:200)
To avoid overflow some truncation occurred when calculating the cost function, :math:C. All output is returned as normal.

(errno :math:201)
To avoid overflow some truncation occurred when calculating the parameter estimates returned in :math:\mathrm{sparam}. All output is returned as normal.

.. _g13nd-py2-py-notes:

**Notes**
Let :math:y_{{1:n}} = \left\{y_j:j = 1,2,\ldots,n\right\} denote a series of data and :math:\tau = \left\{\tau_i:i = 1,2,\ldots,m\right\} denote a set of :math:m ordered (strictly monotonic increasing) indices known as change points, with :math:1\leq \tau_i\leq n and :math:\tau_m = n.
For ease of notation we also define :math:\tau_0 = 0.
The :math:m change points, :math:\tau, split the data into :math:m segments, with the :math:i\ th segment being of length :math:n_i and containing :math:y_{{\tau_{{i-1}}+1:\tau_i}}.

Given a cost function, :math:C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right), cp_binary gives an approximate solution to

.. math::
\textit{minimize}_{{m,\tau }}\sum_{{i = 1}}^m\left(C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right)+\beta \right)

where :math:\beta is a penalty term used to control the number of change points.
The solution is obtained in an iterative manner as follows:

(1) Set :math:u = 1, :math:w = n and :math:k = 0

(#) Set :math:k = k+1. If :math:k > K, where :math:K is a user-supplied control parameter, then terminate the process for this segment.

(#) Find :math:v that minimizes

.. math::
C\left(y_{{u:v}}\right)+C\left(y_{{v+1:w}}\right)

(#) Test

.. math::
C\left(y_{{u:v}}\right)+C\left(y_{{v+1:w}}\right)+\beta < C\left(y_{{u:w}}\right)

(#) If inequality [equation] <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ndf.html#eqn_g13nd_test>__ is false then the process is terminated for this segment.

(#) If inequality [equation] <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13ndf.html#eqn_g13nd_test>__ is true, then :math:v is added to the set of change points, and the segment is split into two subsegments, :math:y_{{u:v}} and :math:y_{{v+1:w}}. The whole process is repeated from step 2 independently on each subsegment, with the relevant changes to the definition of :math:u and :math:w (i.e., :math:w is set to :math:v when processing the left-hand subsegment and :math:u is set to :math:v+1 when processing the right-hand subsegment.

The change points are ordered to give :math:\tau.

cp_binary supplies four families of cost function.
Each cost function assumes that the series, :math:y, comes from some distribution, :math:D\left(\Theta \right).
The parameter space, :math:\Theta = \left\{\theta,\phi \right\} is subdivided into :math:\theta containing those parameters allowed to differ in each segment and :math:\phi those parameters treated as constant across all segments.
All four cost functions can then be described in terms of the likelihood function, :math:L and are given by:

.. math::
C\left(y_{{\left(\tau_{{i-1}}+1\right):\tau_i}}\right) = -2\log\left({L\left(\hat{\theta }_i,\phi |y_{{\left(\tau_{{i-1}}+1\right):\tau_i}}\right)}\right)

where the :math:\hat{\theta }_i is the maximum likelihood estimate of :math:\theta within the :math:i\ th segment.
Four distributions are available; Normal, Gamma, Exponential and Poisson distributions.
Letting

.. math::
S_i = \sum_{{j = \tau_{{i-1}}}}^{\tau_i}y_j

the log-likelihoods and cost functions for the four distributions, and the available subdivisions of the parameter space are:

**Normal distribution:** :math:\Theta = \left\{\mu,\sigma^2\right\}

.. math::
-2\log\left(L\right) = \sum_{{i = 1}}^m\sum_{{j = \tau_{{i-1}}}}^{\tau_i}\log\left(2\pi \right)+\log\left(\sigma_i^2\right)+\frac{\left(y_j-\mu_i\right)^2}{\sigma_i^2}

Mean changes: :math:\theta = \left\{\mu \right\}

.. math::
C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right) = \sum_{{j = \tau_{{i-1}}}}^{\tau_i}\frac{\left(y_j-n_i^{-1}S_i\right)^2}{\sigma^2}

Variance changes: :math:\theta = \left\{\sigma^2\right\}

.. math::
C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right) = n_i\left(\log\left(\sum_{{j = \tau_{{i-1}}}}^{\tau_i}\left(y_j-\mu \right)^2\right)-\log\left(n_i\right)\right)

Both mean and variance change: :math:\theta = \left\{\mu,\sigma^2\right\}

.. math::
C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right) = n_i\left(\log\left(\sum_{{j = \tau_{{i-1}}}}^{\tau_i}\left(y_j-n_i^{-1}S_i\right)^2\right)-\log\left(n_i\right)\right)

**Gamma distribution:** :math:\Theta = \left\{a,b\right\}

.. math::
-2\log\left(L\right) = 2\times \sum_{{i = 1}}^m\sum_{{j = \tau_{{i-1}}}}^{\tau_i}\log\left({\Gamma \left(a_i\right)}\right)+a_i\log\left(b_i\right)+\left(1-a_i\right)\log\left(y_j\right)+\frac{y_j}{b_i}

Scale changes: :math:\theta = \left\{b\right\}

.. math::
C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right) = 2an_i\left(\log\left(S_i\right)-\log\left(an_i\right)\right)

**Exponential Distribution:** :math:\Theta = \left\{\lambda \right\}

.. math::
-2\log\left(L\right) = 2\times \sum_{{i = 1}}^m\sum_{{j = \tau_{{i-1}}}}^{\tau_i}\log\left(\lambda_i\right)+\frac{y_j}{\lambda_i}

Mean changes: :math:\theta = \left\{\lambda \right\}

.. math::
C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right) = 2n_i\left(\log\left(S_i\right)-\log\left(n_i\right)\right)

**Poisson distribution:** :math:\Theta = \left\{\lambda \right\}

.. math::
-2\log\left(L\right) = 2\times \sum_{{i = 1}}^m\sum_{{j = \tau_{{i-1}}}}^{\tau_i}\lambda_i-\mathrm{floor}\left({y_j+0.5}\right)\log\left(\lambda_i\right)+\log\left({\Gamma \left(\mathrm{floor}\left({y_j+0.5}\right)+1\right)}\right)

Mean changes: :math:\theta = \left\{\lambda \right\}

.. math::
C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right) = 2S_i\left(\log\left(n_i\right)-\log\left(S_i\right)\right)

when calculating :math:S_i for the Poisson distribution, the sum is calculated for :math:\mathrm{floor}\left({y_i+0.5}\right) rather than :math:y_i.

.. _g13nd-py2-py-references:

**References**
Chen, J and Gupta, A K, 2010, Parametric Statistical Change Point Analysis With Applications to Genetics, Medicine and Finance (Second Edition), Birkhäuser

West, D H D, 1979, Updating mean and variance estimates: An improved method, Comm. ACM (22), 532--555
"""
raise NotImplementedError

[docs]def cp_binary_user(n, beta, chgpfn, minss=2, mdepth=0, data=None):
r"""
cp_binary_user detects change points in a univariate time series, that is, the time points at which some feature of the data, for example the mean, changes.
Change points are detected using binary segmentation for a user-supplied cost function.

.. _g13ne-py2-py-doc:

For full information please refer to the NAG Library document for g13ne

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13nef.html

.. _g13ne-py2-py-parameters:

**Parameters**
**n** : int
:math:n, the length of the time series.

**beta** : float
:math:\beta, the penalty term.

There are a number of standard ways of setting :math:\beta, including:

SIC or BIC

:math:\beta = p\times \log\left(n\right).

AIC

:math:\beta = 2p.

Hannan-Quinn

:math:\beta = 2p\times \log\left(\log\left(n\right)\right).

where :math:p is the number of parameters being treated as estimated in each segment.

The value of :math:p will depend on the cost function being used.

If no penalty is required then set :math:\beta = 0.

Generally, the smaller the value of :math:\beta the larger the number of suggested change points.

**chgpfn** : callable (v, cost, info) = chgpfn(side, u, w, minss, info, data=None)
:math:\mathrm{chgpfn} must calculate a proposed change point, and the associated costs, within a specified segment.

**Parameters**
**side** : int
Flag indicating what :math:\mathrm{chgpfn} must calculate and at which point of the Binary Segmentation it has been called.

:math:\mathrm{side} = -1

only :math:C\left(y_{{u:w}}\right) need be calculated and returned in :math:\mathrm{cost}[0], neither :math:\mathrm{v} nor the other elements of :math:\mathrm{cost} need be set. In this case, :math:u = 1 and :math:w = n.

:math:\mathrm{side} = 0

all elements of :math:\mathrm{cost} and :math:\mathrm{v} must be set. In this case, :math:u = 1 and :math:w = n.

:math:\mathrm{side} = 1

the segment, :math:y_{{u:w}}, is a left-hand side subsegment from a previous iteration of the Binary Segmentation algorithm. All elements of :math:\mathrm{cost} and :math:\mathrm{v} must be set.

:math:\mathrm{side} = 2

the segment, :math:y_{{u:w}}, is a right-hand side subsegment from a previous iteration of the Binary Segmentation algorithm. All elements of :math:\mathrm{cost} and :math:\mathrm{v} must be set.

The distinction between :math:\mathrm{side} = 1 or :math:2 may allow for :math:\mathrm{chgpfn} to be implemented in a more efficient manner.

The first call to :math:\mathrm{chgpfn} will always have :math:\mathrm{side} = -1 and the second call will always have :math:\mathrm{side} = 0.

All subsequent calls will be made with :math:\mathrm{side} = 1 or :math:2.

**u** : int
:math:u, the start of the segment of interest.

**w** : int
:math:w, the end of the segment of interest.

**minss** : int
The minimum distance between two change points, as passed to cp_binary_user.

**info** : int
:math:\mathrm{info} = 0.

**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.

**Returns**
**v** : int
If :math:\mathrm{side} = -1 then :math:\mathrm{v} need not be set.

if :math:\mathrm{side} \neq -1 then :math:v, the proposed change point.

That is, the value which minimizes

.. math::
\textit{minimize}_vC\left(y_{{u:v}}\right)+C\left(y_{{v+1:w}}\right)

for :math:v = u+\mathrm{minss}-1 to :math:w-\mathrm{minss}.

**cost** : float, array-like, shape :math:\left(3\right)
Costs associated with the proposed change point, :math:v.

If :math:\mathrm{side} = -1 then :math:\mathrm{cost}[0] = C\left(y_{{u:w}}\right) and the remaining two elements of :math:\mathrm{cost} need not be set.

If :math:\mathrm{side} \neq -1 then

:math:\mathrm{cost}[0] = C\left(y_{{u:v}}\right)+C\left(y_{{v+1:w}}\right).

:math:\mathrm{cost}[1] = C\left(y_{{u:v}}\right).

:math:\mathrm{cost}[2] = C\left(y_{{v+1:w}}\right).

**info** : int
In most circumstances :math:\mathrm{info} should remain unchanged.

If :math:\mathrm{info} is set to a strictly positive value then cp_binary_user terminates with :math:\mathrm{errno} = 51.

If :math:\mathrm{info} is set to a strictly negative value the current segment is skipped (i.e., no change points are considered in this segment) and cp_binary_user continues as normal.

If :math:\mathrm{info} was set to a strictly negative value at any point and no other errors occur then cp_binary_user will terminate with :math:\mathrm{errno} = 52.

**minss** : int, optional
The minimum distance between two change points, that is :math:\tau_i-\tau_{{i-1}}\geq \mathrm{minss}.

**mdepth** : int, optional
:math:K, the maximum depth for the iterative process, which in turn puts an upper limit on the number of change points with :math:m\leq 2^K.

If :math:K\leq 0 then no limit is put on the depth of the iterative process and no upper limit is put on the number of change points, other than that inherent in the length of the series and the value of :math:\mathrm{minss}.

**data** : arbitrary, optional
User-communication data for callback functions.

**Returns**
**ntau** : int
:math:m, the number of change points detected.

**tau** : int, ndarray, shape :math:\left(\mathrm{ntau}\right)
The first :math:m elements of :math:\mathrm{tau} hold the location of the change points. The :math:i\ th segment is defined by :math:y_{\left(\tau_{{i-1}}+1\right)} to :math:y_{\tau_i}, where :math:\tau_0 = 0 and :math:\tau_i = \mathrm{tau}[i-1],1\leq i\leq m.

.. _g13ne-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:11)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n}\geq 2.

(errno :math:31)
On entry, :math:\mathrm{minss} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{minss}\geq 2.

(errno :math:51)
User requested termination by setting :math:\mathrm{info} = \langle\mathit{\boldsymbol{value}}\rangle.

**Warns**
**NagAlgorithmicWarning**
(errno :math:52)
User requested a segment to be skipped by setting :math:\mathrm{info} = \langle\mathit{\boldsymbol{value}}\rangle.

.. _g13ne-py2-py-notes:

**Notes**
Let :math:y_{{1:n}} = \left\{y_j:j = 1,2,\ldots,n\right\} denote a series of data and :math:\tau = \left\{\tau_i:i = 1,2,\ldots,m\right\} denote a set of :math:m ordered (strictly monotonic increasing) indices known as change points with :math:1\leq \tau_i\leq n and :math:\tau_m = n.
For ease of notation we also define :math:\tau_0 = 0.
The :math:m change points, :math:\tau, split the data into :math:m segments, with the :math:i\ th segment being of length :math:n_i and containing :math:y_{{\tau_{{i-1}}+1:\tau_i}}.

Given a cost function, :math:C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right), cp_binary_user gives an approximate solution to

.. math::
\textit{minimize}_{{m,\tau }}\sum_{{i = 1}}^m\left(C\left(y_{{\tau_{{i-1}}+1:\tau_i}}\right)+\beta \right)

where :math:\beta is a penalty term used to control the number of change points.
The solution is obtained in an iterative manner as follows:

(1) Set :math:u = 1, :math:w = n and :math:k = 0

(#) Set :math:k = k+1. If :math:k > K, where :math:K is a user-supplied control parameter, then terminate the process for this segment.

(#) Find :math:v that minimizes

.. math::
C\left(y_{{u:v}}\right)+C\left(y_{{v+1:w}}\right)

(#) Test

.. math::
C\left(y_{{u:v}}\right)+C\left(y_{{v+1:w}}\right)+\beta < C\left(y_{{u:w}}\right)

(#) If inequality [equation] <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13nef.html#eqn_g13nc_test>__ is false then the process is terminated for this segment.

(#) If inequality [equation] <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/g13/g13nef.html#eqn_g13nc_test>__ is true, then :math:v is added to the set of change points, and the segment is split into two subsegments, :math:y_{{u:v}} and :math:y_{{v+1:w}}. The whole process is repeated from step 2 independently on each subsegment, with the relevant changes to the definition of :math:u and :math:w (i.e., :math:w is set to :math:v when processing the left-hand subsegment and :math:u is set to :math:v+1 when processing the right-hand subsegment.

The change points are ordered to give :math:\tau.

.. _g13ne-py2-py-references:

**References**
Chen, J and Gupta, A K, 2010, Parametric Statistical Change Point Analysis With Applications to Genetics, Medicine and Finance (Second Edition), Birkhäuser
"""
raise NotImplementedError