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 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.

  • 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.

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

arcpy.geoai.ForecastUsingTimeSeriesModel(in_cube, in_model_definition, out_features, number_of_timesteps_to_forecast, {match_explanatory_variables})
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.

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

Code sample

ForecastUsingTimeSeriesModel (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
)