class_docstr: 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)
docstr: 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.
docstr_tok: ["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","."]
code: def from_components(
      cls,
      k_states,
      a=None,
      Pstar=None,
      Pinf=None,
      A=None,
      R0=None,
      Q0=None,
  ):
      r"""
      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.
      """
      k_states = k_states
  
      # Standardize the input
      a = tools._atleast_1d(a)
      Pstar, Pinf, A, R0, Q0 = tools._atleast_2d(Pstar, Pinf, A, R0, Q0)
  
      # Validate the diffuse component
      if Pstar is not None and (R0 is not None or Q0 is not None):
          raise ValueError(
              "Cannot 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'`)."
          )
      if Pinf is not None and A is not None:
          raise ValueError(
              "Cannot specify both the diffuse covariance"
              " matrix `Pinf` and the selection matrix for"
              " diffuse elements, A, (because Pinf is defined"
              " such that `Pinf=A A'`)."
          )
      elif A is not None:
          Pinf = np.dot(A, A.T)
  
      # Validate the non-diffuse component
      if a is None:
          a = np.zeros(k_states)
      if len(a) != k_states:
          raise ValueError(
              "Must provide constant initialization vector for"
              " the entire state vector."
          )
      if R0 is not None or Q0 is not None:
          if R0 is None or Q0 is None:
              raise ValueError(
                  "If specifying either of R0 or Q0 then you"
                  " must specify both R0 and Q0."
              )
          Pstar = R0.dot(Q0).dot(R0.T)
  
      # Handle the diffuse component
      diffuse_ix = []
      if Pinf is not None:
          diffuse_ix = np.where(np.diagonal(Pinf))[0].tolist()
  
          if Pstar is not None:
              for i in diffuse_ix:
                  if not (
                      np.all(Pstar[i] == 0) and np.all(Pstar[:, i] == 0)
                  ):
                      raise ValueError(
                          f"The state at position {i} was"
                          " specified as diffuse in Pinf, but"
                          " also contains a non-diffuse"
                          " diagonal or off-diagonal in Pstar."
                      )
      k_diffuse_states = len(diffuse_ix)
  
      nondiffuse_ix = [
          i for i in np.arange(k_states) if i not in diffuse_ix
      ]
      k_nondiffuse_states = k_states - k_diffuse_states
  
      # If there are non-diffuse states, require Pstar
      if Pstar is None and k_nondiffuse_states > 0:
          raise ValueError(
              "Must provide initial covariance matrix for"
              " non-diffuse states."
          )
  
      # Construct the initialization
      init = cls(k_states)
      if nondiffuse_ix:
          nondiffuse_groups = np.split(
              nondiffuse_ix,
              np.where(np.diff(nondiffuse_ix) != 1)[0] + 1,
          )
      else:
          nondiffuse_groups = []
      for group in nondiffuse_groups:
          s = slice(group[0], group[-1] + 1)
          init.set(
              s, "known", constant=a[s], stationary_cov=Pstar[s, s]
          )
      for i in diffuse_ix:
          init.set(i, "diffuse")
  
      return init
  
file_path: statsmodels/statsmodels/tsa/statespace/initialization.py
imports: import warnings
  import numpy
  from .None import tools
label_desc: Use image node_id 2 for calling the Initialization obj's underlying member method code with example usage: obj.from_components(cls, k_states, a, Pstar, Pinf, A, R0, Q0) and returns: init