文档 | 教程 | 发布说明 | 中文

TFTS（TensorFlow 时间序列）是一个易于使用的时序包，支持 TensorFlow 或 Keras 中的经典及最新的深度学习方法。

• 支持用于时间序列任务（预测、分类、异常检测）的最先进模型
• 提供适用于工业、研究和竞赛的高级深度学习模型
• 文档位于 time-series-prediction.readthedocs.io

教程

安装

• python >= 3.7
• tensorflow >= 2.4

pip install tfts

快速入门

import matplotlib.pyplot as plt
import tensorflow as tf
import tfts
from tfts import AutoModel, AutoConfig, KerasTrainer

train_length = 24
predict_sequence_length = 8
(x_train, y_train), (x_valid, y_valid) = tfts.get_data("sine", train_length, predict_sequence_length, test_size=0.2)

model_name_or_path = 'seq2seq'  # 'wavenet', 'transformer', 'rnn', 'tcn', 'bert', 'dlinear', 'nbeats', 'informer', 'autoformer'
config = AutoConfig.for_model(model_name_or_path)
model = AutoModel.from_config(config, predict_sequence_length=predict_sequence_length)
trainer = KerasTrainer(model, optimizer=tf.keras.optimizers.Adam(0.0007))
trainer.train((x_train, y_train), (x_valid, y_valid), epochs=30)

pred = trainer.predict(x_valid)
trainer.plot(history=x_valid, true=y_valid, pred=pred)
plt.show()

准备您自己的数据

您可以准备 3D 数据作为输入和目标来训练自己的数据：

• 方案1 np.ndarray
• 方案2 tf.data.Dataset
• 方案3 tf.keras.utils.Sequence

仅编码器模型的输入

import numpy as np
from tfts import AutoConfig, AutoModel, KerasTrainer

train_length = 24
predict_sequence_length = 8
n_feature = 2

x_train = np.random.rand(1, train_length, n_feature)  # 输入：(batch, train_length, feature)
y_train = np.random.rand(1, predict_sequence_length, 1)  # 目标：(batch, predict_sequence_length, 1)
x_valid = np.random.rand(1, train_length, n_feature)
y_valid = np.random.rand(1, predict_sequence_length, 1)

config = AutoConfig.for_model('rnn')
model = AutoModel.from_config(config, predict_sequence_length=predict_sequence_length)
trainer = KerasTrainer(model)
trainer.train(train_dataset=(x_train, y_train), valid_dataset=(x_valid, y_valid), epochs=1)

编码器-解码器模型的输入

# 方案1：np.ndarray
import numpy as np
from tfts import AutoConfig, AutoModel, KerasTrainer

train_length = 24
predict_sequence_length = 8
n_encoder_feature = 2
n_decoder_feature = 3

x_train = (
    np.random.rand(1, train_length, 1),  # 输入：(batch, train_length, 1)
    np.random.rand(1, train_length, n_encoder_feature),  # 编码器特征：(batch, train_length, 编码器特征)
    np.random.rand(1, predict_sequence_length, n_decoder_feature),  # 解码器特征：(batch, predict sequence length, 解码器特征)
)
y_train = np.random.rand(1, predict sequence length, 1)  # 目标：(batch, predict sequence length, 1)

x_valid = (
    np.random.rand(1, train length, 1),
    np.random.rand(1, train length, n_encoder feature),
    np.random.rand(1, predict sequence length, n decoder feature),
)
y_valid = np.random.rand(1, predict sequence length, 1)

config = AutoConfig.for_model("seq2seq")
model = AutoModel from config with predict sequence length and trainer of Keras Trainer trained with x_train and y_train and x_valid and y_valid for one epoch.

# 选项2：tf.data.Dataset
import numpy as np
import tensorflow as tf
from tfts import AutoConfig, AutoModel, KerasTrainer

class FakeReader(object):
    def __init__(self, predict_sequence_length):
        train_length = 24
        n_encoder_feature = 2
        n_decoder_feature = 3
        self.x = np.random.rand(15, train_length, 1)
        self.encoder_feature = np.random.rand(15, train_length, n_encoder_feature)
        self.decoder_feature = np.random.rand(15, predict_sequence_length, n_decoder_feature)
        self.target = np.random.rand(15, predict_sequence_length, 1)

    def __len__(self):
        return len(self.x)

    def __getitem__(self, idx):
        return {
            "x": self.x[idx],
            "encoder_feature": self.encoder_feature[idx],
            "decoder_feature": self.decoder_feature[idx],
        }, self.target[idx]

    def iter(self):
        for i in range(len(self.x)):
            yield self[i]

predict_sequence_length = 10
train_reader = FakeReader(predict_sequence_length=predict_sequence_length)
train_loader = tf.data.Dataset.from_generator(
    train_reader.iter,
    ({"x": tf.float32, "encoder_feature": tf.float32, "decoder_feature": tf.float32}, tf.float32),
)
train_loader = train_loader.batch(batch_size=1)
valid_reader = FakeReader(predict_sequence_length=predict_sequence_length)
valid_loader = tf.data.Dataset.from_generator(
    valid_reader.iter,
    ({"x": tf.float32, "encoder_feature": tf.float32, "decoder_feature": tf.float32}, tf.float32),
)
valid_loader = valid_loader.batch(batch_size=1)

config = AutoConfig.for_model("seq2seq")
model = AutoModel.from_config(config, predict_sequence_length=predict_sequence_length)
trainer = KerasTrainer(model)
trainer.train(train_dataset=train_loader, valid_dataset=valid_loader, epochs=1)

准备自定义模型配置

from tfts import AutoModel, AutoConfig

config = AutoConfig.for_model('rnn')
print(config)
config.rnn_hidden_size = 128

model = AutoModel.from_config(config, predict_sequence_length=7)

构建您自己的模型

tfts AutoModel 支持的完整列表

• rnn
• tcn
• bert
• nbeats
• dlinear
• seq2seq
• wavenet
• transformer
• informer
• autoformer

您可以基于 tfts 构建自定义模型，例如：

• 为分类变量添加自定义嵌入层
• 为分类或异常检测任务添加自定义头部层

import tensorflow as tf
from tensorflow.keras.layers import Input, Dense
from tfts import AutoModel, AutoConfig

train_length = 24
num_train_features = 15
predict_sequence_length = 8

def build_model():
    inputs = Input([train_length, num_train_features])
    config = AutoConfig.for_model("seq2seq")
    backbone = AutoModel.from_config(config, predict_sequence_length=predict_sequence_length)
    outputs = backbone(inputs)
    outputs = Dense(1, activation="sigmoid")(outputs)
    model = tf.keras.Model(inputs=inputs, outputs=outputs)
    model.compile(loss="mse", optimizer="rmsprop")
    return model

示例

• TFTS-Bert 在 KDD 杯 2022 年风电功率预测比赛中荣获 第三名
• TFTS-Seq2seq 在天池 ENSO 指数预测 2021 年比赛中荣获 第四名
• 更多示例 ...

引用

如果您在研究中发现 tfts 项目很有用，请考虑引用：

@misc{tfts2020,
  author = {Longxing Tan},
  title = {TFTS: 时间序列预测},
  year = {2020},
  publisher = {GitHub},
  journal = {GitHub 仓库},
  howpublished = {\url{https://github.com/longxingtan/time-series-prediction}},
}

Time-series-prediction (TFTS) 快速上手指南

TFTS (TensorFlow Time Series) 是一个易于使用的时间序列预测包，基于 TensorFlow/Keras 构建，支持多种经典及最新的深度学习模型（如 Transformer, Informer, N-BEATS 等），适用于工业界、科研及竞赛场景。

1. 环境准备

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

• 操作系统：Linux, macOS 或 Windows
• Python 版本：>= 3.7
• 核心依赖：TensorFlow >= 2.4

2. 安装步骤

推荐使用 pip 进行安装。国内用户建议使用清华源或阿里源以加速下载。

通用安装命令：

pip install tfts

国内加速安装（推荐）：

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

3. 基本使用

以下是最简单的快速入门示例，演示了如何加载内置数据、配置模型、训练并进行预测可视化。

快速开始示例

import matplotlib.pyplot as plt
import tensorflow as tf
import tfts
from tfts import AutoModel, AutoConfig, KerasTrainer

# 1. 准备数据 (使用内置的正弦波数据)
train_length = 24
predict_sequence_length = 8
(x_train, y_train), (x_valid, y_valid) = tfts.get_data("sine", train_length, predict_sequence_length, test_size=0.2)

# 2. 配置模型
# 支持的模型包括：'seq2seq', 'wavenet', 'transformer', 'rnn', 'tcn', 'bert', 'dlinear', 'nbeats', 'informer', 'autoformer'
model_name_or_path = 'seq2seq' 
config = AutoConfig.for_model(model_name_or_path)
model = AutoModel.from_config(config, predict_sequence_length=predict_sequence_length)

# 3. 初始化训练器并训练
trainer = KerasTrainer(model, optimizer=tf.keras.optimizers.Adam(0.0007))
trainer.train((x_train, y_train), (x_valid, y_valid), epochs=30)

# 4. 预测与可视化
pred = trainer.predict(x_valid)
trainer.plot(history=x_valid, true=y_valid, pred=pred)
plt.show()

使用自定义数据

如果您需要使用自己的数据进行训练，只需将数据整理为 3D 数组格式 (batch, time_steps, features) 即可。

仅编码器模型输入示例：

import numpy as np
from tfts import AutoConfig, AutoModel, KerasTrainer

train_length = 24
predict_sequence_length = 8
n_feature = 2

# 构造随机数据作为示例
x_train = np.random.rand(100, train_length, n_feature)  # 输入: (batch, 时间步，特征数)
y_train = np.random.rand(100, predict_sequence_length, 1)  # 目标: (batch, 预测长度，1)
x_valid = np.random.rand(20, train_length, n_feature)
y_valid = np.random.rand(20, predict_sequence_length, 1)

# 构建并训练
config = AutoConfig.for_model('rnn')
model = AutoModel.from_config(config, predict_sequence_length=predict_sequence_length)
trainer = KerasTrainer(model)
trainer.train(train_dataset=(x_train, y_train), valid_dataset=(x_valid, y_valid), epochs=10)

更多高级用法（如自定义模型结构、Encoder-Decoder 架构数据准备等）请参考官方文档。