name: CorrelationDimension : public AlgorithmBase
synopsis:

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

>     #include <CorrelationDimension.h>

>     CorrelationDimension(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, SCALING scaling = DEF_SCALING, float epsilon_min = DEF_EPSILON_MIN, float epsilon_max = DEF_EPSILON_MAX, float epsilon_res = DEF_EPSILON_RES, float delta = DEF_DELTA, long theiler_correction = DEF_THEILER_CORRECTION);
>     boolean eq(const CorrelationDimension& arg) const;
>     boolean compute(VectorFloat& output, const MatrixFloat& input);

quick start:

>     MatrixFloat input;
>     VectorFloat output;
>     CorrelationDimension cdim;
>     cdim.compute(output, input);

description:
The CorrelationDimension class computes the invariant of chaotic system, CorrelationDimension, given Rps of the time series. The dimension of an attractor is a measure of its geometric scaling properties. Many definitions of dimension exist. We implement the widely used correlation dimension. In chaos theory, the correlation dimension is a measure of the dimensionality of the space occupied by a set of random points. The major utility of the correlation dimension is in determining the dimensions of fractal objects. The idea is to construct a function proportional to the probability that two arbitrary points on the orbit in the state space are closer than epsilon. We use CorrelationIntegral for calculating the dimension. For a limited range of epsilon, correlation integral is proportional to epsilon ^ dimension. There are two scaling options for epsilon spacing. User may specify epsilons to be linearly equally spaced or logarithmically equally spaced. CorrelationIntegral class. Dimension is well explained here:

J. Theiler, Estimating Fractal Dimension, Lincoln Laboratories, MIT, Lexington, Massachusetts, USA, pp. 1066-1069, 1990.

Three implementations are supported: backward differentiation, central differentiation and smooth differentiation. The backward differentiation method of implementation is described in:

P.S. Addison, Fractals and Chaos, Institute of Physics Publishing, Bristol, UK, pp. 163-171, 1997.

The smooth differentiation approach is accurate and is described in:

H. Kantz and T. Schreiber, Nonlinear Time Series Analysis, Cambridge University Press, Cambridge, UK, pp. 77-85, 1999.

dependencies:

- AlgorithmBase

public constants:

- define the class name:

      static const String CLASS_NAME = L"CorrelationDimension";

- define the algorithm choices:

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

- define the implementation choices:

      enum IMPLEMENTATION { BACKWARD = 0, CENTRAL, SMOOTH, DEF_IMPLEMENTATION = BACKWARD };

- define the scaling choices:

      enum SCALING { LINSCALE = 0, LOGSCALE, DEF_IMPLEMENTATION = LINSCALE };

- define algorithm name maps:

      static const NameMap CorrelationDimension::ALGO_MAP(L"CORRELATION");

      static const NameMap CorrelationDimension::IMPL_MAP(L"BACKWARD, CENTRAL, SMOOTH");

      static const NameMap CorrelationDimension::SCAL_MAP(L"LINSCALE, LOGSCALE");

- define i/o related variables:

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

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

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

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

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

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

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

      static const String Correlation::PARAM_DELTA = L"delta";

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

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

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

error codes:

- error code indicating CorrelationDimension class general error:

      static const long ERR = 73900;

      static const long ERR_EPSMIN = 73901;

      static const long ERR_EPSMAX = 73902;

      static const long ERR_EPSRES = 73903;

      static const long ERR_EPS = 73904;

      static const long ERR_DELTA_EPSMIN = 73905;

      static const long ERR_DELTA_EPSMAX = 73906;

protected data:

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

        ALGORITHM algorithm_d;

  - implementation type:

        IMPLEMENTATION implementation_d;

  - scaling type:

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

      ~CorrelationDimension();

      CorrelationDimension(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, SCALING scaling = DEF_SCALING);

      CorrelationDimension(const CorrelationDimension& arg);

- assign methods:

      boolean assign(const CorrelationDimension& arg);

- operator= methods:

      CorrelationDimension& operator= (const CorrelationDimension& 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 CorrelationDimension& 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 setEpsilonMin(float epsilon_min);

      boolean setEpsilonMax(float epsilon_max);

      boolean setEpsilonRes(long epsilon_res);

      boolean setDelta(float delta);

      boolean setTheilerCorrection(long theiler_correction);

      boolean set(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, SCALING scaling = DEF_SCALING, float epsilon_min = DEF_EPSILON_MIN, float epsilon_max = EPSILON_MAX, long epsilon_res = DEF_EPSILON_RES, float delta = DEF_DELTA, long theiler_correction = DEF_THEILER_CORRECTION);

- get methods:

      ALGORITHM getAlgorithm() const;

      IMPLEMENTATION getImplementation() const;

      SCALING getScaling() const;

      float getEpsilonMin() const;

      float getEpsilonMax() const;

      long getEpsilonRes() const;

      float getDelta() const;

      float getTheilerCorrection() const;

      boolean get(ALGORITHM& algorithm, IMPLEMENTATION& implementation,SCALING& scaling, float& epsilon_min, float& epsilon_max, long& epsilon_res, float& delta, long& theiler_correction) const;

- computational methods:

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

      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:

      boolean computeCorrDimBackward(VectorFloat& corrdim, const MatrixFloat& rps);

      boolean computeCorrDimCentral(VectorFloat& corrdim, const MatrixFloat& rps);

      boolean computeCorrDimSmooth(VectorFloat& corrdim, const MatrixFloat& rps);

  examples:
  - This example shows how to compute the correlation dimension (using backward differentiation) :

        // declare the CorrelationDimension object
        //
        CorrelationDimension cdim;

        // generate input time series
        //
        VectorFloat time_series, dummy;
        Generator gen1;
        gen1.set(Generator::LORENTZ);
        gen1.setSampleFrequency((float)100);
        gen1.setGenSampleFrequency((float)100);
        gen1.setSignalDuration(10);
        gen1.setFrameDuration(10);
        gen1.compute(time_series, dummy);

        // reconstruct phase space for the input time series
        //
        Long D = 15, svd_window_size = 16;
        Rps rps_block;
        MatrixFloat rps_x;
        rps_block.set(Rps::SVD_EMBEDDING, Rps::EMBEDDING, D, svd_window_size);
        rps_block.compute(rps_x, time_series);

        // set all the variables necessary for computing correlation integral
        //
        Float epsilon_min = 1, epsilon_max = 200;
        Long epsilon_res = 40, theiler_correction = 150;
        Float delta = (float)1;
        cdim.setImplementation(CorrelationDimension::BACKWARD);
        cdim.setScaling(CorrelationDimension::LINSCALE);
        cdim.setEpsilonMin(epsilon_min);
        cdim.setEpsilonMax(epsilon_max);
        cdim.setEpsilonRes(epsilon_res);
        cdim.setTheilerCorrection(theiler_correction);

        // compute correlation dimension
        //
        VectorFloat dimension;
        cdim.compute(dimension, rps_x);
        dimension.debug(L"Dimension");

  - This example shows how to compute the correlation dimension (using smooth differentiation) with log scaling :

        // declare the CorrelationDimension object
        //
        CorrelationDimension cdim;

        // generate input time series
        //
        VectorFloat time_series, dummy;
        Generator gen1;
        gen1.set(Generator::LORENTZ);
        gen1.setSampleFrequency((float)100);
        gen1.setGenSampleFrequency((float)100);
        gen1.setSignalDuration(10);
        gen1.setFrameDuration(10);
        gen1.compute(time_series, dummy);

        // reconstruct phase space for the input time series
        //
        Long D = 15, svd_window_size = 16;
        Rps rps_block;
        MatrixFloat rps_x;
        rps_block.set(Rps::SVD_EMBEDDING, Rps::EMBEDDING, D, svd_window_size);
        rps_block.compute(rps_x, time_series);

        // set all the variables necessary for computing correlation integral
        //
        Float epsilon_min = 1, epsilon_max = 200;
        Long epsilon_res = 40, theiler_correction = 150
        Float delta = (float) 1;
        cdim.setImplementation(CorrelationDimension::SMOOTH);
        cdim.setScaling(CorrelationDimension::LOGSCALE);
        cdim.setEpsilonMin(epsilon_min);
        cdim.setEpsilonMax(epsilon_max);
        cdim.setEpsilonRes(epsilon_res);
        cdim.setTheilerCorrection(theiler_correction);

        // compute correlation dimension
        //
        VectorFloat dimension;
        cdim.compute(dimension, rps_x);
        dimension.debug(L"Dimension");

  notes:
  - none.