TSGM (Time Series Generative Modeling)

TSGM is organized into several functional modules for time-series generative modeling and analysis. Key components include:

• Datasets: Utilities for managing and loading datasets, including tsgm.utils.UCRDataManager for UCR datasets.
• Augmentations: Time-series augmentation techniques located in tsgm.models.augmentations.
• Metrics: Evaluation metrics for time-series data in tsgm.metrics.metrics.
• Generative Models: Implementations of GANs (tsgm.models.cgan), VAEs (tsgm.models.cvae), and STS (tsgm.models.sts).
• Optimization: Algorithms like ABC (Approximate Bayesian Computation) in tsgm.optimization.abc.
• Simulation & Monitoring: Tools for running simulations (tsgm.simulator) and monitoring model behavior (tsgm.models.monitors).
• Utilities: Visualization tools (tsgm.utils.visualization), data processing helpers (tsgm.utils.data_processing), and a model zoo (tsgm.models.architectures.zoo).

A Generator is a central abstraction in TSGM used to simulate realistic time series. Generators follow the standard Keras API and can be trained on historical data using the .fit() method.

Implemented data-driven simulators include:

• tsgm.models.sts.STS (Structural Time Series)
• tsgm.models.cgan.GAN (Standard GAN)
• tsgm.models.cgan.ConditionalGAN (Conditional GAN)
• tsgm.models.cvae.BetaVAE (Beta-VAE)
• tsgm.models.cvae.cBetaVAE (Conditional Beta-VAE)
• tsgm.models.timegan.TimeGAN (TimeGAN)

Once trained, use .generate(n_samples) to produce new synthetic data.

import tsgm
from tensorflow import keras

n, n_ts, n_features  = 1000, 24, 5
data = tsgm.utils.gen_sine_dataset(n, n_ts, n_features)
scaler = tsgm.utils.TSFeatureWiseScaler()        
scaled_data = scaler.fit_transform(data)

# Retrieve architecture from the zoo
architecture = tsgm.models.zoo["vae_conv5"](n_ts, n_features, 10)
encoder, decoder = architecture.encoder, architecture.decoder

# Initialize and train the VAE
vae = tsgm.models.cvae.BetaVAE(encoder, decoder)
vae.compile(optimizer=keras.optimizers.Adam())
vae.fit(scaled_data, epochs=1, batch_size=64)

# Generate synthetic samples
synthetic_data = vae.generate(10)

To generate synthetic time series using a prebuilt architecture from the model zoo, follow these steps:

1. Select an architecture from tsgm.models.architectures.zoo. For example, cgan_base_c4_l1.
2. Extract the discriminator and generator from the architecture object.
3. Initialize a tsgm.models.cgan.GAN object using the extracted components.
4. Compile the GAN with optimizers and a loss function (typically using Keras/TensorFlow components).
5. Train the model using .fit() with your dataset.
6. Generate samples using .generate(n).

Note: The input dataset must be a tensor of shape (n_samples, seq_len, feature_dim).

import tsgm
import keras

# dataset shape: n_samples x seq_len x feature_dim

# 1. Select architecture from the zoo
architecture = tsgm.models.architectures.zoo["cgan_base_c4_l1":(
    seq_len=seq_len, 
    feat_dim=feature_dim,
    latent_dim=latent_dim, 
    output_dim=0
)]

discriminator, generator = architecture.discriminator, architecture.generator

# 2. Initialize GAN object
gan = tsgm.models.cgan.GAN(
    discriminator=discriminator, 
    generator=generator, 
    latent_dim=latent_dim
)

# 3. Compile
gan.compile(
    d_optimizer=keras.optimizers.Adam(learning_rate=0.0003),
    g_optimizer=keras.optimizers.Adam(learning_rate=0.0003),
    loss_fn=keras.losses.BinaryCrossentropy(from_logits=True),
)

# 4. Train
gan.fit(dataset, epochs=1)

# 5. Generate 10 synthetic samples
result = gan.generate(10)

You can automate model selection by defining an objective function for Optuna. This function should:

1. Suggest hyperparameters (like n_layers or num_hidden) using trial.suggest_int or trial.suggest_float.
2. Initialize a tsgm.models.timeGAN.TimeGAN model with those parameters.
3. Train the model using model.fit().
4. Generate synthetic data using model.generate(n_samples=...).
5. Calculate a metric (like DistanceMetric) comparing the synthetic data to real data.
6. Return the metric value to be minimized/maximized.

import tsgm
import optuna
import numpy as np

def objective(trial):
    train_data = get_data()

    # Define search space
    n_layers = trial.suggest_int("n_layers", low=1, high=10)
    num_hidden = trial.suggest_int("num_hidden", low=4, high=128, log=True)

    # Build TimeGAN model
    model = tsgm.models.timeGAN(
        seq_len=24,
        module="gru",
        hidden_dim=num_hidden,
        n_features=5,
        n_layers=n_layers,
        batch_size=256,
        gamma=1.0,
    )
    
    # Note: optimizer selection logic would be integrated here
    model.compile(optimizer=...) 
    model.fit(data=train_data, epochs=100)

    # Evaluate
    _y = model.generate(n_samples=10)
    score = metric_to_optimize(_y, np.array(train_data[:10]))
    return score

study = optuna.create_study(direction="minimize")
study.optimize(objective, n_trials=10)

To implement a Conditional Beta-VAE, you need to define an architecture (encoder and decoder), wrap them in the tsgm.models.cvae.cBetaVAE class, and train using the Keras .fit() method. The model accepts both the time series data X and the class labels y during training and prediction.

Key parameters for the architecture include:

• seq_len: Length of the time series.
• feat_dim: Number of time series features.
• latent_dim: Size of the latent representation.
• output_dim: Number of classes.

Note: When initializing cBetaVAE, you can set temporal=False if the latent space is not intended to be temporal.

# 1. Get architecture from zoo
model_type = tsgm.models.architectures.zoo["cvae_conv5"]
architecture = model_type(seq_len=seq_len, feat_dim=feat_dim, latent_dim=latent_dim, output_dim=2)
encoder, decoder = architecture._encoder, architecture._decoder

# 2. Wrap in cBetaVAE
vae = tsgm.models.cvae.cBetaVAE(encoder, decoder, latent_dim=latent_dim, temporal=False)

# 3. Compile and train
vae.compile(optimizer=keras.optimizers.Adam())
vae.fit(X, y, epochs=1, batch_size=128)

# 4. Predict/Reconstruct
x_decoded = vae.predict([X, y])