// file: $isip_ifc/class/algo/MutualInformation/MutualInformation.h // version: $Id: MutualInformation.h 10437 2006-02-23 20:18:44Z pannuri $ // // make sure definitions are only made once // #ifndef ISIP_MUTUALINFORMATION #define ISIP_MUTUALINFORMATION // isip include files // #ifndef ISIP_ALGORITHM_BASE #include #endif #ifndef ISIP_HISTOGRAM #include #endif // MutualInformation: a class that computes the mutual information // for a given signal. mutual information is a measure of dynamical coupling or // information transmission between X and Y , where X and Y are two time // series. // // it detects the linear and non linear dependencies between the time series. // if one system is completely independent of another, then and only then // the MI between the time series generated from these dynamical systems is // zero. // // formally, the mutual information of two discrete random variables X and Y // can be defined as: // n m // I(X,Y) = sum sum p(xi,yj) * log(p(xi,yj)/(p(xi)*p(yj))) // i=1 j=1 // // auto mutual information is the mutual information of the series and a // delayed version of the same. // in the current implementation we find the auto mutual infomation of a // time series. // this is mostly used to determine a value for the constant time // delay in attractor construction using time shifts. // // I(s(to),s(to+tau)) = p(s(to),s(to+tau)) * // log( p(s(to),s(to+tau))/(p(s(to))*p(s(to+tau)))) // // the mutual information is calculated using histograms. // p(s(to)) is the normalized histogram of the distribution of values // observed for the measurement of s(to). // // this method of using histograms for calculating probabilites is // described briefly at: // // H. Kantz and T. Schreiber, // Nonlinear Time Series Analysis, 2nd 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. // // this class computes the mutual information of the data in FRAME_INTERNAL // and CROSS_FRAME modes. // 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. // class MutualInformation : public AlgorithmBase { //------------------------------------------------------------------------- // // public constants // //--------------------------------------------------------------------------- public: // define the class name // static const String CLASS_NAME; //---------------------------------------- // // other important constants // //---------------------------------------- // define the algorithm choices // enum ALGORITHM { AUTO = 0, CROSS, DEF_ALGORITHM = AUTO }; // define the implementation choices // enum IMPLEMENTATION { HISTOGRAM = 0, DEF_IMPLEMENTATION = HISTOGRAM }; // define normalization choices // enum NORMALIZATION { NONE = 0, DEF_NORMALIZATION = NONE }; // define the static NameMap objects // static const NameMap ALGO_MAP; static const NameMap IMPL_MAP; static const NameMap NORM_MAP; //---------------------------------------- // // i/o related constants // //---------------------------------------- static const String DEF_PARAM; static const String PARAM_ALGORITHM; static const String PARAM_IMPLEMENTATION; static const String PARAM_NORMALIZATION; static const String PARAM_CMODE; static const String PARAM_ORDER; static const String PARAM_NUM_BINS; //---------------------------------------- // // default values and arguments // //---------------------------------------- // define the default value(s) of the class data // static const int32 DEF_ORDER = -1; static const int32 DEF_NUM_BINS = -1; // define default argument(s) // static const AlgorithmData::COEF_TYPE DEF_COEF_TYPE = AlgorithmData::SIGNAL; //---------------------------------------- // // error codes // //---------------------------------------- static const int32 ERR = 73700; static const int32 ERR_INPUT = 73701; static const int32 ERR_DATA = 73702; //--------------------------------------------------------------------------- // // protected data // //--------------------------------------------------------------------------- protected: // algorithm name // ALGORITHM algorithm_d; // implementation name // IMPLEMENTATION implementation_d; // normalization type // NORMALIZATION normalization_d; // the value of the maximum delay to be used // Long order_d; // specifies the number of bins for the pdf calculation // Long num_bins_d; // static memory manager // static MemoryManager mgr_d; //--------------------------------------------------------------------------- // // required public methods // //--------------------------------------------------------------------------- public: // method: name // static const String& name() { return CLASS_NAME; } // other static methods // static bool8 diagnose(Integral::DEBUG debug_level); // debug methods: // setDebug is inherited from the AlgorithmBase class // bool8 debug(const unichar* msg) const; // method: destructor // ~MutualInformation() {} // method: default constructor // MutualInformation(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, NORMALIZATION normalization = DEF_NORMALIZATION, int32 order = DEF_ORDER, int32 num_bins = DEF_NUM_BINS) { algorithm_d = DEF_ALGORITHM; implementation_d = DEF_IMPLEMENTATION; normalization_d = DEF_NORMALIZATION; order_d = order; num_bins_d = num_bins; is_valid_d = false; } // method: copy constructor // MutualInformation(const MutualInformation& arg) { assign(arg); } // method: assign // bool8 assign(const MutualInformation& arg); // method: operator= // MutualInformation& operator= (const MutualInformation& arg) { assign(arg); return *this; } // i/o methods // int32 sofSize() const; bool8 read(Sof& sof, int32 tag, const String& name = CLASS_NAME); bool8 write(Sof& sof, int32 tag, const String& name = CLASS_NAME) const; bool8 readData(Sof& sof, const String& pname = DEF_PARAM, int32 size = SofParser::FULL_OBJECT, bool8 param = true, bool8 nested = false); bool8 writeData(Sof& sof, const String& pname = DEF_PARAM) const; // method: eq // bool8 eq(const MutualInformation& arg) const; // method: new // static void* operator new(size_t size) { return mgr_d.get(); } // method: new[] // static void* operator new[](size_t size) { return mgr_d.getBlock(size); } // method: delete // static void operator delete(void* ptr) { mgr_d.release(ptr); } // method: delete[] // static void operator delete[](void* ptr) { mgr_d.releaseBlock(ptr); } // method: setGrowSize // static bool8 setGrowSize(int32 grow_size) { return mgr_d.setGrow(grow_size); } // other memory management methods // bool8 clear(Integral::CMODE ctype = Integral::DEF_CMODE); //--------------------------------------------------------------------------- // // class-specific public methods: // set methods // //--------------------------------------------------------------------------- // method: setAlgorithm // bool8 setAlgorithm(ALGORITHM algorithm) { algorithm_d = algorithm; is_valid_d = false; return true; } // method: setImplementation // bool8 setImplementation(IMPLEMENTATION implementation) { implementation_d = implementation; is_valid_d = false; return true; } // method: setNormalization // bool8 setNormalization(NORMALIZATION normalization) { normalization_d = normalization; is_valid_d = false; return true; } // set the order value // bool8 setOrder(int32 order) { order_d = order; is_valid_d = false; return true; } // set the number of bins // bool8 setNumBins(int32 num_bins) { num_bins_d = num_bins; is_valid_d = false; return true; } // method: set // bool8 set(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, NORMALIZATION normalization = DEF_NORMALIZATION, int32 order = DEF_ORDER, int32 num_bins = DEF_NUM_BINS) { algorithm_d = algorithm; implementation_d = implementation; normalization_d = normalization; order_d = order; num_bins_d = num_bins; is_valid_d = false; return true; } //--------------------------------------------------------------------------- // // class-specific public methods: // get methods // //--------------------------------------------------------------------------- // method: getAlgorithm // ALGORITHM getAlgorithm() const { return algorithm_d; } // method: getImplementation // IMPLEMENTATION getImplementation() const { return implementation_d; } // method: getNormalization // NORMALIZATION getNormalization() const { return normalization_d; } // method: getOrder // int32 getOrder() const { return order_d; } // method: getNumBins // int32 getNumBins() const { return num_bins_d; } // method: get // bool8 get(ALGORITHM& algorithm, IMPLEMENTATION& implementation, NORMALIZATION& normalization, int32& num_bins, int32& order) const { algorithm = algorithm_d; implementation = implementation_d; normalization = normalization_d; order = order_d; num_bins = num_bins_d; return true; } //--------------------------------------------------------------------------- // // class-specific public methods: // computational methods // //--------------------------------------------------------------------------- // compute method when the input is given as VectorDouble // bool8 compute(VectorDouble& output, const VectorDouble& input, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, int32 index = DEF_CHANNEL_INDEX); bool8 compute(VectorFloat& output, const VectorFloat& input, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, int32 index = DEF_CHANNEL_INDEX); bool8 compute(VectorDouble& output, const VectorDouble& input1, const VectorDouble& input2, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, int32 index = DEF_CHANNEL_INDEX); bool8 compute(VectorFloat& output, const VectorFloat& input1, const VectorFloat& input2, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, int32 index = DEF_CHANNEL_INDEX); //--------------------------------------------------------------------------- // // class-specific public methods: // public methods required by the AlgorithmBase interface contract // //--------------------------------------------------------------------------- // assign method // bool8 assign(const AlgorithmBase& arg); // equality method // bool8 eq(const AlgorithmBase& arg) const; // method: className // const String& className() const { return CLASS_NAME; } // apply method // bool8 apply(Vector& output, const Vector< CircularBuffer >& input); // pad time methods: // cross-frame processing requires non-zero pad times // int32 getLeadingPad() const; int32 getTrailingPad() const; // method to set the parser // bool8 setParser(SofParser* parser); //--------------------------------------------------------------------------- // // private methods // //--------------------------------------------------------------------------- private: // common i/o methods // bool8 readDataCommon(Sof& sof, const String& pname, int32 size = SofParser::FULL_OBJECT, bool8 param = true, bool8 nested = false); bool8 writeDataCommon(Sof& sof, const String& pname) const; // compute auto mutual information // bool8 computeAutoMutualInformation(VectorFloat& mi, const VectorFloat& time_series); // compute cross mutual information // bool8 computeCrossMutualInformation(VectorFloat& mi, const VectorFloat& time_series_1, const VectorFloat& time_series_2); bool8 compute(VectorFloat& output_a, const CircularBuffer& input_a, AlgorithmData::COEF_TYPE coef_type_a, int32 channel_index_a); bool8 compute(VectorFloat& output_a, const CircularBuffer& input1_a, const CircularBuffer& input2_a, AlgorithmData::COEF_TYPE coef_type_a, int32 channel_index_a); }; // end of include file // #endif