TheTime Series AI toolset in the GeoAI toolbox contains tools for analyzing and processing time series data. This toolset includes tools for training and forecasting future values at locations in a space-time cube. It supports the training and application of various deep learning-based time series forecasting models, such as Fully Connected Networks (FCN), Long Short-Term Memory (LSTM), InceptionTime, ResNet, and ResCNN.
While these prebuilt models are robust and effective, they require extensive training on large, domain-specific time series datasets to achieve optimal performance. However, you may need a customized workflow, such as for integrating newer models including time series foundation models, offering off-the-shelf solutions for forecasting. These foundation models are pretrained on vast, diverse time series datasets and can be applied directly to predict future events based on specific input data, without requiring additional training. The functionality to generalize across different time series datasets makes them highly versatile.
Python developers can author a custom time series function to integrate ArcGIS with these external third-party models and package them as Esri deep learning packages (.dlpk files) for use with the Forecast Using Time Series Model tool.
Custom Python time series function
You can create a time series function in Python to integrate third-party time series models into a time series forecasting pipeline.
The time series function methods are listed in the following table and are more fully described in the subsections below.
| Method | Description |
|---|---|
__init__ | Initialize instance variables such as name, description, and other attributes essential for the time series function. |
initialize | Load the time series model and set up any initial configurations. Use this method at the start of the Python time series function. |
getParameterInfo | Define the parameters that the time series function accepts. This includes any configuration settings required to load or connect to the model as well as parameters needed for time series processing. |
getConfiguration | Describe how the tool will perform input processing and generate outputs. It includes details for any preprocessing or postprocessing steps necessary for the function. |
predict | The function responsible for converting input data to the desired output. It uses defined parameters and processing logic to produce the final result. |
Function methods
The time series function methods are described below.
__init__
The __init__ method is the constructor of the custom time series function and initializes instance variables such as the name, description, and other essential attributes. This method sets the properties that define the behavior and characteristics of the time series function.
The constructor creates an instance of a custom time series class with all the attributes necessary for processing and analysis. When an instance of the time series class is created, this method ensures that it is initialized with the required settings and default values. For example, if the time series function requires specific settings, such as the folder path containing the model weights and configuration file, they can be specified in this method.
class MyTimesFM:
def __init__(self, **kwargs):
"""
It sets up the initial state of an object by defining its attributes,
such as name, description, and other properties.
"""
self.name = "TimeSeriesForecast"
self.description = '''The `MyTimesFM` class is designed to perform time series forecasting tasks.'''
# Additional initialization code here
initialize
The initialize method is called at the start of the custom Python time series function and with this method, the kwargs['model'] argument is passed. The kwargs['model'] argument is the path to the Esri model definition file (.emd). The method should be used to load the model weights to set up the time series model, ensuring a reference to it for subsequent operations.
def initialize(self, **kwargs):
"""
Initialize model parameters, such as loading pretrained model weights.
"""
json_file = kwargs['model']
with open(json_file, 'r') as f:
self.json_info = json.load(f)
# Access the model path in the model definition file
model_path = json_info['ModelFile']
# Load your model and keep an instance for the modelt
self.model = load_your_model(model_path)
# Additional initialization code here
getParameterInfo
The getParameterInfo method is called by the Forecast Using Time Series Model tool after the initialize method and defines the parameters required by the model. This method returns a list of input parameters expected by the custom time series function. Each parameter is described using a dictionary containing the name, data type, display name, and description of the parameter, and a Boolean parameter indicating whether the parameter is required, as shown below.
def getParameterInfo(self):
return [
{
"name": "batch_size",
"dataType": "long",
"required": False,
"displayName": "batch_size",
"description": "The number of sequences processed in one forward pass through the model.",
"value": "16"
},
{
"name": "sequence_length",
"dataType": "long",
"required": True,
"displayName": "sequence_length",
"description": "Use the sequence length number of time steps to forecast the next user-defined time steps.",
"value": "32"
},
# Additional code here
]
The method returns a list of dictionaries, each describing a parameter. Key attributes of the dictionary are as follows:
- name—A string identifier for the parameter
- dataType—The type of data that the parameter accepts, such as a long, string, Boolean, or list
- value——The default value for the parameter
- required—A Boolean indicating whether the parameter is required
- displayName—A user-friendly name for the parameter
- domain—A set of allowed values if applicable
- description—A detailed description of the parameter
The list of parameters is displayed to the user through the custom model's model arguments in the Forecast Using Time Series Model tool. Users can set these values interactively using the tool user interface or programmatically pass them into the getConfiguration method as keyword arguments.
getConfiguration
The getConfiguration method configures and manages the parameters for the time series function. It accepts keyword arguments containing parameters updated by users through the tool or supplied programmatically. This method also controls how the function processes and outputs data based on the updated parameters. This method is invoked after the getParameterInfo method and before the predict method. The return value of the function is a dictionary containing value of the batch_size indicating how many sequences the model can process at a time. The return value of the method informs the tool on how to split the input data for processing by the model, one batch at a time.
def getConfiguration(self, **kwargs):
"""
This method configures the supported time series function parameters and
controls further processing based on them.
"""
# Set the sequence_length and batch_size from the provided arguments
self.sequence_length = int(kwargs.get("sequence_length"))
# Set the batch size, limiting it to a maximum of 4
if kwargs.get("batch_size", 0) > 4:
kwargs["batch_size"] = 4
self.batch_size = kwargs.get("batch_size")
# Set the number_of_timesteps_to_forecast from the toolset
self.number_of_timesteps_to_forecast = kwargs.get("number_of_timesteps_to_forecast")
# Return the updated parameter values
return kwargs
In the example above, the custom time series function is configured as follows:
- Set the sequence_length parameter from the provided arguments.
- Set the batch_size parameter to a maximum of 4 if a larger value is provided..
- Set the number_of_timesteps_to_forecast parameter from the toolset.
- Return the updated parameter values.
predict
The predict method performs inference by generating forecasts using the time series model. The method accepts a 2D NumPy array containing the input data and returns the results as a 2D NumPy array. The following outlines a typical workflow:
- Preprocess the input data to match the model’s requirements.
- Apply the time series model to the input data to generate forecasts.
def predict(self, input_sequences):
"""
Forecast time series data based on the input data.
"""
# Preprocessing input code here
# Input_sequences is a 2d Numpy Array of shape (batch_size, total number of time steps).
# Adjust the input sequence length as per the model requirements.
input_sequences = input_sequences[:, -self.sequence_length:]
# Make Forecasts
forecasts = self.model.predict(input_sequences, self.number_of_timesteps_to_forecast)
# Additional code here
# Return the forecasted values in the shape of (batch_size, number_of_timesteps_to_forecast)
return forecasts
Esri .emd file
After creating a custom Python time series function, include a reference to the function in the .emd file by specifying it next to the InferenceFunction parameter. This ensures that the .emd file correctly links to the function, enabling it to be used in time series forecasting.
{
"InferenceFunction": "MyTimesFM.py",
"ModelType": "TimeSeriesForecasting"
}The .emd file must include the following keys:
- InferenceFunction—The name of the file containing the custom time series function
- ModelType—Specifies the type of model, set to TimeSeriesForecasting
Custom .dlpk file
To complete the final third-party custom time series model, create a .dlpk model file. The .dlpk file allows you to use this model with the Forecast Using Time Series Model tool in the Time Series AI Toolset.
Organize the files as follows:
- Create a folder and include the custom time series function file (for example, MyTimesFM.py) and the Esri .emd file (for example, TimesFM.emd). The name of the folder must match the name of the .emd file.
TimesFM/ ├── MyTimesFM.py └── TimesFM.emd - Compress the folder into a ZIP archive. Rename the .zip file to match the name of the .emd file but with a .dlpk extension. The .dlpk file is now ready for use with the Forecast Using Time Series Model tool.