name: KalmanFilter : public AlgorithmBase
synopsis:

>     g++ [flags ...] file ... -l /isip/tools/lib/$ISIP_BINARY/lib_algo.a

>     #include <KalmanFilter.h>

>     KalmanFilter(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, long order);
>     boolean eq(const KalmanFilter& arg);
>     boolean setAlgorithm(ALGORITHM algorithm);
>     boolean setOrder(long order);
>     boolean setNoise(double covar_nse_pro, double covar_nse_obs, double covar_err_est);
>     boolean setParameter(double alpha, double beta, double kappa);

quick start:

>     KalmanFilter kf;
>     VectorDouble input(L"1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15");
>     VectorDouble output;
>     kf.setAlgorithm(CONVENTIONAL);
>     kf.setImplementation(AR_SCALAR);
>     kf.setNoise(0.03, 0.02, 0.0001);
>     kf.setOrder(8);
>     kf.compute(output, input);

description:
The KalmanFilter class is used to filter the speech signal in presence of noise. The speech signal is modeled by state-space model. The two reference documents were used to implement the algorithm for filtering of speech.

M. Gabrea, "Adaptive Kalman Filtering-Based Speech Enhancement Algorithm," IEEE conference on audio and speech signal processing, pp I-314-I317, 2004.

K. Paliwal, "A noise-compesated long correlation matching methods for AR spectral estimation of noisy signals," IEEE Conference on Audio and Speech Singal Processing, ICASSP 1986, Tokyo, Japan, pp 1369-1372, 1986.

These are the couple of references which will help in understanding of Kalman filter.

G. Welch and G. Bishop, "An Introduction to the Kalman filter," Technical report TR 95-041,Department of Computer Science, University of North Carolina at Chapel Hill, Chapel Hill, NC, USA, April 2004.

P. Joseph, Kalman Filters

The unscented Kalman filter implementation is based on

E. Wan and R. Merwe, "The Unscented Kalman Filter for Nonlinear Estimation," Adaptive Systems for Signal Processing, Communications, and Control Symposium 2000, AP-SPCC, pp. 153-159.

This class currently supports two algorithm choice: CONVENTIONAL and UNSCENTED. It is described in detail in the above two references. The state-space equations used to model the speech signals are shown below:
The filter order can be specified by the user using the setOrder() method. Other parameters that need to be specified are process noise covariance, observation noise covariance, and error estimate covariance by using the setParameter() method.
dependencies:

- AlgorithmBase
- CircularDelayLine
- Prediction

public constants:

- define the class name:

      static const String CLASS_NAME = L"KalmanFilter";

- define the algorithm choices:

      enum ALGORITHM { CONVENTIONAL = 0, UNSCENTED, DEF_ALGORITHM = CONVENTIONAL};

- define the implementation choices:

      enum IMPLEMENTATION { AR_SCALAR, AR_VECTOR, DEF_IMPLEMENTATION = AR_SCALAR };

- define the static NameMap objects:

      static const NameMap ALGO_MAP(L"CONVENTIONAL, UNSCENTED");

      static const NameMap IMPL_MAP(L"AR_SCALAR, AR_VECTOR");

- define i/o related constants:

      static const String DEF_PARAM = L"";

      static const String PARAM_ALGORITHM = L"algorithm";

      static const String PARAM_IMPLEMENTATION = L"implementation";

      static const String PARAM_FLOOR = L"order";

      static const String PARAM_NOISE_PRC = L"process_noise";

      static const String PARAM_NOISE_OBS = L"obsn_noise";

      static const String PARAM_NOISE_ERR = L"estimate_eror";

      static const String PARAM_ALPHA = L"alpha";

      static const String PARAM_BETA = L"beta";

      static const String PARAM_KAPPA = L"kappa";

- define default value(s) of the class data:

      static const long DEF_ORDER = -1;

      static const double DEF_PROCESS_NOISE = -1.00;

      static const double DEF_OBSN_NOISE = -1.00;

      static const double DEF_ERR_NOISE = -1.00;

      static const double DEF_ALPHA = -1.00;

      static const double DEF_BETA = -1.00;

      static const double DEF_KAPPA = -1.00;

      static const VectorDouble DEF_STATE_MEM(L"1");

      static const VectorDouble DEF_OBS(L"-1");

      static const MatrixDouble DEF_TRN(1, 1, L"0", Integral::FULL);

- define default argument(s):

      static const AlgorithmData::COEF_TYPE DEF_COEF_TYPE = AlgorithmData::SIGNAL;

error codes:

- error code indicating KalmanFilter class general error:

      static const long ERR = 73300;

      static const long ERR_MISDIM = 73301;

      static const long ERR_UNIPAR = 73302;

protected data:

- data common to all algorithms and implementations:
  - define an algorithm name:

        ALGORITHM algorithm_d;

  - define an implementation name:

        IMPLEMENTATION implementation_d;

  - define a filter order:

        Long order_d;

  - define transition model and observation model:

        MatrixDouble trn_d;

        VectorDouble obs_d;

  - define a buffer to hold the history of the filter

        VectorDouble state_mem_d;

  - define parameters for noise modeling:

        MatrixDouble covar_nse_pro_d;

        double covar_nse_obs_d;

        MatrixDouble covar_err_est_d;

  - define a buffer for filtered data

         VectorDouble data_filt_d;

  - algorithm and implementation specific variables: data specific to unscented algorithm:
  - define parameters to fine tune the filter

         Double alpha_d;

         Double beta_d;

         Double kappa_d;

         Double lambda_d;

  - static memory manager:

        static MemoryManager mgr_d;

required public methods:

- static methods:

      static const String& name();

      static boolean diagnose(Integral::DEBUG debug_level);

- debug methods: setDebug method is inherited from base class

      boolean debug(const unichar* message) const;

- destructor/constructor(s):

      ~KalmanFilter();

      KalmanFilter(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, long order);

      KalmanFilter(const KalmanFilter& arg);

- assign methods:

      boolean assign(const KalmanFilter& arg);

- operator= methods:

      KalmanFilter& operator= (const KalmanFilter& arg);

- i/o methods:

      long sofSize() const;

      boolean read(Sof& sof, long tag, const String& name = CLASS_NAME);

      boolean write(Sof& sof, long tag, const String& name = CLASS_NAME) const;

      boolean readData(Sof& sof, const String& pname = DEF_PARAM, long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = false);

      boolean writeData(Sof& sof, const String& pname = DEF_PARAM) const;

- equality methods:

      boolean eq(const KalmanFilter& arg) const;

- memory management methods:

      static void* operator new(size_t size);

      static void* operator new[](size_t size);

      static void operator delete(void* ptr);

      static void operator delete[](void* ptr);

      static boolean setGrowSize(long grow_size);

      boolean clear(Integral::CMODE ctype = Integral::DEF_CMODE);

class-specific public methods:

- standard set methods:

      boolean setAlgorithm(ALGORITHM algorithm);

      boolean setImplementation(IMPLEMENTATION implementation);

- set methods for both CONVENTIONAL and UNSCENTED algorithms:

      boolean setOrder(double floor = DEF_ORDER);

      boolean setProcessNoise(double covar_nse_pro);

      boolean setObsnNoise(double covar_nse_obs);

      boolean setEstimateError(double covar_err_est);

      boolean setNoise(double covar_nse_pro, double covar_nse_obs, double covar_err_est);

      boolean setInitialState(VectorDouble& state_mem = DEF_STATE_MEM);

      boolean setTransitionModel(MatrixDouble trn = DEF_TRN);

      boolean setObsnModel(VectorDouble obs = DEF_OBS);

      boolean setModel(MatrixDouble trn = DEF_TRN, VectorDouble obs = DEF_OBS);

- set methods specific to unscented kalman filter:

      boolean setAlpha(double alpha = DEF_ALPHA);

      boolean setBeta(double beta = DEF_BETA);

      boolean setKappa(double kappa = DEF_KAPPA);

      boolean setParameters(double alpha = DEF_ALPHA, double beta = DEF_BETA, double kappa = DEF_KAPPA);

      boolean setKF(long order, double covar_nse_pro, double covar_nse_obs, double covar_err_est, VectorDouble state_mem = DEF_STATE_MEM);

- set methods specific to conventional kalman filter

      boolean setKF(VectorDouble& covar_nse_pro, double covar_nse_obs, MatrixDouble& covar_err_est, VectorDouble state_mem = DEF_STATE_MEM, MatrixDouble trn = DEF_TRN, VectorDouble obs = DEF_OBS);

- set methods specific to unscented kalman filter

      boolean setUKF(long order, double covar_nse_pro, double covar_nse_obs, double covar_err_est, VectorDouble state_mem = DEF_STATE_MEM, double alpha = DEF_ALPHA, double beta = DEF_BETA, double kappa = DEF_KAPPA);

      boolean setUKF(VectorDouble& covar_nse_pro, double covar_nse_obs, MatrixDouble& covar_err_est, VectorDouble state_mem = DEF_STATE_MEM, MatrixDouble trn = DEF_TRN, VectorDouble obs = DEF_OBS, double alpha = DEF_ALPHA, double beta = DEF_BETA, double kappa = DEF_KAPPA);

- other set methods

      boolean set(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, long order = DEF_ORDER);

- standard get methods:

      ALGORITHM getAlgorithm() const;

      IMPLEMENTATION getImplementation() const;

- methods applicable to both conventional and unscented kalman filter

      double getOrder() const;

      boolean getInitialState(VectorDouble& state_mem) const;

       boolean getTransitionModel(MatrixDouble& trn) const;

      boolean getObservationModel(VectorDouble& obs) const;

      boolean getModel(MatrixDouble& trn, VectorDouble& obs ) const;

      boolean getProcessNoise(VectorDouble& covar_nse_pro) const;

      boolean getObservationNoise(double covar_nse_obs) const;

      boolean getEstimateError(MatrixDouble& covar_err_est) const;

      boolean getNoise(VectorDouble& covar_nse_pro, double covar_nse_obs, MatrixDouble& covar_err_est) const;

- get method for unscented kalman filter

      boolean getAlpha(double alpha) const;

      boolean getBeta(double beta) const;

      boolean getKappa(double kappa) const;

      boolean getParameters(double alpha, double beta, double kappa) const;

- get method for getting clean signal

      boolean getResult(VectorDouble& data_filt) const;

- other get methods

      boolean get(ALGORITHM& algorithm, IMPLEMENTATION& implementation, Long& order);

- computational methods:

      boolean compute(VectorDouble& output, const VectorDouble& input, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, long index = DEF_CHANNEL_INDEX);

      boolean compute(VectorComplexDouble& output, const VectorComplexDouble& input, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, long index = DEF_CHANNEL_INDEX);

- AlgorithmBase interface contract methods:

      boolean assign(const AlgorithmBase& arg);

      boolean eq(const AlgorithmBase& arg) const;

      const String& className() const;

      boolean init();

      boolean apply(Vector<AlgorithmData>& output, const Vector<AlgorithmData>& input);

      boolean setParser(SofParser* parser);

private methods:

- common i/o methods:

      boolean readDataKalmanFilter(Sof& sof, const String& pname, long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = false);

      boolean writeDataKalmanFilter(Sof& sof, const String& pname) const;

- class-specific computational methods - algorithm : CONVENTIONAL

      boolean computeStates(const VectorDouble& obsn, VectorDouble& filtered_data);

      boolean initializeTransitionModel(const VectorDouble& obsn);

      boolean matrixSqrt(MatrixDouble& mat_in, MatrixDouble& mat_sqrt);

  examples:
  - This example shows how to get the filtered speech by using the CONVENTIONAL algorithm:

        // declare an KalmanFilter object and an output vector
        //
        KalmanFilter kf;
        VectorDouble output;

        // set the input vector
        //
        VectorDouble input(L"0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15");

        // choose algorithm
        //
        kf.setAlgorithm(KalmanFilter::CONVENTIONAL);

        // choose implementation
        //
        kf.setImplementation(KalmanFilter::AR_SCALAR);

        // set the process noise covariance, observation noise covariance,
        // estimate error covariance
        kf.setNoise(0.01, 0.06, 1.0);

        // set the order
        //
        kf.setOrder(8);

        // compute filtered signal
        //
        kf.compute(output, input);

    notes:
    - none.