[!TIP] [2025年5月更新] 🎉 我们的综述论文《用于多变量时间序列插补的深度学习：综述》（Deep Learning for Multivariate Time Series Imputation: A Survey）已被IJCAI 2025接收！ 我们全面回顾了当前最先进的基于深度学习的时间序列插补方法的相关文献，提出了一个基于不确定性与模型架构的新分类体系，系统性地比较了多个工具包，并探讨了该领域的挑战与未来发展方向。

[2024年6月更新] 😎 第一篇全面的时间序列插补基准研究论文 《TSI-Bench：时间序列插补基准测试》（TSI-Bench: Benchmarking Time Series Imputation）现已公开发布。 代码已在仓库Awesome_Imputation中开源。 通过近35,000次实验，我们对28种插补方法、3种缺失模式（点缺失、序列缺失、块缺失）、不同缺失率以及8个真实世界数据集进行了全面的基准测试。

[2024年5月更新] 🔥 我们将SAITS的嵌入和训练策略应用于 PyPOTS中的iTransformer、FiLM、FreTS、Crossformer、PatchTST、DLinear、ETSformer、FEDformer、 Informer、Autoformer、Non-stationary Transformer、Pyraformer、Reformer、SCINet、RevIN、Koopa、MICN、TiDE以及StemGNN，使它们能够适用于时间序列插补任务。

‼️温馨提示：本文档可以帮助您解答许多常见问题,请在运行代码之前仔细阅读。

官方代码库对应的是论文《SAITS：基于自注意力机制的时间序列插补》（SAITS: Self-Attention-based Imputation for Time Series），该论文已被期刊*Expert Systems with Applications (ESWA)*接受 [2022年影响因子8.665，CiteScore 12.2，JCR-Q1，CAS-Q1，CCF-C]。您可能从未听说过ESWA， 但它曾在2016年被Google Scholar评为人工智能领域顶级出版物中的第一名 (信息来源)，并且至今仍是Google Scholar排名首位的人工智能期刊 (当前排名列表，供您参考)。

SAITS是首个在算法中完全采用自注意力机制、而不使用任何递归设计的通用时间序列插补工作。 基本上，您可以将其视为一个经过验证的时间序列插补框架，就像我们通过适配SAITS框架，将超过2️⃣0️⃣种预测模型集成到PyPOTS中一样。 更广泛地说，它也可以用于序列插补。此外，这里的代码以MIT许可证开源。 因此，欢迎您根据自己的研究目的和领域应用修改SAITS代码。 当然，在特定场景或数据输入下，可能需要对模型结构或损失函数进行一些调整。 以下是一份不完全清单，展示了科学界在论文中引用SAITS的情况。

🤗 如果SAITS对您的工作有所帮助，请在您的出版物中引用SAITS。 如果您认为它有用，请为本仓库点亮星标🌟，以便更多人注意到SAITS。 这对我们的开源研究意义重大。感谢您的支持！ 顺带一提，您可能也会喜欢 PyPOTS ，它可以轻松处理您那些部分观测的时间序列数据集。

[!IMPORTANT] 📣 请注意：

SAITS现已集成到PYPOTS中，这是一个用于处理部分观测时间序列（POTS）的数据挖掘Python工具箱。 下面展示了使用SAITS对PhysioNet-2012数据集进行插补的示例。借助PYPOTS，一切都变得轻而易举！😉

import numpy as np
from sklearn.preprocessing import StandardScaler
from pygrinder import mcar, calc_missing_rate
from benchpots.datasets import preprocess_physionet2012
data = preprocess_physionet2012(subset='set-a',rate=0.1) # 我们的生态系统库会自动下载并解压数据集
train_X, val_X, test_X = data["train_X"], data["val_X"], data["test_X"]
print(train_X.shape)  # (n_samples, n_steps, n_features)
print(val_X.shape)  # 训练集和验证集的样本数不同，但它们具有相同的序列长度(n_steps)和特征维度(n_features)
print(f"训练集中有{calc_missing_rate(train_X):.1%}的值缺失")  
train_set = {"X": train_X}  # 在训练集中，只需将不完整的时序数据放入即可
val_set = {
    "X": val_X,
    "X_ori": data["val_X_ori"],  # 在验证集中，我们需要真实标签来进行评估和选择最佳模型检查点
}
test_set = {"X": test_X}  # 在测试集中，只提供待填补的不完整时序数据
test_X_ori = data["test_X_ori"]  # test_X_ori 包含用于评估的真实标签
indicating_mask = np.isnan(test_X) ^ np.isnan(test_X_ori)  # mask 标记了 X 中缺失但 X_ori 中未缺失的值，即真实标签所在的位置

from pypots.imputation import SAITS  # 导入你想要使用的模型
from pypots.nn.functional import calc_mae
saits = SAITS(n_steps=train_X.shape[1], n_features=train_X.shape[2], n_layers=2, d_model=256, n_heads=4, d_k=64, d_v=64, d_ffn=128, dropout=0.1, epochs=5)
saits.fit(train_set, val_set)  # 在数据集上训练模型
imputation = saits.impute(test_set)  # 填补原本缺失以及人为添加的缺失值
mae = calc_mae(imputation, np.nan_to_num(test_X_ori), indicating_mask)  # 在真实标签（人为添加的缺失值）上计算平均绝对误差
saits.save("save_it_here/saits_physionet2012.pypots")  # 保存模型以备将来使用
saits.load("save_it_here/saits_physionet2012.pypots")  # 加载已序列化的模型文件，以便后续填补或训练

❖ 动机与性能

⦿ 动机: SAITS 主要是为了克服基于 RNN 的填补模型的缺点（速度慢、内存限制和误差累积），并在部分观测的时序数据上达到最先进的填补准确度而开发的。

⦿ 性能: SAITS 在 MAE（平均绝对误差）方面比 BRITS 高出 12% ∼ 38%，并且训练速度提高了 2.0 ∼ 2.6 倍。此外，SAITS 还比采用联合优化方法训练的 Transformer 在 MAE 上高出 2% ∼ 19%，同时其模型结构更加高效（为了达到相当的性能，SAITS 所需的参数仅为 Transformer 的 15% ∼ 30%）。与另一个 SOTA 自注意力填补模型 NRTSI 相比，SAITS 的均方误差小了 7% ∼ 39%（其中九个案例中的误差减少超过 20%），而且在实际应用中所需的参数更少，填补时间也更短。有关 SAITS 性能的更多详细信息，请参阅我们的 完整论文。

❖ 方法论简图说明

这里仅展示我们方法的两个主要组成部分：联合优化训练方法和 SAITS 结构。详细的描述和解释，请阅读本仓库中的完整论文 Paper_SAITS.pdf 或者 arXiv 上的版本。

图1：训练方法

图2：SAITS 结构

❖ 引用 SAITS

如果您发现 SAITS 对您的工作有所帮助，请按照以下方式引用我们的论文，⭐️给这个仓库加星，并推荐给可能需要它的人。🤗 谢谢！

@article{du2023saits,
title = {{SAITS: Self-Attention-based Imputation for Time Series}},
journal = {Expert Systems with Applications},
volume = {219},
pages = {119619},
year = {2023},
issn = {0957-4174},
doi = {10.1016/j.eswa.2023.119619},
url = {https://arxiv.org/abs/2202.08516},
author = {Wenjie Du and David Cote and Yan Liu},
}

或者

Wenjie Du, David Cote 和 Yan Liu. SAITS: 基于自注意力机制的时间序列填补。 Expert Systems with Applications, 第219卷，第119619页，2023年。

😎 我们关于时间序列填补的最新综述和基准研究也可能对您的工作有所帮助：

@article{wang2025survey,
title={Deep Learning for Multivariate Time Series Imputation: A Survey},
author={Jun Wang 和 Wenjie Du 和 Yiyuan Yang 和 Linglong Qian 和 Wei Cao 和 Keli Zhang 和 Wenjia Wang 和 Yuxuan Liang 和 Qingsong Wen},
booktitle = {第34届国际人工智能联合会议(IJCAI)论文集},
year={2025}
}

@article{du2024tsibench,
title={TSI-Bench: Benchmarking Time Series Imputation},
author={Wenjie Du 和 Jun Wang 和 Linglong Qian 和 Yiyuan Yang 和 Fanxing Liu 和 Zepu Wang 和 Zina Ibrahim 和 Haoxin Liu 和 Zhiyuan Zhao 和 Yingjie Zhou 和 Wenjia Wang 和 Kaize Ding 和 Yuxuan Liang 和 B. Aditya Prakash 和 Qingsong Wen},
journal={arXiv 预印本 arXiv:2406.12747},
year={2024}
}

🔥 如果您在研究中使用了 PyPOTS，请也引用以下论文：

@article{du2023pypots,
title={{PyPOTS: a Python toolbox for data mining on Partially-Observed Time Series}},
author={Wenjie Du},
journal={arXiv 预印本 arXiv:2305.18811},
year={2023},
}

或者

Wenjie Du. PyPOTS: 一个用于挖掘部分观测时间序列数据的 Python 工具箱。 arXiv，编号 2305.18811，2023年。

❖ 仓库结构

SAITS 的实现位于目录 modeling 中。我们在目录 configs 中提供了模型配置，在目录 dataset_generating_scripts 中提供了数据集链接和预处理脚本。目录 NNI_tuning 则包含超参数搜索的配置。

❖ 开发环境

我们的开发环境的所有依赖项都列在文件 conda_env_dependencies.yml 中。 您可以通过 Anaconda 命令 conda env create -f conda_env_dependencies.yml 快速创建一个可用的 Python 环境。

❖ 数据集

有关数据集的下载和生成，请查看目录 dataset_generating_scripts 中的脚本。

❖ 快速运行

首先生成您需要的数据集。为此，请查看目录 dataset_generating_scripts 中的生成脚本。

数据生成完成后，您可以训练并测试您的模型，例如：

# 创建一个目录来保存日志和结果
mkdir NIPS_results

# 训练模型
nohup python run_models.py \
    --config_path configs/PhysioNet2012_SAITS_best.ini \
    > NIPS_results/PhysioNet2012_SAITS_best.out &

# 在训练过程中，您可以运行以下命令查看训练日志：
less NIPS_results/PhysioNet2012_SAITS_best.out

# 训练结束后，选择最佳模型，并在配置文件中修改用于测试的模型路径，然后运行以下命令进行模型测试：
python run_models.py \
    --config_path configs/PhysioNet2012_SAITS_best.ini \
    --test_mode

❗️请注意，数据集路径和保存目录在不同电脑上可能会有所不同，请务必在配置文件中确认这些路径。

❖ 致谢

感谢 Ciena、Mitacs 以及加拿大自然科学与工程研究委员会（NSERC）提供的资金支持。 感谢所有审稿人对本文质量提升的帮助。 感谢 Ciena 提供的计算资源。 同时也感谢各位对本工作的关注。

✨ 欢迎点赞、叉项目、提交问题和拉取请求！

❖ 最后但同样重要的是

如果您有任何其他问题或有意合作， 请查看我的 GitHub 个人主页 WenjieDu，并随时与我联系 😃。

SAITS 快速上手指南

SAITS (Self-Attention-based Imputation for Time Series) 是一个基于纯自注意力机制的时间序列缺失值填补模型。它克服了传统 RNN 模型速度慢、内存受限及误差累积的缺点，在填补精度和训练速度上均表现优异。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows
• Python 版本: >= 3.8 (推荐 3.9+)
• 深度学习框架: PyTorch (CPU 或 GPU 版本均可)
• 前置依赖:
  • numpy
  • scikit-learn
  • pandas (可选，用于数据处理)

💡 国内加速建议 建议使用国内镜像源安装依赖，以提升下载速度：

• PyPI 镜像：https://pypi.tuna.tsinghua.edu.cn/simple
• PyTorch 镜像：https://download.pytorch.org/whl/cu118 (根据 CUDA 版本调整)

安装步骤

SAITS 的核心功能已集成到 PyPOTS (Python Toolbox for Partially-Observed Time Series) 中，推荐直接安装 PyPOTS 以使用 SAITS。

1. 安装 PyTorch

如果您尚未安装 PyTorch，请访问 PyTorch 官网 获取适合您环境的安装命令。 (以下为 CPU 版本示例，GPU 用户请替换为对应的 cuda 版本)

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

2. 安装 PyPOTS (包含 SAITS)

使用 pip 进行安装（推荐使用清华源）：

pip install pypots -i https://pypi.tuna.tsinghua.edu.cn/simple

若需使用额外的数据集处理工具（如示例中的 benchpots 和 pygrinder），也可一并安装：

pip install benchpots pygrinder -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是一个完整的极简示例，演示如何使用 SAITS 对 PhysioNet-2012 数据集进行缺失值填补。该流程包括数据加载、模型初始化、训练、填补及评估。

import numpy as np
from sklearn.preprocessing import StandardScaler
from pygrinder import mcar, calc_missing_rate
from benchpots.datasets import preprocess_physionet2012

# 1. 数据预处理
# 自动下载并提取数据集 (subset='set-a', 缺失率 0.1)
data = preprocess_physionet2012(subset='set-a', rate=0.1)
train_X, val_X, test_X = data["train_X"], data["val_X"], data["test_X"]

print(f"训练集形状: {train_X.shape}")  # (样本数，时间步长，特征数)
print(f"训练集缺失率：{calc_missing_rate(train_X):.1%}")

# 构造数据集字典
train_set = {"X": train_X}
val_set = {
    "X": val_X,
    "X_ori": data["val_X_ori"],  # 验证集需要真实值以选择最佳模型
}
test_set = {"X": test_X}
test_X_ori = data["test_X_ori"]  # 测试集真实值用于最终评估

# 生成掩码：标记那些原本缺失但在测试集中被人工掩盖的值（用于计算指标）
indicating_mask = np.isnan(test_X) ^ np.isnan(test_X_ori)

# 2. 模型导入与初始化
from pypots.imputation import SAITS
from pypots.nn.functional import calc_mae

saits = SAITS(
    n_steps=train_X.shape[1],   # 时间步长
    n_features=train_X.shape[2],# 特征维度
    n_layers=2,                 # Transformer 层数
    d_model=256,                # 模型维度
    n_heads=4,                  # 注意力头数
    d_k=64,                     # Key 维度
    d_v=64,                     # Value 维度
    d_ffn=128,                  # 前馈网络维度
    dropout=0.1,                # Dropout 比率
    epochs=5                    # 训练轮数
)

# 3. 模型训练
saits.fit(train_set, val_set)

# 4. 执行填补
imputation = saits.impute(test_set)

# 5. 效果评估 (计算 MAE)
mae = calc_mae(imputation, np.nan_to_num(test_X_ori), indicating_mask)
print(f"测试集 MAE: {mae:.4f}")

# 6. 模型保存与加载
saits.save("save_it_here/saits_physionet2012.pypots")
# saits.load("save_it_here/saits_physionet2012.pypots") # 需要时可重新加载

关键参数说明

• n_steps: 输入序列的时间步长。
• n_features: 输入序列的特征维度。
• epochs: 训练迭代次数，可根据验证集损失调整。
• d_model, n_heads: 控制模型容量，数据量较大时可适当增加。

现在您可以尝试将 train_set 替换为您自己的时间序列数据（格式为 (n_samples, n_steps, n_features) 的 numpy 数组或 Tensor），即可开始您的填补任务。