name: CorrelationIntegral : public AlgorithmBase
synopsis:

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

>     #include <CorrelationIntegral.h>

>     CorrelationIntegral(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, SCALING scaling = DEF_SCALING, SPACING_MODE spacing_mode = DEF_SPACING_MODE, float epsilon_min = DEF_EPSILON_MIN, float epsilon_max = DEF_EPSILON_MAX, long epsilon_res = DEF_EPSILON_RES, long theiler_correction = DEF_THEILER_CORRECTION);
>     boolean eq(const CorrelationIntegral& arg) const;
>     boolean compute(VectorFloat& output, const MatrixFloat& input, AlgorithmData::COEF_TYPE coef_type = DEF_COEF_TYPE, long channel_index = DEF_CHANNEL_INDEX);

quick start:

>     MatrixFloat input;
>     input.assign(3, 3, L"1.0, 2.0, 3.0, 6.0, 5.0, 4.0, 7.0, 8.0, 9.0", Integral::FULL");
>     VectorFloat output;
>     CorrelationIntegral corrint;
>     corrint.compute(output, input);

description:
The CorrelationIntegral class is designed to estimate the correlation integral of an attractor's trajectory. It takes as input the Reconstructed Phase Space matrix of an attractor and outputs a vector of correlation integrals, corresponding to a range of neighborhood radii. A good overview of methods to estimate the correlation integral 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:
Four types of scaling are supported: LINSCALE, LOGSCALE, LOG2SCALE, LOG10SCALE. The choice of scaling will ensure that the output vector of corresponding correlation integrals is on a Linear or Logarithmic (with appropriate base) scale.
dependencies:

- AlgorithmBase

public constants:

- define the class name:

      static const String CLASS_NAME = L"CorrelationIntegral";

- define the algorithm choices:

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

- define the implementation choices:

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

- define the scaling choices:

      enum SCALING { LOGSCALE = 0, LINSCALE, LOG2SCALE, LOG10SCALE, DEF_SCALING = LOGSCALE };

- define the spacing mode choices:

      enum SPACING_MODE { LINEAR_EPSILON_SPACING = 0, USER_SPECIFIED_EPSILON_SPACING, DEF_SPACING_MODE = LINEAR_EPSILON_SPACING };

- define algorithm name maps:

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

      static const NameMap CorrelationIntegral::IMPL_MAP(L"REGULAR");

      static const NameMap SCAL_MAP(L"LOGSCALE, LINSCALE, LOG2SCALE, LOG10SCALE");

      static const NameMap SPAC_MAP(L"LINEAR_EPSILON_SPACING, USER_SPECIFIED_EPSILON_SPACING");

- define i/o related variables:

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

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

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

      static const String CorrelationIntegral::PARAM_SCALING = L"scaling";

      static const String CorrelationIntegral::PARAM_SPACING_MODE = L"spacing_mode";

      static const String CorrelationIntegral::PARAM_EPSILON_MIN = L"epsilon_min";

      static const String CorrelationIntegral::PARAM_EPSILON_MAX = L"epsilon_max";

      static const String CorrelationIntegral::PARAM_EPSILON_RES = L"epsilon_res";

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

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

      static const long DEF_EPSILON_MIN = (float)-1;

      static const long DEF_EPSILON_MAX = (float)-10;

      static const long DEF_EPSILON_RES = (long)-10;

      static const long DEF_THEILER_CORRECTION = (long)-5;

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

error codes:

- error code indicating CorrelationIntegral class general error:

      static const long ERR = 73600;

      static const long ERR_UNKALG = 73601;

      static const long ERR_UNCTYP = 73602;

      static const long ERR_EPSMIN = 73603;

      static const long ERR_EPSMAX = 73604;

      static const long ERR_EPSRES = 73605;

      static const long ERR_EPS = 73606;

protected data:

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

        ALGORITHM algorithm_d;

  - implementation type:

        IMPLEMENTATION implementation_d;

  - scaling type:

        SCALING scaling_d;

  - spacing mode type:

        SPACING_MODE spacing_mode_d;

  - minimum epsilon:

        Float epsilon_min_d;

  - maximum epsilon:

        Float epsilon_max_d;

  - resolution of epsilon:

        Long epsilon_res_d;

  - theiler's correction:

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

      ~CorrelationIntegral();

      CorrelationIntegral(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, SCALING scaling = DEF_SCALING, SPACING_MODE spacing_mode = DEF_SPACING_MODE, float epsilon_min = DEF_EPSILON_MIN, float epsilon_max = DEF_EPSILON_MAX, long epsilon_res = DEF_EPSILON_RES,long theiler_correction = DEF_THEILER_CORRECTION);

      CorrelationIntegral(const CorrelationIntegral& arg);

- assign methods:

      boolean assign(const CorrelationIntegral& arg);

- operator= methods:

      CorrelationIntegral& operator= (const CorrelationIntegral& 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 CorrelationIntegral& 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 setScaling(SCALING scaling);

      boolean setSpacingMode(SPACING_MODE spacing_mode);

      boolean set(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, SCALING scaling = DEF_SCALING, SPACING_MODE spacing_mode = DEF_SPACING_MODE);

      boolean setEpsilon(float epsilon_min, float epsilon_max, long epsilon_res);

      boolean setEpsilon(VectorFloat& epsilon);

- get methods:

      ALGORITHM getAlgorithm() const;

      IMPLEMENTATION getImplementation() const;

      SCALING getScaling() const;

      get(ALGORITHM& algorithm, IMPLEMENTATION& implementation)

      SPACING_MODE getSpacingMode() const;

- computational methods:

      boolean compute(VectorFloat& output, const MatrixFloat& 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 computeCorrelationIntegral(VectorFloat& correlationintegral, const MatrixFloat& input)

examples:

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

        // declare the CorrelationIntegral object
        //
        CorrelationIntegral corr_int;

        // define the variables for the corr_int object
        //
        float epsilon_min = 1, epsilon_max = 10;
        long epsilon_res = 10, theiler_correction = 50;

        // Setting the parameters of the CorrelationIntegral block
        //
        corr_int.set(CorrelationIntegral::NORMAL, CorrelationIntegral::REGULAR,
      	       CorrelationIntegral::LOG2SCALE, CorrelationIntegral::LINEAR_EPSILON_SPACING);
        corr_int.setEpsilon(epsilon_min, epsilon_max, epsilon_res);
        corr_int.setTheilerCorrection(theiler_correction);

        // Creating a RPS from a Lorentz time series
        //
        Rps rps_block;
        MatrixFloat rps_x;
        VectorFloat x_scalar_series, dummy, corr_integ;
        long D = 10; // Embedding dimension

        // Length of the time series
        long len = 30;

        // SVD window size for SVD embedding
        long svd_window_size = 15;

        Generator gen1;
        gen1.set(Generator::LORENTZ);
        gen1.setSampleFrequency((float)100);
        gen1.setGenSampleFrequency((float)100);
        gen1.setSignalDuration(len);
        gen1.setFrameDuration(len);
        gen1.setLorentz((float)16, (float)40, (float)4, (float)0.5,
      		  (float)0.5 , (float)0.5, (long)1);
        gen1.compute(x_scalar_series, dummy);

        //Normalizing the attractor to a unit hypercube
        //
        float mean;
        mean = x_scalar_series.mean();
        x_scalar_series.sub(x_scalar_series, mean);

        // Reconstructing the system attractor using SVD based embedding
        //
        rps_block.set(Rps::SVD_EMBEDDING, Rps::EMBEDDING, D, svd_window_size);
        rps_block.compute(rps_x, x_scalar_series);

        // CorrelationIntegral
        //
        corr_int.compute(corr_integ, rps_x);

        // Displaying the correlation integral C(epsilon_min) to C(epsilon_max)
        // on the console
        //
        corr_integ.debug(L"Correlation_Integral");

notes:

- Currently, this implementation supports a basic search through the attractor's trajectory to estimate the correlation integral of the phase space. This may be extended to a more efficient and faster box-assisted search later.