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: Update the filter results
  
  Parameters
  ----------
  kalman_filter : statespace.kalman_filter.KalmanFilter
      The model object from which to take the updated values.
  
  Notes
  -----
  This method is rarely required except for internal usage.
docstr_tok: ["Update","the","filter","results","Parameters","--","--","--","--","--","kalman_filter",":","statespace.kalman_filter.KalmanFilter","The","model","object","from","which","to","take","the","updated","values",".","Notes","--","--","-","This","method","is","rarely","required","except","for","internal","usage","."]
code: def update_filter(self, kalman_filter):
      """
      Update the filter results
  
      Parameters
      ----------
      kalman_filter : statespace.kalman_filter.KalmanFilter
          The model object from which to take the updated values.
  
      Notes
      -----
      This method is rarely required except for internal usage.
      """
      # State initialization
      self.initial_state = np.array(
          kalman_filter.model.initial_state, copy=True
      )
      self.initial_state_cov = np.array(
          kalman_filter.model.initial_state_cov, copy=True
      )
  
      # Save Kalman filter parameters
      self.filter_method = kalman_filter.filter_method
      self.inversion_method = kalman_filter.inversion_method
      self.stability_method = kalman_filter.stability_method
      self.conserve_memory = kalman_filter.conserve_memory
      self.filter_timing = kalman_filter.filter_timing
      self.tolerance = kalman_filter.tolerance
      self.loglikelihood_burn = kalman_filter.loglikelihood_burn
  
      # Save Kalman filter output
      self.converged = bool(kalman_filter.converged)
      self.period_converged = kalman_filter.period_converged
      self.univariate_filter = np.array(
          kalman_filter.univariate_filter, copy=True
      )
  
      self.filtered_state = np.array(
          kalman_filter.filtered_state, copy=True
      )
      self.filtered_state_cov = np.array(
          kalman_filter.filtered_state_cov, copy=True
      )
      self.predicted_state = np.array(
          kalman_filter.predicted_state, copy=True
      )
      self.predicted_state_cov = np.array(
          kalman_filter.predicted_state_cov, copy=True
      )
  
      # Reset caches
      has_missing = np.sum(self.nmissing) > 0
      if not (
          self.memory_no_std_forecast
          or self.invert_lu
          or self.solve_lu
          or self.filter_collapsed
      ):
          if has_missing:
              self._standardized_forecasts_error = np.array(
                  reorder_missing_vector(
                      kalman_filter.standardized_forecast_error,
                      self.missing,
                      prefix=self.prefix,
                  )
              )
          else:
              self._standardized_forecasts_error = np.array(
                  kalman_filter.standardized_forecast_error, copy=True
              )
      else:
          self._standardized_forecasts_error = None
  
      # In the partially missing data case, all entries will
      # be in the upper left submatrix rather than the correct placement
      # Re-ordering does not make sense in the collapsed case.
      if has_missing and (
          not self.memory_no_gain and not self.filter_collapsed
      ):
          self._kalman_gain = np.array(
              reorder_missing_matrix(
                  kalman_filter.kalman_gain,
                  self.missing,
                  reorder_cols=True,
                  prefix=self.prefix,
              )
          )
          self.tmp1 = np.array(
              reorder_missing_matrix(
                  kalman_filter.tmp1,
                  self.missing,
                  reorder_cols=True,
                  prefix=self.prefix,
              )
          )
          self.tmp2 = np.array(
              reorder_missing_vector(
                  kalman_filter.tmp2, self.missing, prefix=self.prefix
              )
          )
          self.tmp3 = np.array(
              reorder_missing_matrix(
                  kalman_filter.tmp3,
                  self.missing,
                  reorder_rows=True,
                  prefix=self.prefix,
              )
          )
          self.tmp4 = np.array(
              reorder_missing_matrix(
                  kalman_filter.tmp4,
                  self.missing,
                  reorder_cols=True,
                  reorder_rows=True,
                  prefix=self.prefix,
              )
          )
      else:
          if not self.memory_no_gain:
              self._kalman_gain = np.array(
                  kalman_filter.kalman_gain, copy=True
              )
          self.tmp1 = np.array(kalman_filter.tmp1, copy=True)
          self.tmp2 = np.array(kalman_filter.tmp2, copy=True)
          self.tmp3 = np.array(kalman_filter.tmp3, copy=True)
          self.tmp4 = np.array(kalman_filter.tmp4, copy=True)
          self.M = np.array(kalman_filter.M, copy=True)
          self.M_diffuse = np.array(kalman_filter.M_inf, copy=True)
  
      # Note: use forecasts rather than forecast, so as not to interfer
      # with the `forecast` methods in subclasses
      self.forecasts = np.array(kalman_filter.forecast, copy=True)
      self.forecasts_error = np.array(
          kalman_filter.forecast_error, copy=True
      )
      self.forecasts_error_cov = np.array(
          kalman_filter.forecast_error_cov, copy=True
      )
      # Note: below we will set self.llf, and in the memory_no_likelihood
      # case we will replace self.llf_obs = None at that time.
      self.llf_obs = np.array(kalman_filter.loglikelihood, copy=True)
  
      # Diffuse objects
      self.nobs_diffuse = kalman_filter.nobs_diffuse
      self.initial_diffuse_state_cov = None
      self.forecasts_error_diffuse_cov = None
      self.predicted_diffuse_state_cov = None
      if self.nobs_diffuse > 0:
          self.initial_diffuse_state_cov = np.array(
              kalman_filter.model.initial_diffuse_state_cov, copy=True
          )
          self.predicted_diffuse_state_cov = np.array(
              kalman_filter.predicted_diffuse_state_cov, copy=True
          )
          if has_missing and not self.filter_collapsed:
              self.forecasts_error_diffuse_cov = np.array(
                  reorder_missing_matrix(
                      kalman_filter.forecast_error_diffuse_cov,
                      self.missing,
                      reorder_cols=True,
                      reorder_rows=True,
                      prefix=self.prefix,
                  )
              )
          else:
              self.forecasts_error_diffuse_cov = np.array(
                  kalman_filter.forecast_error_diffuse_cov, copy=True
              )
  
      # If there was missing data, save the original values from the Kalman
      # filter output, since below will set the values corresponding to
      # the missing observations to nans.
      self.missing_forecasts = None
      self.missing_forecasts_error = None
      self.missing_forecasts_error_cov = None
      if np.sum(self.nmissing) > 0:
          # Copy the provided arrays (which are as the Kalman filter dataset)
          # into new variables
          self.missing_forecasts = np.copy(self.forecasts)
          self.missing_forecasts_error = np.copy(self.forecasts_error)
          self.missing_forecasts_error_cov = np.copy(
              self.forecasts_error_cov
          )
  
      # Save the collapsed values
      self.collapsed_forecasts = None
      self.collapsed_forecasts_error = None
      self.collapsed_forecasts_error_cov = None
      if self.filter_collapsed:
          # Copy the provided arrays (which are from the collapsed dataset)
          # into new variables
          self.collapsed_forecasts = self.forecasts[: self.k_states, :]
          self.collapsed_forecasts_error = self.forecasts_error[
              : self.k_states, :
          ]
          self.collapsed_forecasts_error_cov = self.forecasts_error_cov[
              : self.k_states, : self.k_states, :
          ]
          # Recreate the original arrays (which should be from the original
          # dataset) in the appropriate dimension
          dtype = self.collapsed_forecasts.dtype
          self.forecasts = np.zeros(
              (self.k_endog, self.nobs), dtype=dtype
          )
          self.forecasts_error = np.zeros(
              (self.k_endog, self.nobs), dtype=dtype
          )
          self.forecasts_error_cov = np.zeros(
              (self.k_endog, self.k_endog, self.nobs), dtype=dtype
          )
  
      # Fill in missing values in the forecast, forecast error, and
      # forecast error covariance matrix (this is required due to how the
      # Kalman filter implements observations that are either partly or
      # completely missing)
      # Construct the predictions, forecasts
      can_compute_mean = not (
          self.memory_no_forecast_mean or self.memory_no_predicted_mean
      )
      can_compute_cov = not (
          self.memory_no_forecast_cov or self.memory_no_predicted_cov
      )
      if can_compute_mean or can_compute_cov:
          for t in range(self.nobs):
              design_t = 0 if self.design.shape[2] == 1 else t
              obs_cov_t = 0 if self.obs_cov.shape[2] == 1 else t
              obs_intercept_t = (
                  0 if self.obs_intercept.shape[1] == 1 else t
              )
  
              # For completely missing observations, the Kalman filter will
              # produce forecasts, but forecast errors and the forecast
              # error covariance matrix will be zeros - make them nan to
              # improve clarity of results.
              if self.nmissing[t] > 0:
                  mask = ~self.missing[:, t].astype(bool)
                  # We can recover forecasts
                  # For partially missing observations, the Kalman filter
                  # will produce all elements (forecasts, forecast errors,
                  # forecast error covariance matrices) as usual, but their
                  # dimension will only be equal to the number of non-missing
                  # elements, and their location in memory will be in the
                  # first blocks (e.g. for the forecasts_error, the first
                  # k_endog - nmissing[t] columns will be filled in),
                  # regardless of which endogenous variables they refer to
                  # (i.e. the non- missing endogenous variables for that
                  # observation). Furthermore, the forecast error covariance
                  # matrix is only valid for those elements. What is done is
                  # to set all elements to nan for these observations so that
                  # they are flagged as missing. The variables
                  # missing_forecasts, etc. then provide the forecasts, etc.
                  # provided by the Kalman filter, from which the data can be
                  # retrieved if desired.
                  if can_compute_mean:
                      self.forecasts[:, t] = (
                          np.dot(
                              self.design[:, :, design_t],
                              self.predicted_state[:, t],
                          )
                          + self.obs_intercept[:, obs_intercept_t]
                      )
                      self.forecasts_error[:, t] = np.nan
                      self.forecasts_error[mask, t] = (
                          self.endog[mask, t] - self.forecasts[mask, t]
                      )
                  # TODO: We should only fill in the non-masked elements of
                  # this array. Also, this will give the multivariate version
                  # even if univariate filtering was selected. Instead, we
                  # should use the reordering methods and then replace the
                  # masked values with NaNs
                  if can_compute_cov:
                      self.forecasts_error_cov[:, :, t] = (
                          np.dot(
                              np.dot(
                                  self.design[:, :, design_t],
                                  self.predicted_state_cov[:, :, t],
                              ),
                              self.design[:, :, design_t].T,
                          )
                          + self.obs_cov[:, :, obs_cov_t]
                      )
              # In the collapsed case, everything just needs to be rebuilt
              # for the original observed data, since the Kalman filter
              # produced these values for the collapsed data.
              elif self.filter_collapsed:
                  if can_compute_mean:
                      self.forecasts[:, t] = (
                          np.dot(
                              self.design[:, :, design_t],
                              self.predicted_state[:, t],
                          )
                          + self.obs_intercept[:, obs_intercept_t]
                      )
  
                      self.forecasts_error[:, t] = (
                          self.endog[:, t] - self.forecasts[:, t]
                      )
  
                  if can_compute_cov:
                      self.forecasts_error_cov[:, :, t] = (
                          np.dot(
                              np.dot(
                                  self.design[:, :, design_t],
                                  self.predicted_state_cov[:, :, t],
                              ),
                              self.design[:, :, design_t].T,
                          )
                          + self.obs_cov[:, :, obs_cov_t]
                      )
  
      # Note: if we concentrated out the scale, need to adjust the
      # loglikelihood values and all of the covariance matrices and the
      # values that depend on the covariance matrices
      # Note: concentrated computation is not permitted with collapsed
      # version, so we do not need to modify collapsed arrays.
      self.scale = 1.0
      if self.filter_concentrated and self.model._scale is None:
          d = max(self.loglikelihood_burn, self.nobs_diffuse)
          # Compute the scale
          nmissing = np.array(kalman_filter.model.nmissing)
          nobs_k_endog = np.sum(self.k_endog - nmissing[d:])
  
          # In the univariate case, we need to subtract observations
          # associated with a singular forecast error covariance matrix
          nobs_k_endog -= kalman_filter.nobs_kendog_univariate_singular
  
          scale_obs = np.array(kalman_filter.scale, copy=True)
          if not self.memory_no_likelihood:
              self.scale = np.sum(scale_obs[d:]) / nobs_k_endog
          else:
              self.scale = scale_obs[0] / nobs_k_endog
  
          # Need to modify this for diffuse initialization, since for
          # diffuse periods we only need to add in the scale value if the
          # diffuse forecast error covariance matrix element was singular
          nsingular = 0
          if kalman_filter.nobs_diffuse > 0:
              Finf = kalman_filter.forecast_error_diffuse_cov
              singular = (
                  np.diagonal(Finf).real
                  <= kalman_filter.tolerance_diffuse
              )
              nsingular = np.sum(~singular, axis=1)
  
          # Adjust the loglikelihood obs (see `KalmanFilter.loglikeobs` for
          # defaults on the adjustment)
          if not self.memory_no_likelihood:
              self.llf_obs += -0.5 * (
                  (self.k_endog - nmissing - nsingular)
                  * np.log(self.scale)
                  + scale_obs / self.scale
              )
          else:
              self.llf_obs[0] += -0.5 * np.squeeze(
                  np.sum(
                      (self.k_endog - nmissing - nsingular)
                      * np.log(self.scale)
                  )
                  + scale_obs / self.scale
              )
  
          # Scale the filter output
          self.obs_cov = self.obs_cov * self.scale
          self.state_cov = self.state_cov * self.scale
  
          self.initial_state_cov = self.initial_state_cov * self.scale
          self.predicted_state_cov = (
              self.predicted_state_cov * self.scale
          )
          self.filtered_state_cov = self.filtered_state_cov * self.scale
          self.forecasts_error_cov = (
              self.forecasts_error_cov * self.scale
          )
          if self.missing_forecasts_error_cov is not None:
              self.missing_forecasts_error_cov = (
                  self.missing_forecasts_error_cov * self.scale
              )
  
          # Note: do not have to adjust the Kalman gain or tmp4
          self.tmp1 = self.tmp1 * self.scale
          self.tmp2 = self.tmp2 / self.scale
          self.tmp3 = self.tmp3 / self.scale
          if not (
              self.memory_no_std_forecast
              or self.invert_lu
              or self.solve_lu
              or self.filter_collapsed
          ):
              self._standardized_forecasts_error = (
                  self._standardized_forecasts_error / self.scale**0.5
              )
      # The self.model._scale value is only not None within a fixed_scale
      # context, in which case it is set and indicates that we should
      # generally view this results object as using a concentrated scale
      # (e.g. for d.o.f. computations), but because the fixed scale was
      # actually applied to the model prior to filtering, we do not need to
      # make any adjustments to the filter output, etc.
      elif self.model._scale is not None:
          self.filter_concentrated = True
          self.scale = self.model._scale
  
      # Now, save self.llf, and handle the memory_no_likelihood case
      if not self.memory_no_likelihood:
          self.llf = np.sum(self.llf_obs[self.loglikelihood_burn :])
      else:
          self.llf = self.llf_obs[0]
          self.llf_obs = None
  
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 3 for calling the FilterResults obj's underlying member method code with example usage: obj.update_filter(kalman_filter) without return types