docstr: This model implements a Kalman filter over a time series.
  
  The key method is `KalmanFilter.filter()`.
  It considers the provided time series as containing (possibly noisy) observations z obtained from a
  (possibly noisy) linear dynamical system with hidden state x. The function `filter(series)` returns a new
  `TimeSeries` describing the distribution of the output z (without noise), as inferred by the Kalman filter from
  sequentially observing z from `series`, and the dynamics of the linear system of order dim_x.
  
  This filter also supports missing values in the observation series, in which case the underlying
  Kalman filter will carry on using its mean estimate.
  
  The method `KalmanFilter.fit()` is used to initialize the Kalman filter by estimating the state space model of
  a linear dynamical system and the covariance matrices of the process and measurement noise using the N4SID
  algorithm.
  
  This implementation uses Kalman from the NFourSID package. More information can be found here:
  https://nfoursid.readthedocs.io/en/latest/source/kalman.html.
  
  The dimensionality of the measurements z and optional control signal (covariates) u is automatically inferred
  upon calling `filter()`.
  
  Parameters
  ----------
  dim_x : int
      Size of the Kalman filter state vector.
  kf : nfoursid.kalman.Kalman
      Optionally, an instance of `nfoursid.kalman.Kalman`.
      If this is provided, the parameter dim_x is ignored. This instance will be copied for every
      call to `filter()`, so the state is not carried over from one time series to another across several
      calls to `filter()`.
      The dimensionalities of the filter must match those of the `TimeSeries` used when calling `filter()`.
docstr_tok: ["This","model","implements","a","Kalman","filter","over","a","time","series",".","The","key","method","is","`","KalmanFilter.filter","(",")","`",".","It","considers","the","provided","time","series","as","containing","(","possibly","noisy",")","observations","z","obtained","from","a","(","possibly","noisy",")","linear","dynamical","system","with","hidden","state","x",".","The","function","`","filter","(","series",")","`","returns","a","new","`","TimeSeries","`","describing","the","distribution","of","the","output","z","(","without","noise",")",",","as","inferred","by","the","Kalman","filter","from","sequentially","observing","z","from","`","series","`",",","and","the","dynamics","of","the","linear","system","of","order","dim_x",".","This","filter","also","supports","missing","values","in","the","observation","series",",","in","which","case","the","underlying","Kalman","filter","will","carry","on","using","its","mean","estimate",".","The","method","`","KalmanFilter.fit","(",")","`","is","used","to","initialize","the","Kalman","filter","by","estimating","the","state","space","model","of","a","linear","dynamical","system","and","the","covariance","matrices","of","the","process","and","measurement","noise","using","the","N4SID","algorithm",".","This","implementation","uses","Kalman","from","the","NFourSID","package",".","More","information","can","be","found","here",":","https",":","\/\/nfoursid.readthedocs.io\/en\/latest\/source\/kalman.html",".","The","dimensionality","of","the","measurements","z","and","optional","control","signal","(","covariates",")","u","is","automatically","inferred","upon","calling","`","filter","(",")","`",".","Parameters","--","--","--","--","--","dim_x",":","int","Size","of","the","Kalman","filter","state","vector",".","kf",":","nfoursid.kalman.Kalman","Optionally",",","an","instance","of","`","nfoursid.kalman.Kalman","`",".","If","this","is","provided",",","the","parameter","dim_x","is","ignored",".","This","instance","will","be","copied","for","every","call","to","`","filter","(",")","`",",","so","the","state","is","not","carried","over","from","one","time","series","to","another","across","several","calls","to","`","filter","(",")","`",".","The","dimensionalities","of","the","filter","must","match","those","of","the","`","TimeSeries","`","used","when","calling","`","filter","(",")","`","."]
code: def __init__(self, dim_x: int = 1, kf: Optional[Kalman] = None):
      """
      This model implements a Kalman filter over a time series.
  
      The key method is `KalmanFilter.filter()`.
      It considers the provided time series as containing (possibly noisy) observations z obtained from a
      (possibly noisy) linear dynamical system with hidden state x. The function `filter(series)` returns a new
      `TimeSeries` describing the distribution of the output z (without noise), as inferred by the Kalman filter from
      sequentially observing z from `series`, and the dynamics of the linear system of order dim_x.
  
      This filter also supports missing values in the observation series, in which case the underlying
      Kalman filter will carry on using its mean estimate.
  
      The method `KalmanFilter.fit()` is used to initialize the Kalman filter by estimating the state space model of
      a linear dynamical system and the covariance matrices of the process and measurement noise using the N4SID
      algorithm.
  
      This implementation uses Kalman from the NFourSID package. More information can be found here:
      https://nfoursid.readthedocs.io/en/latest/source/kalman.html.
  
      The dimensionality of the measurements z and optional control signal (covariates) u is automatically inferred
      upon calling `filter()`.
  
      Parameters
      ----------
      dim_x : int
          Size of the Kalman filter state vector.
      kf : nfoursid.kalman.Kalman
          Optionally, an instance of `nfoursid.kalman.Kalman`.
          If this is provided, the parameter dim_x is ignored. This instance will be copied for every
          call to `filter()`, so the state is not carried over from one time series to another across several
          calls to `filter()`.
          The dimensionalities of the filter must match those of the `TimeSeries` used when calling `filter()`.
      """
      # TODO: Add support for x_init. Needs reimplementation of NFourSID.
  
      super().__init__()
  
      if kf is None:
          self.kf = None
          self.dim_x = dim_x
          self._kf_provided = False
      else:
          self.kf = kf
          self.dim_u = kf.state_space.u_dim
          self.dim_x = kf.state_space.x_dim
          self.dim_y = kf.state_space.y_dim
          self._kf_provided = True
          if self.dim_u > 0:
              self._expect_covariates = True
  
file_path: darts/darts/models/filtering/kalman_filter.py
imports: from abc import ABC
  from copy import deepcopy
  from typing import Optional
  import numpy
  import pandas
  from nfoursid.kalman import Kalman
  from nfoursid.nfoursid import NFourSID
  from darts.logging import raise_if, raise_if_not
  from darts.models.filtering.filtering_model import FilteringModel
  from darts.timeseries import TimeSeries
label_desc: Use image node_id 1 to create a new KalmanFilter object from inherited base classes: FilteringModel, ABC with example: obj = KalmanFilter(dim_x, kf)