# Local Development Tools

This document serves as a reference for the various utility scripts available in this repository for running, testing, and optimizing trading strategies locally.

## Strategy Execution

### Validate Strategy
Run a backtest for a specific strategy using historical data and a set of parameters. This is useful for verifying strategy performance on specific datasets.

**Command:**
```bash
python strategies/validate_strategy.py --strategy_file strategy_activation_scores.py --data data/COINBASE_BTCUSD-1D_macro.csv --params_file results/optimization_winner_activation_scores.csv --show-trades
```

### Optimize Strategy
Perform hyperparameter optimization to find the best parameters for a strategy.

**Command:**
```bash
python strategies/optimize_strategy.py --strategy_file strategy_activation_scores.py --data data/COINBASE_BTCUSD-1D.csv --params_file strategies/params_strategy_activation_scores_fast.json
```

### Walk-Forward Analysis
Performs a rolling window analysis (Train on past data -> Test on future data) to validate strategy robustness. 
**Command: **
```bash
python tools/walk_forward_runner.py --data data/COINBASE_BTCUSD-1D.csv --strategy_file strategy_activation_scores.py --params_file strategies/params_strategy_activation_scores.json --train_months 12 --test_months 1
```

## Data & Debugging

### Compare Strategy Outputs (TV vs Python)
Compares the CSV export from TradingView (Pine Script) against the Python strategy output to check for logic parity and divergence.

**Command:**
```bash
python tools/compare_strategies.py --tv_data output/DEBUG-ActivationScores-TV.csv --py_data output/DEBUG-ActivationScores-Py.csv
```

### Analyze Diffs
Tool to analyze differences between datasets or strategy runs (specifics depend on implementation).

**Command:**
```bash
python tools/analyze_diffs.py
```

### Clean Data
Utility to clean and preprocess data files, filtering from a specific start date.

**Command:**
```bash
python tools/clean_data.py --date 2017-10-01
```

### Diagnose Components
Performs a detailed comparison of debug columns between a TradingView export and a Python strategy output to ensure parity.

**Command:**
```bash
python tools/diagnose_components.py --tv output/DEBUG-ActivationScores-TV.csv --py output/DEBUG-ActivationScores-Py.csv
```

### Fetch Macro Data
Downloads and processes macroeconomic data from various sources.

**Command:**
```bash
python tools/fetch_macro_data.py
```