ivolatility-backtesting 2.163__tar.gz → 2.165__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ivolatility_backtesting-2.165/PKG-INFO +253 -0
- ivolatility_backtesting-2.165/README.md +228 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/ivolatility_backtesting/ivolatility_backtesting.py +35 -2
- ivolatility_backtesting-2.165/ivolatility_backtesting.egg-info/PKG-INFO +253 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/ivolatility_backtesting.egg-info/SOURCES.txt +3 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/ivolatility_backtesting.egg-info/requires.txt +2 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/pyproject.toml +4 -3
- ivolatility_backtesting-2.165/tests/test_2164_stock_price_stops.py +64 -0
- ivolatility_backtesting-2.165/tests/test_2165_parquet_engine_error.py +55 -0
- ivolatility_backtesting-2.165/tests/test_2165_renamed_symbol.py +115 -0
- ivolatility_backtesting-2.163/PKG-INFO +0 -73
- ivolatility_backtesting-2.163/README.md +0 -49
- ivolatility_backtesting-2.163/ivolatility_backtesting.egg-info/PKG-INFO +0 -73
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/ivolatility_backtesting/__init__.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/ivolatility_backtesting.egg-info/dependency_links.txt +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/ivolatility_backtesting.egg-info/top_level.txt +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/setup.cfg +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2142_fixes.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2144_duckdb_dedup.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2146_vix_vro.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2147_cents_multiplier.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2148_loader_memory.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2149_client_errors.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2150_prompt_patterns.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2152_cache_lock_and_rate_limit.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2153_cache_lock_kept.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2154_put_atm_legs.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2155_bar_prefetch.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2155_intraday_exits.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2155_ivx_stock_holes.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2155_key_redaction.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2155_long_expiry.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2155_opt_stop_merge.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2156_phantom_quotes.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2157_sl_symbol.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2158_default_path_golden.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2158_entry_time.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2159_entry_rule.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2160_day_price_order.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2160_exit_rule.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2160_option_lean_rule.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2160_prefetch_cancel.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2161_assignment.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2162_entry_minute_window.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2163_rotation.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_price_ta_indicators.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_stock_loader_coverage.py +0 -0
- {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_vix_percentile_direction.py +0 -0
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ivolatility_backtesting
|
|
3
|
+
Version: 2.165
|
|
4
|
+
Summary: A universal backtesting framework for financial strategies using the IVolatility API.
|
|
5
|
+
Author-email: IVolatility <support@ivolatility.com>
|
|
6
|
+
Project-URL: Homepage, https://ivolatility.com
|
|
7
|
+
Keywords: backtesting,finance,trading,ivolatility
|
|
8
|
+
Classifier: Programming Language :: Python :: 3
|
|
9
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Requires-Python: >=3.9
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
Requires-Dist: pandas<3.0,>=1.5.0
|
|
18
|
+
Requires-Dist: numpy<3.0,>=1.21.0
|
|
19
|
+
Requires-Dist: matplotlib>=3.5.0
|
|
20
|
+
Requires-Dist: seaborn>=0.11.0
|
|
21
|
+
Requires-Dist: ivolatility>=1.9.6
|
|
22
|
+
Requires-Dist: psutil>=7.1.0
|
|
23
|
+
Requires-Dist: fastparquet>=2023.1.0
|
|
24
|
+
Requires-Dist: duckdb>=1.0.0
|
|
25
|
+
|
|
26
|
+
# IVolatility Backtesting Framework v1.32
|
|
27
|
+
|
|
28
|
+
A universal options backtesting framework powered by the IVolatility API.
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## Supported Strategies
|
|
33
|
+
|
|
34
|
+
| Strategy | Description | Use Case |
|
|
35
|
+
|----------|-------------|----------|
|
|
36
|
+
| **STRADDLE** | Long/short ATM call + put | Volatility plays |
|
|
37
|
+
| **STRANGLE** | Long/short OTM call + put | Wide volatility plays |
|
|
38
|
+
| **IRON_CONDOR** | Short strangle + long wings | Range-bound income |
|
|
39
|
+
| **VERTICAL** | Bull/bear call or put spreads | Directional bets |
|
|
40
|
+
| **CALENDAR** | Same strike, different expiry | Time decay plays |
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Core Features
|
|
45
|
+
|
|
46
|
+
### Data & Caching
|
|
47
|
+
- **EOD + Intraday bars** - Both timeframes supported for stocks & options
|
|
48
|
+
- **IVolatility API integration** - Options chains, underlying prices, IV data, earnings calendar
|
|
49
|
+
- **DuckDB caching** - Local storage for fast repeated backtests
|
|
50
|
+
- **ASYNC parallel loading** - ~10x faster data preload
|
|
51
|
+
- **Connection pooling** - ~5x faster API calls
|
|
52
|
+
|
|
53
|
+
### Run Modes
|
|
54
|
+
|
|
55
|
+
| Mode | Function | Use Case |
|
|
56
|
+
|------|----------|----------|
|
|
57
|
+
| **Single Run** | `run_backtest()` | Test one specific configuration |
|
|
58
|
+
| **Baseline** | `run_optimization(run_baseline=True)` | Reference benchmark (combo_id=0) |
|
|
59
|
+
| **Combinations** | `run_optimization()` | Grid search to find optimal params |
|
|
60
|
+
| **Chunked** | `run_optimization_chunked()` | Large grids with memory management |
|
|
61
|
+
|
|
62
|
+
#### Single Run
|
|
63
|
+
Run one backtest with fixed parameters. Use for testing a specific strategy configuration.
|
|
64
|
+
```python
|
|
65
|
+
results = run_backtest(strategy_fn, config)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
#### Baseline
|
|
69
|
+
Reference run using `base_config` values before testing combinations. Saved as `combo_id=0` for comparison.
|
|
70
|
+
```python
|
|
71
|
+
all_results = run_optimization(
|
|
72
|
+
base_config=config,
|
|
73
|
+
param_grid=param_grid,
|
|
74
|
+
run_baseline=True # combo_id=0 uses base_config values
|
|
75
|
+
)
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
#### Combinations
|
|
79
|
+
Grid search across all parameter combinations. Each combo gets a unique `combo_id`.
|
|
80
|
+
```python
|
|
81
|
+
param_grid = {
|
|
82
|
+
'z_entry': [-2.0, -1.5, -1.0],
|
|
83
|
+
'z_exit': [0.5, 1.0],
|
|
84
|
+
'dte_target': [30, 45]
|
|
85
|
+
}
|
|
86
|
+
# Runs 3 × 2 × 2 = 12 combinations + baseline = 13 total
|
|
87
|
+
all_results = run_optimization(
|
|
88
|
+
base_config=config,
|
|
89
|
+
param_grid=param_grid,
|
|
90
|
+
run_baseline=True
|
|
91
|
+
)
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
#### Chunked Optimization
|
|
95
|
+
Memory-efficient mode for large parameter spaces. Processes in batches.
|
|
96
|
+
```python
|
|
97
|
+
run_optimization_chunked(
|
|
98
|
+
base_config=config,
|
|
99
|
+
param_grid=large_grid, # 1000+ combinations
|
|
100
|
+
chunk_size=50,
|
|
101
|
+
run_baseline=True
|
|
102
|
+
)
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### Supported Indicators
|
|
106
|
+
|
|
107
|
+
| Indicator | Source | Description |
|
|
108
|
+
|-----------|--------|-------------|
|
|
109
|
+
| `iv_rank` | Options | Current IV position in historical range (0-100) |
|
|
110
|
+
| `iv_rank_ivx` | IVX API | IV Rank from pre-calculated IVX data (faster) |
|
|
111
|
+
| `iv_percentile_ivx` | IVX API | IV Percentile from IVX data |
|
|
112
|
+
| `iv_lean_zscore` | Options | Call-Put IV spread normalized (mean reversion) |
|
|
113
|
+
| `iv_lean_zscore_ivx` | IVX API | IV Lean Z-score from IVX (faster) |
|
|
114
|
+
| `iv_term_structure` | IVX API | Volatility curve slope across tenors |
|
|
115
|
+
| `iv_skew` | Options | Put/Call IV skew at target delta |
|
|
116
|
+
| `vix_percentile` | VIX | VIX percentile rank over lookback |
|
|
117
|
+
| `realized_vol` | Stock | Historical volatility (annualized) |
|
|
118
|
+
|
|
119
|
+
### Entry Signals
|
|
120
|
+
- **Threshold-based** - Enter when indicator crosses level
|
|
121
|
+
- **Z-score signals** - Mean reversion entries
|
|
122
|
+
- **Delta-based selection** - Select strikes by delta target
|
|
123
|
+
- **Custom indicators** - Extensible via INDICATOR_REGISTRY
|
|
124
|
+
|
|
125
|
+
### Position & P&L Management
|
|
126
|
+
- **PositionManager** - Track open positions, calculate real-time P&L
|
|
127
|
+
- **Greeks tracking** - Delta, gamma, theta, vega per leg
|
|
128
|
+
- **Capital at risk** - 1.5x safety buffer for EOD backtests
|
|
129
|
+
- **Multi-leg support** - Spreads, condors, straddles
|
|
130
|
+
|
|
131
|
+
### Exit Management (StopLossManager)
|
|
132
|
+
- **DTE-based exit** - Close at target days to expiry
|
|
133
|
+
- **Stop-loss types:**
|
|
134
|
+
- Directional (underlying moves X%)
|
|
135
|
+
- P&L-based (position loses X%)
|
|
136
|
+
- Combined (both conditions required)
|
|
137
|
+
- **Profit targets** - Close at X% gain (same manager handles SL + PT)
|
|
138
|
+
- **Intraday monitoring** - Check stops on each bar
|
|
139
|
+
- **Earnings blackout** - Skip entries near earnings dates
|
|
140
|
+
|
|
141
|
+
### Analytics & Reporting
|
|
142
|
+
- **BacktestAnalyzer** - Sharpe ratio, max drawdown, win rate, profit factor
|
|
143
|
+
- **Equity curve** - Track portfolio value over time
|
|
144
|
+
- **ResultsReporter** - Generate summary tables and statistics
|
|
145
|
+
- **Trade-level details** - Entry/exit prices, Greeks, stop levels
|
|
146
|
+
|
|
147
|
+
### Visualization (ChartGenerator)
|
|
148
|
+
- **Equity curve charts** - Portfolio growth over time
|
|
149
|
+
- **Drawdown analysis** - Visualize underwater periods
|
|
150
|
+
- **Stop-loss analysis** - Compare exit reasons
|
|
151
|
+
- **Optimization heatmaps** - Parameter sensitivity
|
|
152
|
+
- **Monthly returns** - Calendar view of performance
|
|
153
|
+
|
|
154
|
+
### Optimization
|
|
155
|
+
- **Parameter grid search** - Test multiple configurations
|
|
156
|
+
- **Parallel execution** - Run combinations concurrently
|
|
157
|
+
- **Memory-efficient chunking** - Handle large parameter spaces
|
|
158
|
+
- **Results comparison** - Side-by-side analysis
|
|
159
|
+
|
|
160
|
+
---
|
|
161
|
+
|
|
162
|
+
## Architecture
|
|
163
|
+
|
|
164
|
+
```
|
|
165
|
+
┌─────────────────────────────────────────────────────────┐
|
|
166
|
+
│ User Notebook │
|
|
167
|
+
├─────────────────────────────────────────────────────────┤
|
|
168
|
+
│ run_backtest() / run_backtest_with_stoploss() │
|
|
169
|
+
├──────────────┬──────────────┬───────────────────────────┤
|
|
170
|
+
│ PositionMgr │ StopLossMgr │ DuckDBIndicatorManager │
|
|
171
|
+
├──────────────┴──────────────┴───────────────────────────┤
|
|
172
|
+
│ OptionsChunkManager (async) │
|
|
173
|
+
├─────────────────────────────────────────────────────────┤
|
|
174
|
+
│ DuckDBCacheManager │
|
|
175
|
+
├─────────────────────────────────────────────────────────┤
|
|
176
|
+
│ APIManager → IVolatility API │
|
|
177
|
+
└─────────────────────────────────────────────────────────┘
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## Key Classes
|
|
183
|
+
|
|
184
|
+
| Class | Purpose |
|
|
185
|
+
|-------|---------|
|
|
186
|
+
| `APIManager` | Unified API access with auth |
|
|
187
|
+
| `DuckDBCacheManager` | Persistent data caching (EOD + intraday) |
|
|
188
|
+
| `OptionsChunkManager` | Async parallel data loading |
|
|
189
|
+
| `DuckDBIndicatorManager` | Pre-calculate & cache indicators |
|
|
190
|
+
| `PositionManager` | Track positions, calculate P&L, manage Greeks |
|
|
191
|
+
| `StopLossManager` | Monitor stops + profit targets (intraday capable) |
|
|
192
|
+
| `StrategyRegistry` | Strategy definitions & metadata |
|
|
193
|
+
| `BacktestAnalyzer` | Calculate metrics: Sharpe, drawdown, win rate |
|
|
194
|
+
| `ResultsReporter` | Generate summary tables & statistics |
|
|
195
|
+
| `ChartGenerator` | Create equity curves, heatmaps, analysis charts |
|
|
196
|
+
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
## Quick Start
|
|
200
|
+
|
|
201
|
+
```python
|
|
202
|
+
from ivolatility_backtesting import run_backtest, preload_data
|
|
203
|
+
|
|
204
|
+
# Configure
|
|
205
|
+
config = {
|
|
206
|
+
'symbol': 'SPY',
|
|
207
|
+
'start_date': '2024-01-01',
|
|
208
|
+
'end_date': '2024-12-31',
|
|
209
|
+
'strategy_type': 'STRADDLE',
|
|
210
|
+
'dte_target': 30,
|
|
211
|
+
'entry_signal': 'iv_rank',
|
|
212
|
+
'entry_threshold': 50,
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
# Preload data (uses async for speed)
|
|
216
|
+
preloaded = preload_data(config)
|
|
217
|
+
|
|
218
|
+
# Run backtest
|
|
219
|
+
results = run_backtest(
|
|
220
|
+
strategy_function=straddle_strategy,
|
|
221
|
+
config={**config, **preloaded}
|
|
222
|
+
)
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## Performance
|
|
228
|
+
|
|
229
|
+
| Metric | Before v1.32 | After v1.32 |
|
|
230
|
+
|--------|--------------|-------------|
|
|
231
|
+
| Data preload | ~60s | ~6s (10x faster) |
|
|
232
|
+
| API calls | Sequential | Pooled (5x faster) |
|
|
233
|
+
| Memory usage | High | Chunked (stable) |
|
|
234
|
+
| DuckDB stability | Crashes | Legacy mode (stable) |
|
|
235
|
+
|
|
236
|
+
---
|
|
237
|
+
|
|
238
|
+
## Integration with Claude
|
|
239
|
+
|
|
240
|
+
Use `system_straddle_simple_20260206.promt` as a system prompt to have Claude generate backtesting notebooks. Claude will:
|
|
241
|
+
|
|
242
|
+
1. Ask about strategy parameters
|
|
243
|
+
2. Generate complete notebook code
|
|
244
|
+
3. Include stop-loss/profit-target configuration
|
|
245
|
+
4. Add earnings blackout if requested
|
|
246
|
+
|
|
247
|
+
---
|
|
248
|
+
|
|
249
|
+
## Links
|
|
250
|
+
|
|
251
|
+
- **GitLab:** `gitlab.ivolatility.com/ivolatility/ivolatility-backtesting`
|
|
252
|
+
- **API Docs:** `ivolatility.com/api/openapi.yml`
|
|
253
|
+
- **Changelog:** See `CHANGELOG.md` in repo
|
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
# IVolatility Backtesting Framework v1.32
|
|
2
|
+
|
|
3
|
+
A universal options backtesting framework powered by the IVolatility API.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Supported Strategies
|
|
8
|
+
|
|
9
|
+
| Strategy | Description | Use Case |
|
|
10
|
+
|----------|-------------|----------|
|
|
11
|
+
| **STRADDLE** | Long/short ATM call + put | Volatility plays |
|
|
12
|
+
| **STRANGLE** | Long/short OTM call + put | Wide volatility plays |
|
|
13
|
+
| **IRON_CONDOR** | Short strangle + long wings | Range-bound income |
|
|
14
|
+
| **VERTICAL** | Bull/bear call or put spreads | Directional bets |
|
|
15
|
+
| **CALENDAR** | Same strike, different expiry | Time decay plays |
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Core Features
|
|
20
|
+
|
|
21
|
+
### Data & Caching
|
|
22
|
+
- **EOD + Intraday bars** - Both timeframes supported for stocks & options
|
|
23
|
+
- **IVolatility API integration** - Options chains, underlying prices, IV data, earnings calendar
|
|
24
|
+
- **DuckDB caching** - Local storage for fast repeated backtests
|
|
25
|
+
- **ASYNC parallel loading** - ~10x faster data preload
|
|
26
|
+
- **Connection pooling** - ~5x faster API calls
|
|
27
|
+
|
|
28
|
+
### Run Modes
|
|
29
|
+
|
|
30
|
+
| Mode | Function | Use Case |
|
|
31
|
+
|------|----------|----------|
|
|
32
|
+
| **Single Run** | `run_backtest()` | Test one specific configuration |
|
|
33
|
+
| **Baseline** | `run_optimization(run_baseline=True)` | Reference benchmark (combo_id=0) |
|
|
34
|
+
| **Combinations** | `run_optimization()` | Grid search to find optimal params |
|
|
35
|
+
| **Chunked** | `run_optimization_chunked()` | Large grids with memory management |
|
|
36
|
+
|
|
37
|
+
#### Single Run
|
|
38
|
+
Run one backtest with fixed parameters. Use for testing a specific strategy configuration.
|
|
39
|
+
```python
|
|
40
|
+
results = run_backtest(strategy_fn, config)
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
#### Baseline
|
|
44
|
+
Reference run using `base_config` values before testing combinations. Saved as `combo_id=0` for comparison.
|
|
45
|
+
```python
|
|
46
|
+
all_results = run_optimization(
|
|
47
|
+
base_config=config,
|
|
48
|
+
param_grid=param_grid,
|
|
49
|
+
run_baseline=True # combo_id=0 uses base_config values
|
|
50
|
+
)
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
#### Combinations
|
|
54
|
+
Grid search across all parameter combinations. Each combo gets a unique `combo_id`.
|
|
55
|
+
```python
|
|
56
|
+
param_grid = {
|
|
57
|
+
'z_entry': [-2.0, -1.5, -1.0],
|
|
58
|
+
'z_exit': [0.5, 1.0],
|
|
59
|
+
'dte_target': [30, 45]
|
|
60
|
+
}
|
|
61
|
+
# Runs 3 × 2 × 2 = 12 combinations + baseline = 13 total
|
|
62
|
+
all_results = run_optimization(
|
|
63
|
+
base_config=config,
|
|
64
|
+
param_grid=param_grid,
|
|
65
|
+
run_baseline=True
|
|
66
|
+
)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
#### Chunked Optimization
|
|
70
|
+
Memory-efficient mode for large parameter spaces. Processes in batches.
|
|
71
|
+
```python
|
|
72
|
+
run_optimization_chunked(
|
|
73
|
+
base_config=config,
|
|
74
|
+
param_grid=large_grid, # 1000+ combinations
|
|
75
|
+
chunk_size=50,
|
|
76
|
+
run_baseline=True
|
|
77
|
+
)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### Supported Indicators
|
|
81
|
+
|
|
82
|
+
| Indicator | Source | Description |
|
|
83
|
+
|-----------|--------|-------------|
|
|
84
|
+
| `iv_rank` | Options | Current IV position in historical range (0-100) |
|
|
85
|
+
| `iv_rank_ivx` | IVX API | IV Rank from pre-calculated IVX data (faster) |
|
|
86
|
+
| `iv_percentile_ivx` | IVX API | IV Percentile from IVX data |
|
|
87
|
+
| `iv_lean_zscore` | Options | Call-Put IV spread normalized (mean reversion) |
|
|
88
|
+
| `iv_lean_zscore_ivx` | IVX API | IV Lean Z-score from IVX (faster) |
|
|
89
|
+
| `iv_term_structure` | IVX API | Volatility curve slope across tenors |
|
|
90
|
+
| `iv_skew` | Options | Put/Call IV skew at target delta |
|
|
91
|
+
| `vix_percentile` | VIX | VIX percentile rank over lookback |
|
|
92
|
+
| `realized_vol` | Stock | Historical volatility (annualized) |
|
|
93
|
+
|
|
94
|
+
### Entry Signals
|
|
95
|
+
- **Threshold-based** - Enter when indicator crosses level
|
|
96
|
+
- **Z-score signals** - Mean reversion entries
|
|
97
|
+
- **Delta-based selection** - Select strikes by delta target
|
|
98
|
+
- **Custom indicators** - Extensible via INDICATOR_REGISTRY
|
|
99
|
+
|
|
100
|
+
### Position & P&L Management
|
|
101
|
+
- **PositionManager** - Track open positions, calculate real-time P&L
|
|
102
|
+
- **Greeks tracking** - Delta, gamma, theta, vega per leg
|
|
103
|
+
- **Capital at risk** - 1.5x safety buffer for EOD backtests
|
|
104
|
+
- **Multi-leg support** - Spreads, condors, straddles
|
|
105
|
+
|
|
106
|
+
### Exit Management (StopLossManager)
|
|
107
|
+
- **DTE-based exit** - Close at target days to expiry
|
|
108
|
+
- **Stop-loss types:**
|
|
109
|
+
- Directional (underlying moves X%)
|
|
110
|
+
- P&L-based (position loses X%)
|
|
111
|
+
- Combined (both conditions required)
|
|
112
|
+
- **Profit targets** - Close at X% gain (same manager handles SL + PT)
|
|
113
|
+
- **Intraday monitoring** - Check stops on each bar
|
|
114
|
+
- **Earnings blackout** - Skip entries near earnings dates
|
|
115
|
+
|
|
116
|
+
### Analytics & Reporting
|
|
117
|
+
- **BacktestAnalyzer** - Sharpe ratio, max drawdown, win rate, profit factor
|
|
118
|
+
- **Equity curve** - Track portfolio value over time
|
|
119
|
+
- **ResultsReporter** - Generate summary tables and statistics
|
|
120
|
+
- **Trade-level details** - Entry/exit prices, Greeks, stop levels
|
|
121
|
+
|
|
122
|
+
### Visualization (ChartGenerator)
|
|
123
|
+
- **Equity curve charts** - Portfolio growth over time
|
|
124
|
+
- **Drawdown analysis** - Visualize underwater periods
|
|
125
|
+
- **Stop-loss analysis** - Compare exit reasons
|
|
126
|
+
- **Optimization heatmaps** - Parameter sensitivity
|
|
127
|
+
- **Monthly returns** - Calendar view of performance
|
|
128
|
+
|
|
129
|
+
### Optimization
|
|
130
|
+
- **Parameter grid search** - Test multiple configurations
|
|
131
|
+
- **Parallel execution** - Run combinations concurrently
|
|
132
|
+
- **Memory-efficient chunking** - Handle large parameter spaces
|
|
133
|
+
- **Results comparison** - Side-by-side analysis
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## Architecture
|
|
138
|
+
|
|
139
|
+
```
|
|
140
|
+
┌─────────────────────────────────────────────────────────┐
|
|
141
|
+
│ User Notebook │
|
|
142
|
+
├─────────────────────────────────────────────────────────┤
|
|
143
|
+
│ run_backtest() / run_backtest_with_stoploss() │
|
|
144
|
+
├──────────────┬──────────────┬───────────────────────────┤
|
|
145
|
+
│ PositionMgr │ StopLossMgr │ DuckDBIndicatorManager │
|
|
146
|
+
├──────────────┴──────────────┴───────────────────────────┤
|
|
147
|
+
│ OptionsChunkManager (async) │
|
|
148
|
+
├─────────────────────────────────────────────────────────┤
|
|
149
|
+
│ DuckDBCacheManager │
|
|
150
|
+
├─────────────────────────────────────────────────────────┤
|
|
151
|
+
│ APIManager → IVolatility API │
|
|
152
|
+
└─────────────────────────────────────────────────────────┘
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## Key Classes
|
|
158
|
+
|
|
159
|
+
| Class | Purpose |
|
|
160
|
+
|-------|---------|
|
|
161
|
+
| `APIManager` | Unified API access with auth |
|
|
162
|
+
| `DuckDBCacheManager` | Persistent data caching (EOD + intraday) |
|
|
163
|
+
| `OptionsChunkManager` | Async parallel data loading |
|
|
164
|
+
| `DuckDBIndicatorManager` | Pre-calculate & cache indicators |
|
|
165
|
+
| `PositionManager` | Track positions, calculate P&L, manage Greeks |
|
|
166
|
+
| `StopLossManager` | Monitor stops + profit targets (intraday capable) |
|
|
167
|
+
| `StrategyRegistry` | Strategy definitions & metadata |
|
|
168
|
+
| `BacktestAnalyzer` | Calculate metrics: Sharpe, drawdown, win rate |
|
|
169
|
+
| `ResultsReporter` | Generate summary tables & statistics |
|
|
170
|
+
| `ChartGenerator` | Create equity curves, heatmaps, analysis charts |
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## Quick Start
|
|
175
|
+
|
|
176
|
+
```python
|
|
177
|
+
from ivolatility_backtesting import run_backtest, preload_data
|
|
178
|
+
|
|
179
|
+
# Configure
|
|
180
|
+
config = {
|
|
181
|
+
'symbol': 'SPY',
|
|
182
|
+
'start_date': '2024-01-01',
|
|
183
|
+
'end_date': '2024-12-31',
|
|
184
|
+
'strategy_type': 'STRADDLE',
|
|
185
|
+
'dte_target': 30,
|
|
186
|
+
'entry_signal': 'iv_rank',
|
|
187
|
+
'entry_threshold': 50,
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
# Preload data (uses async for speed)
|
|
191
|
+
preloaded = preload_data(config)
|
|
192
|
+
|
|
193
|
+
# Run backtest
|
|
194
|
+
results = run_backtest(
|
|
195
|
+
strategy_function=straddle_strategy,
|
|
196
|
+
config={**config, **preloaded}
|
|
197
|
+
)
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
## Performance
|
|
203
|
+
|
|
204
|
+
| Metric | Before v1.32 | After v1.32 |
|
|
205
|
+
|--------|--------------|-------------|
|
|
206
|
+
| Data preload | ~60s | ~6s (10x faster) |
|
|
207
|
+
| API calls | Sequential | Pooled (5x faster) |
|
|
208
|
+
| Memory usage | High | Chunked (stable) |
|
|
209
|
+
| DuckDB stability | Crashes | Legacy mode (stable) |
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## Integration with Claude
|
|
214
|
+
|
|
215
|
+
Use `system_straddle_simple_20260206.promt` as a system prompt to have Claude generate backtesting notebooks. Claude will:
|
|
216
|
+
|
|
217
|
+
1. Ask about strategy parameters
|
|
218
|
+
2. Generate complete notebook code
|
|
219
|
+
3. Include stop-loss/profit-target configuration
|
|
220
|
+
4. Add earnings blackout if requested
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
## Links
|
|
225
|
+
|
|
226
|
+
- **GitLab:** `gitlab.ivolatility.com/ivolatility/ivolatility-backtesting`
|
|
227
|
+
- **API Docs:** `ivolatility.com/api/openapi.yml`
|
|
228
|
+
- **Changelog:** See `CHANGELOG.md` in repo
|
|
@@ -8,6 +8,8 @@
|
|
|
8
8
|
# 4. ASYNC parallel chunk loading (~10x faster preload)
|
|
9
9
|
# ============================================================
|
|
10
10
|
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
11
13
|
import atexit
|
|
12
14
|
import bisect
|
|
13
15
|
import collections
|
|
@@ -8429,7 +8431,25 @@ def _is_client_error(exc):
|
|
|
8429
8431
|
return status is not None and 400 <= status < 500 and status != 429
|
|
8430
8432
|
|
|
8431
8433
|
|
|
8432
|
-
def
|
|
8434
|
+
def _stamp_requested_symbol(normalized, endpoint, params):
|
|
8435
|
+
"""API returns the pre-rename symbol in older rows (FB for META); readers key on `symbol`, so stamp the requested one."""
|
|
8436
|
+
if not isinstance(normalized, dict) or '/equities/eod/stock-prices' not in str(endpoint):
|
|
8437
|
+
return normalized
|
|
8438
|
+
sym = params.get('symbol')
|
|
8439
|
+
if not isinstance(sym, str) or not sym.strip() or ',' in sym or ' ' in sym.strip():
|
|
8440
|
+
return normalized
|
|
8441
|
+
data = normalized.get('data')
|
|
8442
|
+
if isinstance(data, pd.DataFrame):
|
|
8443
|
+
if not data.empty:
|
|
8444
|
+
data = data.copy()
|
|
8445
|
+
data['symbol'] = sym
|
|
8446
|
+
normalized = dict(normalized, data=data)
|
|
8447
|
+
elif isinstance(data, list) and data and isinstance(data[0], dict):
|
|
8448
|
+
normalized = dict(normalized, data=[dict(r, symbol=sym) for r in data])
|
|
8449
|
+
return normalized
|
|
8450
|
+
|
|
8451
|
+
|
|
8452
|
+
def api_call(endpoint, cache_config=None, debug=False, max_retries=3, skip_parquet_cache=False,
|
|
8433
8453
|
_chunk_info=None, **kwargs):
|
|
8434
8454
|
"""
|
|
8435
8455
|
Make API call with automatic response normalization, caching, and retry logic
|
|
@@ -8890,6 +8910,7 @@ def _api_call_internal(endpoint, cache_config, debug, debug_level, skip_parquet_
|
|
|
8890
8910
|
# TIMING: Response normalization
|
|
8891
8911
|
t_normalize_start = time.perf_counter()
|
|
8892
8912
|
normalized = APIHelper.normalize_response(response, debug=debug)
|
|
8913
|
+
normalized = _stamp_requested_symbol(normalized, endpoint, kwargs)
|
|
8893
8914
|
t_normalize_elapsed = (time.perf_counter() - t_normalize_start) * 1000 # ms
|
|
8894
8915
|
_bt_logger.info(f"[DIAG] NORMALIZE END {_ci_str} thread={_tid_diag} elapsed={t_normalize_elapsed:.0f}ms")
|
|
8895
8916
|
|
|
@@ -14333,11 +14354,14 @@ class PositionManager:
|
|
|
14333
14354
|
'symbol': position.get('symbol')
|
|
14334
14355
|
}
|
|
14335
14356
|
|
|
14357
|
+
_st = position.get('strategy_type', 'LONG')
|
|
14358
|
+
if _st in STOCK_STRATEGY_TYPES:
|
|
14359
|
+
_st = 'SHORT' if _st in SHORT_STOCK_TYPES else 'LONG'
|
|
14336
14360
|
triggered, stop_level, stop_type, intraday_data = self.sl_manager.check_stop(
|
|
14337
14361
|
position_id=position_id,
|
|
14338
14362
|
current_price=check_value,
|
|
14339
14363
|
current_date=current_date,
|
|
14340
|
-
position_type=
|
|
14364
|
+
position_type=_st,
|
|
14341
14365
|
**stop_kwargs
|
|
14342
14366
|
)
|
|
14343
14367
|
|
|
@@ -14827,6 +14851,7 @@ class PositionManager:
|
|
|
14827
14851
|
pnl_pct = (pnl / entry_cost * 100) if entry_cost > 0 else 0
|
|
14828
14852
|
price_data[pos_id] = {
|
|
14829
14853
|
'current_price': stock_price,
|
|
14854
|
+
'price': stock_price,
|
|
14830
14855
|
'pnl': pnl,
|
|
14831
14856
|
'pnl_pct': pnl_pct,
|
|
14832
14857
|
'underlying_price': stock_price,
|
|
@@ -29715,6 +29740,10 @@ def get_cache_config(disk_enabled: bool = True, memory_enabled: bool = True,
|
|
|
29715
29740
|
# ============================================================
|
|
29716
29741
|
# CACHE MODES (unified caching architecture)
|
|
29717
29742
|
# ============================================================
|
|
29743
|
+
_PARQUET_ENGINE_MISSING = ("parquet engine missing: cached chunks cannot be written, so the backtest would run on 0 rows; "
|
|
29744
|
+
"run `pip install fastparquet` (installed with ivolatility_backtesting>=2.165) or `pip install pyarrow`")
|
|
29745
|
+
|
|
29746
|
+
|
|
29718
29747
|
class CacheMode:
|
|
29719
29748
|
"""Cache mode constants for unified caching architecture."""
|
|
29720
29749
|
ORIGINAL_PARQUET = 'original_parquet' # pandas reads Parquet one-by-one (legacy)
|
|
@@ -30034,6 +30063,8 @@ class UniversalCacheManager:
|
|
|
30034
30063
|
df.to_parquet(file_path, compression='snappy')
|
|
30035
30064
|
else:
|
|
30036
30065
|
df.to_parquet(file_path)
|
|
30066
|
+
except ImportError as e:
|
|
30067
|
+
raise RuntimeError(_PARQUET_ENGINE_MISSING) from e
|
|
30037
30068
|
except Exception as e:
|
|
30038
30069
|
if self.debug:
|
|
30039
30070
|
print(f"[CACHE] ❌ Error saving to disk: {e}")
|
|
@@ -30535,6 +30566,8 @@ class UniversalCacheManager:
|
|
|
30535
30566
|
df.to_parquet(filepath, index=False, compression='snappy')
|
|
30536
30567
|
else:
|
|
30537
30568
|
df.to_parquet(filepath, index=False)
|
|
30569
|
+
except ImportError as e:
|
|
30570
|
+
raise RuntimeError(_PARQUET_ENGINE_MISSING) from e
|
|
30538
30571
|
except Exception as e:
|
|
30539
30572
|
if self.debug:
|
|
30540
30573
|
print(f"[CACHE] ❌ Error saving chunk: {e}")
|