M/Phk@:dZddlZddlmZddlZddlmZddl m Z ddl m Z ddl mZmZmZmZmZmZmZd Zd Zejejejejd Zejejejejd Z ej!ej"ej#ej$d Z%ej&ej'ej(ej)d Z*ej+ej,ej-ej.d Z/ej0ej1ej2ej3d Z4ej5ej6ej7ej8d Z9ej:ej;ej<ej=d Z>ej?ej@ejAejBd ZCejDejEejFejGd ZHejIejJejKejLd ZMejNejOejPejQd ZRejSejTejUejVd ZWejXejYejZej[d Z\ej]ej^ej_ej`d Zaejbejcejdejed Zfd2d Zgd Zhd3dZid4dZjd5dZkd6dZldZmdZn d7dZo d8dZp d9dZqeeqj d9dZrd7dZsdZt d:dZudZv d7dZw d7dZxdZyd Zzd!Z{ d;d"Z|d9d#Z} d;d$Z~d9d%Z d;d&Zd9d'Zd(Zd)Zdd.Z d>d/Zd0Zd1ZdS)?z? Statespace Tools Author: Chad Fulton License: Simplified-BSD N)solve_sylvester)Appender_is_using_pandas)find_best_blas_type)_initialization_representation_kalman_filter_kalman_smoother_simulation_smoother_cfa_simulation_smoother_toolsFT)sdczc(|rtddS)Nz:Compatibility mode is only available in statsmodels <= 0.9)NotImplementedError) compatibilitys `/var/www/html/test/jupyter/venv/lib/python3.11/site-packages/statsmodels/tsa/statespace/tools.pyset_moderrs+9!#899 999cfd}t|ttjfrt|}d}d}nt |dz }|dkrt dt|t tfrj t |d}n#t$rd}YnwxYw|dkrtj |}n<|ddkrtj ||d<d}nd}tj |}tj ||z||zftj |j }tj |dz |z}|d|d|zf}d||<||dkr|dkr|dd |dz |dddf<n|r6t|D]%}||dzj |||z|dz|zd|f<&nmtj|d}t|D]8}tj|||dzj |||z|dz|zd|f<9|S)a 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 interpreted 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, :math:`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 : ndarray Notes ----- Given coefficients of a lag polynomial of the form: .. math:: c(L) = c_0 + c_1 L + \dots + c_p L^p returns a matrix of the form .. math:: \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} where some or all of the :math:`\phi_i` may be non-zero (if `polynomial` is None, then all are equal to zero). If the coefficients provided are scalars :math:`(c_0, c_1, \dots, c_p)`, then the companion matrix is an :math:`n \times n` matrix formed with the elements in the first column defined as :math:`\phi_i = -\frac{c_i}{c_0}, i \in 1, \dots, p`. If the coefficients provided are matrices :math:`(C_0, C_1, \dots, C_p)`, each of shape :math:`(m, m)`, then the companion matrix is an :math:`nm \times nm` matrix formed with the elements in the first column defined as :math:`\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: .. math:: y_t = a_1 y_{t-1} + \dots + a_p y_{t-p} + \varepsilon_t This can be rewritten as: .. math:: (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 The coefficients from this form are defined to be :math:`c_i = - a_i`, and it is the :math:`c_i` coefficients that this function expects to be provided. FrNz=Companion matrix polynomials must include at least two terms.rTdtype) isinstanceintnpintegerlen ValueErrorlisttuple TypeError asanyarrayeyezerosr diag_indicesrangeTlinalginvdot) polynomialidentity_matrixnmmatrixidxir-s rcompanion_matrixr6xsLO*sBJ/003  OO   OOa  q55122 2 j4- 0 0 3  1 &&    Avv]:66 A!## "q 1 "&Az22J Xq1ua!enBM*,E,E,K L L LF /1q5A+ & &C q63q6A: CF3K!a%% 66&qrrN?Z]:F111a4LL  P1XX C C1;AaC1B0Bq1ua!eq[("1",-- C)-- 1 ..C1XX P P13Z!_1M1M1O0Oq1ua!eq[("1",-- Ms<B B! B!czt|d}|stj|n|}|I|dkrC|s||d|d| z }n||}||d}|dz}|dkC|stj||d}n-|dkr'|dd}|dz}|dk'|S)a Difference a series simply and/or seasonally along the zero-th axis. Given a series (denoted :math:`y_t`), performs the differencing operation .. math:: \Delta^d \Delta_s^D y_t where :math:`d =` `diff`, :math:`s =` `seasonal_periods`, :math:`D =` `seasonal\_diff`, and :math:`\Delta` is the difference operator. Parameters ---------- series : array_like The series to be differenced. k_diff : int, optional The number of simple differences to perform. Default is 1. k_seasonal_diff : int or None, optional The number of seasonal differences to perform. Default is no seasonal differencing. seasonal_periods : int, optional The seasonal lag. Default is 1. Unused if there is no seasonal differencing. Returns ------- differenced : ndarray The differenced array. Nrraxis)rrr&diff)seriesk_diffk_seasonal_diffseasonal_periodspandas differencedsdiffeds rr:r:s@fd + +F/5A"-'''6K"!! 9*+;+<+<=*+=-=,=+=> ? &**+;<<%&6&7&78 q O!! gk6::: qjj%**,,QRR0K aKFqjj rctjd|D}tjd|D}tj|}|dkrtdt |t rt |}tt|D]}||dkr$|dkrtj ||||<2||dkr$|dkrtj ||||<b||dkrG|dkrA||r9||j }|| ||<|g||_ ||dkr0|dkr*||s"tj ||j||<tj|rit |dt jr|dj }n t!j|dj g}tdt|D]}||} t | t jrD| j t!jdgr|dd| _ | j } nt!j| j g} |dkr$|| std|dkr4|dj| jstd t!j|| } n=tj|s|rtj|| } ntd | S) a{ Concatenate a set of series. Parameters ---------- series : iterable An iterable of series to be concatenated axis : int, optional The axis along which to concatenate. Default is 1 (columns). allow_mix : bool Whether or not to allow a mix of pandas and non-pandas objects. Default is False. If true, the returned object is an ndarray, and additional pandas metadata (e.g. column names, indices, etc) is lost. Returns ------- concatenated : array or pd.DataFrame The concatenated array. Will be a DataFrame if series are pandas objects. c.g|]}t|dSNr.0rs r zconcat..>s#AAAQ'400AAArc6g|]}tj|S)rndimrEs rrGzconcat..?s ---"'!**---rzA`tools.concat` does not support arrays with 3 or more dimensions.rrNz-Columns must match to concatenate along rows.z.Index must match to concatenate along columns.r8zWAttempted to concatenate Pandas objects with non-Pandas objects with `allow_mix=False`.)rr_maxr"rr$r#r*r! atleast_1d atleast_2dnameto_framecolumnsr+allpd DataFrameIndexequalsindexconcat concatenate) r;r9 allow_mix is_pandasrJmax_ndimr5rP base_columnsr s_columns concatenateds rrYrY)sC*AA&AAABI 5--f--- .Dvd||H!||-.. .&%  f3v;;   3 3 7a<Dq **,,F1I!%F1I   !W\\h!mmIaLm fQi002F1I viH fQi . . 6!!9,LL8VAY^$455Lq#f++&& . .Aq A!R\** /9##BHdV$4$4551 ,RaR 0AII HafX.. qyy!4!4Y!?!?y "*+++6!9?#9#9!'#B#B "-...yd333   HyH~f4888 GHH H rA?ctjt|}tjtj||kS)a 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 :math:`1 - 0.5x` which has root :math:`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 -------- companion_matrix Notes ----- If the coefficients provided are scalars :math:`(c_0, c_1, \dots, c_n)`, then the corresponding polynomial is :math:`c_0 + c_1 L + \dots + c_n L^n`. If the coefficients provided are matrices :math:`(C_0, C_1, \dots, C_n)`, then the corresponding polynomial is :math:`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: .. math:: 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) In order for :math:`C(L)` to be invertible, it must be that each factor :math:`(1 - \lambda_i L)` is invertible; the condition is then that :math:`|\lambda_i| < 1`, where :math:`\lambda_i` is a root of the polynomial. The second method factorizes the polynomial into: .. math:: C(L) & = c_0 + c_1 L + \dots + c_n L^n \\ & = constant (L - \zeta_1) (L - \zeta_2) \dots (L - \zeta_3) The condition is now :math:`|\zeta_i| > 1`, where :math:`\zeta_i` is a root of the polynomial with reversed coefficients and :math:`\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. )rr,eigvalsr6rSabs)r/ thresholdrcs r is_invertiblerfxs@Fi 0 < <==G 6"&//I- . ..rc tj|jd|j}|s|}tj||z}tj||z |}dtjtjtj||z||z}t||| S|}tj||z}tj||z |}dtjtjtj||z||z}t||| S)a Solves the discrete Lyapunov equation using a bilinear transformation. Notes ----- This is a modification of the version in Scipy (see https://github.com/scipy/scipy/blob/master/scipy/linalg/_solvers.py) which allows passing through the complex numbers in the matrix a (usually the transition matrix) in order to allow complex step differentiation. rrrK) rr'shaperconj transposer,r-r.r)aq complex_stepr'aHaHI_invbrs rsolve_discrete_lyapunovrqsR &17 + + +C  5 VVXX   ! !)--S)) F28W % % bfRVBIMM!c'22A66@@ @qvvxx1133Q;;; [[]])--S)) F28W % % bfRVBIMM!c'22A66@@ @q{{}}a!444rcR|jd}tj||f|j}|d|dzzdzz }t |D]P}t |D]1}||dz |f||||dz ||z dz fzz|||f<2|||||f<Q||dz ddf S)a  Transform unconstrained parameters used by the optimizer to constrained parameters used in likelihood evaluation Parameters ---------- unconstrained : ndarray Unconstrained parameters used by the optimizer, to be transformed to stationary coefficients of, e.g., an autoregressive or moving average component. Returns ------- constrained : ndarray Constrained parameters of, e.g., an autoregressive or moving average component, to be transformed to arbitrary parameters used by the optimizer. References ---------- .. [*] Monahan, John F. 1984. "A Note on Enforcing Stationarity in Autoregressive-moving Average Models." Biometrika 71 (2) (August 1): 403-404. rrrrK?N)rhrr(rr*) unconstrainedr1yrkr5s rconstrain_stationary_univariaterxs6 AA !Q}2333AM1,,s23A 1XXq ? ?AAqkAaD1QUAEAI-=+>$>>AadGGA$!Q$ a!eQQQhK<rc|jd}tj||f|j}| ||dz d<t |dz ddD]S}t |D]A}|||f|||f||||z dz fzz d|||fdzz z ||dz |f<BT|}|d|dzz dzz }|S)a  Transform constrained parameters used in likelihood evaluation to unconstrained parameters used by the optimizer Parameters ---------- constrained : ndarray Constrained parameters of, e.g., an autoregressive or moving average component, to be transformed to arbitrary parameters used by the optimizer. Returns ------- unconstrained : ndarray Unconstrained parameters used by the optimizer, to be transformed to stationary coefficients of, e.g., an autoregressive or moving average component. References ---------- .. [*] Monahan, John F. 1984. "A Note on Enforcing Stationarity in Autoregressive-moving Average Models." Biometrika 71 (2) (August 1): 403-404. rrrNrKrs)rhrr(rr*diagonal) constrainedr1rurwr5rvxs r!unconstrain_stationary_univariater~s4 !A !Q{0111AlAacddG 1Q32  KKq K KA1a41QT71Q!AX;#661qAwz>JAac1fII K A a!Q$h_A Hrc~ddlm}g}|t|}||djd}t j|}t |D]j}||}||t j||j zd\}} | | ||| k|S)a- Transform arbitrary matrices to matrices with singular values less than one. Parameters ---------- unconstrained : list Arbitrary matrices. Should be a list of length `order`, where each element is an array sized `k_endog` x `k_endog`. order : int, optional The order of the autoregression. k_endog : int, optional The dimension of the data vector. Returns ------- constrained : list Partial autocorrelation matrices. Should be a list of length `order`, where each element is an array sized `k_endog` x `k_endog`. See Also -------- constrain_stationary_multivariate Notes ----- Corresponds to Lemma 2.2 in Ansley and Kohn (1986). See `constrain_stationary_multivariate` for more details. rr,NTlower scipyr,r!rhrr'r* cho_factorr.r+appendsolve_triangular) rtorderk_endogr,r|r'r5ABrs r"_constrain_sv_less_than_one_pythonr$s@K }M"""(+ &//C 5\\GG ! $$S26!QS>>%9$FF56221au2EEFFFF rc ddlm}|t|}||djd}|s|}t j|||zdzz}|g}|g}|g} g} g} ||d} | g} | g}t|D]}| }| }g} g} | | ||||j ddt j | || dj | d<| | | |||ddt j ||| dj | d<t j | d||}| | j t|D]}| |||t j | d |||d zz z | |||t j | d |||d zz z | |d zxxt j | |d z|||d zz j z cc<|||t j || |j z |||t j t j | |||| |j z | |||d zd||||d zd|d }|stj|}tj|}t j |tj|}tj|}t|D]3}t j t j || ||| |<4| |fS) a Transform matrices with singular values less than one to matrices corresponding to a stationary (or invertible) process. Parameters ---------- partial_autocorrelations : list Partial autocorrelation matrices. Should be a list of length `order`, where each element is an array sized `k_endog` x `k_endog`. error_variance : ndarray 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 : bool, optional Whether or not to transform the error variance term. This option is not typically used, and the default is False. order : int, optional The order of the autoregression. k_endog : int, optional The dimension of the data vector. Returns ------- coefficient_matrices : list Transformed coefficient matrices leading to a stationary VAR representation. See Also -------- constrain_stationary_multivariate Notes ----- Corresponds to Lemma 2.1 in Ansley and Kohn (1986). See `constrain_stationary_multivariate` for more details. rrN Trr+)rtransrzr)rr,r!rhrr'choleskyr*rrr+r.copyinsertr-)partial_autocorrelationserror_variancetransform_variancerrr,initial_varianceforward_variancesbackward_variancesautocovariancesforwards backwardserror_variance_factorforward_factorsbackward_factorsr prev_forwardsprev_backwardstmprwvarianceinitial_variance_factortransformed_variance_factor transform inv_transformr5s r3_compute_coefficients_from_multivariate_pacf_pythonrTsT },--*1-3A6 A) EGOb+@@'(()%&OHI"OON$OGG,-O-.5\\@ @  "    # # #%=a%@%B# $ ' ' ( ( (f_Q/!??   # #"$BB ! fXa["4Q"788sxxzz|,,,q E EA OOA}Q/"& nQ!W53737 7 8 8 8   Qq 1BF" }Q!W55757!7 8 8 8 AaC BF?1Q3+?+8AaC+A+C%E%E E    a 26#x{}#=#= =    !! q ! Fy|%6q%9::!         OO-ac2$O ? ?     OO.qs34O @ @    !$H #%)"4"45E"F"F&(i&8&8&B&B#F29==)DEEGG  i00 u  Arvi!55}EE QKK X rc ttu}|s+j\ }| z} fdt|Dt }djd t | }t |||| \}}|s-tj|d |z}||fS)a 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 : ndarray 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 : bool, 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 [1]_, the arguments `(variance, unconstrained)` are written as :math:`(\Sigma, A_1, \dots, A_p)`, where :math:`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, :math:`(A_1, \dots, A_p)` are transformed into :math:`(P_1, \dots, P_p)` via Lemma 2.2 of [1]_. Second, :math:`(\Sigma, P_1, \dots, P_p)` are transformed into :math:`(\Sigma, \phi_1, \dots, \phi_p)` via Lemmas 2.1 and 2.3 of [1]_. 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 ---------- .. [1] 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. .. [*] Ansley, Craig F, and Paul Newbold. 1979. "Multivariate Partial Autocorrelations." In Proceedings of the Business and Economic Statistics Section, 349-53. American Statistical Association c>g|]}d|z|dzzfSNrrI)rFr5rrts rrGz.LsH    (7(AgIqsGm$;; <   rrrr8) typer#rhr*r!rrrrZreshape) rtrrprefixuse_listrsv_constrainedr|varrs ` @r(constrain_stationary_multivariate_pythonrs LM""d*H  &, '     5\\     EA$Q'G8ug''N K(:E7LLK &n[q999AA Wu_&&   rcv t|tu}|rtj|d}|j\ }| z}|dkrt d dkrt d|t ||g\}}}t|}tj||}tj||}t||| }t||||| \ }tj | tj ||}|r fdt|D |fS)Nrr8zMust have order at least 1z(Must have at least 1 endogenous variablerc>g|]}d|z|dzzfSrrIrFr5r|rs rrGz5constrain_stationary_multivariate..H    !G)QqS'M"99 :   r) rr#rrZrhr"rprefix_dtype_mapasfortranarray prefix_sv_mapprefix_pacf_maparrayr*) rtrrrrrr_rr|rs @@r!constrain_stationary_multivariaterfs M""d*H>}1=== "(NGU gE qyy5666{{CDDD ~. H %''q V $E%m5AAAM 777H #6*=%IIN ,F3"4eWFFK(;e444Kx...H      5\\     rc~ddlm}g}|t|}||djd}t j|}t |D]j}||}||t j||j z d\}} | | ||| k|S)a> Transform matrices with singular values less than one to arbitrary matrices. Parameters ---------- constrained : list The partial autocorrelation matrices. Should be a list of length `order`, where each element is an array sized `k_endog` x `k_endog`. order : int, optional The order of the autoregression. k_endog : int, optional The dimension of the data vector. Returns ------- unconstrained : list Unconstrained matrices. A list of length `order`, where each element is an array sized `k_endog` x `k_endog`. See Also -------- unconstrain_stationary_multivariate Notes ----- Corresponds to the inverse of Lemma 2.2 in Ansley and Kohn (1986). See `unconstrain_stationary_multivariate` for more details. rrNTrr) r|rrr,rtr'r5PB_invrs r_unconstrain_sv_less_than_oners<M }K  a.&q) &//C 5\\MM N((rva~~)=T(JJ u V44UAU4KKLLLL rc tj|}|jdkr|ddtjf}|tj|dz}|j\}}g}t |dzD]}|tj||ft ||z D]4}||xxtj |||||zz cc<5||xx|zcc<|S)a Computer multivariate sample autocovariances Parameters ---------- endog : array_like Sample data on which to compute sample autocovariances. Shaped `nobs` x `k_endog`. maxlag : int Maximum lag to use when computing the sample autocovariances. Returns ------- sample_autocovariances : list A list of the first `maxlag` sample autocovariance matrices. Each matrix is shaped `k_endog` x `k_endog`. Notes ----- This function computes the forward sample autocovariances: .. math:: \hat \Gamma(s) = \frac{1}{n} \sum_{t=1}^{n-s} (Z_t - \bar Z) (Z_{t+s} - \bar Z)' See page 353 of Wei (1990). This function is primarily implemented for checking the partial autocorrelation functions below, and so is quite slow. References ---------- .. [*] Wei, William. 1990. Time Series Analysis : Univariate and Multivariate Methods. Boston: Pearson. rNrr8) rrrJnewaxismeanrhr*rr(outer)endogmaxlagnobsrsample_autocovariancesrts r"_compute_multivariate_sample_acovfrsJ HUOOE zQaaam$ RWU # # ##EKMD' 6A:  **%%bh/A&B&BCCCtax H HA "1 % % %%(E!A#J)G)G G % % % %q!!!T)!!!! !!rc ddlm}ttur#t }djd n+j\ }| z} fdt |D||dz }tdgfdt |Dzj}tj |j}||d d f<| || fdt t||dzD}t ||dz z D]*} tj |  | d  dfgz }+|r/t t |D]} || j|| <|S)a Compute multivariate autocovariances from vector autoregression coefficient matrices Parameters ---------- coefficients : array or list The coefficients matrices. 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 : ndarray The variance / covariance matrix of the error term. Should be sized `k_endog` x `k_endog`. maxlag : int, optional The maximum autocovariance to compute. Default is `order`-1. Can be zero, in which case it returns the variance. forward_autocovariances : bool, optional Whether or not to compute forward autocovariances :math:`E(y_t y_{t+j}')`. Default is False, so that backward autocovariances :math:`E(y_t y_{t-j}')` are returned. Returns ------- autocovariances : list A list of the first `maxlag` autocovariance matrices. Each matrix is shaped `k_endog` x `k_endog`. Notes ----- Computes .. math:: \Gamma(j) = E(y_t y_{t-j}') for j = 1, ..., `maxlag`, unless `forward_autocovariances` is specified, in which case it computes: .. math:: E(y_t y_{t+j}') = \Gamma(j)' Coefficients are assumed to be provided from the VAR model: .. math:: y_t = A_1 y_{t-1} + \dots + A_p y_{t-p} + \varepsilon_t Autocovariances are calculated by solving the associated discrete Lyapunov equation of the state space representation of the VAR process. rrc>g|]}d|z|dzzfSrrI)rFr5 coefficientsrs rrGzA_compute_multivariate_acovf_from_coefficients..@sH    '1W9ac7]#:: ;   rNrcFg|]}tj| SrI)rsqueeze)rFr5rs rrGzA_compute_multivariate_acovf_from_coefficients..Ls*BBB <?+++BBBrc>g|]}d|z|dzzfSrrI)rFr5r stacked_covs rrGzA_compute_multivariate_acovf_from_coefficients..YsH  HWHai1g 556r)rr,rr#r!rhr*r6r+rr(rqminr.) rrrforward_autocovariancesr,r companionselected_variancerr5rrs ` @@r-_compute_multivariate_acovf_from_coefficientsrs l LT!!L!!q/'*%+ '     5\\   ~q ! BBBBU5\\BBBB 11,:hwh()00"@"@ @     !1222!!"3444  OO-a0O = =     OO.q1O > >   66 OOF,, #T*OA,>@@@A C C C   V--!!$d+_Q-?-ACCCD F F F F &ac*,1133G1XX L L26-"2OAaC4H4JKKK OOF,,!!$d+WY8889 ; ; ;   V-- #T*G5556 8 8 8 q 8 8A OOA}Q/"& nQ!W53737 7 8 8 8   Qq 1BF" }Q!W55757!7 8 8 8 8 !''(?(? A x{4DQ4G H H)@))     $#rct|tur#t|}|djd}n|j\}}||z}t}d||||D}t |S)a$ Transform matrices corresponding to a stationary (or invertible) process to matrices with singular values less than one. Parameters ---------- constrained : array or list The coefficients matrices. 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 : ndarray The variance / covariance matrix of the error term. Should be sized `k_endog` x `k_endog`. order : int, optional The order of the autoregression. k_endog : int, optional The dimension of the data vector. Returns ------- pacf : list List of first `order` multivariate partial autocorrelations. See Also -------- unconstrain_stationary_multivariate Notes ----- Note that this computes multivariate partial autocorrelations. Corresponds to the inverse of Lemma 2.1 in Ansley and Kohn (1986). See `unconstrain_stationary_multivariate` for more details. Notes ----- Coefficients are assumed to be provided from the VAR model: .. math:: y_t = A_1 y_{t-1} + \dots + A_p y_{t-p} + \varepsilon_t rcg|] }|j SrI)r+)rFautocovariances rrGz@_compute_multivariate_pacf_from_coefficients..\s(;;;+;;;r)r)rr#r!rhrr)r|rrr_acovfrs r,_compute_multivariate_pacf_from_coefficientsr#sZ KD  K  a.&q)$* ' ;F;;{N5999;;;O ;? K KKrcPttu}|s,j\}|z}fdt|Dn"t }djdt ||}t ||}|stj|d}||fS)a 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 : ndarray 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 : ndarray 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 ---------- .. [*] 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. c>g|]}d|z|dzzfSrrIrs rrGz7unconstrain_stationary_multivariate..rrrrr8) rr#rhr*r!rrrrZ)r|rrrrrtrs` @r#unconstrain_stationary_multivariatercsLK  D(H  *$* '     5\\   K  a.&q) L^UG 5 5 2 %22M >}1=== . ((rct|}|dvrtd||fz|d|kstd|||dfz|d|kstd|||dfz|$|dks|d dkstd |z|d kr0|0|d d|fvr&td ||t|fzdSdSdS) a 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. )rKzTInvalid value for %s matrix. Requires a 2- or 3-dimensional array, got %d dimensionsrz:Invalid dimensions for %s matrix: requires %d rows, got %drz=Invalid dimensions for %s matrix: requires %d columns, got %dNrKrzzInvalid dimensions for %s matrix: time-varying matrices cannot be given unless `nobs` is specified (implicitly when a dataset is bound or else set explicity)rzNInvalid dimensions for time-varying %s matrix. Requires shape (*,*,%d), got %sr!r"str)rPrhnrowsncolsrrJs rvalidate_matrix_shapersZ0 u::D 6I&'' ' 8u  ),0%q+BCDD D 8u  ,/3UE!H.EFGG G |TQYY%)q..'*..// /  qyyT%%)At9*D*DDc%jj1233 3y%%*D*DrcZt|}|dvrtd||fz|d|kstd|||dfz|$|dks|ddkstd|z|d kr.|dd|fvr$td ||t|fzdSdS) av 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. )rrKzTInvalid value for %s vector. Requires a 1- or 2-dimensional array, got %d dimensionsrz:Invalid dimensions for %s vector: requires %d rows, got %dNrrzzInvalid dimensions for %s vector: time-varying vectors cannot be given unless `nobs` is specified (implicitly when a dataset is bound or else set explicity)rKzLInvalid dimensions for time-varying %s vector. Requires shape (*,%d), got %sr)rPrhrrrJs rvalidate_vector_shapers, u::D 6I&'' ' 8u  ),0%q+BCDD D |TQYY%)q..'*..// /  qyyU1XaY..Bc%jj1233 3y..rc|t|fd}t|}|stj|d}||tj|||||S)a Reorder the rows or columns of a time-varying matrix where all non-missing values are in the upper left corner of the matrix. Parameters ---------- matrix : array_like The matrix to be reordered. Must have shape (n, m, nobs). missing : array_like of bool The vector of missing indices. Must have shape (k, nobs) where `k = n` if `reorder_rows is True` and `k = m` if `reorder_cols is True`. reorder_rows : bool, optional Whether or not the rows of the matrix should be re-ordered. Default is False. reorder_cols : bool, optional Whether or not the columns of the matrix should be re-ordered. Default is False. is_diagonal : bool, optional Whether or not the matrix is diagonal. If this is True, must also have `n = m`. Default is False. inplace : bool, optional Whether or not to reorder the matrix in-place. prefix : {'s', 'd', 'c', 'z'}, optional The Fortran prefix of the vector. Default is to automatically detect the dtype. This parameter should only be used with caution. Returns ------- reordered_matrix : array_like The reordered matrix. NrFr)r!prefix_reorder_missing_matrix_maprrr)r3missing reorder_rows reorder_cols is_diagonalinplacerreorders rreorder_missing_matrixr suD~$fY//2/7G ,s+++ GFB%g.. l  Mrc|t|fd}t|}|stj|d}||tj||S)a Reorder the elements of a time-varying vector where all non-missing values are in the first elements of the vector. Parameters ---------- vector : array_like The vector to be reordered. Must have shape (n, nobs). missing : array_like of bool The vector of missing indices. Must have shape (n, nobs). inplace : bool, optional Whether or not to reorder the matrix in-place. Default is False. prefix : {'s', 'd', 'c', 'z'}, optional The Fortran prefix of the vector. Default is to automatically detect the dtype. This parameter should only be used with caution. Returns ------- reordered_vector : array_like The reordered vector. Nrrr)r!prefix_reorder_missing_vector_maprrr)vectorrrrrs rreorder_missing_vectorr:se,~$fY//2/7G ,s+++ GFB%g../// Mrcd|t||fd}t|}|stj|d} |st n+#t t f$rtj|}YnwxYw|||tj|||||S)aT Copy the rows or columns of a time-varying matrix where all non-missing values are in the upper left corner of the matrix. Parameters ---------- A : array_like The matrix from which to copy. Must have shape (n, m, nobs) or (n, m, 1). B : array_like The matrix to copy to. Must have shape (n, m, nobs). missing : array_like of bool The vector of missing indices. Must have shape (k, nobs) where `k = n` if `reorder_rows is True` and `k = m` if `reorder_cols is True`. missing_rows : bool, optional Whether or not the rows of the matrix are a missing dimension. Default is False. missing_cols : bool, optional Whether or not the columns of the matrix are a missing dimension. Default is False. is_diagonal : bool, optional Whether or not the matrix is diagonal. If this is True, must also have `n = m`. Default is False. inplace : bool, optional Whether or not to copy to B in-place. Default is False. prefix : {'s', 'd', 'c', 'z'}, optional The Fortran prefix of the vector. Default is to automatically detect the dtype. This parameter should only be used with caution. Returns ------- copied_matrix : array_like The matrix B with the non-missing submatrix of A copied onto it. Nrrr)rprefix_copy_missing_matrix_maprr is_f_contigr"AttributeErrorr) rrr missing_rows missing_colsrrrrs rcopy_missing_matrixr\sH~$aV,,Q/ )& 1D " GAS ! ! !!}} ,,   J '!!!  a ! DAr ))<  H"A##%B  B c^|t||fd}t|}|stj|d} |st n+#t t f$rtj|}YnwxYw|||tj||S)aJ Reorder the elements of a time-varying vector where all non-missing values are in the first elements of the vector. Parameters ---------- a : array_like The vector from which to copy. Must have shape (n, nobs) or (n, 1). b : array_like The vector to copy to. Must have shape (n, nobs). missing : array_like of bool The vector of missing indices. Must have shape (n, nobs). inplace : bool, optional Whether or not to copy to b in-place. Default is False. prefix : {'s', 'd', 'c', 'z'}, optional The Fortran prefix of the vector. Default is to automatically detect the dtype. This parameter should only be used with caution. Returns ------- copied_vector : array_like The vector b with the non-missing subvector of b copied onto it. Nrrr)rprefix_copy_missing_vector_maprrrr"rr)rkrprrrrs rcopy_missing_vectorr s0~$aV,,Q/ )& 1D " GAS ! ! !!}} ,,   J '!!!  a ! DAr ))*** Hrcd|t||fd}t|}|stj|d} |st n+#t t f$rtj|}YnwxYw|||tj|||||S)aD Copy the rows or columns of a time-varying matrix where all non-index values are in the upper left corner of the matrix. Parameters ---------- A : array_like The matrix from which to copy. Must have shape (n, m, nobs) or (n, m, 1). B : array_like The matrix to copy to. Must have shape (n, m, nobs). index : array_like of bool The vector of index indices. Must have shape (k, nobs) where `k = n` if `reorder_rows is True` and `k = m` if `reorder_cols is True`. index_rows : bool, optional Whether or not the rows of the matrix are a index dimension. Default is False. index_cols : bool, optional Whether or not the columns of the matrix are a index dimension. Default is False. is_diagonal : bool, optional Whether or not the matrix is diagonal. If this is True, must also have `n = m`. Default is False. inplace : bool, optional Whether or not to copy to B in-place. Default is False. prefix : {'s', 'd', 'c', 'z'}, optional The Fortran prefix of the vector. Default is to automatically detect the dtype. This parameter should only be used with caution. Returns ------- copied_matrix : array_like The matrix B with the non-index submatrix of A copied onto it. Nrrr)rprefix_copy_index_matrix_maprrrr"rr) rrrX index_rows index_colsrrrrs rcopy_index_matrixrsH~$aV,,Q/ ' /D " GAS ! ! !!}} ,,   J '!!!  a ! DAr ''Z  Hrc^|t||fd}t|}|stj|d} |st n+#t t f$rtj|}YnwxYw|||tj||S)aB Reorder the elements of a time-varying vector where all non-index values are in the first elements of the vector. Parameters ---------- a : array_like The vector from which to copy. Must have shape (n, nobs) or (n, 1). b : array_like The vector to copy to. Must have shape (n, nobs). index : array_like of bool The vector of index indices. Must have shape (n, nobs). inplace : bool, optional Whether or not to copy to b in-place. Default is False. prefix : {'s', 'd', 'c', 'z'}, optional The Fortran prefix of the vector. Default is to automatically detect the dtype. This parameter should only be used with caution. Returns ------- copied_vector : array_like The vector b with the non-index subvector of b copied onto it. Nrrr)rprefix_copy_index_vector_maprrrr"rr)rkrprXrrrs rcopy_index_vectorrs0~$aV,,Q/ ' /D " GAS ! ! !!}} ,,   J '!!!  a ! DAr ''((( Hrcd}|at|d}|stj|}|jdkr#|s |dddf}nt j|}|jd}||fSNrr)rrasarrayrJrTrUrh)exogk_exogexog_is_using_pandass r prepare_exogr&s F /d;;# $:d##D 9>>' *AAAtG}|D))A D>rc||dkrtjd}n|dkrtjd}n|dkrtjd}n|dkrtjd}ni|d krtjd }nPtj|}|jdkr|dkt }ntd |t tj|}||fS) Nr1rrrr)rrct)rrctt)rrrzValid trend inputs are 'c' (constant), 't' (linear trend in time), 'ct' (both), 'ctt' (both with trend squared) or an interable defining a polynomial, e.g., [1, 1, 0, 1] is `a + b*t + ct**3`. Received ) ronesrLrrJastyperr"sum)trendpolynomial_trendk_trends rprepare_trend_specr"8s } 71:: #58 #5; $5; %5> :>> % 11#66  2+022 "&)**++G W $$rctj|||z}tj||f}d}|dD]5}|dkrtj||dd|f<n ||z|dd|f<|dz }6|Sr)raranger(nonzeror)r r!roffset time_trend trend_datar5rws rprepare_trend_datar)Ys64&=11J4/**J A  % % ' ' * 66!wt~~Jqqq!t  )1}Jqqq!t  Q rc tj|S#tjj$rCtjtj|rtjcYStjcYSwxYw)z3Compute condition while protecting from LinAlgError)rr,cond LinAlgErroranyisnannaninf)rks r _safe_condr1isky~~a   9  6"(1++   6MMM6MMM s!AA8) A87A8?c B|j}|j}|j}t|j}|t j|j}|t j|j}t jt j | t j }| t jt j | t j }| | |ddk}|r|ddkrtd|||||||t|\} } } } t|d|d} t j|jdd| df}t j|r| j}t j| dddd|d|dz|d|dd} t j| t j }t/| |dd | |d|d|d|ddddd} n| dddd} | dddd} | ddd} t j|| z || z }| |} | |} |r | || z } | | | fS) Nrz[If `compute_prior_weights` is set to True, then `compute_j` must include the time period 0.rKrrCrT)rr) _statespacer r )prefix_compute_smoothed_state_weights_maprrr$runiquerNrint32sortr"boolrr.rr-rhrrjrrix_)ssm compute_t compute_jcompute_prior_weightsscale_model_kfilter _smootherfuncweightsstate_intercept_weights prior_weightsrt0rrhix_tjs r_compute_smoothed_state_weightsrJts _F!H$I 5SZ @DIch'' Ich''  "- 2299"(CCDDI NN "- 2299"(CCDDI NN$ )!  1I1!2!2HII I:>8VY 5 "##:%:%6G $mQ Yq\9Q< ( (BhsyBCC())G vg0 #G$5$5aAq$A$A$I$I !HuQx q583%J%@%@AA#GNN28$<$<==wd'+ - - - -??58U1XuQxqJJ$9Q1a00 ##Aq!Q//6??1aKK"++Aq!44M F9r>9r> 2 2EenG5e<6%i"n5 +] ::rcZ|j}||j|,tj|j|jjjk}|r|jddddn|j t|j||||j j S)a Construct the weights of observations and the prior on the smoothed state Parameters ---------- results : MLEResults object Results object from fitting a state space model. compute_t : array_like, optional An explicit list of periods `t` of the smoothed state vector to compute weights for (see the Returns section for more details about the dimension `t`). Default is to compute weights for all periods `t`. However, if weights for only a few time points are desired, then performance can be improved by specifying this argument. compute_j : array_like, optional An explicit list of periods `j` of observations to compute weights for (see the Returns section for more details about the dimension `j`). Default is to compute weights for all periods `j`. However, if weights for only a few time points are desired, then performance can be improved by specifying this argument. compute_prior_weights : bool, optional Whether or not to compute the weight matrices associated with the prior mean (also called the "initial state"). Note that doing so requires that period 0 is in the periods defined in `compute_j`. Default is True if 0 is in `compute_j` (or if the `compute_j` argument is not passed) and False otherwise. resmooth : bool, optional Whether or not to re-perform filtering and smoothing prior to constructing the weights. Default is to resmooth if the smoothed_state vector is different between the given results object and the underlying smoother. Caution is adviced when changing this setting. See the Notes section below for more details. Returns ------- weights : array_like Weight matrices that can be used to construct the smoothed state from the observations. The returned matrix is always shaped `(nobs, nobs, k_states, k_endog)`, and entries that are not computed are set to NaNs. (Entries will not be computed if they are not included in `compute_t` and `compute_j`, or if they correspond to missing observations, or if they are for periods in which the exact diffuse Kalman filter is operative). The `(t, j, m, p)`-th element of this matrix contains the weight of the `p`-th element of the observation vector at time `j` in constructing the `m`-th element of the smoothed state vector at time `t`. prior_weights : array_like Weight matrices that describe the impact of the prior (also called the initialization) on the smoothed state vector. The returned matrix is always shaped `(nobs, k_states, k_states)`. If prior weights are not computed, then all entries will be set to NaNs. The `(t, m, l)`-th element of this matrix contains the weight of the `l`-th element of the prior mean (also called the "initial state") in constructing the `m`-th element of the smoothed state vector at time `t`. Notes ----- In [1]_, Chapter 4.8, it is shown how the smoothed state vector can be written as a weighted vector sum of observations: .. math:: \hat \alpha_t = \sum_{j=1}^n \omega_{jt}^{\hat \alpha} y_j One output of this function is the weights :math:`\omega_{jt}^{\hat \alpha}`. Note that the description in [1]_ assumes that the prior mean (or "initial state") is fixed to be zero. More generally, the smoothed state vector will also depend partly on the prior. The second output of this function are the weights of the prior mean. There are two important technical notes about the computations used here: 1. In the univariate approach to multivariate filtering (see e.g. Chapter 6.4 of [1]_), all observations are introduced one at a time, including those from the same time period. As a result, the weight of each observation can be different than when all observations from the same time point are introduced together, as in the typical multivariate filtering approach. Here, we always compute weights as in the multivariate filtering approach, and we handle singular forecast error covariance matrices by using a pseudo-inverse. 2. Constructing observation weights for periods in which the exact diffuse filter (see e.g. Chapter 5 of [1]_) is operative is not done here, and so the corresponding entries in the returned weight matrices will always be set equal to zeros. While handling these periods may be implemented in the future, one option for constructing these weights is to use an approximate (instead of exact) diffuse initialization for this purpose. Finally, one note about implementation: to compute the weights, we use attributes of the underlying filtering and smoothing Cython objects directly. However, these objects are not frozen with the result computation, and we cannot guarantee that their attributes have not changed since `res` was created. As a result, by default we re-run the filter and smoother to ensure that the attributes there actually correspond to the `res` object. This can be overridden by the user for a small performance boost if they are sure that the attributes have not changed; see the `resmooth` argument. References ---------- .. [1] Durbin, James, and Siem Jan Koopman. 2012. Time Series Analysis by State Space Methods: Second Edition. Oxford University Press. NrF)conserve_memoryupdate_representation update_filterupdate_smoother)r=r>r?r@) modelupdateparamsrr-smoothed_stater<r smooth_initialize_representationrJfilter_resultsr@)resultsr=r>r?resmoothmods rcompute_smoothed_state_weightsrZsR -CJJw~6'0'2ABCC- q%*E  C C C C **,,, * 9 3$* , , ,,rc||||td|}d}||||jdz }|jdz }t|dut|duzt|duzdkrtd|&|$|||\}}}}||dz z}n-|&|$|||\}}}}||dz z }n|| |||\}}}}||z}|||fS)a{ Compute start/end periods and an index, often for impacts of data updates Parameters ---------- previous_model : MLEModel Model used to compute default start/end periods if None are given. In the case of computing impacts of data updates, this would be the model estimated with the previous dataset. Otherwise, can be the same as `updated_model`. updated_model : MLEModel Model used to compute the index. In the case of computing impacts of data updates, this would be the model estimated with the updated dataset. Otherwise, can be the same as `previous_model`. impact_date : {int, str, datetime}, optional Specific individual impact date. Cannot be used in combination with `start`, `end`, or `periods`. start : {int, str, datetime}, optional Starting point of the impact dates. If given, one of `end` or `periods` must also be given. If a negative integer, will be computed relative to the dates in the `updated_model` index. Cannot be used in combination with `impact_date`. end : {int, str, datetime}, optional Ending point of the impact dates. If given, one of `start` or `periods` must also be given. If a negative integer, will be computed relative to the dates in the `updated_model` index. Cannot be used in combination with `impact_date`. periods : int, optional Number of impact date periods. If given, one of `start` or `end` must also be given. Cannot be used in combination with `impact_date`. Returns ------- start : int Integer location of the first included impact dates. end : int Integer location of the last included impact dates (i.e. this integer location is included in the returned `index`). index : pd.Index Index associated with `start` and `end`, as computed from the `updated_model`'s index. Notes ----- This function is typically used as a helper for standardizing start and end periods for a date range where the most sensible default values are based on some initial dataset (here contained in the `previous_model`), while index-related operations (especially relative start/end dates given via negative integers) are most sensibly computed from an updated dataset (here contained in the `updated_model`). NzWCannot use the `impact_date` argument in combination with `start`, `end`, or `periods`.rzOOf the three parameters: start, end, and periods, exactly two must be specified)r"rr_get_prediction_index) previous_model updated_model impact_datestartendperiodsr out_of_sampleprediction_indexs rget_impact_datesre7sot #+'/+,, , }#a'!A% 5D=Ct ,,,s7d?/C/CCqHHCDD D  w2&<rs ((((((......333333111111111111111111111111   "*2-1-!-!-!<;-!`....b4"4"4"p.2 %iiiiX   2IM]$]$]$]$BFJ=L=L=L=L@A)A)A)H232323j,3,3,3^:?;@15,,,,^DINAE6 6 6 6 r) ) ) ) XAF?C6 6 6 6 r) ) ) ) X$%%%B     DHFIB;B;B;B;JGKHL{,{,{,{,|AE37X(X(X(X(v2r