name: MutualInformation : public AlgorithmBase
synopsis:

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

>     #include <MutualInformation.h>

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

quick start:

>     VectorFloat input(L"1.0, 2.0, 3.0, 4.0, 5.0, 9.0, 1.23, 2.3");
>     VectorFloat output;
>     MutualInformation mi;
>     mi.compute(output, input);

description:
The Mutual Information measures the dynamical coupling or information transmission between two time series. Mutual Information may be considered a nonlinear version of correlation function. MI quantifies the information gained about one system from the measurement of another. The MutualInformation class implements autocorrelation and cross-correlation. A good overview of mutual informations can be found in:

H. Kantz and T. Schreiber, Nonlinear Time Series Analysis, Second Edition, Cambridge University Press, Cambridge, UK, pp. 150-152, 1999

P.S. Addison, Fractals and Chaos, An Illustrated Course, Institute of Physics Publishing, Bristol, UK, pp. 172-176, 1997

The design parameters relevant to this class are the analysis order, which specifies the maximum time delay. Starting from zero to order, the mutual information is measured. It also reads in the number of bins for constructing the histogram. Histogram technique is used for finding the probability. For the case of auto mutual information, the time series and its delayed version are taken. For the cross mutual information we find the plot of one time series versus the delayed version of the other.
This class supports two computational modes: FRAME_INTERNAL and CROSS_FRAME. In FRAME_INTERNAL mode, it computes the mutual information of the data within current frame. In CROSS_FRAME mode, data outside the frame is used.
dependencies:

- AlgorithmBase

public constants:

- define the class name:

      static const String CLASS_NAME = L"MutualInformation";

- define algorithm choices:

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

- define implementation choices:

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

- define mode choices:

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

- define normalization choices:

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

- define static NameMap objects:

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

      static const NameMap IMPL_MAP = L"HISTOGRAM";

      static const NameMap NORM_MAP = L"NONE";

- define i/o related constants:

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

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

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

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

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

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

      static const String MutualInformation::PARAM_NUM_BINS = L"num_bins";

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

      static const long DEF_ORDER = -1;

      static const long DEF_NUM_BINS = -1;

- define default argument(s):

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

error codes:

- general error codes:

      static const long ERR = 73700;

      static const long ERR_INPUT = 73701;

      static const long ERR_DATA = 73702;

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;

  - number of bins:

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

      ~MutualInformation();

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

      MutualInformation(const MutualInformation& arg);

- assign methods:

      boolean assign(const MutualInformation& arg);

- operator= methods:

      MutualInformation& operator= (const MutualInformation& 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 MutualInformation& 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 setNumBins(long num_bins);

      boolean set(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, NORMALIZATION normalization = DEF_NORMALIZATION, long order = DEF_ORDER, long num_bins = DEF_NUM_BINS);

- get methods:

      ALGORITHM getAlgorithm() const;

      IMPLEMENTATION getImplementation() const;

      NORMALIZATION getNormalization() const;

      long getOrder() const;

      long getNumBins() const;

      boolean get(ALGORITHM& algorithm, IMPLEMENTATION& implementation, NORMALIZATION& normalization, long& order, long& num_bins);

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

- 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 computeAutoMutualInformation(VectorFloat& mi, const VectorFloat& time_series);

      boolean computeCrossMutualInformation(VectorFloat& mi, const VectorFloat& time_series_1, const VectorFloat& time_series_2);

examples:

- This example shows how to compute the auto mutualinformation for a given input time series:

      // declare the MutualInformation object
      //
      MutualInformation mi;

      // declare the input and output vectors
      //
      VectorFloat input(L"1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0");
      VectorFloat output;

      // set the algorithm, implementation, normalization, and order
      //
      mi.setAlgorithm(MutualInformation::AUTO);
      mi.setImplementation(MutualInformation::HISTOGRAM);
      mi.setOrder(3);
      mi.setNumBins(3);

      // compute the autocorrelation output
      //
      mi.compute(output, input);

- This example shows how to compute the cross-mutualinformation of two time series:

      // declare the MutualInformation object
      //
      MutualInformation cmi;

      // 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
      //
      cmi.setAlgorithm(MutualInformation::CROSS);
      cmi.setImplementation(MutualInformation::HISTOGRAM);
      cmi.setOrder(3);
      cmi.setNumBins(4);

      // compute the cross-correlation
      //
      cmi.compute(output, ref, tst);