将第三方时间序列预测模型与 ArcGIS 结合使用

GeoAI 工具箱中的时序 AI 工具集包含了用于分析和处理时间序列数据的工具。此工具集包含了用于训练和预测时空立方体中位置的未来值的工具。它可为训练和应用各种基于深度学习的时间序列预测模型（例如全连接网络 (FCN)、长短期记忆 (LSTM)、InceptionTime、ResNet 和 ResCNN）提供支持。

虽然这些预构建模型强大且有效，但它们必须在特定领域的大型时间序列数据集上进行大量训练才能实现最佳性能。但是，您可能需要利用自定义工作流来集成较新的模型（包括时间序列基础模型）等等，从而提供现成的预测解决方案。这些基础模型在大量不同的时间序列数据集上进行了预训练，且无需额外的训练即可直接应用于根据特定输入数据预测未来事件。跨不同时间序列数据集进行概化的功能可使其具有很高的通用性。

Python 开发人员可以编写自定义时间序列函数，以将 ArcGIS 与这些外部第三方模型进行集成，并将其打包为 Esri 深度学习包（.dlpk 文件），以便与使用时序模型进行预测工具搭配使用。

自定义 Python 时间序列函数

您可以在 Python 中创建时间序列函数，以将第三方时间序列模型集成到时间序列预测管道中。

下表中列出了时间序列函数方法，并将在后续部分中对其进行更详尽的阐述。


方法	描述
`__init__`	初始化实例变量，例如 `name`、`description`，以及其他对时间序列函数至关重要的属性。
`initialize`	加载时间序列模型并设置任何初始配置。在 Python 时间序列函数的开头使用此方法。
`getParameterInfo`	定义时间序列函数接受的参数。包括加载或连接模型所需的任何配置设置以及时间序列处理所需的参数。
`getConfiguration`	介绍该工具如何执行输入处理并生成输出。包括该函数所需的任何预处理或后处理步骤的详细信息。
`predict`	负责将输入数据转换为所需输出的函数。它使用已定义的参数和处理逻辑以生成最终结果。

函数方法

以下介绍了时间序列函数方法。

init

__init__ 方法是自定义时间序列函数的构造函数，用于初始化实例变量，例如名称、描述和其他必要属性。此方法用于设置相应属性，这些属性将定义时间序列函数的行为和特征。

构造函数将创建自定义时间序列类的实例，该实例具有处理和分析所必需的所有属性。创建时间序列类的实例时，此方法可确保使用所需的设置和默认值对其进行初始化。例如，如果时间序列函数需要特定设置（例如包含模型权重和配置文件的文件夹路径），则可以在该方法中进行指定。

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

将在自定义 Python 时间序列函数启动时调用 initialize 方法，并使用此方法传递 kwargs['model'] 参数。 kwargs['model'] 参数是 Esri 模型定义文件 (.emd) 的路径。该方法用于加载模型权重以设置时间序列模型，由此确保后续操作对其进行引用。

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

getParameterInfo 方法将由使用时序模型进行预测工具在 initialize 方法之后调用，并定义模型所需的参数。此方法将返回自定义时间序列函数所需的输入参数列表。将使用字典来描述每个参数，其中包含参数的名称、数据类型、显示名称和描述，以及指示该参数是否为必填项的布尔参数，如下所示。

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
 ]

该方法将返回一个字典列表，每个字典描述一个参数。该字典的主要属性如下：

name - 参数的字符串标识符
dataType - 参数所接受的数据类型，例如长整型、字符串、布尔值或列表
value - 参数的默认值
required - 指示参数是否为必填项的布尔值
displayName - 参数的用户友好名称
domain - 一组允许的值（如果适用）
description - 参数的详细描述

参数列表将通过使用时序模型进行预测工具中的自定义模型的模型参数显示给用户。用户可以使用工具用户界面以交互方式设置这些值，或者以编程方式将其作为关键字参数传递到 getConfiguration 方法。

getConfiguration

getConfiguration 方法用于配置并管理时间序列函数的参数。它将接受包含用户通过工具更新或以编程方式提供的参数的关键字参数。该方法还将根据已更新参数来控制函数处理和输出数据的方式。将在 getParameterInfo 方法之后，且在 predict 方法之前调用此方法。该函数的返回值是一个字典，其中包含 batch_size 的值，用于指示模型一次可以处理的序列数量。该方法的返回值将告知工具如何分割输入数据，以便模型一次处理一批。

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

在以上示例中，自定义时间序列函数配置如下：

根据提供的参数设置 sequence_length 参数。
如果提供较大的值，则将 batch_size 参数设置为最大值 4。
从工具集设置 number_of_timesteps_to_forecast 参数。
返回已更新参数值。

predict

predict 方法通过使用时间序列模型生成预测来执行推断。该方法可接受包含输入数据的 2D NumPy 数组，并将结果作为 2D NumPy 数组返回。下面概述了一个典型工作流：

预处理输入数据，以匹配模型的要求。
将时间序列模型应用于输入数据以生成预测。

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 文件 {#EF9}

创建自定义 Python 时间序列函数后，通过在 `InferenceFunction` 参数旁指定该函数以在 `.emd` 文件中包含对该函数的引用。 由此可确保 `.emd` 文件正确链接到该函数，从而能够在时间序列预测中使用该函数。

```json
{
 "InferenceFunction": "MyTimesFM.py",
 "ModelType": "TimeSeriesForecasting"
}

.emd 文件必须包含以下关键字：

InferenceFunction - 包含自定义时间序列函数的文件的名称
ModelType - 指定模型的类型，设置为 TimeSeriesForecasting

自定义 .dlpk 文件

要完成最终的第三方自定义时间序列模型，请创建 .dlpk 模型文件。 .dlpk 文件支持将此模型与时序 AI 工具集中的使用时序模型进行预测工具搭配使用。

按如下方式组织文件：

创建文件夹并包含自定义时间序列函数文件（例如 MyTimesFM.py）和 Esri .emd 文件（例如 TimesFM.emd）。文件夹的名称必须与 .emd 文件的名称相匹配。
```
TimesFM/
├── MyTimesFM.py
└── TimesFM.emd
```
包含时间序列函数所需的任何其他文件或文件夹。
将该文件夹压缩为 ZIP 归档。重命名 .zip 文件以与 .emd 文件的名称相匹配，但扩展名为 .dlpk。现在 .dlpk 文件已准备就绪，能够与使用时序模型进行预测工具搭配使用。