backtestingfx 0.3.0__cp315-cp315-win_amd64.whl

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.
@@ -0,0 +1,519 @@
1
+ import itertools
2
+ import operator
3
+ import warnings
4
+ from typing import Any
5
+
6
+ from backtestingfx import _backtestingfx as _rust # type: ignore
7
+ import numpy as np
8
+ import pandas as pd
9
+ from backtestingfx._timestamps import UNITS, index_seconds, timestamp_value
10
+ from backtestingfx._input import (
11
+ REFERENCE_OHLCV, InputMode, ReferenceSnapshot, prepare_reference, reference_columns,
12
+ )
13
+
14
+
15
+ class _DataView:
16
+ # ponytail: a window over the full bars list, visible up to the current bar.
17
+ # Slicing copies only the requested slice, not the growing prefix — this is
18
+ # what keeps data access O(1) per bar instead of O(n) (was O(n^2) overall).
19
+ __slots__ = ("_bars", "_len", "_snapshot")
20
+
21
+ def __init__(self, bars, snapshot=None):
22
+ self._bars = bars
23
+ self._len = 0
24
+ self._snapshot = snapshot
25
+
26
+ @property
27
+ def index(self):
28
+ if self._snapshot is None:
29
+ raise AttributeError("this data view has no source index")
30
+ return self._snapshot.index[:self._len]
31
+
32
+ @property
33
+ def df(self):
34
+ if self._snapshot is None:
35
+ raise AttributeError("this data view has no source frame")
36
+ return self._snapshot.frame.iloc[:self._len]
37
+
38
+ def _set_length(self, length):
39
+ self._len = length
40
+
41
+ def _bar(self, offset):
42
+ bar = self._bars[offset]
43
+ return bar if self._snapshot is None else self._snapshot.record(bar)
44
+
45
+ def __len__(self):
46
+ return self._len
47
+
48
+ def __getitem__(self, i):
49
+ if isinstance(i, slice):
50
+ return [self._bar(k) for k in range(*i.indices(self._len))]
51
+ if i < 0:
52
+ i += self._len
53
+ if not 0 <= i < self._len:
54
+ raise IndexError("bar index out of range")
55
+ return self._bar(i)
56
+
57
+ def __iter__(self):
58
+ return (self._bar(k) for k in range(self._len))
59
+
60
+
61
+ class _StrategyColumn(np.ndarray):
62
+ def __new__(cls, series, index):
63
+ column = np.asarray(series).view(cls)
64
+ column.name = series.name
65
+ column._index = index
66
+ return column
67
+
68
+ def __array_finalize__(self, source):
69
+ self.name = getattr(source, "name", None)
70
+ self._index = getattr(source, "_index", None)
71
+
72
+ def __bool__(self):
73
+ return bool(self[-1]) if self.ndim and self.shape[0] else super().__bool__()
74
+
75
+ def __float__(self):
76
+ return float(self[-1]) if self.ndim and self.shape[0] else super().__float__()
77
+
78
+ @property
79
+ def s(self):
80
+ values = np.atleast_2d(np.asarray(self))
81
+ return pd.Series(values[0], index=self._index[:values.shape[1]], name=self.name)
82
+
83
+ @property
84
+ def df(self):
85
+ values = np.atleast_2d(np.asarray(self))
86
+ return pd.DataFrame(
87
+ values.T, index=self._index[:values.shape[1]], columns=[self.name] * len(values),
88
+ )
89
+
90
+
91
+ class _ReferenceDataView(_DataView):
92
+ __slots__ = ("_columns", "_visible", "_pip")
93
+
94
+ def __init__(self, bars, snapshot):
95
+ super().__init__(bars, snapshot)
96
+ self._columns = {}
97
+ self._visible = {}
98
+ self._pip = None
99
+
100
+ def _set_length(self, length):
101
+ super()._set_length(length)
102
+ self._visible.clear()
103
+
104
+ def _column(self, name):
105
+ if name not in REFERENCE_OHLCV:
106
+ raise KeyError(name)
107
+ if name not in self._columns:
108
+ self._columns[name] = _StrategyColumn(
109
+ self._snapshot.frame[name], self._snapshot.index,
110
+ )
111
+ return self._columns[name]
112
+
113
+ def __getitem__(self, item):
114
+ if not isinstance(item, str):
115
+ return super().__getitem__(item)
116
+ if item not in self._visible:
117
+ self._visible[item] = self._column(item)[:self._len]
118
+ return self._visible[item]
119
+
120
+ def __getattr__(self, name):
121
+ if name in REFERENCE_OHLCV:
122
+ return self[name]
123
+ raise AttributeError(f"Column {name!r} not in data")
124
+
125
+ @property
126
+ def pip(self):
127
+ if self._pip is None:
128
+ prices = np.asarray(self._column("Close")).astype(str)
129
+ decimals = [len(price.partition(".")[2]) for price in prices]
130
+ self._pip = float(10 ** -np.median(decimals))
131
+ return self._pip
132
+
133
+
134
+ class Strategy:
135
+ def __init__(self):
136
+ self._bars: Any = None
137
+ self._bar: Any = None
138
+ self._broker: Any = None
139
+ self._index: int = 0
140
+ self._data_view: Any = None
141
+ self._snapshot = None
142
+ self._queued_execution = False
143
+
144
+ @property
145
+ def positions(self):
146
+ positions = self._broker.positions() if self._broker else []
147
+ return positions if self._snapshot is None else [self._snapshot.record(p) for p in positions]
148
+
149
+ @property
150
+ def position_count(self):
151
+ return self._broker.position_count if self._broker is not None else 0
152
+
153
+ @property
154
+ def has_positions(self):
155
+ return self._broker.has_positions if self._broker is not None else False
156
+
157
+ @property
158
+ def data(self):
159
+ if self._snapshot is not None or self._queued_execution:
160
+ return self._data_view
161
+ if not self._bars:
162
+ return []
163
+ if self._data_view is None:
164
+ self._data_view = _DataView(self._bars)
165
+ self._data_view._len = self._index + 1
166
+ return self._data_view
167
+
168
+ @property
169
+ def index(self):
170
+ return self._index
171
+
172
+ @property
173
+ def cash(self):
174
+ return self._broker.cash if self._broker else 0.0
175
+
176
+ @property
177
+ def equity(self):
178
+ return self._broker.equity(self._bar.close) if self._broker else 0.0
179
+
180
+ @property
181
+ def used_margin(self):
182
+ return self._broker.used_margin(self._bar.close) if self._broker is not None else 0.0
183
+
184
+ @property
185
+ def free_margin(self):
186
+ return self._broker.free_margin(self._bar.close) if self._broker is not None else 0.0
187
+
188
+ def init(self):
189
+ pass
190
+
191
+ def next(self):
192
+ pass
193
+
194
+ def execution_warmup(self):
195
+ """Number of additional bars to skip after bar zero in queued execution."""
196
+ return 0
197
+
198
+ def buy(self, lot_size, stop_loss=None, take_profit=None):
199
+ return self._broker.buy(
200
+ self._bar.close, lot_size, self._bar.timestamp, stop_loss, take_profit
201
+ )
202
+
203
+ def sell(self, lot_size, stop_loss=None, take_profit=None):
204
+ return self._broker.sell(
205
+ self._bar.close, lot_size, self._bar.timestamp, stop_loss, take_profit
206
+ )
207
+
208
+ def close_all(self):
209
+ self._broker.close_all(self._bar.close, self._bar.timestamp)
210
+
211
+ def close_position(self, id):
212
+ self._broker.close_position(id, self._bar.close, self._bar.timestamp)
213
+
214
+ def close_partial(self, id, lot_size):
215
+ """Close `lot_size` lots of a position, leaving the rest open."""
216
+ self._broker.close_partial(id, lot_size, self._bar.close, self._bar.timestamp)
217
+
218
+ def update_sl(self, id, stop_loss):
219
+ """Move a position's stop loss. Returns False if there is no such position."""
220
+ return self._broker.update_sl(id, stop_loss)
221
+
222
+
223
+ class _Adapter:
224
+ def __init__(self, strategy, snapshot=None):
225
+ self._strategy = strategy
226
+ self._index = 0
227
+ self._snapshot = snapshot
228
+
229
+ def init(self, bars):
230
+ self._strategy._bars = bars
231
+ self._strategy._snapshot = self._snapshot
232
+ if self._snapshot is not None:
233
+ self._strategy._data_view = _ReferenceDataView(bars, self._snapshot)
234
+ elif self._strategy._queued_execution:
235
+ self._strategy._data_view = _DataView(bars)
236
+ if self._strategy._data_view is not None:
237
+ self._strategy._data_view._set_length(len(bars))
238
+ self._strategy.init()
239
+
240
+ def _init_execution(self, bars, broker):
241
+ self._strategy._queued_execution = True
242
+ self._strategy._broker = broker
243
+ if bars:
244
+ self._strategy._bar = bars[-1]
245
+ self._strategy._index = len(bars) - 1
246
+ self.init(bars)
247
+ warmup = operator.index(self._strategy.execution_warmup())
248
+ if warmup < 0:
249
+ raise ValueError("execution_warmup() must return a nonnegative integer")
250
+ self._index = min(warmup + 1, max(len(bars), 1))
251
+ return self._index
252
+
253
+ def next(self, bar, broker):
254
+ self._strategy._bar = bar
255
+ self._strategy._broker = broker
256
+ self._strategy._index = self._index if self._snapshot is None else bar.timestamp
257
+ self._index += 1
258
+ if self._snapshot is not None or self._strategy._queued_execution:
259
+ self._strategy._data_view._set_length(self._strategy._index + 1)
260
+ self._strategy.next()
261
+
262
+
263
+ class Backtest:
264
+ """Backtest midpoint OHLC data with a full bid–ask spread in price units.
265
+
266
+ In data_mode='fx' (default), OHLCV and timestamp names are case-insensitive.
267
+ Numeric timestamp columns require timestamp_unit='s', 'ms', 'us', or 'ns'.
268
+ Naive datetimes mean UTC; aware datetimes retain their UTC instant. All
269
+ timestamps floor to whole Unix seconds before ordering checks.
270
+
271
+ data_mode='reference' uses exact Open/High/Low/Close names and preserves
272
+ the prepared pandas index, including periods, duplicates and nanoseconds.
273
+ Orders and sizing still use the FX API; calendar swaps require FX mode.
274
+
275
+ Passing trade_on_close or finalize_trades enables queued market orders
276
+ and a first callback after bar zero. Both flags default to False in that mode.
277
+
278
+ Fills apply half the spread on each side of the midpoint. Open equity marks
279
+ positions at their closing bid/ask, excluding future exit commission.
280
+ """
281
+
282
+ def __init__(
283
+ self,
284
+ df,
285
+ strategy_class=None, # optional: optimize() uses a signal function instead
286
+ cash=10000.0,
287
+ commission=0.0,
288
+ spread=0.0,
289
+ contract_size=100000.0,
290
+ quote_to_account=1.0,
291
+ *,
292
+ swap=None,
293
+ timestamp_unit=None,
294
+ margin=None,
295
+ data_mode="fx",
296
+ trade_on_close=None,
297
+ finalize_trades=None,
298
+ ):
299
+ if not isinstance(df, pd.DataFrame):
300
+ raise TypeError("market data must be a pandas DataFrame")
301
+ _rust._validate_config(cash, commission, spread, contract_size, quote_to_account)
302
+ self._data_mode = InputMode.parse(data_mode)
303
+ for name, flag in (("trade_on_close", trade_on_close), ("finalize_trades", finalize_trades)):
304
+ if flag is not None and not isinstance(flag, bool):
305
+ raise TypeError(f"{name} must be a bool or None")
306
+ self._execution_timing = (
307
+ None if trade_on_close is None and finalize_trades is None
308
+ else (bool(trade_on_close), bool(finalize_trades))
309
+ )
310
+ if self._data_mode is InputMode.REFERENCE and swap is not None:
311
+ raise ValueError("reference input row clocks cannot drive a swap calendar; use data_mode='fx'")
312
+ self._df = prepare_reference(df, cash) if self._data_mode is InputMode.REFERENCE else df
313
+ self._strategy_class = strategy_class
314
+ self._cash = cash
315
+ self._commission = commission
316
+ self._spread = spread
317
+ self._contract_size = contract_size
318
+ self._quote_to_account = quote_to_account
319
+ if swap is not None and not isinstance(swap, _rust.SwapConfig):
320
+ raise TypeError("swap must be a SwapConfig or None")
321
+ self._swap = swap
322
+ if margin is not None and not isinstance(margin, _rust.MarginConfig):
323
+ raise TypeError("margin must be a MarginConfig or None")
324
+ self._margin = margin
325
+ if timestamp_unit is not None and (
326
+ not isinstance(timestamp_unit, str) or timestamp_unit not in UNITS
327
+ ):
328
+ raise ValueError("timestamp_unit must be None, 's', 'ms', 'us', or 'ns'")
329
+ self._timestamp_unit = timestamp_unit
330
+ self._stats = None
331
+ self._report_df = None
332
+ self._report_timestamps = None
333
+ self._report_snapshot = None
334
+
335
+ def _bar_columns(self, df):
336
+ if self._data_mode is InputMode.REFERENCE:
337
+ return reference_columns(df)
338
+ required = {"open", "high", "low", "close"}
339
+ columns = {}
340
+ for column in df.columns:
341
+ normalized = column.lower() if isinstance(column, str) else column
342
+ if normalized in columns:
343
+ raise ValueError(
344
+ f"DataFrame has duplicate columns after normalization: {normalized!r}"
345
+ )
346
+ columns[normalized] = column
347
+ missing = required - columns.keys()
348
+ if missing:
349
+ raise ValueError(f"DataFrame missing required columns: {sorted(missing)}")
350
+
351
+ if isinstance(df.index, pd.DatetimeIndex) and df.index.hasnans:
352
+ offset = int(np.flatnonzero(df.index.isna())[0])
353
+ raise ValueError(f"bar {offset}: timestamp is missing (NaT)")
354
+ if len(df) and not isinstance(df.index, pd.DatetimeIndex) and "timestamp" not in columns:
355
+ if not all(isinstance(index, pd.Timestamp) for index in df.index):
356
+ raise ValueError("DataFrame needs a DatetimeIndex or timestamp column")
357
+
358
+ names = ("open", "high", "low", "close", "volume")
359
+ numeric = all(isinstance(df[columns[name]].dtype, np.dtype)
360
+ and df[columns[name]].dtype.kind in "biuf"
361
+ for name in names if name in columns)
362
+ if not numeric or not isinstance(df.index, pd.DatetimeIndex) or df.index.hasnans:
363
+ return self._scalar_bar_columns(df, columns)
364
+
365
+ timestamps = index_seconds(df.index)
366
+ values = []
367
+ for name in names:
368
+ if name not in columns:
369
+ values.append(np.zeros(len(df), dtype=np.float64))
370
+ continue
371
+ values.append(np.require(df[columns[name]].to_numpy(), dtype=np.float64,
372
+ requirements=["C", "A"]))
373
+ return timestamps, values
374
+
375
+ @staticmethod
376
+ def _float_value(value, field, offset):
377
+ try:
378
+ if np.iscomplexobj(value):
379
+ raise ValueError("complex value")
380
+ return float(value)
381
+ except (TypeError, ValueError, OverflowError) as error:
382
+ raise ValueError(f"bar {offset}: {field} must be a real number, got {value!r}") from error
383
+
384
+ def _scalar_bar_columns(self, df, columns):
385
+ timestamps = np.empty(len(df), dtype=np.int64)
386
+ values = np.empty((5, len(df)), dtype=np.float64)
387
+ names = ("open", "high", "low", "close", "volume")
388
+ positions = [df.columns.get_loc(columns[name]) if name in columns else None for name in names]
389
+ source = df[columns["timestamp"]].array if "timestamp" in columns else None
390
+ # The old iterrows() converter used this common row dtype. Preserve its
391
+ # OHLCV promotion and scalar errors without constructing a Series per row.
392
+ # Read timestamps separately so integer epochs never promote to float.
393
+ for offset, (idx, row) in enumerate(zip(df.index, df.to_numpy())):
394
+ stamp = idx if isinstance(idx, pd.Timestamp) else source[offset]
395
+ timestamps[offset] = timestamp_value(stamp, offset, self._timestamp_unit)
396
+ for field, position in enumerate(positions):
397
+ values[field, offset] = Backtest._float_value(row[position], names[field], offset) if position is not None else 0.0
398
+ return timestamps, values
399
+
400
+ def _to_bars(self, df):
401
+ return _rust._bars_from_columns(self._bar_columns(df), validation=self._data_mode.value)
402
+
403
+ def _engine(self, df, columns=None):
404
+ engine = _rust.Engine._from_columns( # type: ignore
405
+ self._bar_columns(df) if columns is None else columns,
406
+ self._cash,
407
+ self._commission,
408
+ self._spread,
409
+ self._contract_size,
410
+ self._quote_to_account,
411
+ swap=self._swap,
412
+ margin=self._margin,
413
+ validation=self._data_mode.value,
414
+ )
415
+ if self._execution_timing is not None:
416
+ engine._set_execution_timing(*self._execution_timing)
417
+ return engine
418
+
419
+ def run(self):
420
+ if self._strategy_class is None:
421
+ raise ValueError("Backtest needs a strategy_class to run(); use optimize() for signal functions")
422
+
423
+ self._stats = None
424
+ self._report_df = None
425
+ self._report_timestamps = None
426
+ self._report_snapshot = None
427
+ report_df = self._df.copy(deep=True)
428
+ snapshot = ReferenceSnapshot(report_df) if self._data_mode is InputMode.REFERENCE else None
429
+ columns = self._bar_columns(report_df)
430
+ engine = self._engine(report_df, columns)
431
+ strategy = self._strategy_class()
432
+ stats = engine.run(_Adapter(strategy, snapshot))
433
+ if snapshot is not None or self._execution_timing is not None:
434
+ strategy._data_view._set_length(len(report_df))
435
+ if self._execution_timing is not None and not self._execution_timing[1] and stats.open_positions:
436
+ warnings.warn(
437
+ "Some trades remain open at the end of backtest. "
438
+ "Use finalize_trades=True to queue their closure.",
439
+ UserWarning, stacklevel=2,
440
+ )
441
+ self._stats = stats if snapshot is None else snapshot.result(stats)
442
+ self._report_df = report_df
443
+ self._report_timestamps = columns[0].copy()
444
+ self._report_snapshot = snapshot
445
+ return self._stats
446
+
447
+ def optimize(self, signal_fn, maximize="total_return_pct", **grid):
448
+ """Grid-search `signal_fn` over the given parameter ranges. Best result first.
449
+
450
+ `signal_fn(df, **params)` is called once per combination and returns one target
451
+ lot size per bar: positive for long, negative for short, 0.0 for flat. Write it
452
+ vectorised (pandas/numpy) — it runs in Python, but only once per combination,
453
+ never per bar. The simulations themselves run in parallel Rust threads.
454
+
455
+ Returns a list of `(params, stats)` sorted by the named Stats field, so
456
+ `results[0]` is the best run. Sort it yourself to minimise something instead.
457
+ """
458
+ if not grid:
459
+ raise ValueError("optimize needs at least one parameter range")
460
+
461
+ snapshot = ReferenceSnapshot(self._df.copy(deep=True)) if self._data_mode is InputMode.REFERENCE else None
462
+ frame = self._df if snapshot is None else snapshot.frame
463
+ engine = self._engine(frame)
464
+
465
+ names = list(grid)
466
+ combos = [dict(zip(names, values)) for values in itertools.product(*grid.values())]
467
+
468
+ signals = []
469
+ for combo in combos:
470
+ signal = np.asarray(signal_fn(frame, **combo), dtype=float)
471
+ if signal.ndim != 1:
472
+ raise ValueError(f"signal_fn must return a one-dimensional signal for {combo}")
473
+ if len(signal) != len(self._df):
474
+ raise ValueError(
475
+ f"signal_fn returned {len(signal)} values for {combo}, expected "
476
+ f"{len(self._df)} (one per bar)"
477
+ )
478
+ if np.isnan(signal).any():
479
+ raise ValueError(
480
+ f"signal_fn returned NaN for {combo} — indicator warmup should "
481
+ "produce 0.0 (flat), not NaN"
482
+ )
483
+ if not np.isfinite(signal).all():
484
+ raise ValueError(f"signal_fn must return finite values for {combo}")
485
+ # ponytail: tolist() is the cheap bridge into Rust. It costs one Python
486
+ # float per bar per combo; swap in the `numpy` crate for a zero-copy
487
+ # PyReadonlyArray1 if this ever shows up in a profile.
488
+ signals.append(signal.tolist())
489
+
490
+ results = _rust.run_grid(engine, signals) # type: ignore
491
+ if snapshot is not None:
492
+ results = [snapshot.result(stats) for stats in results]
493
+
494
+ return sorted(
495
+ zip(combos, results),
496
+ key=lambda pair: getattr(pair[1], maximize),
497
+ reverse=True,
498
+ )
499
+
500
+ def plot(self, filename="backtest.html", open_browser=True):
501
+ if self._stats is None:
502
+ raise RuntimeError("Run the backtest before plotting it")
503
+
504
+ from backtestingfx.plotting import render_report
505
+
506
+ return render_report(
507
+ self._report_df,
508
+ self._stats,
509
+ timestamps=self._report_timestamps,
510
+ strategy_name=self._strategy_class.__name__,
511
+ filename=filename,
512
+ open_browser=open_browser,
513
+ commission=self._commission,
514
+ spread=self._spread,
515
+ contract_size=self._contract_size,
516
+ quote_to_account=self._quote_to_account,
517
+ swap=self._swap,
518
+ snapshot=self._report_snapshot,
519
+ )