[Extension] Add GluonTS extension

examples/build.gradle

@@ -7,6 +7,7 @@ dependencies {
  implementation "org.apache.logging.log4j:log4j-slf4j-impl:${log4j_slf4j_version}"
  implementation project(":basicdataset")
  implementation project(":model-zoo")
+ implementation project(":extensions:timeseries")
 
  runtimeOnly project(":engines:pytorch:pytorch-model-zoo")
  runtimeOnly project(":engines:tensorflow:tensorflow-model-zoo")

examples/src/main/java/ai/djl/examples/inference/timeseries/DeepARTimeSeries.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright 2022 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
+ * with the License. A copy of the License is located at
+ *
+ * http://aws.amazon.com/apache2.0/
+ *
+ * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
+ * OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions
+ * and limitations under the License.
+ */
+package ai.djl.examples.inference.timeseries;
+
+import ai.djl.ModelException;
+import ai.djl.inference.Predictor;
+import ai.djl.ndarray.NDArray;
+import ai.djl.ndarray.types.DataType;
+import ai.djl.ndarray.types.Shape;
+import ai.djl.repository.zoo.Criteria;
+import ai.djl.repository.zoo.ZooModel;
+import ai.djl.timeseries.ForeCast;
+import ai.djl.timeseries.TimeSeriesData;
+import ai.djl.timeseries.dataset.FieldName;
+import ai.djl.timeseries.translator.DeepARTranslator;
+import ai.djl.training.util.ProgressBar;
+import ai.djl.translate.TranslateException;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.time.LocalDateTime;
+import java.util.Arrays;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/** The example is targeted to specific use case for DeepAR time series forecast. */
+public final class DeepARTimeSeries {
+
+ private static final Logger logger = LoggerFactory.getLogger(DeepARTimeSeries.class);
+
+ private DeepARTimeSeries() {}
+
+ public static void main(String[] args) throws IOException, TranslateException, ModelException {
+ logger.info("model: DeepAR");
+ float[] results = DeepARTimeSeries.predict();
+ logger.info("Prediction result: {}", Arrays.toString(results));
+ }
+
+ public static float[] predict() throws IOException, TranslateException, ModelException {
+ String modelUrl = "https://resources.djl.ai/test-models/mxnet/timeseries/deepar.zip";
+ Map<String, Object> arguments = new ConcurrentHashMap<>();
+ arguments.put("prediction_length", 28);
+ DeepARTranslator.Builder builder = DeepARTranslator.builder(arguments);
+ DeepARTranslator translator = builder.build();
+ Criteria<TimeSeriesData, ForeCast> criteria =
+ Criteria.builder()
+ .setTypes(TimeSeriesData.class, ForeCast.class)
+ .optModelUrls(modelUrl)
+ .optTranslator(translator)
+ .optProgress(new ProgressBar())
+ .build();
+
+ try (ZooModel<TimeSeriesData, ForeCast> model = criteria.loadModel();
+ Predictor<TimeSeriesData, ForeCast> predictor = model.newPredictor()) {
+ TimeSeriesData input = new TimeSeriesData(1);
+ input.setStartTime(LocalDateTime.parse("2011-01-29T00:00"));
+ NDArray target =
+ model.getNDManager()
+ .randomUniform(0f, 50f, new Shape(1857))
+ .toType(DataType.FLOAT32, false);
+ input.setField(FieldName.TARGET, target);
+ ForeCast foreCast = predictor.predict(input);
+
+ return foreCast.mean().toFloatArray();
+ }
+ }
+}

examples/src/main/java/ai/djl/examples/inference/timeseries/TransformerTimeSeries.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright 2022 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
+ * with the License. A copy of the License is located at
+ *
+ * http://aws.amazon.com/apache2.0/
+ *
+ * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
+ * OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions
+ * and limitations under the License.
+ */
+package ai.djl.examples.inference.timeseries;
+
+import ai.djl.ModelException;
+import ai.djl.inference.Predictor;
+import ai.djl.ndarray.NDArray;
+import ai.djl.ndarray.types.DataType;
+import ai.djl.ndarray.types.Shape;
+import ai.djl.repository.zoo.Criteria;
+import ai.djl.repository.zoo.ZooModel;
+import ai.djl.timeseries.ForeCast;
+import ai.djl.timeseries.TimeSeriesData;
+import ai.djl.timeseries.dataset.FieldName;
+import ai.djl.timeseries.translator.TransformerTranslator;
+import ai.djl.training.util.ProgressBar;
+import ai.djl.translate.TranslateException;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.time.LocalDateTime;
+import java.util.Arrays;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/** The example is targeted to specific use case for Transformer time series forecast. */
+public final class TransformerTimeSeries {
+
+ private static final Logger logger = LoggerFactory.getLogger(TransformerTimeSeries.class);
+
+ private TransformerTimeSeries() {}
+
+ public static void main(String[] args) throws IOException, TranslateException, ModelException {
+ logger.info("model: Transformer");
+ float[] results = TransformerTimeSeries.predict();
+ logger.info("Prediction result: {}", Arrays.toString(results));
+ }
+
+ public static float[] predict() throws IOException, TranslateException, ModelException {
+ String modelUrl = "https://resources.djl.ai/test-models/mxnet/timeseries/transformer.zip";
+ Map<String, Object> arguments = new ConcurrentHashMap<>();
+ arguments.put("prediction_length", 28);
+ TransformerTranslator.Builder builder = TransformerTranslator.builder(arguments);
+ TransformerTranslator translator = builder.build();
+ Criteria<TimeSeriesData, ForeCast> criteria =
+ Criteria.builder()
+ .setTypes(TimeSeriesData.class, ForeCast.class)
+ .optModelUrls(modelUrl)
+ .optTranslator(translator)
+ .optProgress(new ProgressBar())
+ .build();
+
+ try (ZooModel<TimeSeriesData, ForeCast> model = criteria.loadModel();
+ Predictor<TimeSeriesData, ForeCast> predictor = model.newPredictor()) {
+ TimeSeriesData input = new TimeSeriesData(1);
+ input.setStartTime(LocalDateTime.parse("2011-01-29T00:00"));
+ NDArray target =
+ model.getNDManager()
+ .randomUniform(0f, 50f, new Shape(1857))
+ .toType(DataType.FLOAT32, false);
+ input.setField(FieldName.TARGET, target);
+ ForeCast foreCast = predictor.predict(input);
+
+ return foreCast.mean().toFloatArray();
+ }
+ }
+}

examples/src/main/java/ai/djl/examples/inference/timeseries/package-info.java

@@ -0,0 +1,14 @@
+/*
+ * Copyright 2022 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
+ * with the License. A copy of the License is located at
+ *
+ * http://aws.amazon.com/apache2.0/
+ *
+ * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
+ * OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions
+ * and limitations under the License.
+ */
+/** Contains examples for time series. */
+package ai.djl.examples.inference.timeseries;

extensions/timeseries/README.md

@@ -0,0 +1,35 @@
+# TimeSeries support
+
+This module contains the time series model support extension with [gluon-ts](https:/awslabs/gluon-ts).
+
+Right now, the package provides the `BaseTimeSeriesTranslator` and transform package that allows you to do inference from your pre-trained time series model.
+
+The following pseudocode demonstrates how to create a `DeepARTranslator` with `arguments`.
+
+```java
+ Map<String, Object> arguments = new ConcurrentHashMap<>();
+ arguments.put("prediction_length", 28);
+ arguments.put("use_feat_dynamic_real", false);
+ DeepARTranslator.Builder builder = DeepARTranslator.builder(arguments);
+ DeepARTranslator translator = builder.build();
+```
+
+If you want to customize your own time series model translator, you can easily use the transform package for your data preprocess.
+
+See [examples](./src/main/java/ai/djl/timeseries/examples) for more details.
+
+We plan to add the following features in the future:
+
+- a `TimeSeriesDataset`class to support creating data entry and transforming raw csv data like in TimeSeries.
+- Many time series models that can be trained in djl.
+- ......
+
+## Documentation
+
+You can build the latest javadocs locally using the following command:
+
+```sh
+./gradlew javadoc
+```
+
+The javadocs output is built in the `build/doc/javadoc` folder.

extensions/timeseries/build.gradle

@@ -0,0 +1,29 @@
+group 'ai.dj.timeseries'
+
+dependencies {
+ api project(":api")
+ api project(":basicdataset")
+ api "tech.tablesaw:tablesaw-core:${tablesaw_version}"
+ api "tech.tablesaw:tablesaw-jsplot:${tablesaw_version}"
+
+ testImplementation("org.testng:testng:${testng_version}") {
+ exclude group: "junit", module: "junit"
+ }
+
+ testImplementation "org.slf4j:slf4j-simple:${slf4j_version}"
+ testImplementation project(":testing")
+
+ testRuntimeOnly project(":engines:mxnet:mxnet-model-zoo")
+}
+
+publishing {
+ publications {
+ maven(MavenPublication) {
+ pom {
+ name = "TimeSeries for DJL"
+ description = "TimeSeries for DJL"
+ url = "http://www.djl.ai/extensions/${project.name}"
+ }
+ }
+ }
+}

extensions/timeseries/gradlew

@@ -0,0 +1 @@
+../../gradlew

extensions/timeseries/src/main/java/ai/djl/timeseries/ForeCast.java

@@ -0,0 +1,98 @@
+/*
+ * Copyright 2022 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
+ * with the License. A copy of the License is located at
+ *
+ * http://aws.amazon.com/apache2.0/
+ *
+ * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
+ * OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions
+ * and limitations under the License.
+ */
+package ai.djl.timeseries;
+
+import ai.djl.ndarray.NDArray;
+
+import java.time.LocalDateTime;
+
+/** An abstract class representing the forecast results for the time series data. */
+public abstract class ForeCast {
+
+ protected LocalDateTime startDate;
+ protected int predictionLength;
+ protected NDArray mean;
+ protected String freq;
+
+ /**
+ * Constructs a {@code Forecast} instance.
+ *
+ * @param startDate the time series start date
+ * @param predictionLength the time length of prediction
+ * @param freq the prediction frequency
+ */
+ public ForeCast(LocalDateTime startDate, int predictionLength, String freq) {
+ this.startDate = startDate;
+ this.predictionLength = predictionLength;
+ this.freq = freq;
+ }
+
+ /**
+ * Computes a quantile from the predicted distribution.
+ *
+ * @param q quantile to compute
+ * @return value of the quantile across the prediction range
+ */
+ public abstract NDArray quantile(float q);
+
+ /**
+ * Computes a quantile from the predicted distribution.
+ *
+ * @param q quantile to compute
+ * @return value of the quantile across the prediction range
+ */
+ public NDArray quantile(String q) {
+ return quantile(Float.parseFloat(q));
+ }
+
+ /**
+ * Computes the median of forecast.
+ *
+ * @return value of the median
+ */
+ public NDArray median() {
+ return quantile(0.5f);
+ }
+
+ /**
+ * Returns the prediction frequency like "D", "H"....
+ *
+ * @return the prediction frequency
+ */
+ public String freq() {
+ return freq;
+ }
+
+ /**
+ * Returns the time length of forecast.
+ *
+ * @return the prediction length
+ */
+ public int predictionLength() {
+ return predictionLength;
+ }
+
+ /**
+ * Computes and returns the forecast mean.
+ *
+ * @return forecast mean
+ */
+ public NDArray mean() {
+ return mean;
+ }
+
+ /** Plots the prediction result with {@code Tablesaw}. */
+ public void plot() {
+ throw new UnsupportedOperationException("plot is not supported yet");
+ }
+}