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:

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:

protected data:

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.