Merlion：时间序列机器学习库

简介

Merlion 是一个用于时间序列智能的 Python 库。它提供了一个端到端的机器学习框架，包括加载和转换数据、构建和训练模型、后处理模型输出以及评估模型性能。它支持多种时间序列学习任务，包括单变量和多变量时间序列的预测、异常检测和变点检测。该库旨在为工程师和研究人员提供一站式解决方案，以便针对其特定的时间序列需求快速开发模型，并在多个时间序列数据集上对其进行基准测试。

Merlion 的关键特性有：

针对广泛的预测和异常检测数据集，提供标准化且易于扩展的数据加载与基准测试。这包括对自定义数据集的透明支持。
一个包含多种异常检测、预测和变点检测模型的库，所有这些模型都统一在共享接口下。模型包括经典统计方法、树集成和深度学习方法。高级用户可根据需要完全配置每个模型。
抽象的 DefaultDetector 和 DefaultForecaster 模型，高效、稳健地实现良好性能，并为新用户提供起点。
用于自动超参数调优和模型选择的 AutoML。
统一 API，可使用各种模型利用外生回归变量进行预测。
实用且受行业启发的异常检测器后处理规则，使异常分数更具可解释性，同时减少误报数量。
易于使用的集成方法，结合多个模型的输出以实现更稳健的性能。
灵活的评估流水线，可模拟模型在生产环境中的实时部署与重新训练，并评估预测和异常检测两方面的性能。
原生支持可视化模型预测，包括可点击的可视化 UI。
使用 PySpark 的分布式计算后端，可用于在工业规模上提供时间序列应用服务。

与相关库的比较

下表直观概述了 Merlion 的关键特性与其他用于时间序列异常检测和/或预测的库的对比。

以下是 Merlion 2.0 中新增的功能：

安装

Merlion 由两个子仓库组成：merlion 实现该库核心的时间序列智能功能，ts_datasets 为多个时间序列数据集提供标准化的数据加载器。这些加载器将时间序列加载为带有相应元数据的 pandas.DataFrame。

您可以通过调用 pip install salesforce-merlion 从 PyPI 安装 merlion。您也可以通过克隆此仓库并调用 pip install Merlion/ 从源码安装，或调用 pip install -e Merlion/ 以可编辑模式安装。您可以通过 pip install salesforce-merlion[all] 安装额外的依赖项，或者如果从源码安装，请调用 pip install "Merlion/[all]"。可选依赖项包括：用于 GUI 仪表盘的 dashboard、用于通过 PySpark 进行分布式计算后端的 spark，以及用于所有深度学习模型的 deep-learning。

要安装数据加载包 ts_datasets，请克隆此仓库并调用 pip install -e Merlion/ts_datasets/。如果您不想在初始化数据加载器时手动指定每个数据集的根目录，则必须以可编辑模式（即使用 -e 标志）安装此包。

请注意以下外部依赖项：

我们的一些预测模型依赖于 OpenMP。如果使用 conda，请在安装我们的包之前执行 conda install -c conda-forge lightgbm。这将确保 OpenMP 在您的 conda 环境中与 lightgbm 包（我们的依赖项之一）正常配合工作。如果使用 Mac，请安装 Homebrew 并调用 brew install libomp，以便模型可以使用 OpenMP 库。
我们的一些异常检测模型依赖于 Java 开发工具包 (JDK)。对于 Ubuntu，请执行 sudo apt-get install openjdk-11-jdk。对于 Mac OS，请安装 Homebrew 并调用 brew tap adoptopenjdk/openjdk && brew install --cask adoptopenjdk11。同时确保 java 可以在您的 PATH 中找到，并且已设置 JAVA_HOME 环境变量。

文档

有关示例代码和 Merlion 的介绍，请参阅 examples 中的 Jupyter 笔记本以及此处的引导式演练。您可以在此处找到详细的 API 文档（包括示例代码）。技术报告概述了 Merlion 的整体架构，并展示了单变量和多变量时间序列在时间序列异常检测与预测方面的实验结果。

快速开始

开始使用的最简单方法是使用基于 GUI 网页的仪表盘。该仪表盘为您提供了一种在自定义数据集上快速试验多种模型的绝佳方式。要使用它，请安装带有可选 dashboard 依赖项的 Merlion（即 pip install salesforce-merlion[dashboard]），然后在命令行中调用 python -m merlion.dashboard。您可以在 http://localhost:8050 查看仪表盘。下面，我们展示异常检测和预测的仪表盘截图。

异常检测仪表盘

预测仪表盘

为了帮助您在自己的代码中开始使用 Merlion，我们在下面提供了一些使用 Merlion 默认模型进行异常检测和预测的最小示例。

异常检测

在这里，我们展示用于复现上述异常检测仪表盘结果的代码。我们首先导入 Merlion 的 TimeSeries 类和 Numenta 异常检测基准 NAB 的数据加载器。然后，我们可以将该数据集中的特定时间序列划分为训练集和测试集。

from merlion.utils import TimeSeries
from ts_datasets.anomaly import NAB

# Data loader returns pandas DataFrames, which we convert to Merlion TimeSeries
time_series, metadata = NAB(subset="realKnownCause")[3]
train_data = TimeSeries.from_pd(time_series[metadata.trainval])
test_data = TimeSeries.from_pd(time_series[~metadata.trainval])
test_labels = TimeSeries.from_pd(metadata.anomaly[~metadata.trainval])

然后，我们可以初始化并训练 Merlion 的 DefaultDetector，这是一个在性能与效率之间取得平衡的异常检测模型。我们还可以获取其在测试集上的预测结果。

from merlion.models.defaults import DefaultDetectorConfig, DefaultDetector
model = DefaultDetector(DefaultDetectorConfig())
model.train(train_data=train_data)
test_pred = model.get_anomaly_label(time_series=test_data)

接下来，我们可视化模型的预测结果。

from merlion.plot import plot_anoms
import matplotlib.pyplot as plt
fig, ax = model.plot_anomaly(time_series=test_data)
plot_anoms(ax=ax, anomaly_labels=test_labels)
plt.show()

异常检测图

最后，我们可以定量评估该模型。精确率和召回率来自模型触发的 3 次警报，其中 2 次真正例、1 次假负例和 1 次假正例。我们还会评估模型正确检测到的每个异常的平均检测时间。

from merlion.evaluate.anomaly import TSADMetric
p = TSADMetric.Precision.value(ground_truth=test_labels, predict=test_pred)
r = TSADMetric.Recall.value(ground_truth=test_labels, predict=test_pred)
f1 = TSADMetric.F1.value(ground_truth=test_labels, predict=test_pred)
mttd = TSADMetric.MeanTimeToDetect.value(ground_truth=test_labels, predict=test_pred)
print(f"Precision: {p:.4f}, Recall: {r:.4f}, F1: {f1:.4f}\n"
      f"Mean Time To Detect: {mttd}")

Precision: 0.6667, Recall: 0.6667, F1: 0.6667
Mean Time To Detect: 1 days 10:22:30

预测

在这里，我们展示用于复现上述预测仪表盘结果的代码。我们首先导入 Merlion 的 TimeSeries 类和 M4 数据集的数据加载器。然后，我们可以将该数据集中的特定时间序列划分为训练集和测试集。

from merlion.utils import TimeSeries
from ts_datasets.forecast import M4

# Data loader returns pandas DataFrames, which we convert to Merlion TimeSeries
time_series, metadata = M4(subset="Hourly")[0]
train_data = TimeSeries.from_pd(time_series[metadata.trainval])
test_data = TimeSeries.from_pd(time_series[~metadata.trainval])

然后，我们可以初始化并训练 Merlion 的 DefaultForecaster，这是一个在性能与效率之间取得平衡的预测模型。我们还可以获取其在测试集上的预测结果。

from merlion.models.defaults import DefaultForecasterConfig, DefaultForecaster
model = DefaultForecaster(DefaultForecasterConfig())
model.train(train_data=train_data)
test_pred, test_err = model.forecast(time_stamps=test_data.time_stamps)

接下来，我们可视化模型的预测结果。

import matplotlib.pyplot as plt
fig, ax = model.plot_forecast(time_series=test_data, plot_forecast_uncertainty=True)
plt.show()

预测图

最后，我们定量评估模型。sMAPE 在 0 到 100 的范围内衡量预测误差（越低越好），而 MSIS 在 0 到 100 的范围内评估 95% 置信带的质量（越低越好）。

# Evaluate the model's predictions quantitatively
from scipy.stats import norm
from merlion.evaluate.forecast import ForecastMetric

# Compute the sMAPE of the predictions (0 to 100, smaller is better)
smape = ForecastMetric.sMAPE.value(ground_truth=test_data, predict=test_pred)

# Compute the MSIS of the model's 95% confidence interval (0 to 100, smaller is better)
lb = TimeSeries.from_pd(test_pred.to_pd() + norm.ppf(0.025) * test_err.to_pd().values)
ub = TimeSeries.from_pd(test_pred.to_pd() + norm.ppf(0.975) * test_err.to_pd().values)
msis = ForecastMetric.MSIS.value(ground_truth=test_data, predict=test_pred,
                                 insample=train_data, lb=lb, ub=ub)
print(f"sMAPE: {smape:.4f}, MSIS: {msis:.4f}")

sMAPE: 4.1944, MSIS: 18.9331

评估与基准测试

Merlion 的关键特性之一是一个评估流水线，可模拟模型在历史数据上的实时部署。这使得您可以在与模型相关的数据集上、在它们可能遇到的生产环境条件下比较模型。我们的评估流水线步骤如下：

在最近的历史训练数据（指定为时间序列的训练集）上训练初始模型。
按固定间隔（例如每天一次）在最新数据上重新训练整个模型。可以是时间序列的完整历史，也可以是更有限的时间窗口（例如 4 周）。
获取模型在两次重新训练之间出现的时间序列值上的预测结果（异常分数或预测值）。您可以自定义是以批量方式（一次预测所有值）、流式方式（在每个数据点后更新模型的内部状态而不完全重新训练）还是某种中间节奏来执行。
将模型的预测结果与真实值（用于异常检测的标注异常，或用于预测的实际时间序列值）进行比较，并报告定量评估指标。

我们提供了一些脚本，使您能够使用此流水线在任意数据集上评估任意模型。例如，调用

python benchmark_anomaly.py --dataset NAB_realAWSCloudwatch --model IsolationForest --retrain_freq 1d

将评估 IsolationForest（每天重新训练一次）在 NAB 数据集的"realAWSCloudwatch"子集上的异常检测性能。类似地，调用

python benchmark_forecast.py --dataset M4_Hourly --model ETS

将评估 ETS 在 M4 数据集 "Hourly" 子集上的批量预测性能（即不重新训练）。您可以在技术报告的实验部分找到运行这些脚本产生的结果。

技术报告与引用 Merlion

您可以在我们的技术报告中找到更多详细信息：https://arxiv.org/abs/2109.09265

如果您在研究中或应用中使用 Merlion，请使用以下 BibTeX 进行引用：

@article{bhatnagar2021merlion,
      title={Merlion: A Machine Learning Library for Time Series},
      author={Aadyot Bhatnagar and Paul Kassianik and Chenghao Liu and Tian Lan and Wenzhuo Yang
              and Rowan Cassius and Doyen Sahoo and Devansh Arpit and Sri Subramanian and Gerald Woo
              and Amrita Saha and Arun Kumar Jagota and Gokulakrishnan Gopalakrishnan and Manpreet Singh
              and K C Krithika and Sukumar Maddineni and Daeki Cho and Bo Zong and Yingbo Zhou
              and Caiming Xiong and Silvio Savarese and Steven Hoi and Huan Wang},
      year={2021},
      eprint={2109.09265},
      archivePrefix={arXiv},
      primaryClass={cs.LG}
}

待办事项

我们正在努力利用 GPU 进行时间序列建模，以进一步提高 Merlion 的速度和吞吐量。敬请期待……

Merlion

最受欢迎