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:

Digital Processing of Speech Signals

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:

Linear Prediction of Speech

The factored approach is a computationally efficient algorithm described in:

Linear Prediction of Speech

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.