M/Ph@dZddlZddlZddlmZGddZdS)zZ State Space Representation - Initialization Author: Chad Fulton License: Simplified-BSD N)toolsceZdZdZ ddZe ddZedZdZdZ dd Z d Z d Z e d Z ddZdS)Initializationa0 State space initialization Parameters ---------- k_states : int exact_diffuse_initialization : bool, optional Whether or not to use exact diffuse initialization; only has an effect if some states are initialized as diffuse. Default is True. approximate_diffuse_variance : float, optional If using approximate diffuse initialization, the initial variance used. Default is 1e6. Notes ----- As developed in Durbin and Koopman (2012), the state space recursions must be initialized for the first time period. The general form of this initialization is: .. math:: \alpha_1 & = a + A \delta + R_0 \eta_0 \\ \delta & \sim N(0, \kappa I), \kappa \to \infty \\ \eta_0 & \sim N(0, Q_0) Thus the state vector can be initialized with a known constant part (elements of :math:`a`), with part modeled as a diffuse initial distribution (as a part of :math:`\delta`), and with a part modeled as a known (proper) initial distribution (as a part of :math:`\eta_0`). There are two important restrictions: 1. An element of the state vector initialized as diffuse cannot be also modeled with a stationary component. In the `validate` method, violations of this cause an exception to be raised. 2. If an element of the state vector is initialized with both a known constant part and with a diffuse initial distribution, the effect of the diffuse initialization will essentially ignore the given known constant value. In the `validate` method, violations of this cause a warning to be given, since it is not technically invalid but may indicate user error. The :math:`\eta_0` compoenent is also referred to as the stationary part because it is often set to the unconditional distribution of a stationary process. Initialization is specified for blocks (consecutive only, for now) of the state vector, with the entire state vector and individual elements as special cases. Denote the block in question as :math:`\alpha_1^{(i)}`. It can be initialized in the following ways: - 'known' - 'diffuse' or 'exact_diffuse' or 'approximate_diffuse' - 'stationary' - 'mixed' In the first three cases, the block's initialization is specified as an instance of the `Initialization` class, with the `initialization_type` attribute set to one of those three string values. In the 'mixed' cases, the initialization is also an instance of the `Initialization` class, but it will itself contain sub-blocks. Details of each type follow. Regardless of the type, for each block, the following must be defined: the `constant` array, an array `diffuse` with indices corresponding to diffuse elements, an array `stationary` with indices corresponding to stationary elements, and `stationary_cov`, a matrix with order equal to the number of stationary elements in the block. **Known** If a block is initialized as known, then a known (possibly degenerate) distribution is used; in particular, the block of states is understood to be distributed :math:`\alpha_1^{(i)} \sim N(a^{(i)}, Q_0^{(i)})`. Here, is is possible to set :math:`a^{(i)} = 0`, and it is also possible that :math:`Q_0^{(i)}` is only positive-semidefinite; i.e. :math:`\alpha_1^{(i)}` may be degenerate. One particular example is that if the entire block's initial values are known, then :math:`R_0^{(i)} = 0`, and so `Var(\alpha_1^{(i)}) = 0`. Here, `constant` must be provided (although it can be zeros), and `stationary_cov` is optional (by default it is a matrix of zeros). **Diffuse** If a block is initialized as diffuse, then set :math:`\alpha_1^{(i)} \sim N(a^{(i)}, \kappa^{(i)} I)`. If the block is initialized using the exact diffuse initialization procedure, then it is understood that :math:`\kappa^{(i)} \to \infty`. If the block is initialized using the approximate diffuse initialization procedure, then `\kappa^{(i)}` is set to some large value rather than driven to infinity. In the approximate diffuse initialization case, it is possible, although unlikely, that a known constant value may have some effect on initialization if :math:`\kappa^{(i)}` is not set large enough. Here, `constant` may be provided, and `approximate_diffuse_variance` may be provided. **Stationary** If a block is initialized as stationary, then the block of states is understood to have the distribution :math:`\alpha_1^{(i)} \sim N(a^{(i)}, Q_0^{(i)})`. :math:`a^{(i)}` is the unconditional mean of the block, computed as :math:`(I - T^{(i)})^{-1} c_t`. :math:`Q_0^{(i)}` is the unconditional variance of the block, computed as the solution to the discrete Lyapunov equation: .. math:: T^{(i)} Q_0^{(i)} T^{(i)} + (R Q R')^{(i)} = Q_0^{(i)} :math:`T^{(i)}` and :math:`(R Q R')^{(i)}` are the submatrices of the corresponding state space system matrices corresponding to the given block of states. Here, no values can be provided. **Mixed** In this case, the block can be further broken down into sub-blocks. Usually, only the top-level `Initialization` instance will be of 'mixed' type, and in many cases, even the top-level instance will be purely 'known', 'diffuse', or 'stationary'. For a block of type mixed, suppose that it has `J` sub-blocks, :math:`\alpha_1^{(i,j)}`. Then :math:`\alpha_1^{(i)} = a^{(i)} + A^{(i)} \delta + R_0^{(i)} \eta_0^{(i)}`. Examples -------- Basic examples have one specification for all of the states: >>> Initialization(k_states=2, 'known', constant=[0, 1]) >>> Initialization(k_states=2, 'known', stationary_cov=np.eye(2)) >>> Initialization(k_states=2, 'known', constant=[0, 1], stationary_cov=np.eye(2)) >>> Initialization(k_states=2, 'diffuse') >>> Initialization(k_states=2, 'approximate_diffuse', approximate_diffuse_variance=1e6) >>> Initialization(k_states=2, 'stationary') More complex examples initialize different blocks of states separately >>> init = Initialization(k_states=3) >>> init.set((0, 1), 'known', constant=[0, 1]) >>> init.set((0, 1), 'known', stationary_cov=np.eye(2)) >>> init.set((0, 1), 'known', constant=[0, 1], stationary_cov=np.eye(2)) >>> init.set((0, 1), 'diffuse') >>> init.set((0, 1), 'approximate_diffuse', approximate_diffuse_variance=1e6) >>> init.set((0, 1), 'stationary') A still more complex example initializes a block using a previously created `Initialization` object: >>> init1 = Initialization(k_states=2, 'known', constant=[0, 1]) >>> init2 = Initialization(k_states=3) >>> init2.set((1, 2), init1) N.Ac||_ttj||_tjdg|z|_i|_d|_tj |j|_ tj |j|jf|_ ||_ ||ntj|_i|_i|_||d|||dSdS)Nconstantstationary_cov)k_statestuplenparange_statesarray_initializationblocksinitialization_typezerosr r approximate_diffuse_variancerprefix_initialization_mapcopy_representations_initializationsset)selfr rinitialization_classesrr r s i/var/www/html/test/jupyter/venv/lib/python3.11/site-packages/statsmodels/tsa/statespace/initialization.py__init__zInitialization.__init__s! RYx0011 !x(9:: $( //  h t}'EFF,H)'=&H " "05577 &!# "  * HHT.$2  4 4 4 4 4 + *c 6|}tj|}tj|||||\}}}}}|||td||td|t j||j}|t j|}t||krtd||@||td|||j}g|t j t j |d |XD]U}t j ||dkr"t j |dd|fdkstd|dVt} fd t j |D} || z } || dkrtd ||} | rGt j| t j t j| d kdd z} ng} | D]H}t!|d|d d z}| |d |||||fID]}| |d| S)a Construct initialization object from component matrices Parameters ---------- a : array_like, optional Vector of constant values describing the mean of the stationary component of the initial state. Pstar : array_like, optional Stationary component of the initial state covariance matrix. If given, should be a matrix shaped `k_states x k_states`. The submatrix associated with the diffuse states should contain zeros. Note that by definition, `Pstar = R0 @ Q0 @ R0.T`, so either `R0,Q0` or `Pstar` may be given, but not both. Pinf : array_like, optional Diffuse component of the initial state covariance matrix. If given, should be a matrix shaped `k_states x k_states` with ones in the diagonal positions corresponding to states with diffuse initialization and zeros otherwise. Note that by definition, `Pinf = A @ A.T`, so either `A` or `Pinf` may be given, but not both. A : array_like, optional Diffuse selection matrix, used in the definition of the diffuse initial state covariance matrix. If given, should be a `k_states x k_diffuse_states` matrix that contains the subset of the columns of the identity matrix that correspond to states with diffuse initialization. Note that by definition, `Pinf = A @ A.T`, so either `A` or `Pinf` may be given, but not both. R0 : array_like, optional Stationary selection matrix, used in the definition of the stationary initial state covariance matrix. If given, should be a `k_states x k_nondiffuse_states` matrix that contains the subset of the columns of the identity matrix that correspond to states with a non-diffuse initialization. Note that by definition, `Pstar = R0 @ Q0 @ R0.T`, so either `R0,Q0` or `Pstar` may be given, but not both. Q0 : array_like, optional Covariance matrix associated with stationary initial states. If given, should be a matrix shaped `k_nondiffuse_states x k_nondiffuse_states`. Note that by definition, `Pstar = R0 @ Q0 @ R0.T`, so either `R0,Q0` or `Pstar` may be given, but not both. Returns ------- initialization Initialization object. Notes ----- The matrices `a, Pstar, Pinf, A, R0, Q0` and the process for initializing the state space model is as given in Chapter 5 of [1]_. For the definitions of these matrices, see equation (5.2) and the subsequent discussion there. References ---------- .. [*] Durbin, James, and Siem Jan Koopman. 2012. Time Series Analysis by State Space Methods: Second Edition. Oxford University Press. NzCannot specify the initial state covariance both as `Pstar` and as the components R0 and Q0 (because `Pstar` is defined such that `Pstar=R0 Q0 R0'`).zCannot specify both the diffuse covariance matrix `Pinf` and the selection matrix for diffuse elements, A, (because Pinf is defined such that `Pinf=A A'`).zHMust provide constant initialization vector for the entire state vector.zFIf specifying either of R0 or Q0 then you must specify both R0 and Q0.rzThe state at position ze was specified as diffuse in Pinf, but also contains a non-diffuse diagonal or off-diagonal in Pstar.cg|]}|v| Sr#).0i diffuse_ixs r z2Initialization.from_components..Cs#OOOq1J;N;N;N;N;Nr z>Must provide initial covariance matrix for non-diffuse states.rknownr diffuse)r _atleast_1d _atleast_2d ValueErrorrdotTrlenwherediagonaltolistallrsplitdiffslicer)clsr aPstarPinfAR0Q0r%k_diffuse_states nondiffuse_ixk_nondiffuse_statesinitnondiffuse_groupsgroupsr&s @rfrom_componentszInitialization.from_componentss0@  a !&!25$2r!J!JtQB  ".BN455 5   899 9]6!QS>>D 9""A q66X  9:: : >R^zRZ "ABBBFF2JJNN24((E  "+d"3"344Q7>>@@J #PPAF58q=11PF5A;!#344P(*O!*O*O*OPPPP z??OOOOBIh$7$7OOO &)99 =0144455 5s8}}  # "rx (>(>!(CDDQG!K!M!M  !# & L LEeAhb A ..A HHQ!A$uQT{H K K K K # #A HHQ " " " " r cr|j}|j}|j}||jj|||S)N)r9r:r;) initial_stateinitial_state_covinitial_diffuse_state_covrFmodelr )r8filter_resultsr9r:r;s r from_resultszInitialization.from_resultsZsI  (07"">#7#@%&e$#@@ @r c2|||dSN)r)rindexrs r __setitem__zInitialization.__setitem__cs +,,,,,r ctj|}||jvrP|j|t j|j|d|j|<np|j|dd|j|ddd<|j|dd|j|ddd<||jvrP|j |}||j |j|d|j|d|j |j|<n|j |j|_ ||fS)Nr r r ) rprefix_dtype_maprr astyperasfortranarrayr rrr r)rprefixdtyper8s r_initialize_initializationz)Initialization._initialize_initializationfsk&v. . . .!M0077"$"3'..u55#7#7--D !& ) ) $$U++AAA.  !& )* 5aaa 8#**511!!!4  !& )*: ;AAA > . . .08C,/C t4V?1-3-3D !& ) )1  !& ) Fu}r c t|tst|ttjfr7t|}|dks ||jkrt d||dzf}n*||f}n$t|tst dt|dkrt dt|}|j |}t|dkrdS|j *||j kst dt|ztj |j |fd}||jvrLtj|s8t dttj||zt|}||jkr||_ ||d kst d ||d kst d |d kr||t d |tj||f}ntj|}|j||fks7t dt|jdt||fd||_nT|dkr|t)jdn7|d kr |||_n'|dkr|t dnt d|tj|}ntj|}|j|fks6t dt|jdt|fd||_dSt|t0r|}n||j}t1|||||}||j|<|D] } ||j | < dS)a Set initialization for states, either globally or for a block Parameters ---------- index : tuple or int or None Arguments used to create a `slice` of states. Can be a tuple with `(start, stop)` (note that for `slice`, stop is not inclusive), or an integer (to select a specific state), or None (to select all the states). initialization_type : str The type of initialization used for the states selected by `index`. Must be one of 'known', 'diffuse', 'approximate_diffuse', or 'stationary'. constant : array_like, optional A vector of constant values, denoted :math:`a`. Most often used with 'known' initialization, but may also be used with 'approximate_diffuse' (although it will then likely have little effect). stationary_cov : array_like, optional The covariance matrix of the stationary part, denoted :math:`Q_0`. Only used with 'known' initialization. approximate_diffuse_variance : float, optional The approximate diffuse variance, denoted :math:`\kappa`. Only applicable with 'approximate_diffuse' initialization. Default is 1e6. rInvalid index.rN'Cannot include a slice step in `index`.zCannot set initialization for the block of states %s because initialization was previously performed globally. You must either re-initialize globally or else unset the global initialization before initializing specific blocks of states.zCannot set initialization for the state(s) %s because they are a subset of a previously initialized block. You must either re-initialize the entire block as a whole or else unset the entire block before re-initializing the subset.approximate_diffusezb`approximate_diffuse_variance` can only be provided when using approximate diffuse initialization.r)zF`stationary_cov` can only be provided when using known initialization.ztMust specify either the constant vector or the stationary covariance matrix (or both) if using known initialization.z2Invalid stationary covariance matrix; given shape z but require shape .r*zOConstant values provided, but they are ignored in exact diffuse initialization. stationaryzAConstant values cannot be provided for stationary initialization.zInvalid initialization type.z%Invalid constant vector; given shape )r r r) isinstancer7intrintegerr r-r r0rrstrequalrrr4rrshaper warningswarnrr r) rrPrr r r uninitializedr rBr%s rrzInitialization.setsy>%'' "%#rz!233 3E 199 6 6$%5666 *u-- 3 !12225zzA~~ !JKKK5ME U# u::?? F  # /8M8MH #5zz *++ +!5ef!>EE  # #BF=,A,A #< #28E??M>#BCC DEE Eu:: t} $ $':D $-8+/DDD "4555*+w66 "@AAA#g--#(>$&8999 ")%'Xx.B%C%CNN%'Xn%=%=N&+(/CCC$*(+N,@(A(A(A(A(+Xx,@(A(A(A(A&CDDD '5##$ 11'M#NOOO$(===/;45$ 44'$&CDDD(!!?@@@8H--8H-->h[00 j$'$7$7$7$7h[9I9I9I9I"KLLL%DMMM-~>> O*/791%1H#11MOOO "&DK  0 0*/$Q'' 0 0r ct|ttjfr7t|}|dks ||jkrt d||dzf}n*||f}n$t|t st dt|dkrt d|jt|}t|dkrdSt|}||jkr(|j !d|_ d|j dd<d|j dd<dS||j vr|D] }d|j|< |j |=dSt d)a# Unset initialization for states, either globally or for a block Parameters ---------- index : tuple or int or None Arguments used to create a `slice` of states. Can be a tuple with `(start, stop)` (note that for `slice`, stop is not inclusive), or an integer (to select a specific state), or None (to select all the states). Notes ----- Note that this specifically unsets initializations previously created using `set` with this same index. Thus you cannot use `index=None` to unset all initializations, but only to unset a previously set global initialization. To unset all initializations (including both global and block level), use the `clear` method. rrZrNr[r\zFThe given index does not correspond to a previously initialized block.)r`rarrbr r-r r0rr7rr r rr)rrPr r%s runsetzInitialization.unset$ss( ec2:. / / /JJEqyyEDM11 !1222EAI&EE ]HEEE5)) /-.. . u::>>FGG G UE]+ u::?? Fu:: t} $ $)A)M'+D $ DM!!! %&D  " " " dk ! ! / /*.$Q'' E""">?? ?r c|jD] }d|j|< t|j}|D] }|j|= d|_d|jdd<d|jdd<dS)zX Clear all previously set initializations, either global or block level Nr)rrlistrkeysrr r )rr%rmkeys rclearzInitialization.clearXs  + +A&*D  # #DK$$&&'' ! !C C  $(  aaa!"AAAr cn|jduo+tjtj|jd SrO)rranyrdr)rs r initializedzInitialization.initializedjs;,4AF28D$8$??@@B Br Fc|j;tjtj|jdrt d|4|j}tjdd}tjddddf}n8tj|d|ddz}tj||}|d|d|df} |d|zdz} |d |dddf} |d dddddf} tj | |  | j } |tj |j }|j |j f}|tj |}|tj |}|jtj |j }tj |j |j f}|jd kr|t d |jd krZtj| }d }tjtj||kst d|jd kr'tj|| z | ||<n |j||<|jdkrtj |j ||<n|||<|jdkr |j||<n|jdkr|||<n|jdkr||jz||<n{|jd krt-j| | |||<nU|jD];\}}|t5tj||f||||<|||fS)ac Construct initialization representation Parameters ---------- model : Representation, optional A state space model representation object, optional if 'stationary' initialization is used and ignored otherwise. See notes for details in the stationary initialization case. model_index : ndarray, optional The base index of the block in the model. initial_state_mean : ndarray, optional An array (or more usually view) in which to place the initial state mean. initial_diffuse_state_cov : ndarray, optional An array (or more usually view) in which to place the diffuse component of initial state covariance matrix. initial_stationary_state_cov : ndarray, optional An array (or more usually view) in which to place the stationary component of initial state covariance matrix. Returns ------- initial_state_mean : ndarray Initial state mean, :math:`a_1^{(0)} = a` initial_diffuse_state_cov : ndarray Diffuse component of initial state covariance matrix, :math:`P_\infty = A A'` initial_stationary_state_cov : ndarray Stationary component of initial state covariance matrix, :math:`P_* = R_0 Q_0 R_0'` Notes ----- If stationary initialization is used either globally or for any block of states, then either `model` or all of `state_intercept`, `transition`, `selection`, and `state_cov` must be provided. Nz\Cannot construct initialization representation because not all states have been initialized.rr(rstate_intercept) transition)r selection state_covr_z~Stationary initialization requires passing either the `model` argument or all of the individual transition equation arguments.gA?zWTransition equation is not stationary, and so stationary initialization cannot be used.r*r)r]) complex_step)rPrKinitial_state_meanrJinitial_stationary_state_cov)rrrqrdrr-rs_ix_r.r/rr eyelinalgeigvalsmaxabssolver r rrsolve_discrete_lyapunovritemsr r)rrPrKryrJrzrxix1ix2rtrurvrwselected_state_cov cov_shaper}rr threshold block_indexrBs r__call__zInitialization.__call__osV  $ ,rx 4d;;<< -NOO O =LE%(C%111+CC%arQ./C&&&C  #$5sA$=>O4t;+> (  # /&''CHdmT];<HL$(CCC[CJ@@[@---   D8<>BZ0Z0Z0Z0x2?2?2?h###$BBXBCG+/AFD.D.D.D.D.D.r r)rrfnumpyrrrr#r rrst e .e .e .e .e .e .e .e .e .e .r