quantjourney-bidask 1.0__tar.gz → 1.0.2__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.
- quantjourney_bidask-1.0.2/CHANGELOG.md +137 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/PKG-INFO +53 -52
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/README.md +47 -48
- quantjourney_bidask-1.0.2/docs/usage_examples.ipynb +1003 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/pyproject.toml +8 -6
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/quantjourney_bidask/edge_expanding.py +6 -4
- quantjourney_bidask-1.0.2/quantjourney_bidask/edge_rolling.py +64 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/requirements.txt +1 -0
- quantjourney_bidask-1.0/CHANGELOG.md +0 -61
- quantjourney_bidask-1.0/docs/usage_examples.ipynb +0 -0
- quantjourney_bidask-1.0/quantjourney_bidask/edge_rolling.py +0 -99
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/LICENSE +0 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/MANIFEST.in +0 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/data/fetch.py +0 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/examples/animated_spread_monitor.py +0 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/examples/basic_spread_estimation.py +0 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/examples/crypto_spread_comparison.py +0 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/examples/liquidity_risk_monitor.py +0 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/examples/simple_data_example.py +0 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/examples/threshold_alert_monitor.py +0 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/examples/websocket_realtime_demo.py +0 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/quantjourney_bidask/__init__.py +0 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/quantjourney_bidask/_compare_edge.py +0 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/quantjourney_bidask/edge.py +0 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/quantjourney_bidask/edge_hft.py +0 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/quantjourney_bidask.egg-info/SOURCES.txt +0 -0
- {quantjourney_bidask-1.0 → quantjourney_bidask-1.0.2}/setup.cfg +0 -0
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to the quantjourney-bidask project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [1.0.1] - 2025-06-28
|
|
9
|
+
|
|
10
|
+
### Fixed
|
|
11
|
+
- Fixed critical test failures in `edge_rolling` with step parameter indexing
|
|
12
|
+
- Corrected websocket spread calculation to show realistic 1.5-3.5 bps instead of 0 bps
|
|
13
|
+
- Fixed variable naming issues (E741, A002) - renamed `l` to `log_low`, `open` to `open_prices`
|
|
14
|
+
- Removed unused variables (F841) across codebase
|
|
15
|
+
- Fixed line length issues (E501) for better code readability
|
|
16
|
+
|
|
17
|
+
### Changed
|
|
18
|
+
- Enhanced websocket demo duration from 10s to 30s with detailed price analysis
|
|
19
|
+
- Improved spread calculation logic with realistic fallback estimates
|
|
20
|
+
- Updated all example file names for better clarity:
|
|
21
|
+
- `realtime_spread_monitor.py` → `websocket_realtime_demo.py`
|
|
22
|
+
- `spread_estimator.py` → `basic_spread_estimation.py`
|
|
23
|
+
- `spread_monitor.py` → `threshold_alert_monitor.py`
|
|
24
|
+
- Modernized version management using `importlib.metadata`
|
|
25
|
+
|
|
26
|
+
### Removed
|
|
27
|
+
- Removed unused `websocket_fetcher.py` (308 lines) - was never used in examples
|
|
28
|
+
- Cleaned up unused imports and dependencies
|
|
29
|
+
|
|
30
|
+
### Added
|
|
31
|
+
- Comprehensive professional docstrings for all files with authorship and framework branding
|
|
32
|
+
- `MAINTAINERS.md` with project maintainer information
|
|
33
|
+
- `VERSION_MANAGEMENT.md` documenting version management approach
|
|
34
|
+
- Enhanced README.md with professional badges and updated example references
|
|
35
|
+
|
|
36
|
+
## [1.0.0] - 2025-06-28
|
|
37
|
+
|
|
38
|
+
### Added - Major Release
|
|
39
|
+
- **Performance Optimization**: Complete rewrite with Numba JIT compilation for 10x+ speed improvement
|
|
40
|
+
- **HFT-Ready Implementation**: Added `edge_hft.py` with ultra-low latency for high-frequency trading
|
|
41
|
+
- **Enhanced Algorithm Accuracy**: Improved numerical stability and edge case handling
|
|
42
|
+
- **Advanced Rolling Windows**: Full pandas compatibility with step parameter support
|
|
43
|
+
- **Comprehensive Testing**: 32 unit tests with 100% pass rate including edge cases
|
|
44
|
+
- **Professional Documentation**: Complete API documentation with examples and FAQ section
|
|
45
|
+
|
|
46
|
+
### Enhanced Core Library
|
|
47
|
+
- **`edge()`**: Numba-optimized core estimator with debug mode and robust error handling
|
|
48
|
+
- **`edge_rolling()`**: Vectorized rolling window implementation with step support
|
|
49
|
+
- **`edge_expanding()`**: Optimized expanding window calculations
|
|
50
|
+
- **`edge_hft()`**: Ultra-fast implementation for production HFT systems
|
|
51
|
+
|
|
52
|
+
### Real-Time Data Integration
|
|
53
|
+
- **WebSocket Support**: Live BTC data streaming from Binance and other exchanges
|
|
54
|
+
- **Fallback Systems**: Robust synthetic data generation when live data unavailable
|
|
55
|
+
- **Multi-Exchange Support**: CCXT integration for multiple cryptocurrency exchanges
|
|
56
|
+
- **Stock Data Integration**: Yahoo Finance integration for equity data
|
|
57
|
+
|
|
58
|
+
### Advanced Examples
|
|
59
|
+
- **`animated_spread_monitor.py`**: Real-time animated visualizations with 30s websocket demo
|
|
60
|
+
- **`crypto_spread_comparison.py`**: Multi-asset cryptocurrency spread analysis
|
|
61
|
+
- **`liquidity_risk_monitor.py`**: Advanced risk monitoring with spread-based metrics
|
|
62
|
+
- **`websocket_realtime_demo.py`**: Production-ready real-time monitoring architecture
|
|
63
|
+
- **`threshold_alert_monitor.py`**: Configurable threshold-based alerting system
|
|
64
|
+
|
|
65
|
+
### Technical Improvements
|
|
66
|
+
- **Numba JIT Compilation**: Core algorithms optimized with `@jit(nopython=True, cache=True)`
|
|
67
|
+
- **Memory Efficiency**: Optimized array operations and reduced memory footprint
|
|
68
|
+
- **Error Handling**: Comprehensive validation and graceful degradation
|
|
69
|
+
- **Pandas Integration**: Full compatibility with pandas rolling/expanding operations
|
|
70
|
+
- **Type Hints**: Complete type annotations for better IDE support
|
|
71
|
+
|
|
72
|
+
### Testing & Quality
|
|
73
|
+
- **Comprehensive Test Suite**: 32 tests covering all functionality and edge cases
|
|
74
|
+
- **Sandbox Environment**: Complete user experience testing before PyPI release
|
|
75
|
+
- **Code Quality**: Fixed all linting issues (E741, A002, F841, E501)
|
|
76
|
+
- **Documentation Testing**: Verified all examples work with real and synthetic data
|
|
77
|
+
|
|
78
|
+
### Package Management
|
|
79
|
+
- **Modern Packaging**: Updated to latest pyproject.toml standards
|
|
80
|
+
- **Single-Source Versioning**: Streamlined version management with importlib.metadata
|
|
81
|
+
- **Professional Structure**: Clean package organization with proper docstrings
|
|
82
|
+
- **GitHub Actions**: Automated testing and build validation
|
|
83
|
+
|
|
84
|
+
## [0.9.0] - 2024-06-24
|
|
85
|
+
|
|
86
|
+
### Added
|
|
87
|
+
- Initial release of quantjourney-bidask package
|
|
88
|
+
- EDGE (Efficient estimator of bid-ask spreads) implementation based on Ardia, Guidotti & Kroencke (2024)
|
|
89
|
+
- Core functionality:
|
|
90
|
+
- `edge()`: Single spread estimate from OHLC data
|
|
91
|
+
- `edge_rolling()`: Rolling window spread estimates with vectorized operations
|
|
92
|
+
- `edge_expanding()`: Expanding window spread estimates
|
|
93
|
+
- Data fetching capabilities:
|
|
94
|
+
- `fetch_yfinance_data()`: Yahoo Finance integration via yfinance
|
|
95
|
+
- `fetch_binance_data()`: Binance API integration via custom FastAPI server
|
|
96
|
+
- Real-time monitoring:
|
|
97
|
+
- `LiveSpreadMonitor`: WebSocket-based real-time spread monitoring
|
|
98
|
+
- Configurable alert thresholds and callbacks
|
|
99
|
+
- Multi-symbol support for cryptocurrency pairs
|
|
100
|
+
- Comprehensive examples:
|
|
101
|
+
- Basic spread estimation with synthetic and real data
|
|
102
|
+
- Animated spread monitoring for presentations
|
|
103
|
+
- Multi-cryptocurrency spread comparison analysis
|
|
104
|
+
- Liquidity risk monitoring with statistical alerts
|
|
105
|
+
- Real-time WebSocket implementation examples
|
|
106
|
+
- Professional documentation:
|
|
107
|
+
- Detailed docstrings following NumPy style
|
|
108
|
+
- Academic paper validation (matches expected results)
|
|
109
|
+
- Usage examples with both synthetic and real market data
|
|
110
|
+
- Testing framework:
|
|
111
|
+
- Unit tests for core functionality
|
|
112
|
+
- Validation against original research paper results
|
|
113
|
+
- Edge case handling (missing data, insufficient observations)
|
|
114
|
+
|
|
115
|
+
### Technical Details
|
|
116
|
+
- Implements the methodology from "Efficient estimation of bid–ask spreads from open, high, low, and close prices" (Journal of Financial Economics, 2024)
|
|
117
|
+
- Vectorized operations for high-performance rolling calculations
|
|
118
|
+
- Proper handling of missing values and edge cases
|
|
119
|
+
- Support for multiple data frequencies (minute, hourly, daily)
|
|
120
|
+
- WebSocket integration for real-time cryptocurrency data
|
|
121
|
+
- Modern Python packaging with pyproject.toml
|
|
122
|
+
|
|
123
|
+
### Dependencies
|
|
124
|
+
- numpy >= 1.20
|
|
125
|
+
- pandas >= 1.5
|
|
126
|
+
- requests >= 2.28
|
|
127
|
+
- yfinance >= 0.2
|
|
128
|
+
- matplotlib >= 3.5
|
|
129
|
+
- plotly >= 5.0
|
|
130
|
+
- websocket-client >= 1.0
|
|
131
|
+
|
|
132
|
+
### Author
|
|
133
|
+
- Jakub Polec (jakub@quantjourney.pro)
|
|
134
|
+
- QuantJourney
|
|
135
|
+
|
|
136
|
+
### License
|
|
137
|
+
- MIT License
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: quantjourney-bidask
|
|
3
|
-
Version: 1.0
|
|
3
|
+
Version: 1.0.2
|
|
4
4
|
Summary: Efficient bid-ask spread estimator from OHLC prices
|
|
5
5
|
Author-email: Jakub Polec <jakub@quantjourney.pro>
|
|
6
6
|
License: MIT
|
|
7
|
-
Project-URL: Homepage, https://github.com/QuantJourneyOrg/
|
|
8
|
-
Project-URL: Repository, https://github.com/QuantJourneyOrg/
|
|
9
|
-
Project-URL: Bug Tracker, https://github.com/QuantJourneyOrg/
|
|
7
|
+
Project-URL: Homepage, https://github.com/QuantJourneyOrg/quantjourney-bidask
|
|
8
|
+
Project-URL: Repository, https://github.com/QuantJourneyOrg/quantjourney-bidask
|
|
9
|
+
Project-URL: Bug Tracker, https://github.com/QuantJourneyOrg/quantjourney-bidask/issues
|
|
10
10
|
Keywords: finance,bid-ask,spread,trading,quantitative,OHLC
|
|
11
11
|
Classifier: Development Status :: 4 - Beta
|
|
12
12
|
Classifier: Intended Audience :: Financial and Insurance Industry
|
|
@@ -26,6 +26,7 @@ Requires-Dist: yfinance>=0.2
|
|
|
26
26
|
Requires-Dist: matplotlib>=3.5
|
|
27
27
|
Requires-Dist: plotly>=5.0
|
|
28
28
|
Requires-Dist: websocket-client>=1.0
|
|
29
|
+
Requires-Dist: numba
|
|
29
30
|
Provides-Extra: dev
|
|
30
31
|
Requires-Dist: pytest>=7.0; extra == "dev"
|
|
31
32
|
Requires-Dist: pytest-mock>=3.10; extra == "dev"
|
|
@@ -34,6 +35,7 @@ Requires-Dist: ruff>=0.1; extra == "dev"
|
|
|
34
35
|
Requires-Dist: mypy>=1.0; extra == "dev"
|
|
35
36
|
Requires-Dist: black>=22.0; extra == "dev"
|
|
36
37
|
Requires-Dist: isort>=5.0; extra == "dev"
|
|
38
|
+
Requires-Dist: numba; extra == "dev"
|
|
37
39
|
Provides-Extra: examples
|
|
38
40
|
Requires-Dist: jupyter>=1.0; extra == "examples"
|
|
39
41
|
Requires-Dist: ipywidgets>=7.0; extra == "examples"
|
|
@@ -41,12 +43,12 @@ Dynamic: license-file
|
|
|
41
43
|
|
|
42
44
|
# QuantJourney Bid-Ask Spread Estimator
|
|
43
45
|
|
|
44
|
-
|
|
45
47
|
[](https://pypi.org/project/quantjourney-bidask/)
|
|
46
48
|
[](https://pypi.org/project/quantjourney-bidask/)
|
|
47
49
|
[](https://pepy.tech/project/quantjourney-bidask)
|
|
48
|
-
[](https://github.com/QuantJourneyOrg/quantjourney-bidask/blob/main/LICENSE)
|
|
51
|
+
[](https://github.com/QuantJourneyOrg/quantjourney-bidask)
|
|
50
52
|
|
|
51
53
|
|
|
52
54
|
The `quantjourney-bidask` library provides an efficient estimator for calculating bid-ask spreads from open, high, low, and close (OHLC) prices, based on the methodology described in:
|
|
@@ -73,56 +75,55 @@ This library is designed for quantitative finance professionals, researchers, an
|
|
|
73
75
|
The package includes comprehensive examples with beautiful visualizations:
|
|
74
76
|
|
|
75
77
|
### Spread Monitor Results
|
|
76
|
-
|
|
77
79
|
|
|
78
80
|
### Basic Data Analysis
|
|
79
|
-
|
|
80
82
|
|
|
81
83
|
### Crypto Spread Comparison
|
|
82
|
-
|
|
83
85
|
|
|
84
86
|
## FAQ
|
|
85
87
|
|
|
86
|
-
### What exactly does the estimator compute?
|
|
87
|
-
The estimator returns the root mean square effective spread over the sample period. This quantifies the average transaction cost implied by bid-ask spreads, based on open, high, low, and close (OHLC) prices.
|
|
88
|
+
### What exactly does the estimator compute?
|
|
89
|
+
The estimator returns the root mean square effective spread over the sample period. This quantifies the average transaction cost implied by bid-ask spreads, based on open, high, low, and close (OHLC) prices.
|
|
88
90
|
|
|
89
|
-
### What is unique about this implementation?
|
|
90
|
-
This package
|
|
91
|
+
### What is unique about this implementation?
|
|
92
|
+
This package provides a highly optimized and robust implementation of the EDGE estimator. Beyond a direct translation of the paper's formula, it features:
|
|
91
93
|
|
|
92
|
-
-
|
|
93
|
-
-
|
|
94
|
-
-
|
|
95
|
-
-
|
|
96
|
-
- Efficient rolling and expanding spread estimators
|
|
94
|
+
- A Hybrid, High-Performance Engine: The core logic leverages fast, vectorized NumPy operations for data preparation and calls a specialized, JIT-compiled kernel via Numba for the computationally intensive GMM calculations.
|
|
95
|
+
- HFT-Ready Version (edge_hft.py): An included, hyper-optimized function that uses fastmath compilation for the absolute lowest latency, designed for production HFT pipelines where every microsecond matters.
|
|
96
|
+
- Robust Data Handling: Gracefully manages missing values (NaN) and non-positive prices to prevent crashes.
|
|
97
|
+
- Advanced Windowing Functions: Efficient and correct edge_rolling and edge_expanding functions that are fully compatible with the powerful features of pandas, including custom step sizes.
|
|
97
98
|
|
|
98
|
-
|
|
99
|
+
### What's the difference between the edge functions?
|
|
100
|
+
The library provides a tiered set of functions for different needs:
|
|
99
101
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
+
- edge(): The core function. It's fast, robust, and computes a single spread estimate for a given sample of data. This is the building block for all other functions.
|
|
103
|
+
- edge_hft(): A specialized version of edge() for HFT users. It's the fastest possible implementation but requires perfectly clean input data (no NaNs) to achieve its speed.
|
|
104
|
+
- edge_rolling(): Computes the spread on a rolling window over a time series. It's perfect for seeing how the spread evolves over time. It is highly optimized and accepts all arguments from pandas.DataFrame.rolling() (like window and step).
|
|
105
|
+
- edge_expanding(): Computes the spread on an expanding (cumulative) window. This is useful for analyzing how the spread estimate converges or changes as more data becomes available.
|
|
102
106
|
|
|
103
|
-
###
|
|
104
|
-
|
|
107
|
+
### What is the minimum number of observations?
|
|
108
|
+
At least 3 valid observations are required.
|
|
105
109
|
|
|
106
|
-
|
|
110
|
+
### How should I choose the window size or frequency?
|
|
111
|
+
Short windows (e.g. a few days) reflect local spread conditions but may be noisy. Longer windows (e.g. 1 year) reduce variance but smooth over changes. For intraday use, minute-level frequency is recommended if the asset trades frequently.
|
|
107
112
|
|
|
108
|
-
|
|
109
|
-
Yes — the estimator supports intraday OHLC data directly. For tick data, resample into OHLC format first (e.g., using pandas resample).
|
|
113
|
+
Rule of thumb: ensure on average ≥2 trades per interval.
|
|
110
114
|
|
|
111
|
-
###
|
|
112
|
-
|
|
115
|
+
### Can I use intraday or tick data?
|
|
116
|
+
Yes — the estimator supports intraday OHLC data directly. For tick data, resample into OHLC format first (e.g., using pandas.resample).
|
|
113
117
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
- Probability thresholds are not met (e.g. insufficient variance in prices)
|
|
117
|
-
- Spread variance is non-positive
|
|
118
|
+
### What if I get NaN results?
|
|
119
|
+
The estimator may return NaN if:
|
|
118
120
|
|
|
119
|
-
|
|
121
|
+
- Input prices are inconsistent (e.g. high < low)
|
|
122
|
+
- There are too many missing or invalid values
|
|
123
|
+
- Probability thresholds are not met (e.g. insufficient variance in prices)
|
|
124
|
+
- Spread variance is non-positive
|
|
120
125
|
|
|
121
|
-
|
|
122
|
-
- `edge()` computes a point estimate over a static sample.
|
|
123
|
-
- `edge_rolling()` computes rolling window estimates, optimized for speed.
|
|
124
|
-
|
|
125
|
-
Both use the same core logic and yield identical results on valid, complete data.
|
|
126
|
+
In these cases, re-examine your input or adjust the sampling frequency.
|
|
126
127
|
|
|
127
128
|
## Installation
|
|
128
129
|
|
|
@@ -135,8 +136,8 @@ pip install quantjourney-bidask
|
|
|
135
136
|
For development (local setup):
|
|
136
137
|
|
|
137
138
|
```bash
|
|
138
|
-
git clone https://github.com/QuantJourneyOrg/
|
|
139
|
-
cd
|
|
139
|
+
git clone https://github.com/QuantJourneyOrg/quantjourney-bidask
|
|
140
|
+
cd quantjourney-bidask
|
|
140
141
|
pip install -e .
|
|
141
142
|
```
|
|
142
143
|
|
|
@@ -185,9 +186,9 @@ from quantjourney_bidask import edge_rolling
|
|
|
185
186
|
import asyncio
|
|
186
187
|
|
|
187
188
|
# Fetch stock data
|
|
188
|
-
stock_df = get_stock_data("
|
|
189
|
+
stock_df = get_stock_data("PL", period="1mo", interval="1d")
|
|
189
190
|
stock_spreads = edge_rolling(stock_df, window=20)
|
|
190
|
-
print(f"
|
|
191
|
+
print(f"PL average spread: {stock_spreads.mean():.6f}")
|
|
191
192
|
|
|
192
193
|
# Fetch crypto data (async)
|
|
193
194
|
async def get_crypto_spreads():
|
|
@@ -274,7 +275,7 @@ quantjourney_bidask/
|
|
|
274
275
|
│ ├── test_edge_rolling.py
|
|
275
276
|
│ └── test_edge_expanding.py
|
|
276
277
|
│ └── test_data_fetcher.py
|
|
277
|
-
│ └──
|
|
278
|
+
│ └── test_estimators.py
|
|
278
279
|
└── _output/ # Example output images
|
|
279
280
|
├── simple_data_example.png
|
|
280
281
|
├── crypto_spread_comparison.png
|
|
@@ -302,8 +303,8 @@ for example in examples_path.glob('*.py'):
|
|
|
302
303
|
Or clone the repository for full access to examples and tests:
|
|
303
304
|
|
|
304
305
|
```bash
|
|
305
|
-
git clone https://github.com/QuantJourneyOrg/
|
|
306
|
-
cd
|
|
306
|
+
git clone https://github.com/QuantJourneyOrg/quantjourney-bidask
|
|
307
|
+
cd quantjourney-bidask
|
|
307
308
|
python examples/simple_data_example.py
|
|
308
309
|
python examples/basic_spread_estimation.py
|
|
309
310
|
python examples/animated_spread_monitor.py # 30s real BTC websocket demo
|
|
@@ -338,8 +339,8 @@ For full development access including tests:
|
|
|
338
339
|
|
|
339
340
|
```bash
|
|
340
341
|
# Clone the repository
|
|
341
|
-
git clone https://github.com/QuantJourneyOrg/
|
|
342
|
-
cd
|
|
342
|
+
git clone https://github.com/QuantJourneyOrg/quantjourney-bidask
|
|
343
|
+
cd quantjourney-bidask
|
|
343
344
|
|
|
344
345
|
# Install in development mode
|
|
345
346
|
pip install -e .
|
|
@@ -419,8 +420,8 @@ Contributions are welcome! Please feel free to submit a Pull Request. For major
|
|
|
419
420
|
### Development Setup
|
|
420
421
|
|
|
421
422
|
```bash
|
|
422
|
-
git clone https://github.com/QuantJourneyOrg/
|
|
423
|
-
cd
|
|
423
|
+
git clone https://github.com/QuantJourneyOrg/quantjourney-bidask
|
|
424
|
+
cd quantjourney-bidask
|
|
424
425
|
pip install -e ".[dev]"
|
|
425
426
|
|
|
426
427
|
# Run tests
|
|
@@ -433,6 +434,6 @@ python examples/websocket_realtime_demo.py # Full dashboard
|
|
|
433
434
|
|
|
434
435
|
## Support
|
|
435
436
|
|
|
436
|
-
- **Documentation**: [GitHub Repository](https://github.com/QuantJourneyOrg/
|
|
437
|
-
- **Issues**: [Bug Tracker](https://github.com/QuantJourneyOrg/
|
|
437
|
+
- **Documentation**: [GitHub Repository](https://github.com/QuantJourneyOrg/quantjourney-bidask)
|
|
438
|
+
- **Issues**: [Bug Tracker](https://github.com/QuantJourneyOrg/quantjourney-bidask/issues)
|
|
438
439
|
- **Contact**: jakub@quantjourney.pro
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
# QuantJourney Bid-Ask Spread Estimator
|
|
2
2
|
|
|
3
|
-
|
|
4
4
|
[](https://pypi.org/project/quantjourney-bidask/)
|
|
5
5
|
[](https://pypi.org/project/quantjourney-bidask/)
|
|
6
6
|
[](https://pepy.tech/project/quantjourney-bidask)
|
|
7
|
-
[](https://github.com/QuantJourneyOrg/quantjourney-bidask/blob/main/LICENSE)
|
|
8
|
+
[](https://github.com/QuantJourneyOrg/quantjourney-bidask)
|
|
9
9
|
|
|
10
10
|
|
|
11
11
|
The `quantjourney-bidask` library provides an efficient estimator for calculating bid-ask spreads from open, high, low, and close (OHLC) prices, based on the methodology described in:
|
|
@@ -32,56 +32,55 @@ This library is designed for quantitative finance professionals, researchers, an
|
|
|
32
32
|
The package includes comprehensive examples with beautiful visualizations:
|
|
33
33
|
|
|
34
34
|
### Spread Monitor Results
|
|
35
|
-
|
|
36
36
|
|
|
37
37
|
### Basic Data Analysis
|
|
38
|
-
|
|
39
39
|
|
|
40
40
|
### Crypto Spread Comparison
|
|
41
|
-
|
|
42
42
|
|
|
43
43
|
## FAQ
|
|
44
44
|
|
|
45
|
-
### What exactly does the estimator compute?
|
|
46
|
-
The estimator returns the root mean square effective spread over the sample period. This quantifies the average transaction cost implied by bid-ask spreads, based on open, high, low, and close (OHLC) prices.
|
|
45
|
+
### What exactly does the estimator compute?
|
|
46
|
+
The estimator returns the root mean square effective spread over the sample period. This quantifies the average transaction cost implied by bid-ask spreads, based on open, high, low, and close (OHLC) prices.
|
|
47
47
|
|
|
48
|
-
### What is unique about this implementation?
|
|
49
|
-
This package
|
|
48
|
+
### What is unique about this implementation?
|
|
49
|
+
This package provides a highly optimized and robust implementation of the EDGE estimator. Beyond a direct translation of the paper's formula, it features:
|
|
50
50
|
|
|
51
|
-
-
|
|
52
|
-
-
|
|
53
|
-
-
|
|
54
|
-
-
|
|
55
|
-
- Efficient rolling and expanding spread estimators
|
|
51
|
+
- A Hybrid, High-Performance Engine: The core logic leverages fast, vectorized NumPy operations for data preparation and calls a specialized, JIT-compiled kernel via Numba for the computationally intensive GMM calculations.
|
|
52
|
+
- HFT-Ready Version (edge_hft.py): An included, hyper-optimized function that uses fastmath compilation for the absolute lowest latency, designed for production HFT pipelines where every microsecond matters.
|
|
53
|
+
- Robust Data Handling: Gracefully manages missing values (NaN) and non-positive prices to prevent crashes.
|
|
54
|
+
- Advanced Windowing Functions: Efficient and correct edge_rolling and edge_expanding functions that are fully compatible with the powerful features of pandas, including custom step sizes.
|
|
56
55
|
|
|
57
|
-
|
|
56
|
+
### What's the difference between the edge functions?
|
|
57
|
+
The library provides a tiered set of functions for different needs:
|
|
58
58
|
|
|
59
|
-
|
|
60
|
-
|
|
59
|
+
- edge(): The core function. It's fast, robust, and computes a single spread estimate for a given sample of data. This is the building block for all other functions.
|
|
60
|
+
- edge_hft(): A specialized version of edge() for HFT users. It's the fastest possible implementation but requires perfectly clean input data (no NaNs) to achieve its speed.
|
|
61
|
+
- edge_rolling(): Computes the spread on a rolling window over a time series. It's perfect for seeing how the spread evolves over time. It is highly optimized and accepts all arguments from pandas.DataFrame.rolling() (like window and step).
|
|
62
|
+
- edge_expanding(): Computes the spread on an expanding (cumulative) window. This is useful for analyzing how the spread estimate converges or changes as more data becomes available.
|
|
61
63
|
|
|
62
|
-
###
|
|
63
|
-
|
|
64
|
+
### What is the minimum number of observations?
|
|
65
|
+
At least 3 valid observations are required.
|
|
64
66
|
|
|
65
|
-
|
|
67
|
+
### How should I choose the window size or frequency?
|
|
68
|
+
Short windows (e.g. a few days) reflect local spread conditions but may be noisy. Longer windows (e.g. 1 year) reduce variance but smooth over changes. For intraday use, minute-level frequency is recommended if the asset trades frequently.
|
|
66
69
|
|
|
67
|
-
|
|
68
|
-
Yes — the estimator supports intraday OHLC data directly. For tick data, resample into OHLC format first (e.g., using pandas resample).
|
|
70
|
+
Rule of thumb: ensure on average ≥2 trades per interval.
|
|
69
71
|
|
|
70
|
-
###
|
|
71
|
-
|
|
72
|
+
### Can I use intraday or tick data?
|
|
73
|
+
Yes — the estimator supports intraday OHLC data directly. For tick data, resample into OHLC format first (e.g., using pandas.resample).
|
|
72
74
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
- Probability thresholds are not met (e.g. insufficient variance in prices)
|
|
76
|
-
- Spread variance is non-positive
|
|
75
|
+
### What if I get NaN results?
|
|
76
|
+
The estimator may return NaN if:
|
|
77
77
|
|
|
78
|
-
|
|
78
|
+
- Input prices are inconsistent (e.g. high < low)
|
|
79
|
+
- There are too many missing or invalid values
|
|
80
|
+
- Probability thresholds are not met (e.g. insufficient variance in prices)
|
|
81
|
+
- Spread variance is non-positive
|
|
79
82
|
|
|
80
|
-
|
|
81
|
-
- `edge()` computes a point estimate over a static sample.
|
|
82
|
-
- `edge_rolling()` computes rolling window estimates, optimized for speed.
|
|
83
|
-
|
|
84
|
-
Both use the same core logic and yield identical results on valid, complete data.
|
|
83
|
+
In these cases, re-examine your input or adjust the sampling frequency.
|
|
85
84
|
|
|
86
85
|
## Installation
|
|
87
86
|
|
|
@@ -94,8 +93,8 @@ pip install quantjourney-bidask
|
|
|
94
93
|
For development (local setup):
|
|
95
94
|
|
|
96
95
|
```bash
|
|
97
|
-
git clone https://github.com/QuantJourneyOrg/
|
|
98
|
-
cd
|
|
96
|
+
git clone https://github.com/QuantJourneyOrg/quantjourney-bidask
|
|
97
|
+
cd quantjourney-bidask
|
|
99
98
|
pip install -e .
|
|
100
99
|
```
|
|
101
100
|
|
|
@@ -144,9 +143,9 @@ from quantjourney_bidask import edge_rolling
|
|
|
144
143
|
import asyncio
|
|
145
144
|
|
|
146
145
|
# Fetch stock data
|
|
147
|
-
stock_df = get_stock_data("
|
|
146
|
+
stock_df = get_stock_data("PL", period="1mo", interval="1d")
|
|
148
147
|
stock_spreads = edge_rolling(stock_df, window=20)
|
|
149
|
-
print(f"
|
|
148
|
+
print(f"PL average spread: {stock_spreads.mean():.6f}")
|
|
150
149
|
|
|
151
150
|
# Fetch crypto data (async)
|
|
152
151
|
async def get_crypto_spreads():
|
|
@@ -233,7 +232,7 @@ quantjourney_bidask/
|
|
|
233
232
|
│ ├── test_edge_rolling.py
|
|
234
233
|
│ └── test_edge_expanding.py
|
|
235
234
|
│ └── test_data_fetcher.py
|
|
236
|
-
│ └──
|
|
235
|
+
│ └── test_estimators.py
|
|
237
236
|
└── _output/ # Example output images
|
|
238
237
|
├── simple_data_example.png
|
|
239
238
|
├── crypto_spread_comparison.png
|
|
@@ -261,8 +260,8 @@ for example in examples_path.glob('*.py'):
|
|
|
261
260
|
Or clone the repository for full access to examples and tests:
|
|
262
261
|
|
|
263
262
|
```bash
|
|
264
|
-
git clone https://github.com/QuantJourneyOrg/
|
|
265
|
-
cd
|
|
263
|
+
git clone https://github.com/QuantJourneyOrg/quantjourney-bidask
|
|
264
|
+
cd quantjourney-bidask
|
|
266
265
|
python examples/simple_data_example.py
|
|
267
266
|
python examples/basic_spread_estimation.py
|
|
268
267
|
python examples/animated_spread_monitor.py # 30s real BTC websocket demo
|
|
@@ -297,8 +296,8 @@ For full development access including tests:
|
|
|
297
296
|
|
|
298
297
|
```bash
|
|
299
298
|
# Clone the repository
|
|
300
|
-
git clone https://github.com/QuantJourneyOrg/
|
|
301
|
-
cd
|
|
299
|
+
git clone https://github.com/QuantJourneyOrg/quantjourney-bidask
|
|
300
|
+
cd quantjourney-bidask
|
|
302
301
|
|
|
303
302
|
# Install in development mode
|
|
304
303
|
pip install -e .
|
|
@@ -378,8 +377,8 @@ Contributions are welcome! Please feel free to submit a Pull Request. For major
|
|
|
378
377
|
### Development Setup
|
|
379
378
|
|
|
380
379
|
```bash
|
|
381
|
-
git clone https://github.com/QuantJourneyOrg/
|
|
382
|
-
cd
|
|
380
|
+
git clone https://github.com/QuantJourneyOrg/quantjourney-bidask
|
|
381
|
+
cd quantjourney-bidask
|
|
383
382
|
pip install -e ".[dev]"
|
|
384
383
|
|
|
385
384
|
# Run tests
|
|
@@ -392,6 +391,6 @@ python examples/websocket_realtime_demo.py # Full dashboard
|
|
|
392
391
|
|
|
393
392
|
## Support
|
|
394
393
|
|
|
395
|
-
- **Documentation**: [GitHub Repository](https://github.com/QuantJourneyOrg/
|
|
396
|
-
- **Issues**: [Bug Tracker](https://github.com/QuantJourneyOrg/
|
|
394
|
+
- **Documentation**: [GitHub Repository](https://github.com/QuantJourneyOrg/quantjourney-bidask)
|
|
395
|
+
- **Issues**: [Bug Tracker](https://github.com/QuantJourneyOrg/quantjourney-bidask/issues)
|
|
397
396
|
- **Contact**: jakub@quantjourney.pro
|