overfitting 0.4.2__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 (32) hide show
  1. {overfitting-0.4.2 → overfitting-0.5.0}/PKG-INFO +57 -22
  2. {overfitting-0.4.2 → overfitting-0.5.0}/README.md +52 -20
  3. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/broker.py +140 -16
  4. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/data.py +5 -5
  5. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/errors.py +3 -0
  6. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/position.py +13 -2
  7. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/strategy.py +48 -8
  8. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting.egg-info/PKG-INFO +57 -22
  9. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting.egg-info/SOURCES.txt +10 -1
  10. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting.egg-info/requires.txt +4 -0
  11. {overfitting-0.4.2 → overfitting-0.5.0}/pyproject.toml +10 -3
  12. overfitting-0.5.0/tests/test_accounting.py +198 -0
  13. overfitting-0.5.0/tests/test_data.py +97 -0
  14. overfitting-0.5.0/tests/test_funding.py +146 -0
  15. overfitting-0.5.0/tests/test_liquidation.py +276 -0
  16. overfitting-0.5.0/tests/test_margin.py +205 -0
  17. overfitting-0.5.0/tests/test_orders.py +333 -0
  18. overfitting-0.5.0/tests/test_position.py +179 -0
  19. overfitting-0.5.0/tests/test_readme.py +39 -0
  20. overfitting-0.5.0/tests/test_strategy.py +281 -0
  21. {overfitting-0.4.2 → overfitting-0.5.0}/LICENSE +0 -0
  22. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/__init__.py +0 -0
  23. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/analysis/__init__.py +0 -0
  24. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/analysis/graph.py +0 -0
  25. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/analysis/report.py +0 -0
  26. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/indicators.py +0 -0
  27. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/order.py +0 -0
  28. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/slippage.py +0 -0
  29. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/types.py +0 -0
  30. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting.egg-info/dependency_links.txt +0 -0
  31. {overfitting-0.4.2 → overfitting-0.5.0}/overfitting.egg-info/top_level.txt +0 -0
  32. {overfitting-0.4.2 → 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.2
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
@@ -28,12 +28,17 @@ Provides-Extra: examples
28
28
  Requires-Dist: notebook; extra == "examples"
29
29
  Requires-Dist: ipykernel; extra == "examples"
30
30
  Requires-Dist: ipython; extra == "examples"
31
+ Provides-Extra: test
32
+ Requires-Dist: pytest>=7; extra == "test"
31
33
  Provides-Extra: dev
32
34
  Requires-Dist: twine>=4.0.2; extra == "dev"
35
+ Requires-Dist: pytest>=7; extra == "dev"
33
36
  Dynamic: license-file
34
37
 
35
38
  # Overfitting (Futures Backtesting)
36
39
 
40
+ [![Tests](https://github.com/dohyunkjuly/overfitting/actions/workflows/tests.yml/badge.svg)](https://github.com/dohyunkjuly/overfitting/actions/workflows/tests.yml)
41
+
37
42
  Overfitting simulates a realistic crypto futures trading environment including
38
43
  - **Liquidation**, **Margin**, **Leverage** for stress testing
39
44
  - **Multiple Currency** Trading (e.g., backtesting BTC PERP & ETH PERP at the same time)
@@ -44,14 +49,16 @@ Overfitting simulates a realistic crypto futures trading environment including
44
49
  $ pip install overfitting
45
50
 
46
51
  ## Usage
52
+ Run from the repository root; the example reads the sample data in `examples/data/`.
53
+
47
54
  ```python
48
55
  import pandas as pd
49
56
  from overfitting import Strategy
50
57
  from overfitting.indicators import SMA
51
58
 
52
59
  def load_data():
53
- df = pd.read_csv('./data/BTCUSDT.csv')
54
- 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
55
62
  df['timestamp'] = pd.to_datetime(df['timestamp'], unit='ms')
56
63
  df.set_index('timestamp', inplace=True)
57
64
 
@@ -117,14 +124,14 @@ Start Date 2023-01-01 00:00:00
117
124
  End Date 2024-08-29 00:00:00
118
125
  Initial Balance 100,000.00000000
119
126
  Final Balance 205,328.91120000
120
- CAGR 0.52684228
127
+ CAGR 0.54238181
121
128
  Cumulative Return 2.05328911
122
- Sharpe Ratio 1.24678659
123
- Sortino Ratio 3.54979579
124
- Max Drawdown -0.26332695
125
- Daily Value At Risk -0.04147282
126
- Skew 0.44515551
127
- 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
128
135
  Total Trades 182.00000000
129
136
  Winning Trades 69.00000000
130
137
  Losing Trades 113.00000000
@@ -136,16 +143,16 @@ Avg Return (%) 0.38834383
136
143
  Avg Profit (%) 3.54140613
137
144
  Avg Loss (%) -1.53697740
138
145
  Net drawdown in % Peak date Valley date Recovery date Duration
139
- 0 26.332695 2024-03-13 2024-06-30 NaT NaN
140
- 1 19.678014 2023-03-20 2023-09-07 2023-10-26 159
141
- 2 6.297244 2023-12-07 2024-01-24 2024-02-14 50
142
- 3 5.585429 2023-01-22 2023-02-14 2023-02-17 20
143
- 4 3.898568 2023-02-17 2023-03-11 2023-03-15 19
144
- 5 3.336877 2023-11-12 2023-11-18 2023-12-07 19
145
- 6 2.699556 2024-02-20 2024-02-26 2024-03-01 9
146
- 7 0.767196 2024-03-01 2024-03-03 2024-03-06 4
147
- 8 0.324161 2023-01-03 2023-01-07 2023-01-18 12
148
- 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
149
156
  ```
150
157
 
151
158
  ## Performance Visualizations Examples
@@ -165,7 +172,35 @@ The liquidation logic is based on **isolated margin mode**:
165
172
  - Long Position Liquidation Price => Entry Price - (Initial Margin - Maintenance Margin)
166
173
  - Short Position Liquidation Price => Entry Price + (Initial Margin - Maintenance Margin)
167
174
 
168
- 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()`.
169
204
 
170
205
  ## Supported Order Types
171
206
  Supports four order types: LIMIT, MARKET, STOP LIMIT, and STOP MARKET. Each behaves according to standard trading conventions.
@@ -1,5 +1,7 @@
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)
@@ -10,14 +12,16 @@ Overfitting simulates a realistic crypto futures trading environment including
10
12
  $ pip install overfitting
11
13
 
12
14
  ## Usage
15
+ Run from the repository root; the example reads the sample data in `examples/data/`.
16
+
13
17
  ```python
14
18
  import pandas as pd
15
19
  from overfitting import Strategy
16
20
  from overfitting.indicators import SMA
17
21
 
18
22
  def load_data():
19
- df = pd.read_csv('./data/BTCUSDT.csv')
20
- 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
21
25
  df['timestamp'] = pd.to_datetime(df['timestamp'], unit='ms')
22
26
  df.set_index('timestamp', inplace=True)
23
27
 
@@ -83,14 +87,14 @@ Start Date 2023-01-01 00:00:00
83
87
  End Date 2024-08-29 00:00:00
84
88
  Initial Balance 100,000.00000000
85
89
  Final Balance 205,328.91120000
86
- CAGR 0.52684228
90
+ CAGR 0.54238181
87
91
  Cumulative Return 2.05328911
88
- Sharpe Ratio 1.24678659
89
- Sortino Ratio 3.54979579
90
- Max Drawdown -0.26332695
91
- Daily Value At Risk -0.04147282
92
- Skew 0.44515551
93
- 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
94
98
  Total Trades 182.00000000
95
99
  Winning Trades 69.00000000
96
100
  Losing Trades 113.00000000
@@ -102,16 +106,16 @@ Avg Return (%) 0.38834383
102
106
  Avg Profit (%) 3.54140613
103
107
  Avg Loss (%) -1.53697740
104
108
  Net drawdown in % Peak date Valley date Recovery date Duration
105
- 0 26.332695 2024-03-13 2024-06-30 NaT NaN
106
- 1 19.678014 2023-03-20 2023-09-07 2023-10-26 159
107
- 2 6.297244 2023-12-07 2024-01-24 2024-02-14 50
108
- 3 5.585429 2023-01-22 2023-02-14 2023-02-17 20
109
- 4 3.898568 2023-02-17 2023-03-11 2023-03-15 19
110
- 5 3.336877 2023-11-12 2023-11-18 2023-12-07 19
111
- 6 2.699556 2024-02-20 2024-02-26 2024-03-01 9
112
- 7 0.767196 2024-03-01 2024-03-03 2024-03-06 4
113
- 8 0.324161 2023-01-03 2023-01-07 2023-01-18 12
114
- 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
115
119
  ```
116
120
 
117
121
  ## Performance Visualizations Examples
@@ -131,7 +135,35 @@ The liquidation logic is based on **isolated margin mode**:
131
135
  - Long Position Liquidation Price => Entry Price - (Initial Margin - Maintenance Margin)
132
136
  - Short Position Liquidation Price => Entry Price + (Initial Margin - Maintenance Margin)
133
137
 
134
- 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()`.
135
167
 
136
168
  ## Supported Order Types
137
169
  Supports four order types: LIMIT, MARKET, STOP LIMIT, and STOP MARKET. Each behaves according to standard trading conventions.
@@ -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
 
@@ -61,13 +61,13 @@ class Data(dict):
61
61
 
62
62
 
63
63
  def _to_datetime_ns(self, ts: pd.Series) -> pd.Series:
64
- """Coerce whatever the user gave us into tz-naive datetime64[ns]."""
64
+ """Coerce whatever the user gave us into tz-naive datetimes."""
65
65
  if is_datetime64_any_dtype(ts):
66
66
  dt = pd.to_datetime(ts)
67
- try:
68
- return dt.tz_localize(None)
69
- except Exception:
70
- return dt
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
71
 
72
72
  if is_integer_dtype(ts) or is_float_dtype(ts):
73
73
  # Big numbers look like milliseconds; smaller ones look like seconds.
@@ -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
@@ -48,7 +48,9 @@ class Position:
48
48
  initial_margin = notional / self.leverage
49
49
  maint_margin = max(0.0, notional * self.maint_margin_rate - self.maint_amount)
50
50
 
51
- self.margin = initial_margin + maint_margin
51
+ # Isolated margin: the collateral locked for this position is the
52
+ # initial margin. It is also the most the position can lose.
53
+ self.margin = initial_margin
52
54
 
53
55
  # How far the price can move against us before we get liquidated.
54
56
  # Long: liquidates when price drops by `offset`.
@@ -77,6 +79,12 @@ class Position:
77
79
  self.leverage = leverage
78
80
  self._recalc_liquidation()
79
81
 
82
+ def unrealized_pnl(self, price: float) -> float:
83
+ """Profit or loss of the open position if it were closed at `price`."""
84
+ if self.qty == 0:
85
+ return 0.0
86
+ return (price - self.price) * float(self.qty)
87
+
80
88
  def process_trade(self, order: Order, liquidation: bool = False) -> float:
81
89
  """Apply an executed order. Returns realized PnL (commission excluded)."""
82
90
  if order.symbol != self.symbol:
@@ -84,7 +92,10 @@ class Position:
84
92
  if order.qty == 0:
85
93
  raise ValueError("Order quantity cannot be zero.")
86
94
 
87
- if liquidation: # Force liquidation
95
+ if liquidation:
96
+ # Forced close: the whole isolated margin is lost. The part of it
97
+ # still left at the liquidation price (the maintenance margin)
98
+ # is kept by the exchange.
88
99
  loss = -self.margin
89
100
  self._reset()
90
101
  return loss
@@ -35,13 +35,15 @@ class Strategy:
35
35
  maint_amount=maint_amount,
36
36
  slippage_model=slippage_model
37
37
  )
38
- self.balances = []
38
+ self.balances = [] # the curve returns are computed from
39
+ self.equity_curve = [] # cash + unrealized PnL at each bar's close
40
+ self.realized_balances = [] # cash only; moves when trades close
39
41
  self.returns= []
40
42
  self.init()
41
43
 
42
44
  def __repr__(self):
43
45
  return (f"Strategy("
44
- f"initial_capital={self.broker.initial_captial}, "
46
+ f"initial_capital={self.broker.initial_capital}, "
45
47
  f"commission_rate={self.broker.commission_rate}, "
46
48
  f"balances={self.balances}, "
47
49
  f"returns={self.returns})")
@@ -117,10 +119,22 @@ class Strategy:
117
119
 
118
120
  def get_balance(self) -> float:
119
121
  """
120
- Fetch the current balance
122
+ Fetch the current balance (realized cash, excluding open positions)
121
123
  """
122
124
  return self.broker.cash
123
125
 
126
+ def get_equity(self) -> float:
127
+ """
128
+ Fetch the current balance plus unrealized PnL of open positions
129
+ """
130
+ return self.broker.equity()
131
+
132
+ def get_available_margin(self) -> float:
133
+ """
134
+ Fetch the cash that is not locked as margin in open positions
135
+ """
136
+ return self.broker.available_margin()
137
+
124
138
  def get_open_orders(self, symbol: str) -> Dict[str, Order]:
125
139
  """
126
140
  Fetch the current open orders
@@ -198,27 +212,37 @@ class Strategy:
198
212
 
199
213
  return target_column[i]
200
214
 
201
- def run(self) -> pd.Series:
215
+ def run(self, mark_to_market: bool = True) -> pd.Series:
202
216
  """
203
217
  Executes the strategy over the dataset.
204
218
 
205
219
  It handles the iteration over each time period in the data. It calls the
206
220
  user-defined `next` method on each iteration to apply the strategy's logic.
207
221
  Additionally, it updates account balances, and calculates the returns.
208
-
222
+
223
+ Parameters
224
+ ----------
225
+ mark_to_market : bool
226
+ True (default): returns are based on equity, which is cash plus the
227
+ unrealized PnL of open positions at each bar's close.
228
+ False: returns are based on cash only, which moves when trades close.
229
+
209
230
  Returns:
210
231
  A pandas Series containing the returns, indexed by the corresponding timestamps.
211
232
  """
212
233
  t = pd.to_datetime(self.data.index)
213
- b = np.zeros(len(t))
234
+ equity = np.zeros(len(t))
235
+ realized = np.zeros(len(t))
214
236
  r = np.zeros(len(t))
237
+ b = equity if mark_to_market else realized
215
238
 
216
239
  for i in range(len(t)):
217
240
  self.next(i)
218
241
  self.broker.next()
219
242
 
220
243
  # Update Balance
221
- b[i] = self.broker.cash
244
+ realized[i] = self.broker.cash
245
+ equity[i] = self.broker.equity(i)
222
246
 
223
247
  if i > 0:
224
248
  # Updates the Returns
@@ -226,6 +250,8 @@ class Strategy:
226
250
  r[i] = (b[i] - pb) / pb
227
251
 
228
252
  self.balances = b.tolist()
253
+ self.equity_curve = equity.tolist()
254
+ self.realized_balances = realized.tolist()
229
255
  self.returns = r.tolist()
230
256
 
231
257
  return pd.Series(self.returns, index=t.tolist())
@@ -244,7 +270,7 @@ class Strategy:
244
270
  If None, plots will only be shown but not saved.
245
271
  """
246
272
  trades_list = self.broker.trades
247
- captial = self.broker.initial_captial
273
+ captial = self.broker.initial_capital
248
274
 
249
275
  p = Report(
250
276
  returns_series=returns,
@@ -265,6 +291,20 @@ class Strategy:
265
291
  """
266
292
  return pd.DataFrame(self.broker.trades)
267
293
 
294
+ def fetch_funding(self) -> pd.DataFrame:
295
+ """
296
+ Returns the funding payments as a pandas DataFrame, one row per payment.
297
+ Negative amounts were paid, positive amounts were received.
298
+ """
299
+ return pd.DataFrame(self.broker.funding_payments)
300
+
301
+ def fetch_rejected_orders(self) -> pd.DataFrame:
302
+ """
303
+ Returns orders that were dropped at fill time because the account
304
+ could no longer afford them.
305
+ """
306
+ return pd.DataFrame(self.broker.rejected_orders)
307
+
268
308
  def save_trades_to_csv(self, path='', filename="trade_history"):
269
309
  """
270
310
  Save the trade history to a CSV file.