# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 30.2 `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.
See Also
--------
``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://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/g13/g13intro.html
"""
# NAG Copyright 2017-2024.
[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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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.
.. _g13ad-py2-py-doc:
For full information please refer to the NAG Library document for g13ad
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/g13/g13adf.html
.. _g13ad-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.
**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}`.|
+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. _g13ad-py2-py-errors:
**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.
.. _g13ad-py2-py-notes:
**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`.
.. _g13ad-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_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://support.nag.com/numeric/nl/nagdoc_30.2/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::
\textit{df} = N-p-q-P-Q\quad \text{ }\quad \left(-1\text{ if }c\text{ is estimated}\right)\text{.}
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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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`
Additive Holt--Winters.
: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.
**ad** : float
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}
Additive Holt--Winters Smoothing
.. 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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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
See Also
--------
: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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/g13/g13baf.html#eqn1>`__, `(2) <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/g13/g13baf.html#eqn1>`__ and `(3) <https://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/g13/g13baf.html#eqn4>`__ and `(5) <https://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/g13/g13baf.html#eqn1>`__, `(2) <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/g13/g13baf.html#eqn1>`__ and `(3) <https://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/g13/g13baf.html#eqn4>`__ and `(5) <https://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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::
r_{{xy}}\left(l\right)\text{, }\quad l = 0,1,\ldots,L
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 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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/g13/g13dbf.html#eqn1>`__ becomes :math:`M_1 = C^\mathrm{T}_1` and neither `(2) <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/g13/g13dbf.html#eqn2>`__ and `(3) <https://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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`.
In addition the statistic
.. 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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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)
See Also
--------
: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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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
See Also
--------
: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://support.nag.com/numeric/nl/nagdoc_30.2/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
See Also
--------
: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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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::
\mu = e^{{-\alpha }}\quad \text{ and }\quad \alpha = \frac{{t_i-t_{{i-1}}}}{\tau }\text{.}
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
See Also
--------
: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://support.nag.com/numeric/nl/nagdoc_30.2/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::
\mu = e^{{-\alpha }}\quad \text{ and }\quad \alpha = \frac{{t_i-t_{{i-1}}}}{\tau }\text{.}
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://support.nag.com/numeric/nl/nagdoc_30.2/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::
\mu = e^{{-\alpha }}\quad \text{ and }\quad \alpha = \frac{{t_i-t_{{i-1}}}}{\tilde{\tau }}\text{.}
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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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
See Also
--------
: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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/g13/g13ndf.html#eqn_g13nd_test>`__ is false then the process is terminated for this segment.
(#) If inequality `[equation] <https://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/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://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/g13/g13nef.html#eqn_g13nc_test>`__ is false then the process is terminated for this segment.
(#) If inequality `[equation] <https://support.nag.com/numeric/nl/nagdoc_30.2/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
