name: Correlation : public AlgorithmBase

synopsis:

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

#include <Correlation.h>

Correlation(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, NORMALIZATION normalization = DEF_NORMALIZATION, long order = DEF_ORDER);
boolean eq(const Correlation& arg);
boolean assign(const Correlation& arg);
boolean setAlgorithm(ALGORITHM algorithm);
boolean setNormalization(NORMALIZATION normalization);
boolean setOrder(long order);
boolean compute(VectorFloat& output, const VectorFloat& input, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE);

quick start:

VectorFloat input(L"1.0, 2.0, 3.0, 4.0, 5.0");
VectorFloat output;
Correlation corr(3);
corr.compute(output, input);

description:

The Correlation class implements three types of correlation operations: autocorrelation (including a tapered version intended to reduce bias), cross-correlation, and convolution. A good overview of correlation operators can be found in:

Digital Signal Processing: Principles, Algorithms, and Applications

The mathematical descriptions of the algorithms implemented in this class are shown below:

The only design parameter relevant to this class is the analysis order, which only applies to the autocorrelation algorithm choice.

The autocorrelation algorithm choice, denoted AUTO, supports computations using various data types including signals and linear prediction coefficients. Two computation modes are supported: factored and unfactored. Unfactored is the standard dot product formulation. The factored implementation is a computationally efficient approach described in:

Linear Prediction of Speech

Conversions from linear prediction coefficients to correlation functions are also supported using recursions described in:

Digital Processing of Speech Signals

The convolution and cross-correlation algorithms are described in:

Digital Signal Processing: Principles, Algorithms, and Applications

The convolution and cross-correlation algorithms do not support a FACTORED implementation, and operate only on signal data.

The result of these computations can be scaled using the normalization mode. LENGTH simply divides the result by the number of samples used to compute each term in the computation. For the algorithm AUTO_TAPERED, this is the length of the vector minus the lag value (e.g., N-i). UNIT_ENERGY scales the result so that the energy of the signal is unity.

dependencies:

AlgorithmBase

public constants:

define the class name:

static const String CLASS_NAME = L"Correlation";

define algorithm choices:

enum ALGORITHM { AUTO = 0, TAPERED_AUTO, CROSS, CONV, DEF_ALGORITHM = AUTO };

define implementation choices:

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

define mode choices:

the mode choices are defined in an enumeration in the base class

define normalization choices:

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

define static NameMap objects:

static const NameMap ALGO_MAP = L"AUTO, TAPERED_AUTO, CROSS, CONV";

static const NameMap IMPL_MAP = L"FACTORED, UNFACTORED, CIRCULAR";

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

define i/o related constants:

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

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

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

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

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

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

define default value(s) of the class data:
```
static const long DEF_ORDER = -1;
```

define default argument(s):

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

error codes:

general error codes:

static const long ERR = 70100;

static const long ERR_INPUT = 70101;

static const long ERR_DATA = 70102;

static const long ERR_STABLE = 70103;

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;

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

~Correlation();

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

Correlation(const Correlation& arg);

assign methods:
```
boolean assign(const Correlation& arg);
```

operator= methods:

Correlation& operator= (const Correlation& 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 Correlation& 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);

computational methods:

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

boolean compute(VectorFloat& output, const VectorFloat& input1, const VectorFloat& input2, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, long channel_index = DEF_CHANNEL_INDEX);

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

boolean compute(VectorComplexFloat& output, const VectorComplexFloat& input1, const VectorComplexFloat& input2, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, long channel_index = DEF_CHANNEL_INDEX);

AlgorithmBase interface contract methods:

boolean assign(const AlgorithmBase& arg);

boolean eq(const AlgorithmBase& arg) const;

const String& className() const;

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

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) const;

algorithm-specific computation methods: signals

boolean computeAutoFactoredFromSignal(VectorFloat& output, const VectorFloat& input);

boolean computeAutoUnfactoredFromSignal(VectorFloat& output, const VectorFloat& input);

algorithm-specific computation methods: linear prediction models

boolean computeAutoFromPrediction(VectorFloat& output, const VectorFloat& input);

boolean computeAutoFromReflection(VectorFloat& output, const VectorFloat& input);

boolean convertFromPrediction(VectorFloat& output, const VectorFloat& input);

algorithm-specific computation methods: cross-correlation and convolution

boolean computeCross(VectorFloat& output, const VectorFloat& ref, const VectorFloat& tst);

boolean computeConv(VectorFloat& output, const VectorFloat& input, const VectorFloat& filter);

examples:

This example shows how to compute the autocorrelation for a given input signal:

// declare the Correlation object
//
Correlation autoc;
         
// declare the input and output vectors
//
VectorFloat input(L"1, 2, 3, 4, 5, 6, 7");
VectorFloat output;

// set the algorithm, implementation, normalization, and order
//
autoc.setAlgorithm(Correlation::AUTO);
autoc.setImplementation(Correlation::FACTORED);
autoc.setMode(Correlation::FRAME_INTERNAL);
autoc.setNormalization(Correlation::UNIT_ENERGY);
autoc.setOrder(3);
        
// compute the autocorrelation output
//
autoc.compute(output, input);

This example shows how to compute the cross-correlation of two signals:

// declare the Correlation object
//
Correlation xcor;
         
// declare the input and output vectors
//
VectorFloat ref(L"1, 1, 2, 3, 2, 1, 1, 1");
VectorFloat tst(L"2, 3, 2");
VectorFloat output;

// set the algorithm, implementation, normalization, and order
//
xcor.setAlgorithm(Correlation::CROSS);
xcor.setImplementation(Correlation::UNFACTORED);
xcor.setMode(Correlation::FRAME_INTERNAL);        
xcor.setNormalization(Correlation::NONE);
       
// compute the cross-correlation
//
xcor.compute(output, ref, tst);

notes:

The factored correlation approach requires the analysis order to be less than one-third the length of the input data.
The cross-correlation and convolution algorithms set the order to the length of the input signal. Hence, they do not need the order to be set before computations.