class_docstr: Results from applying the Kalman filter to a state space model.
  
  Parameters
  ----------
  model : Representation
      A Statespace representation
  
  Attributes
  ----------
  nobs : int
      Number of observations.
  nobs_diffuse : int
      Number of observations under the diffuse Kalman filter.
  k_endog : int
      The dimension of the observation series.
  k_states : int
      The dimension of the unobserved state process.
  k_posdef : int
      The dimension of a guaranteed positive definite
      covariance matrix describing the shocks in the
      measurement equation.
  dtype : dtype
      Datatype of representation matrices
  prefix : str
      BLAS prefix of representation matrices
  shapes : dictionary of name,tuple
      A dictionary recording the shapes of each of the
      representation matrices as tuples.
  endog : ndarray
      The observation vector.
  design : ndarray
      The design matrix, :math:`Z`.
  obs_intercept : ndarray
      The intercept for the observation equation, :math:`d`.
  obs_cov : ndarray
      The covariance matrix for the observation equation :math:`H`.
  transition : ndarray
      The transition matrix, :math:`T`.
  state_intercept : ndarray
      The intercept for the transition equation, :math:`c`.
  selection : ndarray
      The selection matrix, :math:`R`.
  state_cov : ndarray
      The covariance matrix for the state equation :math:`Q`.
  missing : array of bool
      An array of the same size as `endog`, filled
      with boolean values that are True if the
      corresponding entry in `endog` is NaN and False
      otherwise.
  nmissing : array of int
      An array of size `nobs`, where the ith entry
      is the number (between 0 and `k_endog`) of NaNs in
      the ith row of the `endog` array.
  time_invariant : bool
      Whether or not the representation matrices are time-invariant
  initialization : str
      Kalman filter initialization method.
  initial_state : array_like
      The state vector used to initialize the Kalamn filter.
  initial_state_cov : array_like
      The state covariance matrix used to initialize the Kalamn filter.
  initial_diffuse_state_cov : array_like
      Diffuse state covariance matrix used to initialize the Kalamn filter.
  filter_method : int
      Bitmask representing the Kalman filtering method
  inversion_method : int
      Bitmask representing the method used to
      invert the forecast error covariance matrix.
  stability_method : int
      Bitmask representing the methods used to promote
      numerical stability in the Kalman filter
      recursions.
  conserve_memory : int
      Bitmask representing the selected memory conservation method.
  filter_timing : int
      Whether or not to use the alternate timing convention.
  tolerance : float
      The tolerance at which the Kalman filter
      determines convergence to steady-state.
  loglikelihood_burn : int
      The number of initial periods during which
      the loglikelihood is not recorded.
  converged : bool
      Whether or not the Kalman filter converged.
  period_converged : int
      The time period in which the Kalman filter converged.
  filtered_state : ndarray
      The filtered state vector at each time period.
  filtered_state_cov : ndarray
      The filtered state covariance matrix at each time period.
  predicted_state : ndarray
      The predicted state vector at each time period.
  predicted_state_cov : ndarray
      The predicted state covariance matrix at each time period.
  forecast_error_diffuse_cov : ndarray
      Diffuse forecast error covariance matrix at each time period.
  predicted_diffuse_state_cov : ndarray
      The predicted diffuse state covariance matrix at each time period.
  kalman_gain : ndarray
      The Kalman gain at each time period.
  forecasts : ndarray
      The one-step-ahead forecasts of observations at each time period.
  forecasts_error : ndarray
      The forecast errors at each time period.
  forecasts_error_cov : ndarray
      The forecast error covariance matrices at each time period.
  llf_obs : ndarray
      The loglikelihood values at each time period.
class_docstr_tok: ["Results","from","applying","the","Kalman","filter","to","a","state","space","model",".","Parameters","--","--","--","--","--","model",":","Representation","A","Statespace","representation","Attributes","--","--","--","--","--","nobs",":","int","Number","of","observations",".","nobs_diffuse",":","int","Number","of","observations","under","the","diffuse","Kalman","filter",".","k_endog",":","int","The","dimension","of","the","observation","series",".","k_states",":","int","The","dimension","of","the","unobserved","state","process",".","k_posdef",":","int","The","dimension","of","a","guaranteed","positive","definite","covariance","matrix","describing","the","shocks","in","the","measurement","equation",".","dtype",":","dtype","Datatype","of","representation","matrices","prefix",":","str","BLAS","prefix","of","representation","matrices","shapes",":","dictionary","of","name",",","tuple","A","dictionary","recording","the","shapes","of","each","of","the","representation","matrices","as","tuples",".","endog",":","ndarray","The","observation","vector",".","design",":","ndarray","The","design","matrix",",",":","math",":","`","Z","`",".","obs_intercept",":","ndarray","The","intercept","for","the","observation","equation",",",":","math",":","`","d","`",".","obs_cov",":","ndarray","The","covariance","matrix","for","the","observation","equation",":","math",":","`","H","`",".","transition",":","ndarray","The","transition","matrix",",",":","math",":","`","T","`",".","state_intercept",":","ndarray","The","intercept","for","the","transition","equation",",",":","math",":","`","c","`",".","selection",":","ndarray","The","selection","matrix",",",":","math",":","`","R","`",".","state_cov",":","ndarray","The","covariance","matrix","for","the","state","equation",":","math",":","`","Q","`",".","missing",":","array","of","bool","An","array","of","the","same","size","as","`","endog","`",",","filled","with","boolean","values","that","are","True","if","the","corresponding","entry","in","`","endog","`","is","NaN","and","False","otherwise",".","nmissing",":","array","of","int","An","array","of","size","`","nobs","`",",","where","the","ith","entry","is","the","number","(","between","0","and","`","k_endog","`",")","of","NaNs","in","the","ith","row","of","the","`","endog","`","array",".","time_invariant",":","bool","Whether","or","not","the","representation","matrices","are","time-invariant","initialization",":","str","Kalman","filter","initialization","method",".","initial_state",":","array_like","The","state","vector","used","to","initialize","the","Kalamn","filter",".","initial_state_cov",":","array_like","The","state","covariance","matrix","used","to","initialize","the","Kalamn","filter",".","initial_diffuse_state_cov",":","array_like","Diffuse","state","covariance","matrix","used","to","initialize","the","Kalamn","filter",".","filter_method",":","int","Bitmask","representing","the","Kalman","filtering","method","inversion_method",":","int","Bitmask","representing","the","method","used","to","invert","the","forecast","error","covariance","matrix",".","stability_method",":","int","Bitmask","representing","the","methods","used","to","promote","numerical","stability","in","the","Kalman","filter","recursions",".","conserve_memory",":","int","Bitmask","representing","the","selected","memory","conservation","method",".","filter_timing",":","int","Whether","or","not","to","use","the","alternate","timing","convention",".","tolerance",":","float","The","tolerance","at","which","the","Kalman","filter","determines","convergence","to","steady-state",".","loglikelihood_burn",":","int","The","number","of","initial","periods","during","which","the","loglikelihood","is","not","recorded",".","converged",":","bool","Whether","or","not","the","Kalman","filter","converged",".","period_converged",":","int","The","time","period","in","which","the","Kalman","filter","converged",".","filtered_state",":","ndarray","The","filtered","state","vector","at","each","time","period",".","filtered_state_cov",":","ndarray","The","filtered","state","covariance","matrix","at","each","time","period",".","predicted_state",":","ndarray","The","predicted","state","vector","at","each","time","period",".","predicted_state_cov",":","ndarray","The","predicted","state","covariance","matrix","at","each","time","period",".","forecast_error_diffuse_cov",":","ndarray","Diffuse","forecast","error","covariance","matrix","at","each","time","period",".","predicted_diffuse_state_cov",":","ndarray","The","predicted","diffuse","state","covariance","matrix","at","each","time","period",".","kalman_gain",":","ndarray","The","Kalman","gain","at","each","time","period",".","forecasts",":","ndarray","The","one-step-ahead","forecasts","of","observations","at","each","time","period",".","forecasts_error",":","ndarray","The","forecast","errors","at","each","time","period",".","forecasts_error_cov",":","ndarray","The","forecast","error","covariance","matrices","at","each","time","period",".","llf_obs",":","ndarray","The","loglikelihood","values","at","each","time","period","."]
docstr: In-sample and out-of-sample prediction for state space models generally
  
  Parameters
  ----------
  start : int, optional
      Zero-indexed observation number at which to start prediction, i.e.,
      the first prediction will be at start.
  end : int, optional
      Zero-indexed observation number at which to end prediction, i.e.,
      the last prediction will be at end.
  dynamic : int, optional
      Offset relative to `start` at which to begin dynamic prediction.
      Prior to this observation, true endogenous values will be used for
      prediction; starting with this observation and continuing through
      the end of prediction, predicted endogenous values will be used
      instead.
  **kwargs
      If the prediction range is outside of the sample range, any
      of the state space representation matrices that are time-varying
      must have updated values provided for the out-of-sample range.
      For example, of `obs_intercept` is a time-varying component and
      the prediction range extends 10 periods beyond the end of the
      sample, a (`k_endog` x 10) matrix must be provided with the new
      intercept values.
  
  Returns
  -------
  results : kalman_filter.PredictionResults
      A PredictionResults object.
  
  Notes
  -----
  All prediction is performed by applying the deterministic part of the
  measurement equation using the predicted state variables.
  
  Out-of-sample prediction first applies the Kalman filter to missing
  data for the number of periods desired to obtain the predicted states.
docstr_tok: ["In-sample","and","out-of-sample","prediction","for","state","space","models","generally","Parameters","--","--","--","--","--","start",":","int",",","optional","Zero-indexed","observation","number","at","which","to","start","prediction",",","i.e.",",","the","first","prediction","will","be","at","start",".","end",":","int",",","optional","Zero-indexed","observation","number","at","which","to","end","prediction",",","i.e.",",","the","last","prediction","will","be","at","end",".","dynamic",":","int",",","optional","Offset","relative","to","`","start","`","at","which","to","begin","dynamic","prediction",".","Prior","to","this","observation",",","true","endogenous","values","will","be","used","for","prediction",";","starting","with","this","observation","and","continuing","through","the","end","of","prediction",",","predicted","endogenous","values","will","be","used","instead",".","*","*","kwargs","If","the","prediction","range","is","outside","of","the","sample","range",",","any","of","the","state","space","representation","matrices","that","are","time-varying","must","have","updated","values","provided","for","the","out-of-sample","range",".","For","example",",","of","`","obs_intercept","`","is","a","time-varying","component","and","the","prediction","range","extends","10","periods","beyond","the","end","of","the","sample",",","a","(","`","k_endog","`","x","10",")","matrix","must","be","provided","with","the","new","intercept","values",".","Returns","--","--","--","-","results",":","kalman_filter.PredictionResults","A","PredictionResults","object",".","Notes","--","--","-","All","prediction","is","performed","by","applying","the","deterministic","part","of","the","measurement","equation","using","the","predicted","state","variables",".","Out-of-sample","prediction","first","applies","the","Kalman","filter","to","missing","data","for","the","number","of","periods","desired","to","obtain","the","predicted","states","."]
code: def predict(self, start=None, end=None, dynamic=None, **kwargs):
      r"""
      In-sample and out-of-sample prediction for state space models generally
  
      Parameters
      ----------
      start : int, optional
          Zero-indexed observation number at which to start prediction, i.e.,
          the first prediction will be at start.
      end : int, optional
          Zero-indexed observation number at which to end prediction, i.e.,
          the last prediction will be at end.
      dynamic : int, optional
          Offset relative to `start` at which to begin dynamic prediction.
          Prior to this observation, true endogenous values will be used for
          prediction; starting with this observation and continuing through
          the end of prediction, predicted endogenous values will be used
          instead.
      **kwargs
          If the prediction range is outside of the sample range, any
          of the state space representation matrices that are time-varying
          must have updated values provided for the out-of-sample range.
          For example, of `obs_intercept` is a time-varying component and
          the prediction range extends 10 periods beyond the end of the
          sample, a (`k_endog` x 10) matrix must be provided with the new
          intercept values.
  
      Returns
      -------
      results : kalman_filter.PredictionResults
          A PredictionResults object.
  
      Notes
      -----
      All prediction is performed by applying the deterministic part of the
      measurement equation using the predicted state variables.
  
      Out-of-sample prediction first applies the Kalman filter to missing
      data for the number of periods desired to obtain the predicted states.
      """
      # Get the start and the end of the entire prediction range
      if start is None:
          start = 0
      elif start < 0:
          raise ValueError(
              "Cannot predict values previous to the sample."
          )
      if end is None:
          end = self.nobs
  
      # Prediction and forecasting is performed by iterating the Kalman
      # Kalman filter through the entire range [0, end]
      # Then, everything is returned corresponding to the range [start, end].
      # In order to perform the calculations, the range is separately split
      # up into the following categories:
      # - static:   (in-sample) the Kalman filter is run as usual
      # - dynamic:  (in-sample) the Kalman filter is run, but on missing data
      # - forecast: (out-of-sample) the Kalman filter is run, but on missing
      #             data
  
      # Short-circuit if end is before start
      if end <= start:
          raise ValueError("End of prediction must be after start.")
  
      # Get the number of forecasts to make after the end of the sample
      nforecast = max(0, end - self.nobs)
  
      # Get the number of dynamic prediction periods
  
      # If `dynamic=True`, then assume that we want to begin dynamic
      # prediction at the start of the sample prediction.
      if dynamic is True:
          dynamic = 0
      # If `dynamic=False`, then assume we want no dynamic prediction
      if dynamic is False:
          dynamic = None
  
      # Check validity of dynamic and warn or error if issues
      dynamic, ndynamic = _check_dynamic(dynamic, start, end, self.nobs)
  
      # Get the number of in-sample static predictions
      if dynamic is None:
          nstatic = min(end, self.nobs) - min(start, self.nobs)
      else:
          # (use max(., 0), since dynamic can be prior to start)
          nstatic = max(dynamic - start, 0)
  
      # Cannot do in-sample prediction if we do not have appropriate
      # arrays (we can do out-of-sample forecasting, however)
      if nstatic > 0 and self.memory_no_forecast_mean:
          raise ValueError(
              "In-sample prediction is not available if memory"
              " conservation has been used to avoid storing"
              " forecast means."
          )
      # Cannot do dynamic in-sample prediction if we do not have appropriate
      # arrays (we can do out-of-sample forecasting, however)
      if ndynamic > 0 and self.memory_no_predicted:
          raise ValueError(
              "In-sample dynamic prediction is not available if"
              " memory conservation has been used to avoid"
              " storing forecasted or predicted state means"
              " or covariances."
          )
  
      # Construct the predicted state and covariance matrix for each time
      # period depending on whether that time period corresponds to
      # one-step-ahead prediction, dynamic prediction, or out-of-sample
      # forecasting.
  
      # If we only have simple prediction, then we can use the already saved
      # Kalman filter output
      if ndynamic == 0 and nforecast == 0:
          results = self
          oos_results = None
      # If we have dynamic prediction or forecasting, then we need to
      # re-apply the Kalman filter
      else:
          # Figure out the period for which we need to run the Kalman filter
          if dynamic is not None:
              kf_start = min(dynamic, self.nobs)
          else:
              kf_start = self.nobs
          kf_end = end
  
          # Make start, end consistent with the results that we're generating
          # start = max(start - kf_start, 0)
          # end = kf_end - kf_start
  
          # We must at least store forecasts and predictions
          kwargs["conserve_memory"] = (
              self.conserve_memory
              & ~MEMORY_NO_FORECAST
              & ~MEMORY_NO_PREDICTED
          )
  
          # Can't use Chandrasekhar recursions for prediction
          kwargs["filter_method"] = (
              self.model.filter_method & ~FILTER_CHANDRASEKHAR
          )
  
          # TODO: there is a corner case here when the filter has not
          #       exited the diffuse filter, in which case this known
          #       initialization is not correct.
          # Even if we have not stored all predicted values (means and covs),
          # we can still do pure out-of-sample forecasting because we will
          # always have stored the last predicted values. In this case, we
          # will initialize the forecasting filter with these values
          if self.memory_no_predicted:
              constant = self.predicted_state[..., -1]
              stationary_cov = self.predicted_state_cov[..., -1]
          # Otherwise initialize with the predicted state / cov from the
          # existing results, at index kf_start (note that the time
          # dimension of predicted_state and predicted_state_cov is
          # self.nobs + 1; so e.g. in the case of pure forecasting we should
          # be using the very last predicted state and predicted state cov
          # elements, and kf_start will equal self.nobs which is correct)
          else:
              constant = self.predicted_state[..., kf_start]
              stationary_cov = self.predicted_state_cov[..., kf_start]
  
          kwargs.update(
              {
                  "initialization": "known",
                  "constant": constant,
                  "stationary_cov": stationary_cov,
              }
          )
  
          # Construct the new endogenous array.
          endog = np.zeros((nforecast, self.k_endog)) * np.nan
          model = self.model.extend(
              endog, start=kf_start, end=kf_end - nforecast, **kwargs
          )
          # Have to retroactively modify the model's endog
          if ndynamic > 0:
              model.endog[:, -(ndynamic + nforecast) :] = np.nan
  
          with model.fixed_scale(self.scale):
              oos_results = model.filter()
  
          results = self
  
      return PredictionResults(
          results,
          start,
          end,
          nstatic,
          ndynamic,
          nforecast,
          oos_results=oos_results,
      )
  
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 6 for calling the FilterResults obj's underlying member method code with example usage: obj.predict(start, end, dynamic) and returns: PredictionResults