# Quick Start Guide

## Installation & Setup

### Step 1: Install Dependencies

```bash
cd /Volumes/BAT_Systems/synthetic_generator
pip3 install -r requirements.txt
```

This will install:
- Flask (web framework)
- pandas, numpy (data processing)
- ydata-synthetic (TimeGAN)
- scipy (Shapiro-Wilk test)
- tensorflow (deep learning backend)
- matplotlib, plotly (visualizations)

### Step 2: Start the Application

**Option A: Use the run script**
```bash
./run.sh
```

**Option B: Run directly**
```bash
cd src
python3 app.py
```

### Step 3: Open the Web Interface

Open your browser and navigate to:
```
http://localhost:5000
```

## Using the Application

### 1. Set Parameters

**Simulation Length** (100 - 100,000)
- Number of synthetic data points to generate
- Example: 5000 generates 5000 bid/ask records
- Larger values take longer but provide more data

**Volatility Multiplier** (0.1 - 10.0)
- Controls price movement intensity
- 1.0 = same volatility as reference data
- 1.5 = 50% more volatile
- 0.5 = 50% less volatile

### 2. Generate Data

Click "Generate Synthetic Data"

The process:
1. Loads reference data (50,000 XAUUSD records)
2. Trains TimeGAN model (first run takes ~1-2 minutes)
3. Generates synthetic bid/ask data
4. Validates with Shapiro-Wilk test
5. Displays results and visualizations

### 3. View Results

**Summary Statistics**
- Data points generated
- Mean bid/ask prices
- Average spread

**Shapiro-Wilk Test**
- Tests if bid-ask spread follows normal distribution
- Shows test statistic and p-value
- Interprets normality (p > 0.05 = normal)

**Visualizations**
- Time series plot: Bid and ask prices over time
- Distribution plot: Histogram of bid-ask spread

**Data Preview**
- First 10 rows with timestamps
- Last 10 rows with timestamps
- Filename of saved parquet file

### 4. Access Generated Data

Files are saved in:
```
/Volumes/BAT_Systems/synthetic_generator/data/synthetic_data/
```

Filename format:
```
synthetic_{length}_{volatility}x_{timestamp}.parquet
```

Example:
```
synthetic_5000_1.5x_20251203_174500.parquet
```

## Reading Generated Data

### Python
```python
import pandas as pd

df = pd.read_parquet('data/synthetic_data/synthetic_5000_1.5x_20251203_174500.parquet')
print(df.head())
```

### Structure
- Index: DatetimeIndex (timestamp column)
- Columns: `bid`, `ask` (float64)

## Troubleshooting

### Dependencies Not Installing
Try upgrading pip first:
```bash
pip3 install --upgrade pip
pip3 install -r requirements.txt
```

### Port 5000 Already in Use
Change the port in `src/app.py`:
```python
app.run(debug=True, host='0.0.0.0', port=5001)  # Use 5001 instead
```

### Generation Taking Too Long
- Reduce simulation length (try 1000-2000)
- First run always slower (model training)
- Subsequent runs are faster (cached model)

### Memory Issues
- Reduce simulation length below 10,000
- Close other applications
- Increase system swap space

## Example Use Cases

### 1. Quick Test (Fast)
- Simulation Length: 1000
- Volatility: 1.0
- Time: ~30 seconds

### 2. Standard Generation
- Simulation Length: 5000
- Volatility: 1.5
- Time: ~1-2 minutes

### 3. Large Dataset
- Simulation Length: 50,000
- Volatility: 2.0
- Time: ~3-5 minutes

### 4. Low Volatility Test
- Simulation Length: 10,000
- Volatility: 0.5
- Time: ~1-2 minutes

## Technical Notes

- TimeGAN uses sliding windows of 24 bars
- Model trains for 50 epochs (balanced speed/quality)
- Shapiro-Wilk samples 5000 points if dataset > 5000
- GPU acceleration automatic if available
- Data normalized during training, denormalized for output

## Support

For issues or questions:
1. Check console output for error messages
2. Verify all dependencies installed correctly
3. Ensure sample_data.parquet exists in data/ folder
4. Check logs in terminal where Flask is running

---

**Ready to generate!** 🚀
