Forecast Using Time Series Model (GeoAI)

Summary

Predicts the values of each location of a space-time cube using a deep learning-based time series forecasting model that has been trained using the Train Time Series Forecasting Model tool.

Usage

  • You must install the proper deep learning framework for Python in ArcGIS AllSource.

    Learn how to install deep learning frameworks for ArcGIS

  • The input is an Esri model definition file (.emd) or a deep learning package file (.dlpk), which can be created using the Train Time Series Forecasting Model tool.

  • This tool accepts netCDF data created by the Create Space Time Cube By Aggregating Points, Create Space Time Cube From Defined Locations, Create Space Time Cube from Multidimensional Raster Layer, and Subset Space Time Cube tools.

  • This tool uses deep learning-based time series forecasting models. Deep learning models have a high capacity to learn and are appropriate for time series that follow complex trends and are difficult to model with simple mathematical functions. However, they require a larger volume of training data to learn such complex trends and use more computational resources for training and inference. A GPU is recommended for using this tool.

  • The Outlier Option parameter can be used to detect statistically significant outliers in the time series values at each location.

    Learn more about detecting time series outliers

  • To run this tool using a GPU, set the Processor Type environment to GPU. If you have more than one GPU, specify the GPU ID environment instead.

  • This tool uses a single global forecast model that has been trained on time series data from each location.

  • The Output Features parameter value will be added to the Contents pane with rendering based on the best saved model forecasted time step.

  • This tool creates geoprocessing messages and pop-up charts you can use to understand and visualize the forecast results. The messages contain information about the structure of the space-time cube and summary statistics of the RMSE values. Click a feature using the Explore navigation tool to display a line chart in the Pop-up pane showing the values of the space-time cube and fitted values and forecasted values for that location

  • For information about requirements for running this tool and issues you may encounter, see Deep Learning frequently asked questions.

Parameters

LabelExplanationData Type
Input Time Series Data

The netCDF cube containing the variable that will be used to forecast to future time steps. This file must have an .nc file extension and must have been created using the Create Space Time Cube By Aggregating Points, Create Space Time Cube From Defined Locations, or Create Space Time Cube From Multidimensional Raster Layer tool.

File
Model Definition

The trained deep learning model file (.dlpk or .emd) that will be used to make the predictions. The model can be trained using the Train Time Series Forecasting Model tool.

File
Output Features

The output feature class of all locations in the space-time cube with forecasted values stored as fields. The layer displays the forecast for the final time step and contains pop-up charts showing the time series and forecasts for each location.

Feature Class
Number of Time Steps to Forecast

A positive integer specifying the number of time steps that will be used to forecast the analysis variable. The default value is 2. This value cannot be larger than 50 percent of the total time steps in the input space-time cube for one-step forecasting, and it cannot be larger than 50 percent of the Sequence Length parameter value in the Train Time Series Forecasting Model tool for multistep forecasting.

Long
Match Explanatory Variables
(Optional)

The mapping of field names from the prediction set to the training set. Use this parameter if the field names of the training and prediction sets are different. The values are the field names in the prediction dataset that match the field names in the input time series data.

Value Table
Output Cube
(Optional)

An output space-time cube (.nc file) containing the values of the input space-time cube with the forecasted time steps appended. Use the Visualize Space Time Cube in 3D tool to see all of the observed and forecasted values simultaneously.

File
Outlier Option
(Optional)

Specifies whether statistically significant time series outliers will be identified.

  • NoneOutliers will not be identified. This is the default.
  • Identify outliersOutliers will be identified using the Generalized ESD test.
String
Level of Confidence
(Optional)

Specifies the confidence level that will be used for the test for time series outliers.

  • 90%The confidence level for the test will be 90 percent. This is the default.
  • 95%The confidence level for the test will be 95 percent.
  • 99%The confidence level for the test will be 99 percent.
String
Maximum Number of Outliers

The maximum number of time steps that can be declared outliers for each location. The default value corresponds to 5 percent (rounded down) of the number of time steps of the input space-time cube (a value of at least 1 will always be used). The value cannot exceed 20 percent of the number of time steps.

Long

arcpy.geoai.ForecastUsingTimeSeriesModel(in_cube, in_model_definition, out_features, number_of_timesteps_to_forecast, {match_explanatory_variables}, {out_cube}, {outlier_option}, {level_of_confidence}, maximum_number_of_outliers)
NameExplanationData Type
in_cube

The netCDF cube containing the variable that will be used to forecast to future time steps. This file must have an .nc file extension and must have been created using the Create Space Time Cube By Aggregating Points, Create Space Time Cube From Defined Locations, or Create Space Time Cube From Multidimensional Raster Layer tool.

File
in_model_definition

The trained deep learning model file (.dlpk or .emd) that will be used to make the predictions. The model can be trained using the Train Time Series Forecasting Model tool.

File
out_features

The output feature class of all locations in the space-time cube with forecasted values stored as fields. The layer displays the forecast for the final time step and contains pop-up charts showing the time series and forecasts for each location.

Feature Class
number_of_timesteps_to_forecast

A positive integer specifying the number of time steps that will be used to forecast the analysis variable. The default value is 2. This value cannot be larger than 50 percent of the total time steps in the input space-time cube for one-step forecasting, and it cannot be larger than 50 percent of the sequence_length parameter value in the Train Time Series Forecasting Model tool for multistep forecasting.

Long
match_explanatory_variables
[match_explanatory_variables,...]
(Optional)

The mapping of field names from the prediction set to the training set. Use this parameter if the field names of the training and prediction sets are different. The values are the field names in the prediction dataset that match the field names in the input time series data.

Value Table
out_cube
(Optional)

An output space-time cube (.nc file) containing the values of the input space-time cube with the forecasted time steps appended. Use the Visualize Space Time Cube in 3D tool to see all of the observed and forecasted values simultaneously.

File
outlier_option
(Optional)

Specifies whether statistically significant time series outliers will be identified.

  • NONEOutliers will not be identified. This is the default.
  • IDENTIFYOutliers will be identified using the Generalized ESD test.
String
level_of_confidence
(Optional)

Specifies the confidence level that will be used for the test for time series outliers.

  • 90%The confidence level for the test will be 90 percent. This is the default.
  • 95%The confidence level for the test will be 95 percent.
  • 99%The confidence level for the test will be 99 percent.
String
maximum_number_of_outliers

The maximum number of time steps that can be declared outliers for each location. The default value corresponds to 5 percent (rounded down) of the number of time steps of the input space-time cube (a value of at least 1 will always be used). The value cannot exceed 20 percent of the number of time steps.

Long

Code sample

ForecastUsingTimeSeriesModel example (stand-alone script)

This example shows how to use the ForecastUsingTimeSeriesModel function.

# Description: Forecast a time series model on space-time cube data with the trained model 
#              obtained by the TrainTimeSeriesForecastingModel function.

# Import system modules
import arcpy
import os

# Set local variables
datapath  = "path_to_data_for_forecasting" 
out_path = "path_to_gdb_for_forecasting"

model_path = os.path.join(out_path, "model.dlpk")
in_cube = os.path.join(datapath, "test_data")
output_features = os.path.join(out_path, "forecasted_feature.gdb", "forecasted")

# Run Forecast Using Time Series Model 
r = arcpy.geoai.ForecastUsingTimeSeriesModel(
    in_cube,
    model_path,
    output_features,
    number_of_timesteps_to_forecast=2,
    match_explanatory_variables=None
)