| Label | Explanation | Data 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.
| String |
Level of Confidence
(Optional) | Specifies the confidence level that will be used for the test for time series outliers.
| 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 |
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.
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.
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
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)| Name | Explanation | Data 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.
| String |
level_of_confidence (Optional) | Specifies the confidence level that will be used for the test for time series outliers.
| 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
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
)