MAESTRO: Making Alpha Estimates through Synthetic TRaining Optimization

Project Overview

This project implements MAESTRO, a GAN-based framework designed to produce synthetic alpha signals for predictive modeling in quantitative finance. This codebase contains the project code for preprocessing, clustering, models, training, evaluation, and visualization.

Getting Started

Follow the instructions below to set up and run the project.

1. Clone the Repo

git clone https://github.com/DavidG1542/maestro.git

Environment Setup

It is recommended to use a virtual environment (e.g., venv or conda).

Install Dependencies

pip install -r requirements.txt

Installing MAESTRO Locally

You can install this project as an editable package using setup.py.

This allows modules like data_processing, training, evaluation, etc. to be imported from anywhere within the project code, and is needed for functionality.

1. Navigate to the root of the project (where setup.py and README.md are located).

2. Install in editable mode using:

pip install -e .

Code Structure

.
├── README.md                 # Project overview and instructions
├── requirements.txt          # Python dependencies
└── maestro/                  # Main source code directory
    ├── main.py               # Entry point script - start here! You can use this to run the entire pipeline.
    ├── data_processing.py    # Data preprocessing steps
    ├── clustering.py         # Various clustering methods, including spectral clustering
    ├── models.py             # Generator and discriminator model implementations
    ├── training.py           # WGAN training loop
    ├── evaluation.py         # Evaluation using both distributional similarity and predictive performance
    ├── visualizations.py     # Creating visualizations

How to Run the Code

The main script is main.py, located inside the maestro/ folder.

You can control the behavior of the pipeline through command-line arguments.

Basic usage:

python maestro/main.py [arguments]

If you don't specify any arguments, default values will be used.

---

Available Command-Line Arguments

Argument	Description	Default
--clustering, -c	Clustering method: single, industry, or spectral	spectral
--selected_stocks, -ss	Stock IDs (only for single mode)	None
--batch_size, -bs	Batch size for GAN training	256
--epochs, -e	Number of training epochs	100
--steps_per_epoch, -spe	Training steps per epoch	500
--gen_lr, -glr	Generator learning rate	1e-4
--disc_lr, -dlr	Discriminator learning rate	1e-4
--gan_type, -gt	GAN variant: solid or feature_matching	solid
--resume, -r	Resume training from checkpoint (flag)	False
--resume_epoch, -re	Epoch number to resume from	None

---

Important

• Step-by-Step Sections in the Code:
  In main.py, many major steps (such as clustering, GAN training, evaluation) are already coded but commented out.

• To run only specific parts (e.g., just training, just evaluation), you can comment/uncomment the relevant blocks inside main.py.

• Recommended Workflow:

  1. Set command-line arguments as needed.
  2. Open main.py and uncomment the sections you want to execute (e.g., just Training, or Evaluation).
  3. Run the script.

---

Notes

• You should not need to modify internal functions unless you want to customize anything.
• All intermediate files (like models, plots, evaluation results) will be automatically saved in the appropriate subfolders.
• If any required directory does not exist, it will be created automatically.

---

Contact

• David Geng (davidgen@andrew.cmu.edu)