name: Rps : public AlgorithmBase
synopsis:

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

>     #include <Rps.h>

>     Rps(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, long embed_dimension = DEF_EMBED_DIMENSION, long svd_window_size = DEF_SVD_WINDOW_SIZE, float delay = DEF_DELAY, float svd_threshold = DEF_SVD_THRESHOLD);
>     boolean compute(MatrixFloat& output, const VectorFloat& input, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, long index = DEF_CHANNEL_INDEX);
>     boolean compute(MatrixFloat& output, const MatrixFloat& input, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, long index = DEF_CHANNEL_INDEX);

quick start:

>     Rps rps0;
>     Rps rps1(rps0);
>     VectorFloat input(L"0, 1, 2, 3, 4, 5");
>     MatrixFloat output;
>     rps1.setAlgorithm(Rps::SVD_EMBEDDING);
>     rps1.compute(output, input);

description:
The Rps (Reconstruced Phase Space) class reconstructs a pseudo phase space of a dynamical system from one (scalar) or more (vector) time-series measurements of the system by the process of embedding. Two ways (algorithms) of achieving embedding are TIME_DELAY_EMBEDDING and SVD_EMBEDDING. The details can be found in:

D. S. Broomhead and Gregory P. King, Extracting qualitative dynamics from experimental data, Physica D 20, pp. 217, 1986.

Rps class works in FRAME-INTERNAL mode for both the algorithms and for both scalar and vector embedding but ACCUMULATE mode is possible only with scalar embedding presently. It should also be noted that the ouput RPS matrix has a last appended column with all its elements ones except for the last element which is zero. This is useful to mark discontinuities when concatenating Rps matrices.
dependencies:

- AlgorithmBase

public constants:

- define the class name:

      static const String CLASS_NAME = L"Rps";

- define algorithm choices:

      enum ALGORITHM { TIME_DELAY_EMBEDDING = 0, SVD_EMBEDDING, DEF_ALGORITHM = TIME_DELAY_EMBEDDING };

- define implementation choices:

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

- define static NameMap objects:

      static const NameMap Rps::ALGO_MAP(L"TIME_DELAY_EMBEDDING, SVD_EMBEDDING");

      static const NameMap IMPL_MAP = L"EMBEDDING";

- define i/o related constants:

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

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

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

      static const String Rps::PARAM_CMODE = L"compute_mode";

      static const String Rps::PARAM_EMBED_DIMENSION = L"embed_dimension";

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

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

      static const String Rps::PARAM_SVD_THRESHOLD = L"svd_threshold";

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

      static const long DEF_EMBED_DIMENSION = -1;

      static const float DEF_DELAY = -1.0;

      static const long DEF_SVD_WINDOW_SIZE = -1;

      static const float DEF_SVD_THRESHOLD = -1.0;

- define default argument(s):

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

error codes:

- general error codes:

      static const long ERR = 73400;

      static const long ERR_INP = 73401;

      static const long ERR_EMBEDDIM = 73402;

      static const long ERR_SVDDIM = 73403;

protected data:

- algorithm name:

      ALGORITHM algorithm_d;

- implementation name:

      IMPLEMENTATION implementation_d;

- (global) embedding dimension:

      Long embed_dimension_d;

- delay (tau) for embedding in seconds:

      Float delay_d;

- SVD window size (initial embedding dimension for SVD embedding):

      Long svd_window_size_d;

- SVD threshold for fixing embedding dimension from singular values:

      Float svd_threshold_d;

- buffer for accumulating input frames in ACCUMULATE mode

      VectorFloat accum_buf_d;

- static memory manager

      static MemoryManager mgr_d;

required public methods:

- static methods:

      static const String& name();

      static boolean diagnose(Integral::DEBUG debug_level);

- debug methods: setDebug is inherited from the AlgorithmBase class

      boolean debug(const unichar* message) const;

- destructor/constructor(s):

      ~Rps();

      Rps(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, long embed_dimension = DEF_EMBED_DIMENSION, long svd_window_size = DEF_SVD_WINDOW_SIZE, float delay = DEF_DELAY, float svd_threshold = DEF_SVD_THRESHOLD);

      Rps(const Rps& arg);

- assign methods:

      boolean assign(const Rps& arg);

- operator= methods:

      Rps& operator= (const Rps& 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 Rps& 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 setEmbedDimension(long embed_dimension);

      boolean setSVDWindowSize(long svd_window_size);

      boolean setDelay(float delay);

      boolean setSVDThreshold(float svd_threshold);

      boolean set(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, long embed_dimension = DEF_EMBED_DIMENSION, long svd_window_size = DEF_SVD_WINDOW_SIZE, float delay = DEF_DELAY, float svd_threshold = DEF_SVD_THRESHOLD);

- get methods:

      ALGORITHM getAlgorithm();

      IMPLEMENTATION getImplementation() const;

      long getEmbedDimension();

      long getSVDWindowSize();

      float getDelay();

      float getSVDThreshold();

      boolean get(ALGORITHM& algorithm, IMPLEMENTATION& implementation, long& embed_dimension, long& svd_window_size, float& delay, float& svd_threshold) const;

- computational methods:

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

      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;

      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;

- mode and computation mode-specific computation methods

      boolean computeFrameInt(MatrixFloat& output, const VectorFloat& input);

      boolean computeFrameInt(MatrixFloat& output, const MatrixFloat& input);

      boolean computeAccumulate(MatrixFloat& output, const VectorFloat& input, long index = DEF_CHANNEL_INDEX);

- algorithm and implementation specific computation methods:

      boolean computeTimeDelayEmbedding(MatrixFloat& output, const VectorFloat& input);

      boolean computeTimeDelayEmbedding(MatrixFloat& output, const MatrixFloat& input);

      boolean computeSVDEmbedding(MatrixFloat& output, const VectorFloat& input);

      boolean computeSVDEmbedding(MatrixFloat& output, const MatrixFloat& input);

examples:

- This example shows how to compute RPS matrix from a time-series using SVD embedding:

      // isip include files
      //
      #include <Rps.h>

      // main program starts here
      //
      int main(int argc, const char **argv) {
        // declare Rps object
        Rps rps(Rps::TIME_DELAY_EMBEDDING, Rps::EMBEDDING, 3, 1, 0.01);

        // set the sample frequency (needed for calculating delay in samples)
        //
        rps.setSampleFrequency(100);

        // declare input
        //
        VectorFloat input(L"0, 1, 2, 3, 4, 5, 6");

        // declare output
        //
        MatrixFloat output;

        // compute time-delay embedding
        //
        rps.compute(output, input);

        output.debug(L"rps matrix");

        // exit gracefully
        //
        return true;
      }

notes:

- It should be remembered to set the sampling frequency of the samples for the correct delay to be calculated in samples from time in seconds.
- The matrix output from Rps has an extra column appended to it that is 1's throughout except the last element which is 0. This is done to enable detection of points of discontinuities during concatenation of RPS matrices. Such concatenation may be used when calculating Lyapunov exponents.