Package ai.libs.jaicore.ml.weka.classification.singlelabel.timeseries.learner.trees

Class TimeSeriesTreeLearningAlgorithm

  • All Implemented Interfaces:
    java.lang.Iterable<org.api4.java.algorithm.events.IAlgorithmEvent>, java.util.concurrent.Callable<TimeSeriesTreeClassifier>, java.util.Iterator<org.api4.java.algorithm.events.IAlgorithmEvent>, org.api4.java.algorithm.IAlgorithm<ai.libs.jaicore.ml.classification.singlelabel.timeseries.dataset.TimeSeriesDataset2,​TimeSeriesTreeClassifier>, org.api4.java.common.control.ICancelable, org.api4.java.common.control.ILoggingCustomizable, org.api4.java.common.event.IEventEmitter<java.lang.Object>, org.api4.java.common.event.IRelaxedEventEmitter
    public class TimeSeriesTreeLearningAlgorithm
extends ai.libs.jaicore.ml.classification.singlelabel.timeseries.learner.ASimplifiedTSCLearningAlgorithm<java.lang.Integer,​TimeSeriesTreeClassifier>
    Algorithm to build a time series tree as described in Deng, Houtao et al. "A Time Series Forest for Classification and Feature Extraction." Inf. Sci. 239 (2013): 142-153.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static double ENTROPY_APLHA
      Alpha parameter used to weight the importance of the feature's margins to the threshold candidates.
      static int NUM_THRESH_CANDIDATES
      Number of threshold candidates created in each tree recursion step.
      static boolean USE_BIAS_CORRECTION
      Indicator that the bias (Bessel's) correction should be used for the calculation of the standard deviation.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static double calculateDeltaEntropy​(double[] dataValues, int[] targets, double thresholdCandidate, java.util.List<java.lang.Integer> classes, double parentEntropy)
      Function calculating the delta entropy for a given thresholdCandidate and parentEntropy.
      static double calculateEntrance​(double deltaEntropy, double margin)
      Calculates the entrance gain specified by Deng et. al. in the paper's chapter 4.1.
      static double calculateMargin​(double[] dataValues, double thresholdCandidate)
      Function calculating the margin between the given thresholdCandidate and the nearest feature value from the given dataValues.
      TimeSeriesTreeClassifier call()
      Training procedure construction a time series tree using the given input data.
      void cancel()
      static java.util.List<java.util.List<java.lang.Double>> generateThresholdCandidates​(ai.libs.jaicore.basic.sets.Pair<java.util.List<java.lang.Integer>,​java.util.List<java.lang.Integer>> pairOfIntervalLists, int numOfCandidates, double[][][] transformedFeatures)
      Function generating threshold candidates for each feature type.
      int getBestSplitIndex​(double[] deltaEntropyStarPerFeatureType)
      Function returning feature type used for the split based on given the deltaEntropy star values.
      static ai.libs.jaicore.basic.sets.Pair<java.util.List<java.lang.Integer>,​java.util.List<java.lang.Integer>> getChildDataIndices​(double[][][] transformedData, int n, int fType, int t1t2, double threshold)
      Function returning the data indices assigned to the left and the right child of a binary tree based on the splitting criterion given by the feature type fType, the intervals index t1t2 in the transformed data set transformedData and the threshold.
      int getNumCPUs()
      org.api4.java.algorithm.Timeout getTimeout()
      boolean hasNext()
      java.util.Iterator<org.api4.java.algorithm.events.IAlgorithmEvent> iterator()
      org.api4.java.algorithm.events.IAlgorithmEvent next()
      org.api4.java.algorithm.events.IAlgorithmEvent nextWithException()
      static java.util.List<java.lang.Integer> randomlySampleNoReplacement​(java.util.List<java.lang.Integer> list, int sampleSize, long seed)
      Function sampling a given list randomly without replacement using the given seed.
      void registerListener​(java.lang.Object listener)
      static ai.libs.jaicore.basic.sets.Pair<java.util.List<java.lang.Integer>,​java.util.List<java.lang.Integer>> sampleIntervals​(int m, long seed)
      Function sampling intervals based on the length of the time series m and the given seed.
      void setNumCPUs​(int numberOfCPUs)
      void setTimeout​(org.api4.java.algorithm.Timeout timeout)
      double[][][] transformInstances​(double[][] dataset, ai.libs.jaicore.basic.sets.Pair<java.util.List<java.lang.Integer>,​java.util.List<java.lang.Integer>> pairOfItervalLists)
      Method transforming the given dataset using the interval pairs specified in T1T2 by calculating each TimeSeriesFeature.FeatureType for every instance and interval pair.
      void tree​(double[][] data, int[] targets, double parentEntropy, ai.libs.jaicore.graph.TreeNode<ai.libs.jaicore.ml.weka.classification.singlelabel.timeseries.learner.trees.TimeSeriesTreeClassifier.TimeSeriesTreeNodeDecisionFunction> nodeToBeFilled, int depth)
      Tree generation (cf.

      • Methods inherited from class ai.libs.jaicore.ml.classification.singlelabel.timeseries.learner.ASimplifiedTSCLearningAlgorithm

        getClassifier

      • Methods inherited from class ai.libs.jaicore.basic.algorithm.AAlgorithm

        activate, announceTimeoutDetected, avoidReinterruptionOnShutdownOnCurrentThread, checkAndConductTermination, checkTermination, computeTimeoutAware, getActivationTime, getConfig, getDeadline, getId, getInput, getListeners, getLoggerName, getRemainingTimeToDeadline, getState, getTimeoutPrecautionOffset, hasThreadBeenInterruptedDuringShutdown, interruptThreadAsPartOfShutdown, isCanceled, isShutdownInitialized, isStopCriterionSatisfied, isTimeoutDefined, isTimeouted, post, registerActiveThread, resolveShutdownInterruptOnCurrentThread, setConfig, setDeadline, setLoggerName, setMaxNumThreads, setState, setTimeout, setTimeoutPrecautionOffset, shutdown, terminate, unregisterActiveThread, unregisterThreadAndShutdown

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

      • Methods inherited from interface java.util.Iterator

        forEachRemaining, remove

    • Field Detail

      • NUM_THRESH_CANDIDATES

        public static final int NUM_THRESH_CANDIDATES
        Number of threshold candidates created in each tree recursion step.
        See Also:
        Constant Field Values

      • ENTROPY_APLHA

        public static final double ENTROPY_APLHA
        Alpha parameter used to weight the importance of the feature's margins to the threshold candidates.
        See Also:
        Constant Field Values

      • USE_BIAS_CORRECTION

        public static final boolean USE_BIAS_CORRECTION
        Indicator that the bias (Bessel's) correction should be used for the calculation of the standard deviation.
        See Also:
        Constant Field Values

    • Constructor Detail

      • TimeSeriesTreeLearningAlgorithm

        public TimeSeriesTreeLearningAlgorithm​(TimeSeriesTreeLearningAlgorithm.ITimeSeriesTreeConfig config,
                                       TimeSeriesTreeClassifier tree,
                                       ai.libs.jaicore.ml.classification.singlelabel.timeseries.dataset.TimeSeriesDataset2 data)
        Constructor.
        Parameters:
        maxDepth - Maximal depth of the tree to be trained
        seed - Seed used for randomized operations
        useFeatureCaching - Indicator whether feature caching should be used. Since feature generation is very efficient, this should be only used if the time series is very long

    • Method Detail

      • registerListener

        public void registerListener​(java.lang.Object listener)
        Specified by:
        registerListener in interface org.api4.java.algorithm.IAlgorithm<ai.libs.jaicore.ml.classification.singlelabel.timeseries.dataset.TimeSeriesDataset2,​TimeSeriesTreeClassifier>
        Specified by:
        registerListener in interface org.api4.java.common.event.IEventEmitter<java.lang.Object>
        Overrides:
        registerListener in class ai.libs.jaicore.ml.classification.singlelabel.timeseries.learner.ASimplifiedTSCLearningAlgorithm<java.lang.Integer,​TimeSeriesTreeClassifier>

      • getNumCPUs

        public int getNumCPUs()
        Specified by:
        getNumCPUs in interface org.api4.java.algorithm.IAlgorithm<ai.libs.jaicore.ml.classification.singlelabel.timeseries.dataset.TimeSeriesDataset2,​TimeSeriesTreeClassifier>
        Overrides:
        getNumCPUs in class ai.libs.jaicore.basic.algorithm.AAlgorithm<ai.libs.jaicore.ml.classification.singlelabel.timeseries.dataset.TimeSeriesDataset2,​TimeSeriesTreeClassifier>

      • setNumCPUs

        public void setNumCPUs​(int numberOfCPUs)
        Specified by:
        setNumCPUs in interface org.api4.java.algorithm.IAlgorithm<ai.libs.jaicore.ml.classification.singlelabel.timeseries.dataset.TimeSeriesDataset2,​TimeSeriesTreeClassifier>
        Overrides:
        setNumCPUs in class ai.libs.jaicore.basic.algorithm.AAlgorithm<ai.libs.jaicore.ml.classification.singlelabel.timeseries.dataset.TimeSeriesDataset2,​TimeSeriesTreeClassifier>

      • setTimeout

        public void setTimeout​(org.api4.java.algorithm.Timeout timeout)
        Specified by:
        setTimeout in interface org.api4.java.algorithm.IAlgorithm<ai.libs.jaicore.ml.classification.singlelabel.timeseries.dataset.TimeSeriesDataset2,​TimeSeriesTreeClassifier>
        Overrides:
        setTimeout in class ai.libs.jaicore.basic.algorithm.AAlgorithm<ai.libs.jaicore.ml.classification.singlelabel.timeseries.dataset.TimeSeriesDataset2,​TimeSeriesTreeClassifier>

      • getTimeout

        public org.api4.java.algorithm.Timeout getTimeout()
        Specified by:
        getTimeout in interface org.api4.java.algorithm.IAlgorithm<ai.libs.jaicore.ml.classification.singlelabel.timeseries.dataset.TimeSeriesDataset2,​TimeSeriesTreeClassifier>
        Overrides:
        getTimeout in class ai.libs.jaicore.basic.algorithm.AAlgorithm<ai.libs.jaicore.ml.classification.singlelabel.timeseries.dataset.TimeSeriesDataset2,​TimeSeriesTreeClassifier>

      • nextWithException

        public org.api4.java.algorithm.events.IAlgorithmEvent nextWithException()
        Specified by:
        nextWithException in interface org.api4.java.algorithm.IAlgorithm<ai.libs.jaicore.ml.classification.singlelabel.timeseries.dataset.TimeSeriesDataset2,​TimeSeriesTreeClassifier>
        Overrides:
        nextWithException in class ai.libs.jaicore.ml.classification.singlelabel.timeseries.learner.ASimplifiedTSCLearningAlgorithm<java.lang.Integer,​TimeSeriesTreeClassifier>

      • call

        public TimeSeriesTreeClassifier call()
        Training procedure construction a time series tree using the given input data.

      • iterator

        public java.util.Iterator<org.api4.java.algorithm.events.IAlgorithmEvent> iterator()
        Specified by:
        iterator in interface java.lang.Iterable<org.api4.java.algorithm.events.IAlgorithmEvent>
        Overrides:
        iterator in class ai.libs.jaicore.ml.classification.singlelabel.timeseries.learner.ASimplifiedTSCLearningAlgorithm<java.lang.Integer,​TimeSeriesTreeClassifier>

      • hasNext

        public boolean hasNext()
        Specified by:
        hasNext in interface java.util.Iterator<org.api4.java.algorithm.events.IAlgorithmEvent>
        Overrides:
        hasNext in class ai.libs.jaicore.ml.classification.singlelabel.timeseries.learner.ASimplifiedTSCLearningAlgorithm<java.lang.Integer,​TimeSeriesTreeClassifier>

      • next

        public org.api4.java.algorithm.events.IAlgorithmEvent next()
        Specified by:
        next in interface java.util.Iterator<org.api4.java.algorithm.events.IAlgorithmEvent>
        Overrides:
        next in class ai.libs.jaicore.ml.classification.singlelabel.timeseries.learner.ASimplifiedTSCLearningAlgorithm<java.lang.Integer,​TimeSeriesTreeClassifier>

      • cancel

        public void cancel()
        Specified by:
        cancel in interface org.api4.java.common.control.ICancelable
        Overrides:
        cancel in class ai.libs.jaicore.ml.classification.singlelabel.timeseries.learner.ASimplifiedTSCLearningAlgorithm<java.lang.Integer,​TimeSeriesTreeClassifier>

      • tree

        public void tree​(double[][] data,
                 int[] targets,
                 double parentEntropy,
                 ai.libs.jaicore.graph.TreeNode<ai.libs.jaicore.ml.weka.classification.singlelabel.timeseries.learner.trees.TimeSeriesTreeClassifier.TimeSeriesTreeNodeDecisionFunction> nodeToBeFilled,
                 int depth)
        Tree generation (cf. Algorithm 2 of original paper). Samples the intervals in each recursion step and calculates the features (using caches if TimeSeriesTreeLearningAlgorithm#useFeatureCaching was set true). It then searches for an optimal split regarding several threshold candidates for feature splits. The splitting criterion is based on a metric called Entrance gain which is a combination of the entropy induced by the class proportions and the feature margins to the threshold (cf. chapter 4.1 in the paper). The tree's recursion is stopped at a leaf node if there is no entropy gain, the maxDepth has been reached or the local entropy is zero.
        Parameters:
        data - The untransformed data which will be used for the split in the transformed feature representation
        targets - The targets of the instances
        parentEntropy - The parent entropy calculated in the recursion's previous step
        nodeToBeFilled - The tree node which should be filled with the splitting information to use it for predictions
        depth - The current depth to be compared to the TimeSeriesTreeLearningAlgorithm#maxDepth

      • getChildDataIndices

        public static ai.libs.jaicore.basic.sets.Pair<java.util.List<java.lang.Integer>,​java.util.List<java.lang.Integer>> getChildDataIndices​(double[][][] transformedData,
                                                                                                                                             int n,
                                                                                                                                             int fType,
                                                                                                                                             int t1t2,
                                                                                                                                             double threshold)
        Function returning the data indices assigned to the left and the right child of a binary tree based on the splitting criterion given by the feature type fType, the intervals index t1t2 in the transformed data set transformedData and the threshold.
        Parameters:
        transformedData - Transformed data on which the split is calculated
        n - The number of instances
        fType - The feature type to be used for the split
        t1t2 - The interval's index in the transformedData to be used for the split
        threshold - The threshold to be used for the split
        Returns:
        Returns a pair of two lists, storing the data indices for the data points assigned to the left child of the current node (X) and the data indices assigned to the right child (Y)

      • getBestSplitIndex

        public int getBestSplitIndex​(double[] deltaEntropyStarPerFeatureType)
        Function returning feature type used for the split based on given the deltaEntropy star values. If multiple feature types have generated the same deltaEntropy value, a random decision is taken.
        Parameters:
        deltaEntropyStarPerFeatureType - The delta entropy star value per feature
        Returns:
        Returns the feature type index which has been chosen

      • calculateDeltaEntropy

        public static double calculateDeltaEntropy​(double[] dataValues,
                                           int[] targets,
                                           double thresholdCandidate,
                                           java.util.List<java.lang.Integer> classes,
                                           double parentEntropy)
        Function calculating the delta entropy for a given thresholdCandidate and parentEntropy. The values of the data are the feature type's values for each instance. The delta entropy is formed of the difference between the parent entropy and the weighted sum of the entropy values of the children and their instance assignments based on the split.
        Parameters:
        dataValues - The transformed feature type values for each instance
        targets - The targets of each instance
        thresholdCandidate - The threshold candidate to be evaluated
        classes - List storing the classes whose indices can be looked up
        parentEntropy - The parent entropy used for the delta calculation
        Returns:
        Returns the delta entropy for the threshold candidate of the current feature type

      • calculateEntrance

        public static double calculateEntrance​(double deltaEntropy,
                                       double margin)
        Calculates the entrance gain specified by Deng et. al. in the paper's chapter 4.1.
        Parameters:
        deltaEntropy - The delta entropy
        margin - The features margin
        Returns:
        Returns the entrance gain

      • calculateMargin

        public static double calculateMargin​(double[] dataValues,
                                     double thresholdCandidate)
        Function calculating the margin between the given thresholdCandidate and the nearest feature value from the given dataValues.
        Parameters:
        dataValues - The feature values compared to the candidate
        thresholdCandidate - The threshold candidate which is assessed
        Returns:
        Returns the minimum distance among the feature values and the threshold candidate

      • transformInstances

        public double[][][] transformInstances​(double[][] dataset,
                                       ai.libs.jaicore.basic.sets.Pair<java.util.List<java.lang.Integer>,​java.util.List<java.lang.Integer>> pairOfItervalLists)
        Method transforming the given dataset using the interval pairs specified in T1T2 by calculating each TimeSeriesFeature.FeatureType for every instance and interval pair.
        Parameters:
        dataset - The dataset which should be transformed
        pairOfItervalLists - The start and end interval pairs (see TimeSeriesTreeLearningAlgorithm#sampleIntervals(int, int))
        Returns:
        Returns the transformed instances (shape: number of feature types x number of interval pairs x number of instances)

      • generateThresholdCandidates

        public static java.util.List<java.util.List<java.lang.Double>> generateThresholdCandidates​(ai.libs.jaicore.basic.sets.Pair<java.util.List<java.lang.Integer>,​java.util.List<java.lang.Integer>> pairOfIntervalLists,
                                                                                           int numOfCandidates,
                                                                                           double[][][] transformedFeatures)
        Function generating threshold candidates for each feature type. It calculates the interval [min f_k(t1,t2), max f_k(t1,t2)] among all instances for every feature type and every possible interval and generates numberOfCandidates candidates using equal-width intervals.
        Parameters:
        pairOfIntervalLists - The pair of start and end interval pairs (see TimeSeriesTreeLearningAlgorithm#sampleIntervals(int, int))
        numOfCandidates - The number of candidates to be generated per feature type
        transformedFeatures - The transformed data instances
        Returns:
        Returns a list consisting of a list for each feature type storing the threshold candidates

      • sampleIntervals

        public static ai.libs.jaicore.basic.sets.Pair<java.util.List<java.lang.Integer>,​java.util.List<java.lang.Integer>> sampleIntervals​(int m,
                                                                                                                                         long seed)
        Function sampling intervals based on the length of the time series m and the given seed. Refers to algorithm 1 of the paper. The sampled intervals are stored in a pair of lists where each index of the first list is related to the same index in the second list. Sampling is done without replacement.
        Parameters:
        m - Number of time series attributes (steps)
        seed - The seed used for the randomized sampling
        Returns:
        Returns a pair of lists consisting of the start indices (X) and the end indices (Y)

      • randomlySampleNoReplacement

        public static java.util.List<java.lang.Integer> randomlySampleNoReplacement​(java.util.List<java.lang.Integer> list,
                                                                            int sampleSize,
                                                                            long seed)
        Function sampling a given list randomly without replacement using the given seed. sampleSize many elements are sampled and returned.
        Parameters:
        list - List to be sampled from without replacement
        sampleSize - Number of elements to be sampled (must be <= list.size())
        seed - The seed used for the randomized sampling
        Returns:
        Returns a list of elements which have been sampled