Package ai.libs.jaicore.ml.tsc.util

Class TimeSeriesUtil

  • public class TimeSeriesUtil
extends java.lang.Object
    Utility class for time series operations.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static double EPSILON  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static double[] backwardDifferenceDerivate​(double[] t)
      Calclualtes f'(n) = f(n-1) - f(n)
      static double[] backwardDifferenceDerivateWithBoundaries​(double[] t)
      Calclualtes f'(n) = f(n-1) - f(n)
      static TimeSeriesDataset createDatasetForMatrix​(double[][]... valueMatrices)
      Function creating a TimeSeriesDataset object given one or multiple valueMatrices.
      static TimeSeriesDataset createDatasetForMatrix​(int[] targets, double[][]... valueMatrices)
      Function creating a TimeSeriesDataset object given the targets and one or multiple valueMatrices.
      static double[] createEquidistantTimestamps​(double[] timeSeries)
      Creates equidistant timestamps for a time series.
      static org.nd4j.linalg.api.ndarray.INDArray createEquidistantTimestamps​(org.nd4j.linalg.api.ndarray.INDArray timeSeries)
      Creates equidistant timestamps for a time series.
      static double[] forwardDifferenceDerivate​(double[] t)
      f'(n) = f(n+1) - f(n)
      static double[] forwardDifferenceDerivateWithBoundaries​(double[] t)
      f'(n) = f(n+1) - f(n)
      static java.util.List<java.lang.Integer> getClassesInDataset​(TimeSeriesDataset dataset)
      Returns a list storing the unique Integer class values in the given dataset.
      static double[] getInterval​(double[] timeSeries, int start, int end)
      Function extracting the interval [start, end (exclusive)] out of the given timeSeries vector.
      static <T> T getMaximumKeyByValue​(java.util.Map<T,​java.lang.Integer> map)
      Returns the key with the maximum integer value.
      static int getMode​(int[] array)
      Returns the mode of the given array.
      static int getNumberOfClasses​(TimeSeriesDataset dataset)
      Counts the number of unique classes occurring in the given dataset.
      static ai.libs.jaicore.basic.sets.Pair<TimeSeriesDataset,​TimeSeriesDataset> getTrainingAndTestDataForFold​(int fold, int numFolds, double[][] srcValueMatrix, int[] srcTargetMatrix)
      Functions creating two TimeSeriesDataset objects representing the training and test split for the given fold of a cross validation with numFolds many folds.
      static double[] gulloDerivate​(double[] t)
      Calculates the derivative of a timeseries as described first by Gullo et. al (2009).
      static double[] gulloDerivateWithBoundaries​(double[] t)
      f'(n) = \frac{f(i+1)-f(i-1)}{2}
      static boolean isSameLength​(double[] timeSeries1, double[]... timeSeries)
      Checks whether multiple arrays have the same length.
      static boolean isSameLength​(org.nd4j.linalg.api.ndarray.INDArray timeSeries1, org.nd4j.linalg.api.ndarray.INDArray... timeSeries)
      Checks whether multiple arrays have the same length.
      static void isSameLengthOrException​(double[] timeSeries1, double[]... timeSeries)
      Checks whether multiple arrays have the same length.
      static void isSameLengthOrException​(org.nd4j.linalg.api.ndarray.INDArray timeSeries1, org.nd4j.linalg.api.ndarray.INDArray... timeSeries)
      Checks whether multiple arrays have the same length.
      static boolean isTimeSeries​(int length, double[]... array)
      Checks, whether given array are valid time series with a given length.
      static boolean isTimeSeries​(int length, org.nd4j.linalg.api.ndarray.INDArray... array)
      Checks, whether given INDArrays are valid time series with a given length.
      static boolean isTimeSeries​(org.nd4j.linalg.api.ndarray.INDArray... array)
      Checks, whether given INDArray are valid time series.
      static void isTimeSeriesOrException​(int length, double[]... array)
      Checks, whether given INDArrays are valid time series with a given length.
      static void isTimeSeriesOrException​(int length, org.nd4j.linalg.api.ndarray.INDArray... array)
      Checks, whether given INDArrays are valid time series with a given length.
      static void isTimeSeriesOrException​(org.nd4j.linalg.api.ndarray.INDArray... array)
      Checks, whether given INDArrays are valid time series.
      static double[] keoghDerivate​(double[] t)
      Calculates the derivative of a timeseries as described first by Keogh and Pazzani (2001).
      static double[] keoghDerivateWithBoundaries​(double[] t)
      Calculates the derivateive of a timeseries as described first by Keogh and Pazzani (2001).
      static double mean​(double[] t)  
      static double[] normalizeByStandardDeviation​(double[] t)  
      static org.nd4j.linalg.api.ndarray.INDArray normalizeINDArray​(org.nd4j.linalg.api.ndarray.INDArray array, boolean inplace)
      Normalizes an INDArray vector object.
      static void shuffleTimeSeriesDataset​(TimeSeriesDataset dataset, int seed)
      Shuffles the given TimeSeriesDataset object using the given seed.
      static java.util.List<java.lang.Integer> sortIndexes​(double[] vector, boolean ascending)
      Sorts the indices of the given vector based on the the vector's values (argsort).
      static double standardDeviation​(double[] t)
      Calculates the (population) standard deviation of the values of a times series.
      static double sum​(double[] t)  
      static java.lang.String toString​(double[] timeSeries)
      Enables printing of time series.
      static double variance​(double[] t)
      Calculates the (population) variance of the values of a times series.
      static double[] zNormalize​(double[] dataVector, boolean besselsCorrection)
      Z-normalizes a given dataVector.
      static double[] zTransform​(double[] t)  

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • isTimeSeries

        public static boolean isTimeSeries​(org.nd4j.linalg.api.ndarray.INDArray... array)
        Checks, whether given INDArray are valid time series.
        Parameters:
        array -
        Returns:
        True, if the all arrays are valid time series.

      • isTimeSeries

        public static boolean isTimeSeries​(int length,
                                   org.nd4j.linalg.api.ndarray.INDArray... array)
        Checks, whether given INDArrays are valid time series with a given length.
        Parameters:
        array -
        length -
        Returns:
        True, if the array is a valid time series of the given length. False, otherwise.

      • isTimeSeries

        public static boolean isTimeSeries​(int length,
                                   double[]... array)
        Checks, whether given array are valid time series with a given length.
        Parameters:
        array -
        length -
        Returns:
        True, if the array is a valid time series of the given length. False, otherwise.

      • isTimeSeriesOrException

        public static void isTimeSeriesOrException​(org.nd4j.linalg.api.ndarray.INDArray... array)
        Checks, whether given INDArrays are valid time series. Throws an exception otherwise.
        Parameters:
        array -
        Throws:
        java.lang.IllegalArgumentException

      • isTimeSeriesOrException

        public static void isTimeSeriesOrException​(int length,
                                           org.nd4j.linalg.api.ndarray.INDArray... array)
        Checks, whether given INDArrays are valid time series with a given length. Throws an exception otherwise.
        Parameters:
        array -
        length -
        Throws:
        java.lang.IllegalArgumentException

      • isTimeSeriesOrException

        public static void isTimeSeriesOrException​(int length,
                                           double[]... array)
        Checks, whether given INDArrays are valid time series with a given length. Throws an exception otherwise.
        Parameters:
        array -
        length -
        Throws:
        java.lang.IllegalArgumentException

      • isSameLength

        public static boolean isSameLength​(org.nd4j.linalg.api.ndarray.INDArray timeSeries1,
                                   org.nd4j.linalg.api.ndarray.INDArray... timeSeries)
        Checks whether multiple arrays have the same length.
        Parameters:
        timeSeries1 -
        timeSeries2 -
        Returns:
        True if the arrays have the same length. False, otherwise.

      • isSameLength

        public static boolean isSameLength​(double[] timeSeries1,
                                   double[]... timeSeries)
        Checks whether multiple arrays have the same length.
        Parameters:
        timeSeries1 -
        timeSeries2 -
        Returns:
        True if the arrays have the same length. False, otherwise.

      • isSameLengthOrException

        public static void isSameLengthOrException​(org.nd4j.linalg.api.ndarray.INDArray timeSeries1,
                                           org.nd4j.linalg.api.ndarray.INDArray... timeSeries)
        Checks whether multiple arrays have the same length. Throws an exception otherwise.
        Parameters:
        timeSeries1 -
        timeSeries2 -
        Throws:
        TimeSeriesLengthException

      • isSameLengthOrException

        public static void isSameLengthOrException​(double[] timeSeries1,
                                           double[]... timeSeries)
        Checks whether multiple arrays have the same length. Throws an exception otherwise.
        Parameters:
        timeSeries1 -
        timeSeries2 -
        Throws:
        TimeSeriesLengthException

      • createEquidistantTimestamps

        public static org.nd4j.linalg.api.ndarray.INDArray createEquidistantTimestamps​(org.nd4j.linalg.api.ndarray.INDArray timeSeries)
        Creates equidistant timestamps for a time series.
        Parameters:
        timeSeries - Time series to generate timestamps for. Let n be its length.
        Returns:
        Equidistant timestamp, i.e. {0, 1, .., n-1}.

      • createEquidistantTimestamps

        public static double[] createEquidistantTimestamps​(double[] timeSeries)
        Creates equidistant timestamps for a time series.
        Parameters:
        timeSeries - Time series to generate timestamps for. Let n be its length.
        Returns:
        Equidistant timestamp, i.e. {0, 1, .., n-1}.

      • getInterval

        public static double[] getInterval​(double[] timeSeries,
                                   int start,
                                   int end)
        Function extracting the interval [start, end (exclusive)] out of the given timeSeries vector.
        Parameters:
        timeSeries - Time series vector source
        start - Start of the interval
        end - End index of the interval (exclusive)
        Returns:
        Returns the specified interval as a double array

      • normalizeINDArray

        public static org.nd4j.linalg.api.ndarray.INDArray normalizeINDArray​(org.nd4j.linalg.api.ndarray.INDArray array,
                                                                     boolean inplace)
        Normalizes an INDArray vector object.
        Parameters:
        array - INDArray row vector with single shape dimension
        inplace - Indication whether the normalization should be performed in place or on a new array copy
        Returns:
        Returns the view on the transformed INDArray (if inplace) or a normalized copy of the input array (if not inplace)

      • getMode

        public static int getMode​(int[] array)
        Returns the mode of the given array. If there are multiple values with the same frequency, the lower value will be taken.
        Parameters:
        array - The array which mode should be returned
        Returns:
        Returns the mode, i. e. the most frequently occurring int value

      • getMaximumKeyByValue

        public static <T> T getMaximumKeyByValue​(java.util.Map<T,​java.lang.Integer> map)
        Returns the key with the maximum integer value. If there are multiple values with the same value, the lower key with regard to its type will be taken.
        Parameters:
        map - The map storing the keys with its corresponding integer values
        Returns:
        Returns the key of type storing the maximum integer value

      • zNormalize

        public static double[] zNormalize​(double[] dataVector,
                                  boolean besselsCorrection)
        Z-normalizes a given dataVector. Uses Bessel's correction (1/(n-1) in the calculation of the standard deviation) if set.
        Parameters:
        dataVector - Vector to be z-normalized
        besselsCorrection - Indicator whether the std dev correction using n-1 instead of n should be applied
        Returns:
        Z-normalized vector

      • sortIndexes

        public static java.util.List<java.lang.Integer> sortIndexes​(double[] vector,
                                                            boolean ascending)
        Sorts the indices of the given vector based on the the vector's values (argsort).
        Parameters:
        vector - Vector where the values are extracted from
        ascending - Indicator whether the indices should be sorted ascending
        Returns:
        Returns the list of indices which are sorting based on the vector's values

      • getNumberOfClasses

        public static int getNumberOfClasses​(TimeSeriesDataset dataset)
        Counts the number of unique classes occurring in the given dataset.
        Parameters:
        dataset - Dataset to be evaluated
        Returns:
        Returns the number of unique classes occurring in target matrix of the given dataset

      • getClassesInDataset

        public static java.util.List<java.lang.Integer> getClassesInDataset​(TimeSeriesDataset dataset)
        Returns a list storing the unique Integer class values in the given dataset.
        Parameters:
        dataset - Dataset to be evaluated
        Returns:
        Returns a List object storing the unique Integer class values of the dataset

      • shuffleTimeSeriesDataset

        public static void shuffleTimeSeriesDataset​(TimeSeriesDataset dataset,
                                            int seed)
        Shuffles the given TimeSeriesDataset object using the given seed.
        Parameters:
        dataset - The dataset to be shuffled
        seed - The seed used within the randomized shuffling

      • getTrainingAndTestDataForFold

        public static ai.libs.jaicore.basic.sets.Pair<TimeSeriesDataset,​TimeSeriesDataset> getTrainingAndTestDataForFold​(int fold,
                                                                                                                       int numFolds,
                                                                                                                       double[][] srcValueMatrix,
                                                                                                                       int[] srcTargetMatrix)
        Functions creating two TimeSeriesDataset objects representing the training and test split for the given fold of a cross validation with numFolds many folds. Data is extracted (and copied) from the given srcValueMatrix and srcTargetMatrix. The function uses the two functions TimeSeriesUtil#selectTrainingDataForFold(int, int, int, int, double[][], int[]) and TimeSeriesUtil#selectTestDataForFold(int, int, int, int, double[][], int[]).
        Parameters:
        fold - The current fold for which the datasets should be prepared
        numFolds - Number of total folds using within the performed cross validation
        srcValueMatrix - Source dataset from which the instances are copied
        srcTargetMatrix - Source targets from which the targets are copied
        Returns:
        Returns a pair consisting of the training and test dataset

      • createDatasetForMatrix

        public static TimeSeriesDataset createDatasetForMatrix​(int[] targets,
                                                       double[][]... valueMatrices)
        Function creating a TimeSeriesDataset object given the targets and one or multiple valueMatrices.
        Parameters:
        targets - The target values of the instances
        valueMatrices - One or more matrices storing the time series values
        Returns:
        Returns a TimeSeriesDataset object constructed out of the given parameters

      • createDatasetForMatrix

        public static TimeSeriesDataset createDatasetForMatrix​(double[][]... valueMatrices)
        Function creating a TimeSeriesDataset object given one or multiple valueMatrices.
        Parameters:
        valueMatrices - One or more matrices storing the time series values
        Returns:
        Returns a TimeSeriesDataset object constructed out of the given parameters

      • toString

        public static java.lang.String toString​(double[] timeSeries)
        Enables printing of time series.
        Parameters:
        timeSeries - Time series to print.
        Returns:
        Readable string of the time series, i.e. "{1.0, 2.0, 3.0, 4.0}"

      • keoghDerivate

        public static double[] keoghDerivate​(double[] t)
        Calculates the derivative of a timeseries as described first by Keogh and Pazzani (2001). f'(n) = \frac{ f(n) - f(n-1) + /frac{f(i+1) - f(i-1)}{2} }{2}
        Parameters:
        t -
        Returns:

      • keoghDerivateWithBoundaries

        public static double[] keoghDerivateWithBoundaries​(double[] t)
        Calculates the derivateive of a timeseries as described first by Keogh and Pazzani (2001). f'(n) = \frac{ f(n) - f(n-1) + /frac{f(i+1) - f(i-1)}{2} }{2}
        Parameters:
        t -
        Returns:

      • backwardDifferenceDerivate

        public static double[] backwardDifferenceDerivate​(double[] t)
        Calclualtes f'(n) = f(n-1) - f(n)
        Parameters:
        t - Time series.
        Returns:

      • backwardDifferenceDerivateWithBoundaries

        public static double[] backwardDifferenceDerivateWithBoundaries​(double[] t)
        Calclualtes f'(n) = f(n-1) - f(n)
        Parameters:
        t - Time series.
        Returns:

      • forwardDifferenceDerivate

        public static double[] forwardDifferenceDerivate​(double[] t)
        f'(n) = f(n+1) - f(n)
        Parameters:
        t -
        Returns:

      • forwardDifferenceDerivateWithBoundaries

        public static double[] forwardDifferenceDerivateWithBoundaries​(double[] t)
        f'(n) = f(n+1) - f(n)
        Parameters:
        t -
        Returns:

      • gulloDerivate

        public static double[] gulloDerivate​(double[] t)
        Calculates the derivative of a timeseries as described first by Gullo et. al (2009).
        Parameters:
        t -
        Returns:

      • gulloDerivateWithBoundaries

        public static double[] gulloDerivateWithBoundaries​(double[] t)
        f'(n) = \frac{f(i+1)-f(i-1)}{2}
        Parameters:
        t -
        Returns:

      • sum

        public static double sum​(double[] t)

      • mean

        public static double mean​(double[] t)

      • variance

        public static double variance​(double[] t)
        Calculates the (population) variance of the values of a times series.

      • standardDeviation

        public static double standardDeviation​(double[] t)
        Calculates the (population) standard deviation of the values of a times series.

      • zTransform

        public static double[] zTransform​(double[] t)

      • normalizeByStandardDeviation

        public static double[] normalizeByStandardDeviation​(double[] t)