alpha_lab/README.md

Alpha Lab

Quantitative research experiments for qshare library. This repository contains Jupyter notebooks and analysis scripts for exploring trading strategies and machine learning models.

Philosophy

• Notebook-centric: Experiments are interactive notebooks, not rigid scripts
• Minimal abstraction: Simple functions over complex class hierarchies
• Self-contained: Each task directory is independent
• Ad-hoc friendly: Easy to modify for exploration

Structure

alpha_lab/
├── common/              # Shared utilities (keep minimal!)
│   ├── paths.py         # Path management
│   └── plotting.py      # Common plotting functions
│
├── cta_1d/             # CTA 1-day return prediction
│   ├── 01_data_check.ipynb
│   ├── 02_label_analysis.ipynb
│   ├── 03_baseline_xgb.ipynb
│   ├── 04_blend_comparison.ipynb
│   └── src/            # Task-specific helpers
│
├── stock_15m/          # Stock 15-minute return prediction
│   ├── 01_data_exploration.ipynb
│   ├── 02_baseline_model.ipynb
│   └── src/
│
└── results/            # Output directory (gitignored)
    ├── cta_1d/
    └── stock_15m/

Setup

# Install dependencies
pip install -r requirements.txt

# Create environment file
cp .env.template .env
# Edit .env with your settings

Usage

Start Jupyter and run notebooks interactively:

jupyter notebook

Each task directory contains numbered notebooks:

• 01_*.ipynb - Data loading and exploration
• 02_*.ipynb - Analysis and baseline models
• 03_*.ipynb - Advanced experiments
• 04_*.ipynb - Comparisons and ablations

Experiment Tracking

Experiments are tracked manually in results/{task}/README.md:

## 2025-01-15: Baseline XGB
- Notebook: `cta_1d/03_baseline_xgb.ipynb` (cells 1-50)
- Config: eta=0.5, lambda=0.1
- Train IC: 0.042
- Test IC: 0.038
- Notes: Dual normalization, 4 trades/day

Adding a New Task

1. Create directory: mkdir my_task
2. Add src/ subdirectory for helpers
3. Create numbered notebooks
4. Add entry to results/my_task/README.md

Best Practices

1. Keep it simple: Only add to common/ after 3+ copies
2. Notebook configs: Define CONFIG dict in first cell for easy modification
3. Document results: Update results README after significant runs
4. Git discipline: Don't commit large files, results, or credentials