TimeGAN

You can execute the full TimeGAN pipeline for training and evaluation using either a command-line interface or a Jupyter Notebook tutorial.

To run the pipeline via the command line, use the main_timegan.py module. For an interactive guided experience, use the tutorial_timegan.ipynb notebook.

# Run via command line
python3 -m main_timegan.py

# Or use the Jupyter Notebook tutorial
tutorial_timegan.ipynb

The TimeGAN framework is organized into three main functional areas:

1. timegan: The core synthetic time-series data generation module.
2. data_loading: Functions for loading and preprocessing real datasets (stock, energy) or generating synthetic ones (sine).
3. metrics: Evaluation tools including discriminative_score_metrics, predictive_score_metrics, and visualization (PCA/tSNE).

from timegan import timegan
from data_loading import real_data_loading, sine_data_generation
from metrics.discriminative_metrics import discriminative_score_metrics
from metrics.predictive_metrics import predictive_score_metrics
from metrics.visualization_metrics import visualization

To use the TimeGAN framework, clone the repository to your current directory:

git clone https://github.com/jsyoon0823/timeGAN.git

TimeGAN requires a dictionary of parameters to define the architecture and training process.

Parameter Keys:

• module: The RNN unit type. Supported values: 'gru', 'lstm', or 'lstmLN'.
• hidden_dim: Integer representing hidden dimensions.
• num_layer: Integer representing the number of layers.
• iterations: Integer representing the number of training iterations.
• batch_size: Integer representing the number of samples per batch.

parameters = dict()
parameters['module'] = 'gru' 
parameters['hidden_dim'] = 24
parameters['num_layer'] = 3
parameters['iterations'] = 10000
parameters['batch_size'] = 128

The following arguments are available for configuring the TimeGAN execution:

• data_name: The dataset to use (sine, stock, or energy).
• seq_len: The sequence length for the time-series data.
• module: The architecture type for the generator/discriminator (gru, lstm, or lstmLN).
• hidden_dim: The number of hidden dimensions in the network.
• num_layer: The number of layers in the network.
• iteration: The number of training iterations.
• batch_size: The number of samples in each batch.
• metric_iteration: The number of iterations used for metric computation.

After running the pipeline, the following outputs are produced:

• ori_data: The original input data.
• generated_data: The synthetic data produced by the trained TimeGAN.
• metric_results: The calculated discriminative and predictive scores.
• visualization: PCA and t-SNE analysis plots comparing the datasets.

When running main_timegan.py, you can customize the training process using the following command-line inputs. Note that network parameters should be optimized specifically for the dataset being used.

$ python3 main_timegan.py --data_name stock --seq_len 24 --module gru --hidden_dim 24 --num_layer 3 --iteration 50000 --batch_size 128 --metric_iteration 10

Use real_data_loading for existing datasets or sine_data_generation for synthetic sine waves. You must specify the seq_len (sequence length).

Supported data_name values:

• 'stock'
• 'energy'
• 'sine'

# For real datasets
data_name = 'stock'
seq_len = 24
ori_data = real_data_loading(data_name, seq_len)

# For sine dataset
no, dim = 10000, 5
seq_len = 24
ori_data = sine_data_generation(no, seq_len, dim)

Pass the original data and the parameters dictionary to the timegan function to produce synthetic data.

# Run TimeGAN
generated_data = timegan(ori_data, parameters)   

Use the following metrics to evaluate the quality of the generated data:

1. Discriminative Score: Measures how well a post-hoc RNN can distinguish real data from synthetic data. The output is $|classification\ accuracy - 0.5|$. Lower is better.
2. Predictive Score: Evaluates prediction performance using a 'train on synthetic, test on real' setting. It uses a post-hoc RNN to predict one-step ahead and reports the Mean Absolute Error (MAE).

# Discriminative Score
temp_disc = discriminative_score_metrics(ori_data, generated_data)

# Predictive Score
temp_pred = predictive_score_metrics(ori_data, generated_data)

Use the visualization function to compare the distributions of original and synthetic data using dimensionality reduction techniques.

Supported methods:

• 'pca'
• 'tsne'

visualization(ori_data, generated_data, 'pca')
visualization(ori_data, generated_data, 'tsne')