Curve Fit Forecast (Space Time Pattern Mining)—ArcGIS Pro

Summary

Forecasts the values of each location of a space-time cube using curve fitting.

The tool fits a parametric curve to each location in the Input Space Time Cube parameter and forecasts the time series by extrapolating this curve to future time steps. The curves can be linear, parabolic, S-shaped (Gompertz), or exponential. You can use the same curve type at each location of the space-time cube or allow the tool to set the curve type that best fits each location.

Learn more about how Curve Fit Forecast works

Illustration

Four curve types are shown.

Usage

This tool accepts netCDF files created by the Create Space Time Cube By Aggregating Points, Create Space Time Cube From Defined Features, and Create Space Time Cube from Multidimensional Raster Layer tools.
Compared to other forecasting tools in the Time Series Forecasting toolset, this tool is the most straightforward, and it is most appropriate for time series that follow a predictable trend that does not display strong seasonality. If your data follows a complex trend or displays strong seasonal cycles, use other forecasting tools.
Multiple forecasted space-time cubes can be compared and merged using the Evaluate Forecasts By Location tool. This allows you to create multiple forecast cubes using different forecasting tools and parameters, and the tool will identify the best forecast for each location using either Forecast root mean square error (RMSE) or Validation RMSE.
For each location in the Input Space Time Cube parameter, the tool builds two models that serve different purposes.
- Forecast model—This model is used to forecast values of the space-time cube by fitting a curve to the values of the time series and extrapolating this curve to future time steps. The fit of the forecast model to the values of the space-time cube is measured by the Forecast RMSE value.
- Validation model—This model is used to validate the forecast model and test how accurately it can forecast values. If a number greater than 0 is specified for the Number of Time Steps to Exclude for Validation parameter, this model is fitted to the time steps that were included and is used to forecast the values of the time steps that were excluded. This allows you to see how well the chosen curve type can forecast values. The fit of the forecasted values to the excluded values is measured by the Validation RMSE value.
Learn more about the forecast model, validation model, and RMSE statistics
The Auto-Detect option of the Curve Type parameter will fit all four curve types at each location and identify the one with the smallest Validation RMSE. If no time steps are excluded for validation, the curve with the smallest Forecast RMSE is used.
The Output Features parameter values will be added to the Contents pane with rendering based on the final forecasted time step.
This tool creates geoprocessing messages and pop-up charts to help you 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. Clicking a feature using the Explore navigation tool displays a line chart in the Pop-up pane showing the values of the space-time cube, the curve used to forecast, and the forecasted values for that location.
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
Deciding how many time steps to exclude for validation is an important choice. The more time steps are excluded, the fewer time steps remain to estimate the validation model. However, if too few time steps are excluded, the Validation RMSE will be estimated using a small amount of data and may be misleading. It is recommended that you exclude as many time steps as possible while maintaining sufficient time steps to estimate the validation model. It is also suggested that you withhold at least as many time steps for validation as the number of time steps you intend to forecast, if your space-time cube has enough time steps to allow this.

Parameters

Label	Explanation	Data Type
Input Space Time Cube	The netCDF cube containing the variable 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
Analysis Variable	The numeric variable in the netCDF file that will be forecasted to future time steps.	String
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-ups charts showing the time series and forecasts for each location.	Feature Class
Output Space Time Cube (Optional)	A new space-time cube (.nc file) containing the values of the input space-time cube with the forecasted time steps appended. The Visualize Space Time Cube in 3D tool can be used to see all of the observed and forecasted values simultaneously.	File
Number of Time Steps to Forecast (Optional)	A positive integer specifying the number of time steps to forecast. This value cannot be larger than 50 percent of the total time steps in the input space-time cube. The default value is one time step.	Long
Curve Type (Optional)	Specifies the curve type that will be used to forecast the values of the input space-time cube. Linear —The time series increases or decreases linearly over time. Parabolic —The time series follows a parabola or quadratic curve over time. Exponential —The time series increases or decreases exponentially over time. S-shaped (Gompertz) —The time series increases or decreases following the shape of an S over time. Auto-detect —All four curve types are run for each location and the model is provided the smallest Validation RMSE. If no time slices are excluded for validation, the model with the smallest Forecast RMSE is used. This is the default.	String
Number of Time Steps to Exclude for Validation (Optional)	The number of time steps at the end of each time series to exclude for validation. The default value is 10 percent (rounded down) of the number of input time steps, and this value cannot be larger than 25 percent of the number of time steps. Provide the value 0 to not exclude any time steps.	Long
Outlier Option (Optional)	Specifies whether statistically significant time series outliers will be identified. None —Outliers will not be identified. This is the default. Identify outliers —Outliers will be identified using the Generalized ESD test.	String
Level of Confidence (Optional)	Specifies the confidence level for the test for time series outliers. 90% — The confidence level for the test is 90 percent. This is the default. 95% — The confidence level for the test is 95 percent. 99% — The confidence level for the test is 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). This value cannot exceed 20 percent of the number of time steps.	Long

arcpy.stpm.CurveFitForecast(in_cube, analysis_variable, output_features, {output_cube}, {number_of_time_steps_to_forecast}, {curve_type}, {number_for_validation}, {outlier_option}, {level_of_confidence}, maximum_number_of_outliers)

Name	Explanation	Data Type
in_cube	The netCDF cube containing the variable 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
analysis_variable	The numeric variable in the netCDF file that will be forecasted to future time steps.	String
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-ups charts showing the time series and forecasts for each location.	Feature Class
output_cube (Optional)	A new space-time cube (.nc file) containing the values of the input space-time cube with the forecasted time steps appended. The Visualize Space Time Cube in 3D tool can be used to see all of the observed and forecasted values simultaneously.	File
number_of_time_steps_to_forecast (Optional)	A positive integer specifying the number of time steps to forecast. This value cannot be larger than 50 percent of the total time steps in the input space-time cube. The default value is one time step.	Long
curve_type (Optional)	Specifies the curve type that will be used to forecast the values of the input space-time cube. LINEAR —The time series increases or decreases linearly over time. PARABOLIC —The time series follows a parabola or quadratic curve over time. EXPONENTIAL —The time series increases or decreases exponentially over time. GOMPERTZ —The time series increases or decreases following the shape of an S over time. AUTO_DETECT —All four curve types are run for each location and the model is provided the smallest Validation RMSE. If no time slices are excluded for validation, the model with the smallest Forecast RMSE is used. This is the default.	String
number_for_validation (Optional)	The number of time steps at the end of each time series to exclude for validation. The default value is 10 percent (rounded down) of the number of input time steps, and this value cannot be larger than 25 percent of the number of time steps. Provide the value 0 to not exclude any time steps.	Long
outlier_option (Optional)	Specifies whether statistically significant time series outliers will be identified. NONE —Outliers will not be identified. This is the default. IDENTIFY —Outliers will be identified using the Generalized ESD test.	String
level_of_confidence (Optional)	Specifies the confidence level for the test for time series outliers. 90% —The confidence level for the test is 90 percent. This is the default. 95% —The confidence level for the test is 95 percent. 99% —The confidence level for the test is 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). This value cannot exceed 20 percent of the number of time steps.	Long

Code sample

CurveFitForecast example 1 (Python window)

The following Python script demonstrates how to use the CurveFitForecast tool.

import arcpy
arcpy.env.workspace = "C:/Analysis"

# Forecast four time steps using a linear curve.
arcpy.stpm.CurveFitForecast("Population.nc", "Pop_NONE_ZEROS", 
                            "Analysis.gdb/Forecasts", 
                            "outForecastCube.nc", 4, 
                            "LINEAR", 5)

CurveFitForecast example 2 (stand-alone script)

The following Python script demonstrates how to use the CurveFitForecast tool to forecast population:

# Forecast population levels using curve fitting.

# Import system modules.
import arcpy

# Set property to overwrite existing output.
arcpy.env.overwriteOutput = True

# Set workspace.
workspace = r"C:\Analysis"
arcpy.env.workspace = workspace

# Forecast three time steps using auto-detect.
arcpy.stpm.CurveFitForecast("Population.nc", "Pop_NONE_ZEROS", 
                            "Analysis.gdb/Forecasts", "outForecastCube.nc"
                            3, "AUTO_DETECT", 5, "IDENTIFY", "90%", 4)

# Create a feature class visualizing the forecasts.
# Output can only be viewed in a Scene view.
arcpy.stpm.VisualizeSpaceTimeCube3D("outForecastCube.nc", "Pop_NONE_ZEROS", 
                                    "VALUE", "Analysis.gdb/ForecastsFC")

Environments

Output Coordinate System

Licensing information

Basic: Yes
Standard: Yes
Advanced: Yes