name: ParticleFilter : public AlgorithmBase
synopsis:

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

>     #include <ParticleFilter.h>

>     ParticleFilter(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, long order);
>     boolean eq(const ParticleFilter& arg);
>     boolean setAlgorithm(ALGORITHM algorithm);
>     boolean setOrder(long order);
>     boolean setNoise(Float process_noise, Float obsn_noise, Float err_noise);

quick start:

>     ParticleFilter pf;
>     VectorFloat input(L"1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15");
>     VectorFloat output;
>     pf.setAlgorithm(CONVENTIONAL);
>     pf.setImplementation(AR_SCALAR);
>     pf.setOrder(8);
>     pf.compute(output, input);

description:
The ParticleFilter 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.

R. van der Merve, N. de Freitas, A. Doucet, and E. Wan, "The Unscented Particle Filter," >i>Technical Report CUED/F-INFENG/TR 380, Cambridge University Engineering Department, Cambridge University, U.K., August 2000

N. Arulampalam, S. Maskell, N. Gordan, and T. Clapp, "Tutorial On Particle Filters For Online Nonlinear/ Non-Gaussian Bayesian Tracking," IEEE Transactions on Signal Processing, vol. 50, no. 2, pp. 174-188, February 2002.

This class currently supports one algorithm choice: CONVENTIONAL and one implementation choice: AR_SCALAR. 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 are specified by the user using the setNoise() method..
dependencies:

- AlgorithmBase
- CircularDelayLine
- Prediction

public constants:

- define the class name:

      static const String CLASS_NAME = L"ParticleFilter";

- 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_PROCESS_NOISE = L"process_noise";

      static const String PARAM_OBSN_NOISE = L"obsn_noise";

      static const String PARAM_ERR_NOISE = L"err_noise";

      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 = 8;

      static const float DEF_PROCESS_NOISE = -1.00;

      static const float DEF_OBSN_NOISE = -1.00;

      static const float DEF_ERR_NOISE = -1.00;

- define default argument(s):

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

error codes:

- error code indicating ParticleFilter class general error:

      static const long ERR_DIMEN = 73300;

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:

        MatrixFloat model_trn_d;

        MatrixFloat model_obs_d;

  - define output and input data:

        MatrixFloat state_d;

        MatrixFloat obsn_d;

  - define noise covariances - process, observation, and error:

        MatrixFloat covar_nse_pro_d;

        MatrixFloat covar_nse_obs_d;

        MatrixFloat covar_err_est_d;

  - define kalman gain:

        MatrixFloat gain_d;

  - static memory manager:

        static MemoryManager mgr_d;

- algorithm and implementation specific variables:
- define weights associated with data and its covariances:

      VectorFloat weights_m_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):

      ~ParticleFilter();

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

      ParticleFilter(const ParticleFilter& arg);

- assign methods:

      boolean assign(const ParticleFilter& arg);

- operator= methods:

      ParticleFilter& operator= (const ParticleFilter& 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 ParticleFilter& 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:

- set methods:

      boolean setAlgorithm(ALGORITHM algorithm);

      boolean setImplementation(IMPLEMENTATION implementation);

      boolean setOrder(float floor = DEF_ORDER);

      boolean setObservation(VectorFloat& data);

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

- get methods:

      ALGORITHM getAlgorithm() const;

      IMPLEMENTATION getImplementation() const;

      VectorFloat getInitialState() const;

      float getOrder() const;

      MatrixFloat getState() const;

      MatrixFloat getTransitionModel() const;

      MatrixFloat getObservationModel() const;

      MatrixFloat getProcessNoise() const;

      MatrixFloat getObsnNoise() const;

      MatrixFloat getEstimateError() const;

      MatrixFloat getNoise() const;

      MatrixFloat getTimeIndex() const;

      MatrixFloat getObservation() const;

      MatrixFloat getResult() const;

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

- computational methods:

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

      boolean computeStates();

- 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:

- filter i/o methods:

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

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

- class-specific computational methods

      boolean computePredictState();

      boolean computePredictEstimateErrCovar();

      boolean computeCorrectKalmanGain();

      boolean computeCorrectState();

      boolean computeCorrectEstimateErrCovar();

      boolean computeLPC(VectorFloat& autoc, VectorFloat& lpc);

      boolean computeAutoCorrelation(VectorFloat& data, VectorFloat& autoc, int arr_size);

      boolean computeNoiseVariance(VectorFloat& autoc, VectorFloat& lpc, Float& noise_variance);

      boolean initializeTransitionModel((VectorFloat lpc);

      boolean initializeNoiseVariances(Float& noise_variance);

      boolean initializeInitialState(int i, VectorFloat& buf);

      boolean initializeObservationModel();

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

        // declare an ParticleFilter object and an output vector
        //
        ParticleFilter pf;
        VectorFloat output;

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

        // choose algorithm
        //
        pf.setAlgorithm(ParticleFilter::CONVENTIONAL);

        // choose implementation
        //
        pf.setImplementation(ParticleFilter::AR_SCALAR);

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

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

        // compute the energy of input data
        //
        pf.compute(output, input);

    notes:
    - none.