quantjourney-bidask 0.9.4__tar.gz → 1.0.1__tar.gz

{quantjourney_bidask-0.9.4 → quantjourney_bidask-1.0.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: quantjourney-bidask
-Version: 0.9.4
+Version: 1.0.1
 Summary: Efficient bid-ask spread estimator from OHLC prices
 Author-email: Jakub Polec <jakub@quantjourney.pro>
-License-Expression: MIT
+License: 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
@@ -26,6 +26,7 @@ Requires-Dist: yfinance>=0.2
 Requires-Dist: matplotlib>=3.5
 Requires-Dist: plotly>=5.0
 Requires-Dist: websocket-client>=1.0
+Requires-Dist: numba
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.10; extra == "dev"
@@ -34,6 +35,7 @@ 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"
+Requires-Dist: numba; extra == "dev"
 Provides-Extra: examples
 Requires-Dist: jupyter>=1.0; extra == "examples"
 Requires-Dist: ipywidgets>=7.0; extra == "examples"
@@ -41,9 +43,13 @@ 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)
+![Build Status](https://github.com/QuantJourneyOrg/qj_bidask/actions/workflows/test.yml/badge.svg)
+[![PyPi Version](https://img.shields.io/pypi/v/quantjourney-bidask.svg)](https://pypi.org/project/quantjourney-bidask/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/quantjourney-bidask.svg)](https://pypi.org/project/quantjourney-bidask/)
+[![Downloads](https://pepy.tech/badge/quantjourney-bidask)](https://pepy.tech/project/quantjourney-bidask)
+[![License](https://img.shields.io/github/license/QuantJourneyOrg/qj_bidask.svg)](https://github.com/QuantJourneyOrg/qj_bidask/blob/main/LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/QuantJourneyOrg/qj_bidask?style=social)](https://github.com/QuantJourneyOrg/qj_bidask)
+
 
 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:
 
@@ -51,6 +57,8 @@ The `quantjourney-bidask` library provides an efficient estimator for calculatin
 
 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.
 
+🚀 **Part of the [QuantJourney](https://quantjourney.substack.com/) ecosystem** - The framework with advanced quantitative finance tools and insights!
+
 ## Features
 
 - **Efficient Spread Estimation**: Implements the EDGE estimator for single, rolling, and expanding windows.
@@ -62,6 +70,61 @@ This library is designed for quantitative finance professionals, researchers, an
 - **Comprehensive Tests**: Extensive unit tests with known test cases from the original paper.
 - **Clear Documentation**: Detailed docstrings and usage examples.
 
+## Examples and Visualizations
+
+The package includes comprehensive examples with beautiful visualizations:
+
+### Spread Monitor Results
+![Spread Monitor](https://raw.githubusercontent.com/QuantJourneyOrg/qj_bidask/refs/heads/main/_output/spread_monitor_results.png)
+
+### Basic Data Analysis
+![Crypto Spread Analysis](https://raw.githubusercontent.com/QuantJourneyOrg/qj_bidask/ad49bd78c82ab1c44561d0f2e707ae304575a147/_output/crypto_spread_comprehensive_analysis.png)
+
+### Crypto Spread Comparison  
+![Crypto Spread Comparison](https://raw.githubusercontent.com/QuantJourneyOrg/qj_bidask/refs/heads/main/_output/crypto_spread_comparison.png)
+
+## FAQ
+
+ ### What exactly does the estimator compute?
+ 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.
+
+ ### What is unique about this implementation?
+ This package provides a highly optimized and robust implementation of the EDGE estimator. Beyond a direct translation of the paper's formula, it features:
+
+ - 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.
+ - 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.
+ - Robust Data Handling: Gracefully manages missing values (NaN) and non-positive prices to prevent crashes.
+ - 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.
+
+ ### What's the difference between the edge functions?
+ The library provides a tiered set of functions for different needs:
+
+ - 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.
+ - 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.
+ - 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).
+ - 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.
+
+ ### What is the minimum number of observations?
+ At least 3 valid observations are required.
+
+ ### How should I choose the window size or frequency?
+ 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.
+
+ Rule of thumb: ensure on average ≥2 trades per interval.
+
+ ### Can I use intraday or tick data?
+ Yes — the estimator supports intraday OHLC data directly. For tick data, resample into OHLC format first (e.g., using pandas.resample).
+
+ ### What if I get NaN results?
+ The estimator may return NaN if:
+
+ - Input prices are inconsistent (e.g. high < low)
+ - There are too many missing or invalid values
+ - Probability thresholds are not met (e.g. insufficient variance in prices)
+ - Spread variance is non-positive
+
+ In these cases, re-examine your input or adjust the sampling frequency.
+
 ## Installation
 
 Install the library via pip:
@@ -123,9 +186,9 @@ from quantjourney_bidask import edge_rolling
 import asyncio
 
 # Fetch stock data
-stock_df = get_stock_data("AAPL", period="1mo", interval="1d")
+stock_df = get_stock_data("PL", period="1mo", interval="1d")
 stock_spreads = edge_rolling(stock_df, window=20)
-print(f"AAPL average spread: {stock_spreads.mean():.6f}")
+print(f"PL average spread: {stock_spreads.mean():.6f}")
 
 # Fetch crypto data (async)
 async def get_crypto_spreads():
@@ -178,10 +241,13 @@ monitor.start_monitoring("1m")
 
 ```python
 # Run the real-time dashboard
-python examples/realtime_spread_monitor.py --mode dashboard
+python examples/websocket_realtime_demo.py --mode dashboard
+
+# Or console mode  
+python examples/websocket_realtime_demo.py --mode console
 
-# Or console mode
-python examples/realtime_spread_monitor.py --mode console
+# Quick 30-second BTC websocket demo
+python examples/animated_spread_monitor.py
 ```
 
 ## Project Structure
@@ -190,42 +256,32 @@ python examples/realtime_spread_monitor.py --mode console
 quantjourney_bidask/
 ├── quantjourney_bidask/          # Main library code
 │   ├── __init__.py
-│   ├── edge.py                   # Core EDGE estimator
+│   ├── edge.py                   # Core EDGE estimator 
+│   ├── edge_hft.py               # EDGE estimator optimised HFT-version
 │   ├── edge_rolling.py           # Rolling window estimation
 │   └── edge_expanding.py         # Expanding window estimation
 ├── data/
 │   └── fetch.py                  # Simplified data fetcher for examples
 ├── examples/                     # Comprehensive usage examples
 │   ├── simple_data_example.py    # Basic usage demonstration
-│   ├── spread_estimator.py       # Spread estimation examples
+│   ├── basic_spread_estimation.py # Core spread estimation examples
 │   ├── animated_spread_monitor.py # Animated visualizations
 │   ├── crypto_spread_comparison.py # Crypto spread analysis
 │   ├── liquidity_risk_monitor.py  # Risk monitoring
-│   ├── realtime_spread_monitor.py # Live monitoring dashboard
-│   └── stock_liquidity_risk.py    # Stock liquidity analysis
+│   ├── websocket_realtime_demo.py # Live websocket monitoring demo
+│   └── threshold_alert_monitor.py # Threshold-based spread alerts
 ├── tests/                        # Unit tests (GitHub only)
 │   ├── test_edge.py
 │   ├── test_edge_rolling.py
+│   └── test_edge_expanding.py
 │   └── test_data_fetcher.py
+│   └── test_estimators.py
 └── _output/                      # Example output images
     ├── simple_data_example.png
     ├── crypto_spread_comparison.png
     └── spread_estimator_results.png
 ```
 
-## Examples and Visualizations
-
-The package includes comprehensive examples with beautiful visualizations:
-
-### Basic Data Analysis
-![Crypto Spread Analysis](https://raw.githubusercontent.com/QuantJourneyOrg/qj_bidask/ad49bd78c82ab1c44561d0f2e707ae304575a147/_output/crypto_spread_comprehensive_analysis.png)
-
-### Crypto Spread Comparison  
-![Crypto Spread Comparison](https://raw.githubusercontent.com/QuantJourneyOrg/qj_bidask/refs/heads/main/_output/crypto_spread_comparison.png)
-
-### Spread Estimation Results
-![Spread Estimator Results](https://raw.githubusercontent.com/QuantJourneyOrg/qj_bidask/refs/heads/main/_output/spread_estimator_results.png)
-
 ### Running Examples
 
 After installing via pip, examples are included in the package:
@@ -250,19 +306,20 @@ Or clone the repository for full access to examples and tests:
 git clone https://github.com/QuantJourneyOrg/qj_bidask
 cd qj_bidask
 python examples/simple_data_example.py
-python examples/spread_estimator.py
+python examples/basic_spread_estimation.py
+python examples/animated_spread_monitor.py  # 30s real BTC websocket demo
 python examples/crypto_spread_comparison.py
 ```
 
 ### Available Examples
 
 - **`simple_data_example.py`** - Basic usage with stock and crypto data
-- **`spread_estimator.py`** - Core spread estimation functionality
-- **`animated_spread_monitor.py`** - Real-time animated visualizations
-- **`crypto_spread_comparison.py`** - Multi-asset crypto analysis
+- **`basic_spread_estimation.py`** - Core spread estimation functionality
+- **`animated_spread_monitor.py`** - Real-time animated visualizations with 30s websocket demo
+- **`crypto_spread_comparison.py`** - Multi-asset crypto analysis and comparison
 - **`liquidity_risk_monitor.py`** - Risk monitoring and alerts
-- **`realtime_spread_monitor.py`** - Live websocket monitoring dashboard
-- **`stock_liquidity_risk.py`** - Stock-specific liquidity analysis
+- **`websocket_realtime_demo.py`** - Live websocket monitoring dashboard
+- **`threshold_alert_monitor.py`** - Threshold-based spread alerts and monitoring
 
 ## Testing and Development
 
@@ -297,7 +354,8 @@ python -m pytest tests/test_data_fetcher.py -v
 
 # Run examples
 python examples/simple_data_example.py
-python examples/spread_estimator.py
+python examples/basic_spread_estimation.py
+python examples/animated_spread_monitor.py  # Real BTC websocket demo
 ```
 
 ### Package vs Repository
@@ -370,7 +428,8 @@ pip install -e ".[dev]"
 pytest
 
 # Run examples
-python examples/realtime_spread_monitor.py
+python examples/animated_spread_monitor.py  # 30s real BTC websocket demo
+python examples/websocket_realtime_demo.py  # Full dashboard
 ```
 
 ## Support

{quantjourney_bidask-0.9.4 → quantjourney_bidask-1.0.1}/README.md

@@ -1,8 +1,12 @@
 # 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)
+![Build Status](https://github.com/QuantJourneyOrg/qj_bidask/actions/workflows/test.yml/badge.svg)
+[![PyPi Version](https://img.shields.io/pypi/v/quantjourney-bidask.svg)](https://pypi.org/project/quantjourney-bidask/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/quantjourney-bidask.svg)](https://pypi.org/project/quantjourney-bidask/)
+[![Downloads](https://pepy.tech/badge/quantjourney-bidask)](https://pepy.tech/project/quantjourney-bidask)
+[![License](https://img.shields.io/github/license/QuantJourneyOrg/qj_bidask.svg)](https://github.com/QuantJourneyOrg/qj_bidask/blob/main/LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/QuantJourneyOrg/qj_bidask?style=social)](https://github.com/QuantJourneyOrg/qj_bidask)
+
 
 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:
 
@@ -10,6 +14,8 @@ The `quantjourney-bidask` library provides an efficient estimator for calculatin
 
 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.
 
+🚀 **Part of the [QuantJourney](https://quantjourney.substack.com/) ecosystem** - The framework with advanced quantitative finance tools and insights!
+
 ## Features
 
 - **Efficient Spread Estimation**: Implements the EDGE estimator for single, rolling, and expanding windows.
@@ -21,6 +27,61 @@ This library is designed for quantitative finance professionals, researchers, an
 - **Comprehensive Tests**: Extensive unit tests with known test cases from the original paper.
 - **Clear Documentation**: Detailed docstrings and usage examples.
 
+## Examples and Visualizations
+
+The package includes comprehensive examples with beautiful visualizations:
+
+### Spread Monitor Results
+![Spread Monitor](https://raw.githubusercontent.com/QuantJourneyOrg/qj_bidask/refs/heads/main/_output/spread_monitor_results.png)
+
+### Basic Data Analysis
+![Crypto Spread Analysis](https://raw.githubusercontent.com/QuantJourneyOrg/qj_bidask/ad49bd78c82ab1c44561d0f2e707ae304575a147/_output/crypto_spread_comprehensive_analysis.png)
+
+### Crypto Spread Comparison  
+![Crypto Spread Comparison](https://raw.githubusercontent.com/QuantJourneyOrg/qj_bidask/refs/heads/main/_output/crypto_spread_comparison.png)
+
+## FAQ
+
+ ### What exactly does the estimator compute?
+ 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.
+
+ ### What is unique about this implementation?
+ This package provides a highly optimized and robust implementation of the EDGE estimator. Beyond a direct translation of the paper's formula, it features:
+
+ - 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.
+ - 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.
+ - Robust Data Handling: Gracefully manages missing values (NaN) and non-positive prices to prevent crashes.
+ - 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.
+
+ ### What's the difference between the edge functions?
+ The library provides a tiered set of functions for different needs:
+
+ - 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.
+ - 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.
+ - 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).
+ - 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.
+
+ ### What is the minimum number of observations?
+ At least 3 valid observations are required.
+
+ ### How should I choose the window size or frequency?
+ 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.
+
+ Rule of thumb: ensure on average ≥2 trades per interval.
+
+ ### Can I use intraday or tick data?
+ Yes — the estimator supports intraday OHLC data directly. For tick data, resample into OHLC format first (e.g., using pandas.resample).
+
+ ### What if I get NaN results?
+ The estimator may return NaN if:
+
+ - Input prices are inconsistent (e.g. high < low)
+ - There are too many missing or invalid values
+ - Probability thresholds are not met (e.g. insufficient variance in prices)
+ - Spread variance is non-positive
+
+ In these cases, re-examine your input or adjust the sampling frequency.
+
 ## Installation
 
 Install the library via pip:
@@ -82,9 +143,9 @@ from quantjourney_bidask import edge_rolling
 import asyncio
 
 # Fetch stock data
-stock_df = get_stock_data("AAPL", period="1mo", interval="1d")
+stock_df = get_stock_data("PL", period="1mo", interval="1d")
 stock_spreads = edge_rolling(stock_df, window=20)
-print(f"AAPL average spread: {stock_spreads.mean():.6f}")
+print(f"PL average spread: {stock_spreads.mean():.6f}")
 
 # Fetch crypto data (async)
 async def get_crypto_spreads():
@@ -137,10 +198,13 @@ monitor.start_monitoring("1m")
 
 ```python
 # Run the real-time dashboard
-python examples/realtime_spread_monitor.py --mode dashboard
+python examples/websocket_realtime_demo.py --mode dashboard
+
+# Or console mode  
+python examples/websocket_realtime_demo.py --mode console
 
-# Or console mode
-python examples/realtime_spread_monitor.py --mode console
+# Quick 30-second BTC websocket demo
+python examples/animated_spread_monitor.py
 ```
 
 ## Project Structure
@@ -149,42 +213,32 @@ python examples/realtime_spread_monitor.py --mode console
 quantjourney_bidask/
 ├── quantjourney_bidask/          # Main library code
 │   ├── __init__.py
-│   ├── edge.py                   # Core EDGE estimator
+│   ├── edge.py                   # Core EDGE estimator 
+│   ├── edge_hft.py               # EDGE estimator optimised HFT-version
 │   ├── edge_rolling.py           # Rolling window estimation
 │   └── edge_expanding.py         # Expanding window estimation
 ├── data/
 │   └── fetch.py                  # Simplified data fetcher for examples
 ├── examples/                     # Comprehensive usage examples
 │   ├── simple_data_example.py    # Basic usage demonstration
-│   ├── spread_estimator.py       # Spread estimation examples
+│   ├── basic_spread_estimation.py # Core spread estimation examples
 │   ├── animated_spread_monitor.py # Animated visualizations
 │   ├── crypto_spread_comparison.py # Crypto spread analysis
 │   ├── liquidity_risk_monitor.py  # Risk monitoring
-│   ├── realtime_spread_monitor.py # Live monitoring dashboard
-│   └── stock_liquidity_risk.py    # Stock liquidity analysis
+│   ├── websocket_realtime_demo.py # Live websocket monitoring demo
+│   └── threshold_alert_monitor.py # Threshold-based spread alerts
 ├── tests/                        # Unit tests (GitHub only)
 │   ├── test_edge.py
 │   ├── test_edge_rolling.py
+│   └── test_edge_expanding.py
 │   └── test_data_fetcher.py
+│   └── test_estimators.py
 └── _output/                      # Example output images
     ├── simple_data_example.png
     ├── crypto_spread_comparison.png
     └── spread_estimator_results.png
 ```
 
-## Examples and Visualizations
-
-The package includes comprehensive examples with beautiful visualizations:
-
-### Basic Data Analysis
-![Crypto Spread Analysis](https://raw.githubusercontent.com/QuantJourneyOrg/qj_bidask/ad49bd78c82ab1c44561d0f2e707ae304575a147/_output/crypto_spread_comprehensive_analysis.png)
-
-### Crypto Spread Comparison  
-![Crypto Spread Comparison](https://raw.githubusercontent.com/QuantJourneyOrg/qj_bidask/refs/heads/main/_output/crypto_spread_comparison.png)
-
-### Spread Estimation Results
-![Spread Estimator Results](https://raw.githubusercontent.com/QuantJourneyOrg/qj_bidask/refs/heads/main/_output/spread_estimator_results.png)
-
 ### Running Examples
 
 After installing via pip, examples are included in the package:
@@ -209,19 +263,20 @@ Or clone the repository for full access to examples and tests:
 git clone https://github.com/QuantJourneyOrg/qj_bidask
 cd qj_bidask
 python examples/simple_data_example.py
-python examples/spread_estimator.py
+python examples/basic_spread_estimation.py
+python examples/animated_spread_monitor.py  # 30s real BTC websocket demo
 python examples/crypto_spread_comparison.py
 ```
 
 ### Available Examples
 
 - **`simple_data_example.py`** - Basic usage with stock and crypto data
-- **`spread_estimator.py`** - Core spread estimation functionality
-- **`animated_spread_monitor.py`** - Real-time animated visualizations
-- **`crypto_spread_comparison.py`** - Multi-asset crypto analysis
+- **`basic_spread_estimation.py`** - Core spread estimation functionality
+- **`animated_spread_monitor.py`** - Real-time animated visualizations with 30s websocket demo
+- **`crypto_spread_comparison.py`** - Multi-asset crypto analysis and comparison
 - **`liquidity_risk_monitor.py`** - Risk monitoring and alerts
-- **`realtime_spread_monitor.py`** - Live websocket monitoring dashboard
-- **`stock_liquidity_risk.py`** - Stock-specific liquidity analysis
+- **`websocket_realtime_demo.py`** - Live websocket monitoring dashboard
+- **`threshold_alert_monitor.py`** - Threshold-based spread alerts and monitoring
 
 ## Testing and Development
 
@@ -256,7 +311,8 @@ python -m pytest tests/test_data_fetcher.py -v
 
 # Run examples
 python examples/simple_data_example.py
-python examples/spread_estimator.py
+python examples/basic_spread_estimation.py
+python examples/animated_spread_monitor.py  # Real BTC websocket demo
 ```
 
 ### Package vs Repository
@@ -329,7 +385,8 @@ pip install -e ".[dev]"
 pytest
 
 # Run examples
-python examples/realtime_spread_monitor.py
+python examples/animated_spread_monitor.py  # 30s real BTC websocket demo
+python examples/websocket_realtime_demo.py  # Full dashboard
 ```
 
 ## Support