quantjourney-bidask 0.5.0__tar.gz

quantjourney_bidask-0.5.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to the quantjourney-bidask project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-06-24
+
+### Added
+- Initial release of quantjourney-bidask package
+- EDGE (Efficient estimator of bid-ask spreads) implementation based on Ardia, Guidotti & Kroencke (2024)
+- Core functionality:
+  - `edge()`: Single spread estimate from OHLC data
+  - `edge_rolling()`: Rolling window spread estimates with vectorized operations
+  - `edge_expanding()`: Expanding window spread estimates
+- Data fetching capabilities:
+  - `fetch_yfinance_data()`: Yahoo Finance integration via yfinance
+  - `fetch_binance_data()`: Binance API integration via custom FastAPI server
+- Real-time monitoring:
+  - `LiveSpreadMonitor`: WebSocket-based real-time spread monitoring
+  - Configurable alert thresholds and callbacks
+  - Multi-symbol support for cryptocurrency pairs
+- Comprehensive examples:
+  - Basic spread estimation with synthetic and real data
+  - Animated spread monitoring for presentations
+  - Multi-cryptocurrency spread comparison analysis
+  - Liquidity risk monitoring with statistical alerts
+  - Real-time WebSocket implementation examples
+- Professional documentation:
+  - Detailed docstrings following NumPy style
+  - Academic paper validation (matches expected results)
+  - Usage examples with both synthetic and real market data
+- Testing framework:
+  - Unit tests for core functionality
+  - Validation against original research paper results
+  - Edge case handling (missing data, insufficient observations)
+
+### Technical Details
+- Implements the methodology from "Efficient estimation of bid–ask spreads from open, high, low, and close prices" (Journal of Financial Economics, 2024)
+- Vectorized operations for high-performance rolling calculations
+- Proper handling of missing values and edge cases
+- Support for multiple data frequencies (minute, hourly, daily)
+- WebSocket integration for real-time cryptocurrency data
+- Modern Python packaging with pyproject.toml
+
+### Dependencies
+- numpy >= 1.20
+- pandas >= 1.5
+- requests >= 2.28
+- yfinance >= 0.2
+- matplotlib >= 3.5
+- plotly >= 5.0
+- websocket-client >= 1.0
+
+### Author
+- Jakub Polec (jakub@quantjourney.pro)
+- QuantJourney
+
+### License
+- MIT License

quantjourney_bidask-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jakub Polec, QuantJourney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quantjourney_bidask-0.5.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include pyproject.toml
+include CHANGELOG.md
+include requirements.txt
+include docs/usage_examples.ipynb
+include examples/*.py
+include tests/*.py
+recursive-include quantjourney_bidask *.py

quantjourney_bidask-0.5.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: quantjourney-bidask
+Version: 0.5.0
+Summary: Efficient bid-ask spread estimator from OHLC prices
+Author-email: Jakub Polec <jakub@quantjourney.pro>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/QuantJourneyOrg/qj_bidask
+Project-URL: Repository, https://github.com/QuantJourneyOrg/qj_bidask
+Project-URL: Bug Tracker, https://github.com/QuantJourneyOrg/qj_bidask/issues
+Keywords: finance,bid-ask,spread,trading,quantitative,OHLC
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: pandas>=1.5
+Requires-Dist: requests>=2.28
+Requires-Dist: yfinance>=0.2
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: plotly>=5.0
+Requires-Dist: websocket-client>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: black>=22.0; extra == "dev"
+Requires-Dist: isort>=5.0; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: jupyter>=1.0; extra == "examples"
+Requires-Dist: ipywidgets>=7.0; extra == "examples"
+Dynamic: license-file
+
+# QuantJourney Bid-Ask Spread Estimator
+
+![PyPI](https://img.shields.io/pypi/v/quantjourney-bidask)
+![License](https://img.shields.io/github/license/quantjourney/bidask)
+![Tests](https://img.shields.io/github/workflow/status/quantjourney/bidask/Test)
+
+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:
+
+> Ardia, D., Guidotti, E., Kroencke, T.A. (2024). Efficient Estimation of Bid-Ask Spreads from Open, High, Low, and Close Prices. *Journal of Financial Economics*, 161, 103916. [doi:10.1016/j.jfineco.2024.103916](https://doi.org/10.1016/j.jfineco.2024.103916)
+
+This library is designed for quantitative finance professionals, researchers, and traders who need accurate and computationally efficient spread estimates for equities, cryptocurrencies, and other assets.
+
+## Features
+
+- **Efficient Spread Estimation**: Implements the EDGE estimator for single, rolling, and expanding windows.
+- **Data Integration**: Fetch OHLC data from Binance (via custom FastAPI server) and Yahoo Finance (via yfinance).
+- **Robust Handling**: Supports missing values, non-positive prices, and various data frequencies.
+- **Comprehensive Tests**: Extensive unit tests with known test cases from the original paper.
+- **Clear Documentation**: Detailed docstrings and usage examples.
+
+## Installation
+
+Install the library via pip:
+
+```bash
+pip install quantjourney-bidask
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from quantjourney_bidask import edge
+
+# Example OHLC data (as lists or numpy arrays)
+open_prices = [100.0, 101.5, 99.8, 102.1, 100.9]
+high_prices = [102.3, 103.0, 101.2, 103.5, 102.0]
+low_prices = [99.5, 100.8, 98.9, 101.0, 100.1]
+close_prices = [101.2, 100.2, 101.8, 100.5, 101.5]
+
+# Calculate bid-ask spread
+spread = edge(open_prices, high_prices, low_prices, close_prices)
+print(f"Estimated bid-ask spread: {spread:.6f}")
+```
+
+### Rolling Window Analysis
+
+```python
+from quantjourney_bidask import edge_rolling
+
+# Calculate rolling spreads with a 20-period window
+rolling_spreads = edge_rolling(
+    open_prices, high_prices, low_prices, close_prices, 
+    window=20
+)
+print(f"Rolling spreads: {rolling_spreads}")
+```
+
+### Data Fetching Integration
+
+```python
+from quantjourney_bidask import fetch_yfinance_data, edge
+
+# Fetch OHLC data for a stock
+data = fetch_yfinance_data("AAPL", period="1mo", interval="1h")
+
+# Calculate spread from fetched data
+spread = edge(data['Open'], data['High'], data['Low'], data['Close'])
+print(f"AAPL spread estimate: {spread:.6f}")
+```
+
+### Live Monitoring
+
+```python
+from quantjourney_bidask import LiveSpreadMonitor
+
+# Monitor live spreads for cryptocurrency
+monitor = LiveSpreadMonitor("BTCUSDT", window=100)
+monitor.start()
+
+# Get current spread estimate
+current_spread = monitor.get_current_spread()
+print(f"Current BTC/USDT spread: {current_spread:.6f}")
+
+monitor.stop()
+```
+
+## API Reference
+
+### Core Functions
+
+- `edge(open, high, low, close, sign=False)`: Single-period spread estimation
+- `edge_rolling(open, high, low, close, window, min_periods=None)`: Rolling window estimation
+- `edge_expanding(open, high, low, close, min_periods=3)`: Expanding window estimation
+
+### Data Fetching
+
+- `fetch_yfinance_data(symbol, period, interval)`: Fetch data from Yahoo Finance
+- `fetch_binance_data(symbol, interval, limit)`: Fetch data from Binance API
+
+### Live Monitoring
+
+- `LiveSpreadMonitor(symbol, window)`: Real-time spread monitoring via WebSocket
+
+## Requirements
+
+- Python >= 3.8
+- numpy >= 1.20
+- pandas >= 1.5
+- requests >= 2.28
+- yfinance >= 0.2
+
+## Academic Citation
+
+If you use this library in academic research, please cite:
+
+```bibtex
+@article{ardia2024efficient,
+  title={Efficient Estimation of Bid-Ask Spreads from Open, High, Low, and Close Prices},
+  author={Ardia, David and Guidotti, Emanuele and Kroencke, Tim A},
+  journal={Journal of Financial Economics},
+  volume={161},
+  pages={103916},
+  year={2024},
+  publisher={Elsevier}
+}
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+## Support
+
+- **Documentation**: [GitHub Repository](https://github.com/QuantJourneyOrg/qj_bidask)
+- **Issues**: [Bug Tracker](https://github.com/QuantJourneyOrg/qj_bidask/issues)
+- **Contact**: jakub@quantjourney.pro

quantjourney_bidask-0.5.0/README.md

@@ -0,0 +1,142 @@
+# QuantJourney Bid-Ask Spread Estimator
+
+![PyPI](https://img.shields.io/pypi/v/quantjourney-bidask)
+![License](https://img.shields.io/github/license/quantjourney/bidask)
+![Tests](https://img.shields.io/github/workflow/status/quantjourney/bidask/Test)
+
+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:
+
+> Ardia, D., Guidotti, E., Kroencke, T.A. (2024). Efficient Estimation of Bid-Ask Spreads from Open, High, Low, and Close Prices. *Journal of Financial Economics*, 161, 103916. [doi:10.1016/j.jfineco.2024.103916](https://doi.org/10.1016/j.jfineco.2024.103916)
+
+This library is designed for quantitative finance professionals, researchers, and traders who need accurate and computationally efficient spread estimates for equities, cryptocurrencies, and other assets.
+
+## Features
+
+- **Efficient Spread Estimation**: Implements the EDGE estimator for single, rolling, and expanding windows.
+- **Data Integration**: Fetch OHLC data from Binance (via custom FastAPI server) and Yahoo Finance (via yfinance).
+- **Robust Handling**: Supports missing values, non-positive prices, and various data frequencies.
+- **Comprehensive Tests**: Extensive unit tests with known test cases from the original paper.
+- **Clear Documentation**: Detailed docstrings and usage examples.
+
+## Installation
+
+Install the library via pip:
+
+```bash
+pip install quantjourney-bidask
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from quantjourney_bidask import edge
+
+# Example OHLC data (as lists or numpy arrays)
+open_prices = [100.0, 101.5, 99.8, 102.1, 100.9]
+high_prices = [102.3, 103.0, 101.2, 103.5, 102.0]
+low_prices = [99.5, 100.8, 98.9, 101.0, 100.1]
+close_prices = [101.2, 100.2, 101.8, 100.5, 101.5]
+
+# Calculate bid-ask spread
+spread = edge(open_prices, high_prices, low_prices, close_prices)
+print(f"Estimated bid-ask spread: {spread:.6f}")
+```
+
+### Rolling Window Analysis
+
+```python
+from quantjourney_bidask import edge_rolling
+
+# Calculate rolling spreads with a 20-period window
+rolling_spreads = edge_rolling(
+    open_prices, high_prices, low_prices, close_prices, 
+    window=20
+)
+print(f"Rolling spreads: {rolling_spreads}")
+```
+
+### Data Fetching Integration
+
+```python
+from quantjourney_bidask import fetch_yfinance_data, edge
+
+# Fetch OHLC data for a stock
+data = fetch_yfinance_data("AAPL", period="1mo", interval="1h")
+
+# Calculate spread from fetched data
+spread = edge(data['Open'], data['High'], data['Low'], data['Close'])
+print(f"AAPL spread estimate: {spread:.6f}")
+```
+
+### Live Monitoring
+
+```python
+from quantjourney_bidask import LiveSpreadMonitor
+
+# Monitor live spreads for cryptocurrency
+monitor = LiveSpreadMonitor("BTCUSDT", window=100)
+monitor.start()
+
+# Get current spread estimate
+current_spread = monitor.get_current_spread()
+print(f"Current BTC/USDT spread: {current_spread:.6f}")
+
+monitor.stop()
+```
+
+## API Reference
+
+### Core Functions
+
+- `edge(open, high, low, close, sign=False)`: Single-period spread estimation
+- `edge_rolling(open, high, low, close, window, min_periods=None)`: Rolling window estimation
+- `edge_expanding(open, high, low, close, min_periods=3)`: Expanding window estimation
+
+### Data Fetching
+
+- `fetch_yfinance_data(symbol, period, interval)`: Fetch data from Yahoo Finance
+- `fetch_binance_data(symbol, interval, limit)`: Fetch data from Binance API
+
+### Live Monitoring
+
+- `LiveSpreadMonitor(symbol, window)`: Real-time spread monitoring via WebSocket
+
+## Requirements
+
+- Python >= 3.8
+- numpy >= 1.20
+- pandas >= 1.5
+- requests >= 2.28
+- yfinance >= 0.2
+
+## Academic Citation
+
+If you use this library in academic research, please cite:
+
+```bibtex
+@article{ardia2024efficient,
+  title={Efficient Estimation of Bid-Ask Spreads from Open, High, Low, and Close Prices},
+  author={Ardia, David and Guidotti, Emanuele and Kroencke, Tim A},
+  journal={Journal of Financial Economics},
+  volume={161},
+  pages={103916},
+  year={2024},
+  publisher={Elsevier}
+}
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+## Support
+
+- **Documentation**: [GitHub Repository](https://github.com/QuantJourneyOrg/qj_bidask)
+- **Issues**: [Bug Tracker](https://github.com/QuantJourneyOrg/qj_bidask/issues)
+- **Contact**: jakub@quantjourney.pro