POST-PROCESSING GAN-GENERATED SYNTHETIC TIME SERIES USING SOFT-DTW
==================================================================

1. PROJECT MOTIVATION & USE CASE
---------------------------------
This project was developed as part of a research workflow focusing on improving
the realism of GAN-generated synthetic time-series data. The motivation is to
bridge the gap between generative modeling (via DoppelGANger, or DGAN) and
statistical alignment methods (via Soft Dynamic Time Warping). The framework
provides a unified approach to generate, align, and evaluate synthetic data
using both temporal and spectral metrics.

It is particularly suited for:
- Time-series analysis in economics, biology, and sensor data.
- Synthetic data validation in research and industrial data science.
- Thesis and academic work focusing on statistical modeling and GAN evaluation.

------------------------------------------------------------------

2. PROJECT OVERVIEW
--------------------
This repository implements a complete end-to-end framework for post-processing
and evaluating synthetic time-series data generated using DoppelGANger (DGAN).
The pipeline uses Soft Dynamic Time Warping (Soft-DTW) to realign generated
series and then performs statistical, spectral, and ARMA-based diagnostics to
evaluate temporal similarity and distributional fidelity.

------------------------------------------------------------------

3. METHODOLOGY
---------------
Step 1. Real Data
   - Load a univariate time series from the 'data/' directory.

Step 2. Synthetic Generation (DGAN)
   - Train a DoppelGANger (DGAN) model on the real data.
   - Generate synthetic time-series samples that mimic temporal patterns.
   - If DGAN is not used, an ARMA(p, q) surrogate can be simulated.

Step 3. Soft-DTW Alignment
- Use Soft-DTW to align the synthetic sequence onto the real sequence’s timeline.
- Compute the expected mapping φ(i) from (real, synthetic) and produce the aligned synthetic series.
- Smooth φ(i) with a Savitzky–Golay filter to ensure a stable, monotonic mapping.

Step 4. Statistical Evaluation
   - Distributional Analysis (Histogram + KDE)
   - Spectral Analysis (Periodogram + Welch PSD)
   - Autocorrelation Function (ACF)
   - ARMA Model Fitting (via AIC)
   - Residual Diagnostics (Ljung–Box, Shapiro–Wilk, Jarque–Bera)

Step 5. Performance Metrics
   - Soft-DTW distance (before vs. after alignment)
   - Correlation and peak lag
   - Spectral similarity (Welch)
   - ACF similarity
   - All metrics summarized in 'metrics_summary.csv'

------------------------------------------------------------------

4. DIRECTORY STRUCTURE
-----------------------
DGAN-SoftDTW-Postprocessing/
│
├── main.py                        Main pipeline script
├── README.txt                     This file
├── requirements.txt               Dependencies
│
├── data/
│   └── simulated_arma_data.csv    Example input data
│
├── configs/
│   └── dgan_config.json           Example DoppelGANger config
│
├── src/
│   ├── generate_synthetic.py      DGAN + AR(1) generators
│   ├── align_softdtw.py           Soft-DTW alignment
│   ├── evaluate_alignment.py      Metrics and scoring
│   ├── model_arma.py              ARMA fit and diagnostics
│   ├── plots.py                   Distribution, PSD, ACF plots
│   ├── utils.py                   Helper functions
│   ├── surrogates.py              ARMA surrogate generation
│   ├── original_impl.py           Your exact original DGAN script
│   └── original_compat.py         Bridge to call your original functions
│
└── results/                       Output directory (auto-created)

------------------------------------------------------------------

5. HOW TO RUN
---------------
A. Using your original DGAN implementation:
   pip install -r requirements.txt
   python main.py --real data/simulated_arma_data.csv \
       --use-dgan \
       --use-original \
       --dgan-train-csv data/simulated_arma_data.csv \
       --dgan-config configs/dgan_config.json \
       --gamma 0.25

B. Without DGAN (ARMA surrogate):
   python main.py --real data/simulated_arma_data.csv --real-only --gamma 0.25

C. Demo mode (AR(1) simulation):
   python main.py --demo

------------------------------------------------------------------

6. OUTPUT FILES (in results/)
------------------------------
- metrics_summary.csv            Alignment metrics
- alignment_phi.png              Expected mapping φ(i)
- series_before_after.png        Overlay of real, synthetic, aligned
- distribution_hist_kde.png      Histogram + KDE
- periodogram.png                Periodogram spectrum
- welch_psd.png                  Welch Power Spectral Density
- acf_plot.png                   Autocorrelation function
- arma_aic.csv                   ARMA model AIC comparison
- residual_diagnostics.csv       Statistical diagnostics
- residuals_*.png                Residual plots per series
- metrics_original_parity.txt    Results from your exact functions (optional)

------------------------------------------------------------------

7. SUMMARY
------------
This framework provides a reproducible pipeline that connects GAN-based data
generation, dynamic time warping alignment, and rigorous statistical evaluation.
It captures the full research workflow — from data generation to alignment and
model diagnostics.

------------------------------------------------------------------

Developed by: Md Raisul Islam Roni
Affiliation: East Tennessee State University