# 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

```bash
# 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:

```bash
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`:

```markdown
## 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