DTW.h

Go to the documentation of this file.

#ifndef GRT_DTW_HEADER
#define GRT_DTW_HEADER

#include "../../CoreModules/Classifier.h"
#include "../../Util/TimeSeriesClassificationSampleTrimmer.h"

GRT_BEGIN_NAMESPACE

class GRT_API IndexDist{
    public:
    IndexDist(int x=0,int y=0,Float dist=0){
        this->x = x;
        this->y = y;
        this->dist = dist;
    }
    ~IndexDist(){};
    IndexDist& operator=(const IndexDist &rhs){
        if(this!=&rhs){
            this->x = rhs.x;
            this->y = rhs.y;
            this->dist = rhs.dist;
        }
        return (*this);
    }
    
    int x;
    int y;
    Float dist;
};

class GRT_API DTWTemplate{
    public:
    DTWTemplate(){
        classLabel = 0;
        trainingMu = 0.0;
        trainingSigma = 0.0;
        averageTemplateLength=0;
    }
    ~DTWTemplate(){};
    
    UINT classLabel;                    //The class that this template belongs to
    MatrixFloat timeSeries;            //The raw time series
    Float trainingMu;                  //The mean distance value of the training data with the trained template
    Float trainingSigma;               //The sigma of the distance value of the training data with the trained template
    UINT averageTemplateLength;          //The average length of the examples used to train this template
};

class GRT_API DTW : public Classifier
{
public:

    enum DistanceMethods{ABSOLUTE_DIST=0,EUCLIDEAN_DIST,NORM_ABSOLUTE_DIST};
    enum RejectionModes{TEMPLATE_THRESHOLDS=0,CLASS_LIKELIHOODS,THRESHOLDS_AND_LIKELIHOODS};
    
    DTW(bool useScaling=false,bool useNullRejection=false,Float nullRejectionCoeff=3.0,UINT rejectionMode = DTW::TEMPLATE_THRESHOLDS,bool dtwConstrain=true,Float radius=0.2,bool offsetUsingFirstSample=false,bool useSmoothing = false,UINT smoothingFactor = 5, Float nullRejectionLikelihoodThreshold = 0.99);
    
    DTW(const DTW &rhs);
    
    virtual ~DTW(void);
    
    DTW& operator=(const DTW &rhs);
    
    virtual bool deepCopyFrom(const Classifier *classifier);
    
    virtual bool train_(TimeSeriesClassificationData &trainingData);
    
    virtual bool predict_(VectorFloat &inputVector);
    
    virtual bool predict_(MatrixFloat &timeSeries);
    
    virtual bool reset();
    
    virtual bool clear();
    
    virtual bool save( std::fstream &file ) const;
    
    virtual bool load( std::fstream &file );
    
    virtual bool recomputeNullRejectionThresholds();
    
    UINT getNumTemplates() const { return numTemplates; }
    
    bool setRejectionMode(UINT rejectionMode);
    
    bool setNullRejectionThreshold(Float nullRejectionLikelihoodThreshold);
    
    bool setOffsetTimeseriesUsingFirstSample(bool offsetUsingFirstSample);
    
    bool setContrainWarpingPath(bool constrain);
    
    bool setWarpingRadius(Float radius);
    
    UINT getRejectionMode() const { return rejectionMode; }
    
    bool enableZNormalization(bool useZNormalization,bool constrainZNorm = true);
    
    bool enableTrimTrainingData(bool trimTrainingData,Float trimThreshold,Float maximumTrimPercentage);
    
    Vector< DTWTemplate > getModels() const { return templatesBuffer; }
    
    bool setModels( Vector< DTWTemplate > newTemplates );
    
    Vector< VectorFloat > getInputDataBuffer() const { return continuousInputDataBuffer.getData(); }
    
    const Vector< MatrixFloat >& getDistanceMatrices() const { return distanceMatrices; }
    
    const Vector< Vector< IndexDist > >& getWarpingPaths() const { return warpPaths; }

    static std::string getId();
    
    //Tell the compiler we are using the base class train method to stop hidden virtual function warnings
    using MLBase::save;
    using MLBase::load;
    using MLBase::train_;
    using MLBase::predict_;
    
protected:
    //Public training and prediction methods
    bool train_NDDTW(TimeSeriesClassificationData &trainingData,DTWTemplate &dtwTemplate,UINT &bestIndex);
    
    //The actual DTW function
    Float computeDistance(MatrixFloat &timeSeriesA,MatrixFloat &timeSeriesB,MatrixFloat &distanceMatrix,Vector< IndexDist > &warpPath);
    Float d(int m,int n,MatrixFloat &distanceMatrix,const int M,const int N);
    Float inline MIN_(Float a,Float b, Float c);
    
    //Scaling and Utility Functions
    void scaleData(TimeSeriesClassificationData &trainingData);
    void scaleData(MatrixFloat &data,MatrixFloat &scaledData);
    void znormData(TimeSeriesClassificationData &trainingData);
    void znormData(MatrixFloat &data,MatrixFloat &normData);
    void smoothData(VectorFloat &data,UINT smoothFactor,VectorFloat &resultsData);
    void smoothData(MatrixFloat &data,UINT smoothFactor,MatrixFloat &resultsData);
    void offsetTimeseries(MatrixFloat &timeseries);
    bool loadLegacyModelFromFile( std::fstream &file );
    
    Vector< DTWTemplate > templatesBuffer;      //A buffer to store the templates for each time series
    Vector< MatrixFloat > distanceMatrices;
    Vector< Vector< IndexDist > > warpPaths;
    CircularBuffer< VectorFloat > continuousInputDataBuffer;
    UINT                numTemplates;           //The number of templates in our buffer
    UINT                rejectionMode;          //The rejection mode used to reject null gestures during the prediction phase
    
    //Flags
    bool                useSmoothing;           //A flag to check if we need to smooth the data
    bool                useZNormalisation;      //A flag to check if we need to znorm the training and prediction data
    bool                offsetUsingFirstSample; //A flag to check if each timeseries should be offset by the first sample in the time series
    bool                constrainZNorm;         //A flag to check if we need to constrain zNorm (only zNorm if stdDev > zNormConstrainThreshold)
    bool                constrainWarpingPath;   //A flag to check if we need to constrain the dtw cost matrix and search
    bool                trimTrainingData;       //A flag to check if we need to trim the training data first before training
    
    Float               zNormConstrainThreshold;//The threshold value to be used if constrainZNorm is turned on
    Float              radius;
    Float               trimThreshold;          //Sets the threshold under which training data should be trimmed (default 0.1)
    Float               maximumTrimPercentage;  //Sets the maximum amount of data that can be trimmed for each training sample (default 20)
    Float               nullRejectionLikelihoodThreshold; //Sets the threshold for null rejection based on likelihoods
    
    UINT                smoothingFactor;        //The smoothing factor if smoothing is used
    UINT                distanceMethod;         //The distance method to be used (should be of enum DISTANCE_METHOD)
    UINT                averageTemplateLength;  //The overall average template length (over all the templates)
    
private:
    static RegisterClassifierModule< DTW > registerModule;
    static const std::string id;
};

GRT_END_NAMESPACE

#endif //GRT_DTW_HEADER