class_docstr: State space representation of a time series process, with Kalman filter
  
  Parameters
  ----------
  k_endog : {array_like, int}
      The observed time-series process :math:`y` if array like or the
      number of variables in the process if an integer.
  k_states : int
      The dimension of the unobserved state process.
  k_posdef : int, optional
      The dimension of a guaranteed positive definite covariance matrix
      describing the shocks in the transition equation. Must be less than
      or equal to `k_states`. Default is `k_states`.
  loglikelihood_burn : int, optional
      The number of initial periods during which the loglikelihood is not
      recorded. Default is 0.
  tolerance : float, optional
      The tolerance at which the Kalman filter determines convergence to
      steady-state. Default is 1e-19.
  results_class : class, optional
      Default results class to use to save filtering output. Default is
      `FilterResults`. If specified, class must extend from `FilterResults`.
  **kwargs
      Keyword arguments may be used to provide values for the filter,
      inversion, and stability methods. See `set_filter_method`,
      `set_inversion_method`, and `set_stability_method`.
      Keyword arguments may be used to provide default values for state space
      matrices. See `Representation` for more details.
  
  See Also
  --------
  FilterResults
  statsmodels.tsa.statespace.representation.Representation
  
  Notes
  -----
  There are several types of options available for controlling the Kalman
  filter operation. All options are internally held as bitmasks, but can be
  manipulated by setting class attributes, which act like boolean flags. For
  more information, see the `set_*` class method documentation. The options
  are:
  
  filter_method
      The filtering method controls aspects of which
      Kalman filtering approach will be used.
  inversion_method
      The Kalman filter may contain one matrix inversion: that of the
      forecast error covariance matrix. The inversion method controls how and
      if that inverse is performed.
  stability_method
      The Kalman filter is a recursive algorithm that may in some cases
      suffer issues with numerical stability. The stability method controls
      what, if any, measures are taken to promote stability.
  conserve_memory
      By default, the Kalman filter computes a number of intermediate
      matrices at each iteration. The memory conservation options control
      which of those matrices are stored.
  filter_timing
      By default, the Kalman filter follows Durbin and Koopman, 2012, in
      initializing the filter with predicted values. Kim and Nelson, 1999,
      instead initialize the filter with filtered values, which is
      essentially just a different timing convention.
  
  The `filter_method` and `inversion_method` options intentionally allow
  the possibility that multiple methods will be indicated. In the case that
  multiple methods are selected, the underlying Kalman filter will attempt to
  select the optional method given the input data.
  
  For example, it may be that INVERT_UNIVARIATE and SOLVE_CHOLESKY are
  indicated (this is in fact the default case). In this case, if the
  endogenous vector is 1-dimensional (`k_endog` = 1), then INVERT_UNIVARIATE
  is used and inversion reduces to simple division, and if it has a larger
  dimension, the Cholesky decomposition along with linear solving (rather
  than explicit matrix inversion) is used. If only SOLVE_CHOLESKY had been
  set, then the Cholesky decomposition method would *always* be used, even in
  the case of 1-dimensional data.
class_docstr_tok: ["State","space","representation","of","a","time","series","process",",","with","Kalman","filter","Parameters","--","--","--","--","--","k_endog",":","{","array_like",",","int","}","The","observed","time-series","process",":","math",":","`","y","`","if","array","like","or","the","number","of","variables","in","the","process","if","an","integer",".","k_states",":","int","The","dimension","of","the","unobserved","state","process",".","k_posdef",":","int",",","optional","The","dimension","of","a","guaranteed","positive","definite","covariance","matrix","describing","the","shocks","in","the","transition","equation",".","Must","be","less","than","or","equal","to","`","k_states","`",".","Default","is","`","k_states","`",".","loglikelihood_burn",":","int",",","optional","The","number","of","initial","periods","during","which","the","loglikelihood","is","not","recorded",".","Default","is","0.","tolerance",":","float",",","optional","The","tolerance","at","which","the","Kalman","filter","determines","convergence","to","steady-state",".","Default","is","1e-19",".","results_class",":","class",",","optional","Default","results","class","to","use","to","save","filtering","output",".","Default","is","`","FilterResults","`",".","If","specified",",","class","must","extend","from","`","FilterResults","`",".","*","*","kwargs","Keyword","arguments","may","be","used","to","provide","values","for","the","filter",",","inversion",",","and","stability","methods",".","See","`","set_filter_method","`",",","`","set_inversion_method","`",",","and","`","set_stability_method","`",".","Keyword","arguments","may","be","used","to","provide","default","values","for","state","space","matrices",".","See","`","Representation","`","for","more","details",".","See","Also","--","--","--","--","FilterResults","statsmodels.tsa.statespace.representation.Representation","Notes","--","--","-","There","are","several","types","of","options","available","for","controlling","the","Kalman","filter","operation",".","All","options","are","internally","held","as","bitmasks",",","but","can","be","manipulated","by","setting","class","attributes",",","which","act","like","boolean","flags",".","For","more","information",",","see","the","`","set_","*","`","class","method","documentation",".","The","options","are",":","filter_method","The","filtering","method","controls","aspects","of","which","Kalman","filtering","approach","will","be","used",".","inversion_method","The","Kalman","filter","may","contain","one","matrix","inversion",":","that","of","the","forecast","error","covariance","matrix",".","The","inversion","method","controls","how","and","if","that","inverse","is","performed",".","stability_method","The","Kalman","filter","is","a","recursive","algorithm","that","may","in","some","cases","suffer","issues","with","numerical","stability",".","The","stability","method","controls","what",",","if","any",",","measures","are","taken","to","promote","stability",".","conserve_memory","By","default",",","the","Kalman","filter","computes","a","number","of","intermediate","matrices","at","each","iteration",".","The","memory","conservation","options","control","which","of","those","matrices","are","stored",".","filter_timing","By","default",",","the","Kalman","filter","follows","Durbin","and","Koopman",",","2012",",","in","initializing","the","filter","with","predicted","values",".","Kim","and","Nelson",",","1999",",","instead","initialize","the","filter","with","filtered","values",",","which","is","essentially","just","a","different","timing","convention",".","The","`","filter_method","`","and","`","inversion_method","`","options","intentionally","allow","the","possibility","that","multiple","methods","will","be","indicated",".","In","the","case","that","multiple","methods","are","selected",",","the","underlying","Kalman","filter","will","attempt","to","select","the","optional","method","given","the","input","data",".","For","example",",","it","may","be","that","INVERT_UNIVARIATE","and","SOLVE_CHOLESKY","are","indicated","(","this","is","in","fact","the","default","case",")",".","In","this","case",",","if","the","endogenous","vector","is","1-dimensional","(","`","k_endog","`","=","1",")",",","then","INVERT_UNIVARIATE","is","used","and","inversion","reduces","to","simple","division",",","and","if","it","has","a","larger","dimension",",","the","Cholesky","decomposition","along","with","linear","solving","(","rather","than","explicit","matrix","inversion",")","is","used",".","If","only","SOLVE_CHOLESKY","had","been","set",",","then","the","Cholesky","decomposition","method","would","*","always","*","be","used",",","even","in","the","case","of","1-dimensional","data","."]
docstr: Impulse response function
  
  Parameters
  ----------
  steps : int, optional
      The number of steps for which impulse responses are calculated.
      Default is 10. Note that the initial impulse is not counted as a
      step, so if `steps=1`, the output will have 2 entries.
  impulse : int or array_like
      If an integer, the state innovation to pulse; must be between 0
      and `k_posdef-1` where `k_posdef` is the same as in the state
      space model. Alternatively, a custom impulse vector may be
      provided; must be a column vector with shape `(k_posdef, 1)`.
  orthogonalized : bool, optional
      Whether or not to perform impulse using orthogonalized innovations.
      Note that this will also affect custum `impulse` vectors. Default
      is False.
  cumulative : bool, optional
      Whether or not to return cumulative impulse responses. Default is
      False.
  
  Returns
  -------
  impulse_responses : ndarray
      Responses for each endogenous variable due to the impulse
      given by the `impulse` argument. A (steps + 1 x k_endog) array.
  
  Notes
  -----
  Intercepts in the measurement and state equation are ignored when
  calculating impulse responses.
  
  TODO: add note about how for time-varying systems this is - perhaps
  counter-intuitively - returning the impulse response within the given
  model (i.e. starting at period 0 defined by the model) and it is *not*
  doing impulse responses after the end of the model. To compute impulse
  responses from arbitrary time points, it is necessary to clone a new
  model with the appropriate system matrices.
docstr_tok: ["Impulse","response","function","Parameters","--","--","--","--","--","steps",":","int",",","optional","The","number","of","steps","for","which","impulse","responses","are","calculated",".","Default","is","10",".","Note","that","the","initial","impulse","is","not","counted","as","a","step",",","so","if","`","steps=1","`",",","the","output","will","have","2","entries",".","impulse",":","int","or","array_like","If","an","integer",",","the","state","innovation","to","pulse",";","must","be","between","0","and","`","k_posdef-1","`","where","`","k_posdef","`","is","the","same","as","in","the","state","space","model",".","Alternatively",",","a","custom","impulse","vector","may","be","provided",";","must","be","a","column","vector","with","shape","`","(","k_posdef",",","1",")","`",".","orthogonalized",":","bool",",","optional","Whether","or","not","to","perform","impulse","using","orthogonalized","innovations",".","Note","that","this","will","also","affect","custum","`","impulse","`","vectors",".","Default","is","False",".","cumulative",":","bool",",","optional","Whether","or","not","to","return","cumulative","impulse","responses",".","Default","is","False",".","Returns","--","--","--","-","impulse_responses",":","ndarray","Responses","for","each","endogenous","variable","due","to","the","impulse","given","by","the","`","impulse","`","argument",".","A","(","steps","+","1","x","k_endog",")","array",".","Notes","--","--","-","Intercepts","in","the","measurement","and","state","equation","are","ignored","when","calculating","impulse","responses",".","TODO",":","add","note","about","how","for","time-varying","systems","this","is","-","perhaps","counter-intuitively","-","returning","the","impulse","response","within","the","given","model","(","i.e",".","starting","at","period","0","defined","by","the","model",")","and","it","is","*","not","*","doing","impulse","responses","after","the","end","of","the","model",".","To","compute","impulse","responses","from","arbitrary","time","points",",","it","is","necessary","to","clone","a","new","model","with","the","appropriate","system","matrices","."]
code: def impulse_responses(
      self,
      steps=10,
      impulse=0,
      orthogonalized=False,
      cumulative=False,
      direct=False,
  ):
      r"""
      Impulse response function
  
      Parameters
      ----------
      steps : int, optional
          The number of steps for which impulse responses are calculated.
          Default is 10. Note that the initial impulse is not counted as a
          step, so if `steps=1`, the output will have 2 entries.
      impulse : int or array_like
          If an integer, the state innovation to pulse; must be between 0
          and `k_posdef-1` where `k_posdef` is the same as in the state
          space model. Alternatively, a custom impulse vector may be
          provided; must be a column vector with shape `(k_posdef, 1)`.
      orthogonalized : bool, optional
          Whether or not to perform impulse using orthogonalized innovations.
          Note that this will also affect custum `impulse` vectors. Default
          is False.
      cumulative : bool, optional
          Whether or not to return cumulative impulse responses. Default is
          False.
  
      Returns
      -------
      impulse_responses : ndarray
          Responses for each endogenous variable due to the impulse
          given by the `impulse` argument. A (steps + 1 x k_endog) array.
  
      Notes
      -----
      Intercepts in the measurement and state equation are ignored when
      calculating impulse responses.
  
      TODO: add note about how for time-varying systems this is - perhaps
      counter-intuitively - returning the impulse response within the given
      model (i.e. starting at period 0 defined by the model) and it is *not*
      doing impulse responses after the end of the model. To compute impulse
      responses from arbitrary time points, it is necessary to clone a new
      model with the appropriate system matrices.
      """
      # We need to add an additional step, since the first simulated value
      # will always be zeros (note that we take this value out at the end).
      steps += 1
  
      # For time-invariant models, add an additional `step`. This is the
      # default for time-invariant models based on the expected behavior for
      # ARIMA and VAR models: we want to record the initial impulse and also
      # `steps` values of the responses afterwards.
      if (
          self._design.shape[2] == 1
          and self._transition.shape[2] == 1
          and self._selection.shape[2] == 1
      ):
          steps += 1
  
      # Check for what kind of impulse we want
      if type(impulse) is int:
          if impulse >= self.k_posdef or impulse < 0:
              raise ValueError(
                  "Invalid value for `impulse`. Must be the"
                  " index of one of the state innovations."
              )
  
          # Create the (non-orthogonalized) impulse vector
          idx = impulse
          impulse = np.zeros(self.k_posdef)
          impulse[idx] = 1
      else:
          impulse = np.array(impulse)
          if impulse.ndim > 1:
              impulse = np.squeeze(impulse)
          if not impulse.shape == (self.k_posdef,):
              raise ValueError(
                  "Invalid impulse vector. Must be shaped"
                  " (%d,)" % self.k_posdef
              )
  
      # Orthogonalize the impulses, if requested, using Cholesky on the
      # first state covariance matrix
      if orthogonalized:
          state_chol = np.linalg.cholesky(self.state_cov[:, :, 0])
          impulse = np.dot(state_chol, impulse)
  
      # If we have time-varying design, transition, or selection matrices,
      # then we can't produce more IRFs than we have time points
      time_invariant_irf = (
          self._design.shape[2]
          == self._transition.shape[2]
          == self._selection.shape[2]
          == 1
      )
  
      # Note: to generate impulse responses following the end of a
      # time-varying model, one should `clone` the state space model with the
      # new time-varying model, and then compute the IRFs using the cloned
      # model
      if not time_invariant_irf and steps > self.nobs:
          raise ValueError(
              "In a time-varying model, cannot create more"
              " impulse responses than there are"
              " observations"
          )
  
      # Impulse responses only depend on the design, transition, and
      # selection matrices. We set the others to zeros because they must be
      # set in the call to `clone`.
      # Note: we don't even need selection after the first point, because
      # the state shocks will be zeros in every period except the first.
      sim_model = self.clone(
          endog=np.zeros((steps, self.k_endog), dtype=self.dtype),
          obs_intercept=np.zeros(self.k_endog),
          design=self["design", :, :, :steps],
          obs_cov=np.zeros((self.k_endog, self.k_endog)),
          state_intercept=np.zeros(self.k_states),
          transition=self["transition", :, :, :steps],
          selection=self["selection", :, :, :steps],
          state_cov=np.zeros((self.k_posdef, self.k_posdef)),
      )
  
      # Get the impulse response function via simulation of the state
      # space model, but with other shocks set to zero
      measurement_shocks = np.zeros((steps, self.k_endog))
      state_shocks = np.zeros((steps, self.k_posdef))
      state_shocks[0] = impulse
      initial_state = np.zeros((self.k_states,))
      irf, _ = sim_model.simulate(
          steps,
          measurement_shocks=measurement_shocks,
          state_shocks=state_shocks,
          initial_state=initial_state,
      )
  
      # Get the cumulative response if requested
      if cumulative:
          irf = np.cumsum(irf, axis=0)
  
      # Here we ignore the first value, because it is always zeros (we added
      # an additional `step` at the top to account for this).
      return irf[1:]
  
imports: import contextlib
  from warnings import warn
  import numpy
  from .representation import OptionWrapper, Representation, FrozenRepresentation
  from .tools import reorder_missing_matrix, reorder_missing_vector
  from .None import tools
  from statsmodels.tools.sm_exceptions import ValueWarning
label_desc: Use image node_id 23 for calling the KalmanFilter obj's underlying member method code with example usage: obj.impulse_responses(steps, impulse, orthogonalized, cumulative, direct) and returns: irf