name: Covariance : public AlgorithmBase
synopsis:

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

>     #include <Covariance.h>

>     Covariance(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, NORMALIZATION normalization = DEF_NORMALIZATION, long order = DEF_ORDER);
>     boolean eq(const Covariance& arg) const;
>     boolean compute(MatrixFloat& output, const VectorFloat& input);

quick start:

>     VectorFloat input(L"1.0, 2.0, 3.0, 4.0, 5.0");
>     MatrixFloat output;
>     Covariance cov(4);
>     cov.compute(output, input);

description:
The Covariance class is used to compute a covariance matrix from signal and feature vectors. This class is similar in design and function to the Correlation class. A good overview of covariance methods can be found in:

L. Rabiner and R. Schafer, Digital Processing of Speech Signals, Prentice-Hall, Englewood Cliffs, New Jersey, USA, pp. 396, 1976.

The mathematical descriptions of these algorithms are provided below for reference purposes:
Two implementations are supported: factored and unfactored. The unfactored implementation is described in:

J.D. Markel and A.H. Gray, Jr., Linear Prediction of Speech, Springer-Verlag, New York, New York, USA, pp. 51, 1976.

The factored approach is a computationally efficient algorithm described in:

J.D. Markel and A.H. Gray, Jr., Linear Prediction of Speech, Springer-Verlag, New York, New York, USA, pp. 220, 1976.

The factored and unfactored approaches produce the same result.
This class supports two computational modes. In FRAME_INTERNAL mode, a covariance matrix is computed on a single vector of data, contained within the current analysis frame. One matrix is output per frame. On the other hand, in ACCUMULATE mode, a single covariance matrix is computed across a sequence of frames. One covariance matrix is returned per file. The latter mode is typically used by speech recognition systems to compute covariances of feature vectors.
dependencies:

- AlgorithmBase

public constants:

- define the class name:

      static const String CLASS_NAME = L"Covariance";

- define the algorithm choices:

      enum ALGORITHM { NORMAL = 0, DEF_ALGORITHM = NORMAL };

- define the implementation choices:

      enum IMPLEMENTATION { FACTORED = 0, UNFACTORED, DEF_IMPLEMENTATION = FACTORED };

- define normalization choices:

      enum NORMALIZATION { NONE = 0, LENGTH, UNIT_ENERGY, DEF_NORMALIZATION = NONE };

- define algorithm name maps:

      static const NameMap Covariance::ALGO_MAP(L"NORMAL");

      static const NameMap Covariance::IMPL_MAP(L"FACTORED, UNFACTORED");

      static const NameMap NORM_MAP = L"NONE, LENGTH, UNIT_ENERGY";

- define i/o related variables:

      static const String Covariance::DEF_PARAM = L"";

      static const String Covariance::PARAM_ALGORITHM = L"algorithm";

      static const String Covariance::PARAM_IMPLEMENTATION = L"implementation";

      static const String Covariance::PARAM_MODE = L"mode";

      static const String Covariance::PARAM_NORMALIZATION = L"normalization";

      static const String Covariance::PARAM_ORDER = L"order";

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

      static const long DEF_ORDER = (long)-1;

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

error codes:

- error code indicating Covariance class general error:

      static const long ERR = 70400;

protected data:

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

        ALGORITHM algorithm_d;

  - implementation type:

        IMPLEMENTATION implementation_d;

  - normalization type:

        NORMALIZATION normalization_d;

  - analysis order:

        Long order_d;

  - specific variables for accumulation update:

        Vector>MatrixFloat< accum_cov_d;

        Vector>VectorFloat< accum_sum_d;

        Long accum_frame_d;

  - static memory manager:

        static MemoryManager mgr_d;

- algorithm and implementation specific variables:
  none.

required public methods:

- static methods:

      static const String& name();

      static boolean diagnose(Integral::DEBUG debug_level);

- debug methods: setDebug method is inherited from the base class

      boolean debug(const unichar* message) const;

- destructor/constructor(s):

      ~Covariance();

      Covariance(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, NORMALIZATION normalization = DEF_NORMALIZATION, long order = DEF_ORDER);

      Covariance(const Covariance& arg);

- assign methods:

      boolean assign(const Covariance& arg);

- operator= methods:

      Covariance& operator= (const Covariance& 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, constString& pname = DEF_PARAM) const;

- equality methods:

      boolean eq(const Covariance& 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 setNormalization(NORMALIZATION normalization);

      boolean setOrder(long order);

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

- get methods:

      ALGORITHM getAlgorithm() const;

      IMPLEMENTATION getImplementation() const;

      NORMALIZATION getNormalization() const;

      long getOrder() const;

      boolean get(ALGORITHM& algorithm, IMPLEMENTATION& implementation, NORMALIZATION& normalization, long& order) const;

- computational methods:

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

      boolean compute(MatrixComplexFloat& output, const VectorFloat& 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;

      boolean const String& className() const;

      boolean init();

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

      long getLeadingPad() const;

      long getTrailingPad() const;

      boolean setParser(SofParser* parser);

private methods:

- common i/o methods:

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

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

- algorithm-specific compute methods: Normal (FRAME_INTERNAL)

      boolean computeNormalFactored(MatrixFloat& covcoeff, const VectorFloat& input);

      boolean computeNormalUnFactored(MatrixFloat& covcoeff, const VectorFloat& input);

- algorithm-specific compute methods: Normal (ACCUMULATE)

      boolean computeAccumulate(MatrixFloat& output, const VectorFloat& input, long chan);

examples:

- This example shows how to compute the covariance for a given function:

      // declare the Covariance object
      //
      Covariance cov;

      // declare the input and output vectors
      //
      VectorFloat input;
      MatrixFloat output;

      // calculate the covariance for the following function
      // x(n) = 0 when n = 0, 1, 2, 3;
      // x(n) = pow(0.9, 2(n-4)) - pow(0.9, (n-4)),  when 4 <= n < 20;
      // x(n) = 0 when n = 20, 21, 22, 23
      //
      input.setLength(24);

      double z = 1;
      for (long i = 4; i < 20; i++) {
        input(i) = z * z - z;
        z = 0.9 * z;
      }

      // set the order
      //
      cov.setOrder(4);

      // compute the output
      //
      cov.compute(output, input);

notes:

- none.