Documentation | Tutorials | Release Notes | 中文

TFTS (TensorFlow Time Series) is an easy-to-use time series package, supporting the classical and latest deep learning methods in TensorFlow or Keras.

• Support sota models for time series tasks (prediction, classification, anomaly detection)
• Provide advanced deep learning models for industry, research and competition
• Documentation lives at time-series-prediction.readthedocs.io

Getting started

Installation

• python >= 3.8
• tensorflow >= 2.4

pip install tfts matplotlib

Quick start

import matplotlib.pyplot as plt
import tensorflow as tf
import tfts
from tfts import AutoConfig, AutoModel, AutoModelForForecasting, 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 = AutoModelForForecasting.from_config(config, output_chunk_length=predict_sequence_length)
trainer = KerasTrainer(model)
trainer.train(
    (x_train, y_train),
    (x_valid, y_valid),
    optimizer=tf.keras.optimizers.Adam(0.0007),
    epochs=30,
)

# Save the model
model_dir = "./outputs/quickstart_forecasting"
trainer.save_model(model_dir)

# Load the model
restored_model = AutoModel.from_pretrained(model_dir, sample_batch=x_valid[:1])
pred = restored_model(x_valid, training=False).predictions.numpy()
trainer.plot(history=x_valid, true=y_valid, pred=pred)
plt.show()

Prepare your own data

You could train your own data by preparing 3D data as inputs, for both inputs and targets

• option1 np.ndarray
• option2 tf.data.Dataset
• option3 tf.keras.utils.Sequence

Encoder only model inputs

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

train_length = 24
predict_sequence_length = 8
n_feature = 2

x_train = np.random.rand(1, train_length, n_feature)  # inputs: (batch, train_length, feature)
y_train = np.random.rand(1, predict_sequence_length, 1)  # target: (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 = AutoModelForForecasting.from_config(config, output_chunk_length=predict_sequence_length)
trainer = KerasTrainer(model)
trainer.train(train_dataset=(x_train, y_train), valid_dataset=(x_valid, y_valid), epochs=1)

model_dir = "./outputs/encoder_only"
trainer.save_model(model_dir)
restored_model = AutoModel.from_pretrained(model_dir, sample_batch=x_valid[:1])
inference = restored_model(x_valid[:1], training=False).predictions.numpy()
print(inference.shape)

Encoder-decoder model inputs

# option1: np.ndarray — pass features as a dict with canonical TimeSeriesBatch fields
import numpy as np
from tfts import AutoConfig, AutoModel, AutoModelForForecasting, KerasTrainer

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

x_train = {
    "past_values": np.random.rand(1, train_length, 1),  # observed time series: (batch, train_length, 1)
    "past_time_features": np.random.rand(1, train_length, n_encoder_feature),  # encoder feature: (batch, train_length, encoder_features)
    "future_time_features": np.random.rand(1, predict_sequence_length, n_decoder_feature),  # decoder feature: (batch, predict_sequence_length, decoder_features)
}
y_train = np.random.rand(1, predict_sequence_length, 1)  # target: (batch, predict_sequence_length, 1)

x_valid = {
    "past_values": np.random.rand(1, train_length, 1),
    "past_time_features": np.random.rand(1, train_length, n_encoder_feature),
    "future_time_features": 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 = AutoModelForForecasting.from_config(config, output_chunk_length=predict_sequence_length)
trainer = KerasTrainer(model)
trainer.train((x_train, y_train), (x_valid, y_valid), epochs=1)

model_dir = "./outputs/encoder_decoder"
trainer.save_model(model_dir)
restored_model = AutoModel.from_pretrained(model_dir, sample_batch=x_valid)
inference = restored_model(x_valid, training=False).predictions.numpy()
print(inference.shape)

# option2: tf.data.Dataset
import numpy as np
import tensorflow as tf
from tfts import AutoConfig, AutoModel, AutoModelForForecasting, 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 {
            "past_values": self.x[idx],
            "past_time_features": self.encoder_feature[idx],
            "future_time_features": 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,
    ({"past_values": tf.float32, "past_time_features": tf.float32, "future_time_features": 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,
    ({"past_values": tf.float32, "past_time_features": tf.float32, "future_time_features": tf.float32}, tf.float32),
)
valid_loader = valid_loader.batch(batch_size=1)

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

model_dir = "./outputs/encoder_decoder_tfdata"
trainer.save_model(model_dir)
inference_inputs = next(iter(valid_loader.take(1)))[0]
restored_model = AutoModel.from_pretrained(model_dir, sample_batch=inference_inputs)
inference = restored_model(inference_inputs, training=False).predictions.numpy()
print(inference.shape)

Prepare custom model config

from tfts import AutoConfig, AutoModelForForecasting

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

model = AutoModelForForecasting.from_config(config, output_chunk_length=7)

Build your own model

Full list of tfts AutoModel supported

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

You could build the custom model based on tfts, like

• add custom-defined embeddings for categorical variables
• add custom-defined head layers for classification or anomaly task

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

train_length = 24
num_train_features = 15
predict_sequence_length = 8

def build_model():
    class CustomForecaster(tf.keras.Model):
        def __init__(self):
            super().__init__()
            config = AutoConfig.for_model("seq2seq")
            self.backbone = AutoBackbone.from_config(config, output_chunk_length=predict_sequence_length)
            self.projection = Dense(1, activation="sigmoid")

        def call(self, inputs, training=None):
            output = self.backbone(inputs, training=training)
            return self.projection(output.native_forecast)

    model = CustomForecaster()
    model.compile(loss="mse", optimizer="rmsprop")
    return model

Examples

• Forecasting: train, restore, and forecast with either the estimator or manual API
• Classification: train, restore, and evaluate a FordA classifier
• Anomaly detection: train, restore, calibrate, and score ECG windows
• Parameter tuning: save each Optuna trial and restore the best trial for inference
• TFTS-Bert wins the 3rd place in KDD Cup 2022-wind power forecasting
• TFTS-Seq2seq wins the 4th place in Tianchi-ENSO index prediction 2021
• More examples ...

Citation

If you find tfts project useful in your research, please consider cite:

@misc{tfts2020,
  author = {Longxing Tan},
  title = {TFTS: Time series prediction},
  year = {2020},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/longxingtan/time-series-prediction}},
}