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.
- {overfitting-0.4.2 → overfitting-0.5.0}/PKG-INFO +57 -22
- {overfitting-0.4.2 → overfitting-0.5.0}/README.md +52 -20
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/broker.py +140 -16
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/data.py +5 -5
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/errors.py +3 -0
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/position.py +13 -2
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/strategy.py +48 -8
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting.egg-info/PKG-INFO +57 -22
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting.egg-info/SOURCES.txt +10 -1
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting.egg-info/requires.txt +4 -0
- {overfitting-0.4.2 → overfitting-0.5.0}/pyproject.toml +10 -3
- overfitting-0.5.0/tests/test_accounting.py +198 -0
- overfitting-0.5.0/tests/test_data.py +97 -0
- overfitting-0.5.0/tests/test_funding.py +146 -0
- overfitting-0.5.0/tests/test_liquidation.py +276 -0
- overfitting-0.5.0/tests/test_margin.py +205 -0
- overfitting-0.5.0/tests/test_orders.py +333 -0
- overfitting-0.5.0/tests/test_position.py +179 -0
- overfitting-0.5.0/tests/test_readme.py +39 -0
- overfitting-0.5.0/tests/test_strategy.py +281 -0
- {overfitting-0.4.2 → overfitting-0.5.0}/LICENSE +0 -0
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/__init__.py +0 -0
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/analysis/__init__.py +0 -0
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/analysis/graph.py +0 -0
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/analysis/report.py +0 -0
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/indicators.py +0 -0
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/order.py +0 -0
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/slippage.py +0 -0
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting/types.py +0 -0
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting.egg-info/dependency_links.txt +0 -0
- {overfitting-0.4.2 → overfitting-0.5.0}/overfitting.egg-info/top_level.txt +0 -0
- {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.
|
|
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.
|
|
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
|
+
[](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('
|
|
54
|
-
benchamrk_df = pd.read_csv('
|
|
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.
|
|
127
|
+
CAGR 0.54238181
|
|
121
128
|
Cumulative Return 2.05328911
|
|
122
|
-
Sharpe Ratio 1.
|
|
123
|
-
Sortino Ratio
|
|
124
|
-
Max Drawdown -0.
|
|
125
|
-
Daily Value At Risk -0.
|
|
126
|
-
Skew 0.
|
|
127
|
-
Kurtosis 2.
|
|
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.
|
|
140
|
-
1
|
|
141
|
-
2
|
|
142
|
-
3 5.
|
|
143
|
-
4
|
|
144
|
-
5
|
|
145
|
-
6
|
|
146
|
-
7
|
|
147
|
-
8
|
|
148
|
-
9
|
|
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
|
+
[](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('
|
|
20
|
-
benchamrk_df = pd.read_csv('
|
|
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.
|
|
90
|
+
CAGR 0.54238181
|
|
87
91
|
Cumulative Return 2.05328911
|
|
88
|
-
Sharpe Ratio 1.
|
|
89
|
-
Sortino Ratio
|
|
90
|
-
Max Drawdown -0.
|
|
91
|
-
Daily Value At Risk -0.
|
|
92
|
-
Skew 0.
|
|
93
|
-
Kurtosis 2.
|
|
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.
|
|
106
|
-
1
|
|
107
|
-
2
|
|
108
|
-
3 5.
|
|
109
|
-
4
|
|
110
|
-
5
|
|
111
|
-
6
|
|
112
|
-
7
|
|
113
|
-
8
|
|
114
|
-
9
|
|
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
|
-
|
|
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.
|
|
22
|
-
self.cash = self.
|
|
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.
|
|
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=
|
|
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
|
|
96
|
-
|
|
97
|
-
elif type.upper()
|
|
98
|
-
type = OrderType.
|
|
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
|
-
|
|
187
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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.
|
|
@@ -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
|
-
|
|
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:
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|