overfitting 0.4.1__tar.gz → 0.5.0__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.

Potentially problematic release.


This version of overfitting might be problematic. Click here for more details.

Files changed (35) hide show
  1. {overfitting-0.4.1 → overfitting-0.5.0}/PKG-INFO +61 -32
  2. {overfitting-0.4.1 → overfitting-0.5.0}/README.md +56 -29
  3. {overfitting-0.4.1 → overfitting-0.5.0}/overfitting/__init__.py +0 -1
  4. {overfitting-0.4.1 → overfitting-0.5.0}/overfitting/broker.py +140 -16
  5. overfitting-0.5.0/overfitting/data.py +89 -0
  6. {overfitting-0.4.1 → overfitting-0.5.0}/overfitting/errors.py +3 -0
  7. overfitting-0.5.0/overfitting/indicators.py +210 -0
  8. {overfitting-0.4.1 → overfitting-0.5.0}/overfitting/position.py +13 -2
  9. {overfitting-0.4.1 → overfitting-0.5.0}/overfitting/strategy.py +106 -20
  10. {overfitting-0.4.1 → overfitting-0.5.0}/overfitting.egg-info/PKG-INFO +61 -32
  11. {overfitting-0.4.1 → overfitting-0.5.0}/overfitting.egg-info/SOURCES.txt +9 -1
  12. {overfitting-0.4.1 → overfitting-0.5.0}/overfitting.egg-info/requires.txt +4 -1
  13. {overfitting-0.4.1 → overfitting-0.5.0}/pyproject.toml +10 -4
  14. overfitting-0.5.0/tests/test_accounting.py +198 -0
  15. overfitting-0.5.0/tests/test_data.py +97 -0
  16. overfitting-0.5.0/tests/test_funding.py +146 -0
  17. overfitting-0.5.0/tests/test_liquidation.py +276 -0
  18. overfitting-0.5.0/tests/test_margin.py +205 -0
  19. overfitting-0.5.0/tests/test_orders.py +333 -0
  20. overfitting-0.5.0/tests/test_position.py +179 -0
  21. overfitting-0.5.0/tests/test_readme.py +39 -0
  22. overfitting-0.5.0/tests/test_strategy.py +281 -0
  23. overfitting-0.4.1/overfitting/analysis/viewer.py +0 -894
  24. overfitting-0.4.1/overfitting/data.py +0 -89
  25. overfitting-0.4.1/overfitting/indicators.py +0 -207
  26. {overfitting-0.4.1 → overfitting-0.5.0}/LICENSE +0 -0
  27. {overfitting-0.4.1 → overfitting-0.5.0}/overfitting/analysis/__init__.py +0 -0
  28. {overfitting-0.4.1 → overfitting-0.5.0}/overfitting/analysis/graph.py +0 -0
  29. {overfitting-0.4.1 → overfitting-0.5.0}/overfitting/analysis/report.py +0 -0
  30. {overfitting-0.4.1 → overfitting-0.5.0}/overfitting/order.py +0 -0
  31. {overfitting-0.4.1 → overfitting-0.5.0}/overfitting/slippage.py +0 -0
  32. {overfitting-0.4.1 → overfitting-0.5.0}/overfitting/types.py +0 -0
  33. {overfitting-0.4.1 → overfitting-0.5.0}/overfitting.egg-info/dependency_links.txt +0 -0
  34. {overfitting-0.4.1 → overfitting-0.5.0}/overfitting.egg-info/top_level.txt +0 -0
  35. {overfitting-0.4.1 → overfitting-0.5.0}/setup.cfg +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: overfitting
3
- Version: 0.4.1
3
+ Version: 0.5.0
4
4
  Summary: A Robust Futures CryptoCurrency Backtesting Library.
5
5
  Author-email: Dohyun Kim <dohyun.k.july@gmail.com>
6
6
  License: MIT
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python
15
15
  Classifier: Programming Language :: Python :: 3
16
16
  Classifier: Operating System :: OS Independent
17
17
  Classifier: Topic :: Office/Business :: Financial :: Investment
18
- Requires-Python: >=3.8
18
+ Requires-Python: >=3.10
19
19
  Description-Content-Type: text/markdown
20
20
  License-File: LICENSE
21
21
  Requires-Dist: numpy>=1.17.0
@@ -24,37 +24,41 @@ Requires-Dist: seaborn
24
24
  Requires-Dist: matplotlib
25
25
  Requires-Dist: scipy
26
26
  Requires-Dist: plotly
27
- Requires-Dist: PySide6
28
27
  Provides-Extra: examples
29
28
  Requires-Dist: notebook; extra == "examples"
30
29
  Requires-Dist: ipykernel; extra == "examples"
31
30
  Requires-Dist: ipython; extra == "examples"
31
+ Provides-Extra: test
32
+ Requires-Dist: pytest>=7; extra == "test"
32
33
  Provides-Extra: dev
33
34
  Requires-Dist: twine>=4.0.2; extra == "dev"
35
+ Requires-Dist: pytest>=7; extra == "dev"
34
36
  Dynamic: license-file
35
37
 
36
38
  # Overfitting (Futures Backtesting)
37
39
 
40
+ [![Tests](https://github.com/dohyunkjuly/overfitting/actions/workflows/tests.yml/badge.svg)](https://github.com/dohyunkjuly/overfitting/actions/workflows/tests.yml)
41
+
38
42
  Overfitting simulates a realistic crypto futures trading environment including
39
43
  - **Liquidation**, **Margin**, **Leverage** for stress testing
40
44
  - **Multiple Currency** Trading (e.g., backtesting BTC PERP & ETH PERP at the same time)
41
45
  - Four Different Order Types: LIMIT, MARKET, STOP_LIMIT, STOP_MARKET
42
46
  - Slippage/Commission Setting
43
47
 
44
- ![Backtest Viewer](https://raw.githubusercontent.com/dohyunkjuly/overfitting/main/documents/viewer.gif)
45
-
46
48
  ## Installation
47
49
  $ pip install overfitting
48
50
 
49
51
  ## Usage
52
+ Run from the repository root; the example reads the sample data in `examples/data/`.
53
+
50
54
  ```python
51
55
  import pandas as pd
52
- from overfitting import Strategy, BacktestViewer
56
+ from overfitting import Strategy
53
57
  from overfitting.indicators import SMA
54
58
 
55
59
  def load_data():
56
- df = pd.read_csv('./data/BTCUSDT.csv')
57
- benchamrk_df = pd.read_csv('./data/BTCUSDT.csv') # BTC buy and Hold
60
+ df = pd.read_csv('examples/data/BTCUSDT.csv')
61
+ benchamrk_df = pd.read_csv('examples/data/BTCUSDT.csv') # BTC buy and Hold
58
62
  df['timestamp'] = pd.to_datetime(df['timestamp'], unit='ms')
59
63
  df.set_index('timestamp', inplace=True)
60
64
 
@@ -62,14 +66,14 @@ def load_data():
62
66
  df = df.loc[start_time:]
63
67
 
64
68
  return df, benchamrk_df
65
-
69
+
66
70
  class MyStrategy(Strategy):
67
71
  def init(self):
68
72
  self.asset = 'BTC'
69
73
  self.set_leverage(self.asset, 1)
70
74
 
71
- self.sma_short = SMA(self, self.asset, source="close", window=20)
72
- self.sma_long = SMA(self, self.asset, source="close", window=50)
75
+ self.sma_short = self.indicator(SMA, self.asset, window=20)
76
+ self.sma_long = self.indicator(SMA, self.asset, window=50)
73
77
 
74
78
  def next(self, i):
75
79
  if i == 0:
@@ -109,9 +113,6 @@ strategy = MyStrategy(
109
113
  )
110
114
  returns = strategy.run()
111
115
  strategy.plot(returns)
112
-
113
- # Show Backtest Viewer UI
114
- # BacktestViewer(strategy).show()
115
116
  ```
116
117
 
117
118
  Results
@@ -123,14 +124,14 @@ Start Date 2023-01-01 00:00:00
123
124
  End Date 2024-08-29 00:00:00
124
125
  Initial Balance 100,000.00000000
125
126
  Final Balance 205,328.91120000
126
- CAGR 0.52684228
127
+ CAGR 0.54238181
127
128
  Cumulative Return 2.05328911
128
- Sharpe Ratio 1.24678659
129
- Sortino Ratio 3.54979579
130
- Max Drawdown -0.26332695
131
- Daily Value At Risk -0.04147282
132
- Skew 0.44515551
133
- Kurtosis 2.66444346
129
+ Sharpe Ratio 1.47036287
130
+ Sortino Ratio 2.79869052
131
+ Max Drawdown -0.26533797
132
+ Daily Value At Risk -0.03329469
133
+ Skew 0.72604283
134
+ Kurtosis 2.82598628
134
135
  Total Trades 182.00000000
135
136
  Winning Trades 69.00000000
136
137
  Losing Trades 113.00000000
@@ -142,16 +143,16 @@ Avg Return (%) 0.38834383
142
143
  Avg Profit (%) 3.54140613
143
144
  Avg Loss (%) -1.53697740
144
145
  Net drawdown in % Peak date Valley date Recovery date Duration
145
- 0 26.332695 2024-03-13 2024-06-30 NaT NaN
146
- 1 19.678014 2023-03-20 2023-09-07 2023-10-26 159
147
- 2 6.297244 2023-12-07 2024-01-24 2024-02-14 50
148
- 3 5.585429 2023-01-22 2023-02-14 2023-02-17 20
149
- 4 3.898568 2023-02-17 2023-03-11 2023-03-15 19
150
- 5 3.336877 2023-11-12 2023-11-18 2023-12-07 19
151
- 6 2.699556 2024-02-20 2024-02-26 2024-03-01 9
152
- 7 0.767196 2024-03-01 2024-03-03 2024-03-06 4
153
- 8 0.324161 2023-01-03 2023-01-07 2023-01-18 12
154
- 9 0.019817 2023-11-03 2023-11-04 2023-11-07 3
146
+ 0 26.533797 2024-03-13 2024-06-28 NaT NaN
147
+ 1 20.996185 2023-03-17 2023-09-12 2023-10-23 157
148
+ 2 7.051091 2023-12-05 2024-01-22 2024-02-09 49
149
+ 3 5.980692 2023-01-21 2023-02-13 2023-02-15 18
150
+ 4 5.578214 2023-02-15 2023-03-07 2023-03-12 18
151
+ 5 5.550106 2024-03-04 2024-03-06 2024-03-11 6
152
+ 6 4.538401 2023-11-10 2023-11-16 2023-12-04 17
153
+ 7 2.530832 2023-11-01 2023-11-03 2023-11-09 7
154
+ 8 2.162228 2024-02-18 2024-02-23 2024-02-27 7
155
+ 9 1.603446 2024-02-28 2024-02-29 2024-03-04 4
155
156
  ```
156
157
 
157
158
  ## Performance Visualizations Examples
@@ -171,7 +172,35 @@ The liquidation logic is based on **isolated margin mode**:
171
172
  - Long Position Liquidation Price => Entry Price - (Initial Margin - Maintenance Margin)
172
173
  - Short Position Liquidation Price => Entry Price + (Initial Margin - Maintenance Margin)
173
174
 
174
- When the price crosses the calculated liquidation level, the position is force-closed and the **entire margin is lost**.
175
+ When the price crosses the calculated liquidation level, the position is force-closed and the **entire initial margin is lost**. Nothing more is charged on top, so an isolated position can never lose more than the margin posted for it. Liquidations are marked in the trade log with `is_liquidation_order = True`.
176
+
177
+ ## Margin Check
178
+
179
+ An order that opens or increases a position needs `price × quantity / leverage` of free margin, where free margin is the cash balance minus the margin locked in open positions.
180
+
181
+ - If the account cannot afford the order when it is placed, `InsufficientMargin` is raised.
182
+ - If the account can no longer afford a resting order when it fills, the order is dropped and listed in `strategy.fetch_rejected_orders()`.
183
+ - Orders that reduce or close a position are always accepted.
184
+
185
+ ## Equity Curve
186
+
187
+ `strategy.run()` returns are based on **equity**: cash plus the unrealized PnL of open positions, marked at each bar's close. Drawdown and Sharpe therefore include losses on positions that are still open.
188
+
189
+ ```python
190
+ returns = strategy.run() # mark-to-market (default)
191
+ returns = strategy.run(mark_to_market=False) # realized only: moves when trades close
192
+
193
+ strategy.equity_curve # cash + unrealized PnL per bar
194
+ strategy.realized_balances # cash per bar
195
+ ```
196
+
197
+ ## Funding Rate
198
+
199
+ Add a `funding_rate` column to a symbol's DataFrame to simulate funding. A non-zero value on a bar means funding is settled at that bar's open, on the position held into it:
200
+
201
+ payment = -position quantity × open price × funding rate
202
+
203
+ Longs pay and shorts receive when the rate is positive. Bars with `0` or `NaN` settle nothing. Payments change the cash balance and are listed in `strategy.fetch_funding()`.
175
204
 
176
205
  ## Supported Order Types
177
206
  Supports four order types: LIMIT, MARKET, STOP LIMIT, and STOP MARKET. Each behaves according to standard trading conventions.
@@ -1,25 +1,27 @@
1
1
  # Overfitting (Futures Backtesting)
2
2
 
3
+ [![Tests](https://github.com/dohyunkjuly/overfitting/actions/workflows/tests.yml/badge.svg)](https://github.com/dohyunkjuly/overfitting/actions/workflows/tests.yml)
4
+
3
5
  Overfitting simulates a realistic crypto futures trading environment including
4
6
  - **Liquidation**, **Margin**, **Leverage** for stress testing
5
7
  - **Multiple Currency** Trading (e.g., backtesting BTC PERP & ETH PERP at the same time)
6
8
  - Four Different Order Types: LIMIT, MARKET, STOP_LIMIT, STOP_MARKET
7
9
  - Slippage/Commission Setting
8
10
 
9
- ![Backtest Viewer](https://raw.githubusercontent.com/dohyunkjuly/overfitting/main/documents/viewer.gif)
10
-
11
11
  ## Installation
12
12
  $ pip install overfitting
13
13
 
14
14
  ## Usage
15
+ Run from the repository root; the example reads the sample data in `examples/data/`.
16
+
15
17
  ```python
16
18
  import pandas as pd
17
- from overfitting import Strategy, BacktestViewer
19
+ from overfitting import Strategy
18
20
  from overfitting.indicators import SMA
19
21
 
20
22
  def load_data():
21
- df = pd.read_csv('./data/BTCUSDT.csv')
22
- benchamrk_df = pd.read_csv('./data/BTCUSDT.csv') # BTC buy and Hold
23
+ df = pd.read_csv('examples/data/BTCUSDT.csv')
24
+ benchamrk_df = pd.read_csv('examples/data/BTCUSDT.csv') # BTC buy and Hold
23
25
  df['timestamp'] = pd.to_datetime(df['timestamp'], unit='ms')
24
26
  df.set_index('timestamp', inplace=True)
25
27
 
@@ -27,14 +29,14 @@ def load_data():
27
29
  df = df.loc[start_time:]
28
30
 
29
31
  return df, benchamrk_df
30
-
32
+
31
33
  class MyStrategy(Strategy):
32
34
  def init(self):
33
35
  self.asset = 'BTC'
34
36
  self.set_leverage(self.asset, 1)
35
37
 
36
- self.sma_short = SMA(self, self.asset, source="close", window=20)
37
- self.sma_long = SMA(self, self.asset, source="close", window=50)
38
+ self.sma_short = self.indicator(SMA, self.asset, window=20)
39
+ self.sma_long = self.indicator(SMA, self.asset, window=50)
38
40
 
39
41
  def next(self, i):
40
42
  if i == 0:
@@ -74,9 +76,6 @@ strategy = MyStrategy(
74
76
  )
75
77
  returns = strategy.run()
76
78
  strategy.plot(returns)
77
-
78
- # Show Backtest Viewer UI
79
- # BacktestViewer(strategy).show()
80
79
  ```
81
80
 
82
81
  Results
@@ -88,14 +87,14 @@ Start Date 2023-01-01 00:00:00
88
87
  End Date 2024-08-29 00:00:00
89
88
  Initial Balance 100,000.00000000
90
89
  Final Balance 205,328.91120000
91
- CAGR 0.52684228
90
+ CAGR 0.54238181
92
91
  Cumulative Return 2.05328911
93
- Sharpe Ratio 1.24678659
94
- Sortino Ratio 3.54979579
95
- Max Drawdown -0.26332695
96
- Daily Value At Risk -0.04147282
97
- Skew 0.44515551
98
- Kurtosis 2.66444346
92
+ Sharpe Ratio 1.47036287
93
+ Sortino Ratio 2.79869052
94
+ Max Drawdown -0.26533797
95
+ Daily Value At Risk -0.03329469
96
+ Skew 0.72604283
97
+ Kurtosis 2.82598628
99
98
  Total Trades 182.00000000
100
99
  Winning Trades 69.00000000
101
100
  Losing Trades 113.00000000
@@ -107,16 +106,16 @@ Avg Return (%) 0.38834383
107
106
  Avg Profit (%) 3.54140613
108
107
  Avg Loss (%) -1.53697740
109
108
  Net drawdown in % Peak date Valley date Recovery date Duration
110
- 0 26.332695 2024-03-13 2024-06-30 NaT NaN
111
- 1 19.678014 2023-03-20 2023-09-07 2023-10-26 159
112
- 2 6.297244 2023-12-07 2024-01-24 2024-02-14 50
113
- 3 5.585429 2023-01-22 2023-02-14 2023-02-17 20
114
- 4 3.898568 2023-02-17 2023-03-11 2023-03-15 19
115
- 5 3.336877 2023-11-12 2023-11-18 2023-12-07 19
116
- 6 2.699556 2024-02-20 2024-02-26 2024-03-01 9
117
- 7 0.767196 2024-03-01 2024-03-03 2024-03-06 4
118
- 8 0.324161 2023-01-03 2023-01-07 2023-01-18 12
119
- 9 0.019817 2023-11-03 2023-11-04 2023-11-07 3
109
+ 0 26.533797 2024-03-13 2024-06-28 NaT NaN
110
+ 1 20.996185 2023-03-17 2023-09-12 2023-10-23 157
111
+ 2 7.051091 2023-12-05 2024-01-22 2024-02-09 49
112
+ 3 5.980692 2023-01-21 2023-02-13 2023-02-15 18
113
+ 4 5.578214 2023-02-15 2023-03-07 2023-03-12 18
114
+ 5 5.550106 2024-03-04 2024-03-06 2024-03-11 6
115
+ 6 4.538401 2023-11-10 2023-11-16 2023-12-04 17
116
+ 7 2.530832 2023-11-01 2023-11-03 2023-11-09 7
117
+ 8 2.162228 2024-02-18 2024-02-23 2024-02-27 7
118
+ 9 1.603446 2024-02-28 2024-02-29 2024-03-04 4
120
119
  ```
121
120
 
122
121
  ## Performance Visualizations Examples
@@ -136,7 +135,35 @@ The liquidation logic is based on **isolated margin mode**:
136
135
  - Long Position Liquidation Price => Entry Price - (Initial Margin - Maintenance Margin)
137
136
  - Short Position Liquidation Price => Entry Price + (Initial Margin - Maintenance Margin)
138
137
 
139
- When the price crosses the calculated liquidation level, the position is force-closed and the **entire margin is lost**.
138
+ When the price crosses the calculated liquidation level, the position is force-closed and the **entire initial margin is lost**. Nothing more is charged on top, so an isolated position can never lose more than the margin posted for it. Liquidations are marked in the trade log with `is_liquidation_order = True`.
139
+
140
+ ## Margin Check
141
+
142
+ An order that opens or increases a position needs `price × quantity / leverage` of free margin, where free margin is the cash balance minus the margin locked in open positions.
143
+
144
+ - If the account cannot afford the order when it is placed, `InsufficientMargin` is raised.
145
+ - If the account can no longer afford a resting order when it fills, the order is dropped and listed in `strategy.fetch_rejected_orders()`.
146
+ - Orders that reduce or close a position are always accepted.
147
+
148
+ ## Equity Curve
149
+
150
+ `strategy.run()` returns are based on **equity**: cash plus the unrealized PnL of open positions, marked at each bar's close. Drawdown and Sharpe therefore include losses on positions that are still open.
151
+
152
+ ```python
153
+ returns = strategy.run() # mark-to-market (default)
154
+ returns = strategy.run(mark_to_market=False) # realized only: moves when trades close
155
+
156
+ strategy.equity_curve # cash + unrealized PnL per bar
157
+ strategy.realized_balances # cash per bar
158
+ ```
159
+
160
+ ## Funding Rate
161
+
162
+ Add a `funding_rate` column to a symbol's DataFrame to simulate funding. A non-zero value on a bar means funding is settled at that bar's open, on the position held into it:
163
+
164
+ payment = -position quantity × open price × funding rate
165
+
166
+ Longs pay and shorts receive when the rate is positive. Bars with `0` or `NaN` settle nothing. Payments change the cash balance and are listed in `strategy.fetch_funding()`.
140
167
 
141
168
  ## Supported Order Types
142
169
  Supports four order types: LIMIT, MARKET, STOP LIMIT, and STOP MARKET. Each behaves according to standard trading conventions.
@@ -1,3 +1,2 @@
1
1
  from .strategy import Strategy
2
2
  from .slippage import Slippage
3
- from .analysis.viewer import BacktestViewer
@@ -6,7 +6,19 @@ from overfitting.order import Order
6
6
  from overfitting.position import Position
7
7
  from overfitting.slippage import SlippageModel
8
8
  from overfitting.types import OrderType
9
- from overfitting.errors import EmptyOrderParameters, InvalidOrderParameters, LiquidationError, StopOrderRejected
9
+ import warnings
10
+ from overfitting.errors import (
11
+ EmptyOrderParameters,
12
+ InsufficientMargin,
13
+ InvalidOrderParameters,
14
+ LiquidationError,
15
+ StopOrderRejected,
16
+ )
17
+
18
+ # Column in the price data that holds the funding rate, if any.
19
+ FUNDING_COLUMN = "funding_rate"
20
+ # Relative slack on the margin check, so float rounding never rejects an all-in order.
21
+ MARGIN_TOLERANCE = 1e-9
10
22
 
11
23
  class Broker:
12
24
  def __init__(self,
@@ -18,8 +30,8 @@ class Broker:
18
30
  slippage_model:SlippageModel | None):
19
31
 
20
32
  self.data = data
21
- self.initial_captial = cash
22
- self.cash = self.initial_captial
33
+ self.initial_capital = cash
34
+ self.cash = self.initial_capital
23
35
  self.commission_rate = commission_rate
24
36
  self.maint_margin_rate = maint_margin_rate
25
37
  self.maint_amount = maint_amount
@@ -33,11 +45,23 @@ class Broker:
33
45
  self.position: Dict[str, Position] = {}
34
46
 
35
47
  self.trades = []
48
+ self.funding_payments = []
49
+ self.rejected_orders = []
36
50
  self._i = 0
37
51
 
52
+ @property
53
+ def initial_captial(self):
54
+ """Deprecated misspelling of `initial_capital`."""
55
+ warnings.warn(
56
+ "Broker.initial_captial is deprecated, use Broker.initial_capital",
57
+ DeprecationWarning,
58
+ stacklevel=2,
59
+ )
60
+ return self.initial_capital
61
+
38
62
  def __repr__(self):
39
63
  return (f"Broker("
40
- f"initial_capital={self.initial_captial}, "
64
+ f"initial_capital={self.initial_capital}, "
41
65
  f"cash={self.cash}, "
42
66
  f"commission_rate={self.commission_rate}, "
43
67
  f"maint_margin_rate={self.maint_margin_rate}, "
@@ -70,7 +94,7 @@ class Broker:
70
94
  qty: float,
71
95
  price: float,
72
96
  *,
73
- type: str= OrderType.LIMIT,
97
+ type: str = "LIMIT",
74
98
  stop_price: float= None,
75
99
  label: str=None) -> Order:
76
100
  """
@@ -92,12 +116,10 @@ class Broker:
92
116
  if symbol not in self.open_orders:
93
117
  self.open_orders[symbol] = {}
94
118
 
95
- if type.upper() == "LIMIT":
96
- type = OrderType.LIMIT
97
- elif type.upper() == "MARKET":
98
- type = OrderType.MARKET
99
- elif type.upper() == 'STOP':
100
- type = OrderType.STOP
119
+ if isinstance(type, OrderType):
120
+ pass
121
+ elif isinstance(type, str) and type.upper() in OrderType.__members__:
122
+ type = OrderType[type.upper()]
101
123
  else:
102
124
  raise InvalidOrderParameters(f"Invalid Order Type - {type}")
103
125
 
@@ -118,6 +140,15 @@ class Broker:
118
140
  f"STOP order rejected: stop price {order.stop_price} would trigger immediately at current price {open}."
119
141
  )
120
142
 
143
+ # Reject orders the account cannot afford at the price we expect to pay.
144
+ if type == OrderType.MARKET:
145
+ expected_price = self._open(symbol, self._i)
146
+ elif price is not None:
147
+ expected_price = price
148
+ else:
149
+ expected_price = stop_price
150
+ self._check_margin(symbol, order, expected_price)
151
+
121
152
  # Put new order in the open_orders list if not rejected
122
153
  self.open_orders[symbol][order.id] = order
123
154
  return order
@@ -166,6 +197,83 @@ class Broker:
166
197
  raise LiquidationError(
167
198
  f"Cannot change leverage for {symbol}. Position would be liquidated at price {lp}.")
168
199
 
200
+ def available_margin(self) -> float:
201
+ """Cash that is not locked as margin in open positions."""
202
+ return self.cash - sum(p.margin for p in self.position.values())
203
+
204
+ def required_margin(self, symbol: str, qty, price: float) -> float:
205
+ """
206
+ Extra margin needed to trade `qty` of `symbol` at `price`.
207
+ Orders that only reduce a position need none.
208
+ """
209
+ position = self.get_position(symbol)
210
+ qty = Decimal(str(qty))
211
+ new_qty = position.qty + qty
212
+
213
+ if abs(new_qty) <= abs(position.qty):
214
+ return 0.0 # reducing or closing
215
+
216
+ if position.qty == 0 or position.qty * qty > 0:
217
+ # Opening or adding: margin for the added size.
218
+ return float(abs(qty)) * price / position.leverage
219
+
220
+ # Flipping sides: the old margin is released, the new side needs its own.
221
+ new_margin = float(abs(new_qty)) * price / position.leverage
222
+ return max(0.0, new_margin - position.margin)
223
+
224
+ def _check_margin(self, symbol: str, order: Order, price: float) -> None:
225
+ required = self.required_margin(symbol, order.qty, price)
226
+ if required <= 0:
227
+ return # reducing or closing is always allowed
228
+ available = self.available_margin()
229
+ if required > available + MARGIN_TOLERANCE * max(1.0, abs(available)):
230
+ raise InsufficientMargin(
231
+ f"Order for {float(order.qty)} {symbol} needs {required:.2f} margin "
232
+ f"but only {available:.2f} is available."
233
+ )
234
+
235
+ def unrealized_pnl(self, i: Optional[int] = None) -> float:
236
+ """Unrealized PnL of all open positions, marked at the close of bar `i`."""
237
+ if i is None:
238
+ i = min(self._i, len(self.data) - 1)
239
+ return sum(
240
+ p.unrealized_pnl(self._close(s, i))
241
+ for s, p in self.position.items() if p.qty != 0
242
+ )
243
+
244
+ def equity(self, i: Optional[int] = None) -> float:
245
+ """Cash plus unrealized PnL, marked at the close of bar `i`."""
246
+ return self.cash + self.unrealized_pnl(i)
247
+
248
+ def _apply_funding(self) -> None:
249
+ """
250
+ Settle funding for positions held into this bar.
251
+
252
+ A non-zero value in the `funding_rate` column means funding is paid at
253
+ the open of that bar. Longs pay shorts when the rate is positive.
254
+ """
255
+ for symbol, position in self.position.items():
256
+ if position.qty == 0:
257
+ continue
258
+ rates = getattr(self._d(symbol), FUNDING_COLUMN, None)
259
+ if rates is None:
260
+ continue
261
+ rate = rates[self._i]
262
+ if rate is None or rate != rate or rate == 0: # rate != rate catches NaN
263
+ continue
264
+
265
+ price = self._open(symbol, self._i)
266
+ amount = -float(position.qty) * price * float(rate)
267
+ self.cash += amount
268
+ self.funding_payments.append({
269
+ "time": pd.to_datetime(self.data.index[self._i]),
270
+ "symbol": symbol,
271
+ "qty": float(position.qty),
272
+ "price": price,
273
+ "funding_rate": float(rate),
274
+ "amount": amount,
275
+ })
276
+
169
277
  def _slippage(self, symbol: str, order: Order):
170
278
  if self.slippage_model:
171
279
  bars = self._bars(symbol, self._i)
@@ -183,8 +291,21 @@ class Broker:
183
291
 
184
292
  position = self.position[symbol]
185
293
 
186
- notional = float(abs(order.qty)) * order.executed_price
187
- commission = notional * self.commission_rate
294
+ if liquidation:
295
+ # The exchange keeps the margin; nothing more is charged on top.
296
+ commission = 0.0
297
+ else:
298
+ # The account may have changed since the order was placed.
299
+ # Checked at the pre-slippage price, the same basis as at placement,
300
+ # so slippage alone never drops an all-in order.
301
+ try:
302
+ self._check_margin(symbol, order, order.theoretical_price)
303
+ except InsufficientMargin as e:
304
+ self.open_orders.get(symbol, {}).pop(order.id, None)
305
+ self.rejected_orders.append({**order.to_dict(), "reject_reason": str(e)})
306
+ return
307
+ notional = float(abs(order.qty)) * order.executed_price
308
+ commission = notional * self.commission_rate
188
309
  pnl = position.process_trade(order, liquidation)
189
310
  executed_time = pd.to_datetime(self.data.index[self._i])
190
311
 
@@ -193,7 +314,7 @@ class Broker:
193
314
  order.executed_at = executed_time
194
315
  order.commission = commission
195
316
  order.realized_pnl = pnl - commission
196
- self.is_liquidation_order = True if liquidation else False
317
+ order.is_liquidation_order = bool(liquidation)
197
318
 
198
319
  # Update trades and balance
199
320
  self.trades.append(order.to_dict())
@@ -213,8 +334,11 @@ class Broker:
213
334
  # Create MARKET Order for liquidation & Execute
214
335
  order = self.order(p.symbol, -p.qty, lp, type="MARKET")
215
336
  self._execute_trade(p.symbol, order, lp, True)
216
-
217
- # 2) Execute open orders (iterate snapshots to avoid mutation issues)
337
+
338
+ # Funding is settled at the open, before this bar's orders fill.
339
+ self._apply_funding()
340
+
341
+ # Execute open orders (iterate snapshots to avoid mutation issues)
218
342
  for symbol, by_id in list(self.open_orders.items()):
219
343
  open, high, low, _ = self._bars(symbol, self._i)
220
344
 
@@ -0,0 +1,89 @@
1
+ import pandas as pd
2
+ import numpy as np
3
+ from types import SimpleNamespace
4
+ from pandas.api.types import is_datetime64_any_dtype, is_integer_dtype, is_float_dtype
5
+ from overfitting.errors import InitializationError
6
+
7
+ REQUIRED_OHLC = ("open", "high", "low", "close")
8
+
9
+ class Data(dict):
10
+ """
11
+ data = Data({"BTCUSDT": df_btc, "ETHUSDT": df_eth})
12
+ data["BTCUSDT"].close[i] # close price of BTC at step i
13
+ data.index[i] # the timestamp at step i
14
+ data.symbols # ("BTCUSDT", "ETHUSDT")
15
+ len(data) # how many bars there are
16
+ """
17
+ def __init__(self, frames: dict[str, pd.DataFrame]):
18
+ if not isinstance(frames, dict) or not frames:
19
+ raise InitializationError("Pass a non-empty dict mapping symbol -> DataFrame.")
20
+
21
+ bars = {symbol: self._bars_from_frame(df, symbol) for symbol, df in frames.items()}
22
+ self._check_aligned_timelines(bars)
23
+
24
+ super().__init__(bars)
25
+ self.symbols = tuple(bars)
26
+ self.index = next(iter(bars.values())).timestamp
27
+
28
+ def __len__(self) -> int:
29
+ return len(self.index)
30
+
31
+
32
+ def _bars_from_frame(self, df: pd.DataFrame, symbol: str) -> SimpleNamespace:
33
+ """Turn one symbol's DataFrame into a namespace of numpy arrays."""
34
+ if not isinstance(df, pd.DataFrame) or df.empty:
35
+ raise InitializationError(f"'{symbol}': expected a non-empty DataFrame.")
36
+
37
+ missing = [c for c in REQUIRED_OHLC if c not in df.columns]
38
+ if missing:
39
+ raise InitializationError(
40
+ f"'{symbol}': missing required columns {missing}. Got: {list(df.columns)}"
41
+ )
42
+
43
+ timestamps = self._pull_timestamps(df, symbol)
44
+
45
+ arrays = {col: df[col].to_numpy() for col in df.columns}
46
+ arrays["timestamp"] = timestamps
47
+ return SimpleNamespace(**arrays)
48
+
49
+
50
+ def _pull_timestamps(self, df: pd.DataFrame, symbol: str) -> np.ndarray:
51
+ """Find the timestamp series — either a column or the DatetimeIndex — and normalise it."""
52
+ if "timestamp" in df.columns:
53
+ ts = df["timestamp"]
54
+ elif isinstance(df.index, pd.DatetimeIndex) or df.index.name == "timestamp":
55
+ ts = pd.Series(df.index, name="timestamp")
56
+ else:
57
+ raise InitializationError(
58
+ f"'{symbol}': add a 'timestamp' column or use a DatetimeIndex."
59
+ )
60
+ return self._to_datetime_ns(ts).to_numpy()
61
+
62
+
63
+ def _to_datetime_ns(self, ts: pd.Series) -> pd.Series:
64
+ """Coerce whatever the user gave us into tz-naive datetimes."""
65
+ if is_datetime64_any_dtype(ts):
66
+ dt = pd.to_datetime(ts)
67
+ if dt.dt.tz is not None:
68
+ # Keep the wall-clock time, drop the timezone.
69
+ dt = dt.dt.tz_localize(None)
70
+ return dt
71
+
72
+ if is_integer_dtype(ts) or is_float_dtype(ts):
73
+ # Big numbers look like milliseconds; smaller ones look like seconds.
74
+ unit = "ms" if pd.Series(ts).max() > 1e12 else "s"
75
+ return pd.to_datetime(ts, unit=unit)
76
+
77
+ return pd.to_datetime(ts, errors="raise")
78
+
79
+
80
+ def _check_aligned_timelines(self, bars: dict[str, SimpleNamespace]) -> None:
81
+ """All symbols must share the same timeline — for now."""
82
+ # TODO: auto-fill / reindex so symbols with different timelines can co-exist.
83
+ iterator = iter(bars.items())
84
+ _, first = next(iterator)
85
+ for symbol, b in iterator:
86
+ if len(b.timestamp) != len(first.timestamp) or not np.array_equal(b.timestamp, first.timestamp):
87
+ raise InitializationError(
88
+ f"'{symbol}' timeline doesn't match the other symbols."
89
+ )
@@ -24,4 +24,7 @@ class LiquidationError(CustomError):
24
24
  pass
25
25
 
26
26
  class StopOrderRejected(CustomError):
27
+ pass
28
+
29
+ class InsufficientMargin(CustomError):
27
30
  pass