Tools¶

dismalpy.ssm.tools.companion_matrix(polynomial)[source]¶

Create a companion matrix

Parameters:

polynomial : array_like or list If an iterable, interpreted as the coefficients of the polynomial from which to form the companion matrix. Polynomial coefficients are in order of increasing degree, and may be either scalars (as in an AR(p) model) or coefficient matrices (as in a VAR(p) model). If an integer, it is interpereted as the size of a companion matrix of a scalar polynomial, where the polynomial coefficients are initialized to zeros. If a matrix polynomial is passed, \(C_0\) may be set to the scalar value 1 to indicate an identity matrix (doing so will improve the speed of the companion matrix creation).

Returns:

companion_matrix : array

Notes

Given coefficients of a lag polynomial of the form:

\[c(L) = c_0 + c_1 L + \dots + c_p L^p\]

returns a matrix of the form

\[\begin{split}\begin{bmatrix} \phi_1 & 1 & 0 & \cdots & 0 \\ \phi_2 & 0 & 1 & & 0 \\ \vdots & & & \ddots & 0 \\ & & & & 1 \\ \phi_n & 0 & 0 & \cdots & 0 \\ \end{bmatrix}\end{split}\]

where some or all of the \(\phi_i\) may be non-zero (if polynomial is None, then all are equal to zero).

If the coefficients provided are scalars \((c_0, c_1, \dots, c_p)\), then the companion matrix is an \(n \times n\) matrix formed with the elements in the first column defined as \(\phi_i = -\frac{c_i}{c_0}, i \in 1, \dots, p\).

If the coefficients provided are matrices \((C_0, C_1, \dots, C_p)\), each of shape \((m, m)\), then the companion matrix is an \(nm \times nm\) matrix formed with the elements in the first column defined as \(\phi_i = -C_0^{-1} C_i', i \in 1, \dots, p\).

It is important to understand the expected signs of the coefficients. A typical AR(p) model is written as:

\[y_t = a_1 y_{t-1} + \dots + a_p y_{t-p} + \varepsilon_t\]

This can be rewritten as:

\[\begin{split}(1 - a_1 L - \dots - a_p L^p )y_t = \varepsilon_t \\ (1 + c_1 L + \dots + c_p L^p )y_t = \varepsilon_t \\ c(L) y_t = \varepsilon_t\end{split}\]

The coefficients from this form are defined to be \(c_i = - a_i\), and it is the \(c_i\) coefficients that this function expects to be provided.

dismalpy.ssm.tools.diff(series, k_diff=1, k_seasonal_diff=None, k_seasons=1)[source]¶

Difference a series simply and/or seasonally along the zero-th axis.

Given a series (denoted \(y_t\)), performs the differencing operation

\[\Delta^d \Delta_s^D y_t\]

where \(d =\) diff, \(s =\) k_seasons, \(D =\) seasonal_diff, and \(\Delta\) is the difference operator.

Parameters:	series : array_like The series to be differenced. diff : int, optional The number of simple differences to perform. Default is 1. seasonal_diff : int or None, optional The number of seasonal differences to perform. Default is no seasonal differencing. k_seasons : int, optional The seasonal lag. Default is 1. Unused if there is no seasonal differencing.
Returns:	differenced : array The differenced array.

dismalpy.ssm.tools.is_invertible(polynomial, threshold=1.0)[source]¶

Determine if a polynomial is invertible.

Requires all roots of the polynomial lie inside the unit circle.

Parameters:

polynomial : array_like or tuple, list Coefficients of a polynomial, in order of increasing degree. For example, polynomial=[1, -0.5] corresponds to the polynomial \(1 - 0.5x\) which has root \(2\). If it is a matrix polynomial (in which case the coefficients are coefficient matrices), a tuple or list of matrices should be passed. threshold : number Allowed threshold for is_invertible to return True. Default is 1.

See also

dismalpy.ssm.tools.companion_matrix

Notes

If the coefficients provided are scalars \((c_0, c_1, \dots, c_n)\), then the corresponding polynomial is \(c_0 + c_1 L + \dots + c_n L^n\).

If the coefficients provided are matrices \((C_0, C_1, \dots, C_n)\), then the corresponding polynomial is \(C_0 + C_1 L + \dots + C_n L^n\).

There are three equivalent methods of determining if the polynomial represented by the coefficients is invertible:

The first method factorizes the polynomial into:

\[\begin{split}C(L) & = c_0 + c_1 L + \dots + c_n L^n \\ & = constant (1 - \lambda_1 L) (1 - \lambda_2 L) \dots (1 - \lambda_n L)\end{split}\]

In order for \(C(L)\) to be invertible, it must be that each factor \((1 - \lambda_i L)\) is invertible; the condition is then that \(|\lambda_i| < 1\), where \(\lambda_i\) is a root of the polynomial.

The second method factorizes the polynomial into:

\[\begin{split}C(L) & = c_0 + c_1 L + \dots + c_n L^n \\ & = constant (L - \zeta_1) (L - \zeta_2) \dots (L - \zeta_3)\end{split}\]

The condition is now \(|\zeta_i| > 1\), where \(\zeta_i\) is a root of the polynomial with reversed coefficients and \(\lambda_i = \frac{1}{\zeta_i}\).

Finally, a companion matrix can be formed using the coefficients of the polynomial. Then the eigenvalues of that matrix give the roots of the polynomial. This last method is the one actually used.

Examples

>>> dp.ssm.is_invertible([0.5])
True
>>> dp.ssm.is_invertible([1])
False

dismalpy.ssm.tools.constrain_stationary_univariate(unconstrained)[source]¶

Transform unconstrained parameters used by the optimizer to constrained parameters used in likelihood evaluation

Parameters:	unconstrained : array Unconstrained parameters used by the optimizer, to be transformed to stationary coefficients of, e.g., an autoregressive or moving average component.
Returns:	constrained : array Constrained parameters of, e.g., an autoregressive or moving average component, to be transformed to arbitrary parameters used by the optimizer.

References

[R8]	Monahan, John F. 1984. “A Note on Enforcing Stationarity in Autoregressive-moving Average Models.” Biometrika 71 (2) (August 1): 403-404.

dismalpy.ssm.tools.unconstrain_stationary_univariate(constrained)[source]¶

Transform constrained parameters used in likelihood evaluation to unconstrained parameters used by the optimizer

Parameters:	constrained : array Constrained parameters of, e.g., an autoregressive or moving average component, to be transformed to arbitrary parameters used by the optimizer.
Returns:	unconstrained : array Unconstrained parameters used by the optimizer, to be transformed to stationary coefficients of, e.g., an autoregressive or moving average component.

References

[R9]	Monahan, John F. 1984. “A Note on Enforcing Stationarity in Autoregressive-moving Average Models.” Biometrika 71 (2) (August 1): 403-404.

dismalpy.ssm.tools.constrain_stationary_multivariate(unconstrained, variance, transform_variance=False, prefix=None)[source]¶

Transform unconstrained parameters used by the optimizer to constrained parameters used in likelihood evaluation for a vector autoregression.

Parameters:

unconstrained : array or list Arbitrary matrices to be transformed to stationary coefficient matrices of the VAR. If a list, should be a list of length order, where each element is an array sized k_endog x k_endog. If an array, should be the matrices horizontally concatenated and sized k_endog x k_endog * order. error_variance : array The variance / covariance matrix of the error term. Should be sized k_endog x k_endog. This is used as input in the algorithm even if is not transformed by it (when transform_variance is False). The error term variance is required input when transformation is used either to force an autoregressive component to be stationary or to force a moving average component to be invertible. transform_variance : boolean, optional Whether or not to transform the error variance term. This option is not typically used, and the default is False. prefix : {‘s’,’d’,’c’,’z’}, optional The appropriate BLAS prefix to use for the passed datatypes. Only use if absolutely sure that the prefix is correct or an error will result.

Returns:

constrained : array or list Transformed coefficient matrices leading to a stationary VAR representation. Will match the type of the passed unconstrained variable (so if a list was passed, a list will be returned).

Notes

In the notation of [R10], the arguments (variance, unconstrained) are written as \((\Sigma, A_1, \dots, A_p)\), where \(p\) is the order of the vector autoregression, and is here determined by the length of the unconstrained argument.

There are two steps in the constraining algorithm.

First, \((A_1, \dots, A_p)\) are transformed into \((P_1, \dots, P_p)\) via Lemma 2.2 of [R10].

Second, \((\Sigma, P_1, \dots, P_p)\) are transformed into \((\Sigma, \phi_1, \dots, \phi_p)\) via Lemmas 2.1 and 2.3 of [R10].

If transform_variance=True, then only Lemma 2.1 is applied in the second step.

While this function can be used even in the univariate case, it is much slower, so in that case constrain_stationary_univariate is preferred.

References

[R10]

(1, 2, 3, 4) Ansley, Craig F., and Robert Kohn. 1986. “A Note on Reparameterizing a Vector Autoregressive Moving Average Model to Enforce Stationarity.” Journal of Statistical Computation and Simulation 24 (2): 99-106.

[R11]

Ansley, Craig F, and Paul Newbold. 1979. “Multivariate Partial Autocorrelations.” In Proceedings of the Business and Economic Statistics Section, 349-53. American Statistical Association

dismalpy.ssm.tools.unconstrain_stationary_multivariate(constrained, error_variance)[source]¶

Transform constrained parameters used in likelihood evaluation to unconstrained parameters used by the optimizer

Parameters:

constrained : array or list Constrained parameters of, e.g., an autoregressive or moving average component, to be transformed to arbitrary parameters used by the optimizer. If a list, should be a list of length order, where each element is an array sized k_endog x k_endog. If an array, should be the coefficient matrices horizontally concatenated and sized k_endog x k_endog * order. error_variance : array The variance / covariance matrix of the error term. Should be sized k_endog x k_endog. This is used as input in the algorithm even if is not transformed by it (when transform_variance is False).

Returns:

unconstrained : array Unconstrained parameters used by the optimizer, to be transformed to stationary coefficients of, e.g., an autoregressive or moving average component. Will match the type of the passed constrained variable (so if a list was passed, a list will be returned).

Notes

Uses the list representation internally, even if an array is passed.

References

[R12]

Ansley, Craig F., and Robert Kohn. 1986. “A Note on Reparameterizing a Vector Autoregressive Moving Average Model to Enforce Stationarity.” Journal of Statistical Computation and Simulation 24 (2): 99-106.

dismalpy.ssm.tools.validate_matrix_shape(name, shape, nrows, ncols, nobs)[source]¶

Validate the shape of a possibly time-varying matrix, or raise an exception

Parameters:	name : str The name of the matrix being validated (used in exception messages) shape : array_like The shape of the matrix to be validated. May be of size 2 or (if the matrix is time-varying) 3. nrows : int The expected number of rows. ncols : int The expected number of columns. nobs : int The number of observations (used to validate the last dimension of a time-varying matrix)
Raises:	ValueError If the matrix is not of the desired shape.

dismalpy.ssm.tools.validate_vector_shape(name, shape, nrows, nobs)[source]¶

Validate the shape of a possibly time-varying vector, or raise an exception

Parameters:	name : str The name of the vector being validated (used in exception messages) shape : array_like The shape of the vector to be validated. May be of size 1 or (if the vector is time-varying) 2. nrows : int The expected number of rows (elements of the vector). nobs : int The number of observations (used to validate the last dimension of a time-varying vector)
Raises:	ValueError If the vector is not of the desired shape.