name: CorrelationEntropy : public AlgorithmBase
synopsis:

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

>     #include <CorrelationEntropy.h>

>     CorrelationEntropy(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, EMBEDDING embedding = DEF_EMBEDDING, float epsilon = DEF_EPSILON, long embed_dim_min = DEF_EMBED_DIM_MIN, long embed_dim_max = DEF_EMBED_DIM_MAX, long theiler_correction = DEF_THEILER_CORRECTION, long svd_window_size = DEF_SVD_WINDOW_SIZE, float delay = DEF_DELAY);
>     boolean eq(const CorrelationEntropy& arg) const;
>     boolean compute(VectorFloat& output, const VectorFloat& input, AlgorithmData::COEF_TYPE coef_type = DEF_COEF_TYPE, long channel_index = DEF_CHANNEL_INDEX);

quick start:

>     VectorFloat input;
>     input.assign(L"1.0, 2.0, 3.0, 6.0, 5.0, 4.0, 7.0, 8.0, 9.0");
>     VectorFloat output;
>     CorrelationEntropy correntpy;
>     correntpy.compute(output, input);

description:
The CorrelationEntropy class is designed to estimate the second order Kolmogorov-Sinai entropy of an attractor's trajectory. It takes as input the time series and outputs a vector of correlation entropies, corresponding to a range of embedding dimensions. A good overview of methods to estimate the correlation entropy can be found in:

Kantz and Schreiber Nonlinear Time Series Analysis, Cambridge University Press, Cambridge, UK, 2004

The mathematical descriptions of the algorithm is provided below for reference purposes:
Two types of attractor reconstruction (embedding) are currently supported: TIME_DELAY, and, SVD.
dependencies:

- AlgorithmBase

public constants:

- define the class name:

      static const String CLASS_NAME = L"CorrelationEntropy";

- define the algorithm choices:

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

- define the implementation choices:

      enum IMPLEMENTATION { CORRELATION_INTEGRAL = 0, DEF_IMPLEMENTATION = CORRELATION_INTEGRAL };

- define the embedding choices:

       enum EMBEDDING { TIME_DELAY = 0, SVD,
      			DEF_EMBEDDING = TIME_DELAY };

- define algorithm name maps:

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

      static const NameMap CorrelationEntropy::IMPL_MAP(L"CORRELATION_INTEGRAL");

      static const NameMap EMBED_MAP(L"TIME_DELAY");

- define i/o related variables:

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

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

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

      static const String CorrelationEntropy::PARAM_EMBEDDING = L"embedding";

      static const String CorrelationEntropy::PARAM_EPSILON = L"epsilon";

      static const String CorrelationEntropy::PARAM_EMBED_DIM_MIN = L"embed_dim_min";

      static const String CorrelationEntropy::PARAM_EMBED_DIM_MAX = L"embed_dim_max";

      static const String CorrelationEntropy::PARAM_THEILER_CORRECTION = L"theiler_correction";

      static const String CorrelationEntropy::PARAM_THEILER_CORRECTION = L"theiler_correction";

      static const String CorrelationEntropy::PARAM_DELAY = L"delay";

      static const String CorrelationEntropy::PARAM_SVD_WINDOW_SIZE = L"svd_window_size";

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

      static const float DEF_EPSILON = (float) 1;

      static const long DEF_EMBED_DIM_MIN = 3;

      static const long DEF_EMBED_DIM_MAX = 5;

      static const long DEF_THEILER_CORRECTION = 5;

      static const float DEF_DELAY = 5;

      static const long DEF_SVD_WINDOW_SIZE = -1;

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

error codes:

- error code indicating CorrelationEntropy class general error:

      static const long ERR = 73800;

      static const long ERR_UNKALG = 73801;

      static const long ERR_UNCTYP = 73802;

      static const long ERR_EPS = 73803;

      static const long ERR_DIM = 73804;

protected data:

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

        ALGORITHM algorithm_d;

  - implementation type:

        IMPLEMENTATION implementation_d;

  - embedding type:

        EMBEDDING embedding_d;

  - epsilon:

        Float epsilon_d;

  - minimum embedding dimension:

        Long embed_dim_min_d;

  - maximum embedding dimension:

        Long embed_dim_max_d;

  - theiler's correction:

        Long theiler_correction_d;

  - SVD window size:

        Long svd_window_size_d;

  - Delay:

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

      ~CorrelationEntropy();

      CorrelationEntropy(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, EMBEDDING embedding = DEF_EMBEDDING, float epsilon = DEF_EPSILON, long embed_dim_min = DEF_EMBED_DIM_MIN, long embed_dim_max = DEF_EMBED_DIM_MAX, long theiler_correction = DEF_THEILER_CORRECTION, long svd_window_size = DEF_SVD_WINDOW_SIZE, float delay = DEF_DELAY);

      CorrelationEntropy(const CorrelationEntropy& arg);

- assign methods:

      boolean assign(const CorrelationEntropy& arg);

- operator= methods:

      CorrelationEntropy& operator= (const CorrelationEntropy& 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 CorrelationEntropy& 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 setEmbedding(EMBEDDING embedding);

      boolean set(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, EMBEDDING embedding = DEF_EMBEDDING, float epsilon = DEF_EPSILON, long embed_dim_min = DEF_EMBED_DIM_MIN, long embed_dim_max = DEF_EMBED_DIM_MAX, long theiler_correction = DEF_THEILER_CORRECTION, long svd_window_size = DEF_SVD_WINDOW_SIZE, float delay = DEF_DELAY)

- get methods:

      ALGORITHM getAlgorithm() const;

      IMPLEMENTATION getImplementation() const;

      EMBEDDING getEmbedding() const;

      get(ALGORITHM& algorithm, IMPLEMENTATION& implementation, EMBEDDING&, embedding)

- computational methods:

      boolean compute(VectorFloat& output, const VectorFloat& input, AlgorithmData::COEF_TYPE 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;

      boolean const String& className() const;

      boolean init();

      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 compute methods: Normal

      boolean computeCorrelationEntropy(VectorFloat& CorrelationEntropy, const VectorFloat& input)

examples:

- This example shows how to compute the Correlation Entropy for a given Time Series:

        // declare the CorrelationEntropy object
        //
        CorrelationEntropy corr_entpy;

        // define the variables for the corr_entpy object
        //
        float epsilon = 1, delay = 10;
        long embed_dim_min = 3, embed_dim_max = 18;
        long theiler_correction = 150, svd_window_size = 10;
        VectorFloat input, output;

        // Setting the parameters of the CorrelationEntropy block
        //
        corr_entpy.set(CorrelationEntropy::NORMAL,
      	   	 CorrelationEntropy::CORRELATION_INTEGRAL,
      		 CorrelationEntropy::TIME_DELAY,
      		 epsilon, embed_dim_min, embed_dim_max,
      		 theiler_correction, svd_window_size,
      		 delay);
        corr_entpy.setSampleFrequency(8000);
        corr_entpy.compute(output, input);
        output.debug(L"Correlation Entropy");

notes:

- Currently, this implementation supports only the frame internal mode. The entire signal passed to this object is used to perform attractor reconstruction followed by Correlation Entropy estimation. Generally, it is helpful to normalize the attractor to a unit Hyper-Cube, so that a standard range of parameters (such as epsilon) can be used consistently.