quantjourney-bidask 0.9.3__tar.gz → 1.0__tar.gz

{quantjourney_bidask-0.9.3 → quantjourney_bidask-1.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: quantjourney-bidask
-Version: 0.9.3
+Version: 1.0
 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
@@ -41,9 +41,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 +55,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 +68,62 @@ 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 includes a heavily optimized and enhanced implementation of the estimator proposed by Ardia, Guidotti, and Kroencke (2024). It features:
+
+- Robust numerical handling of non-positive or missing prices
+- Floating-point-safe comparisons using configurable epsilon
+- Vectorized log-return computations for faster evaluation
+- Improved error detection and early exits for invalid OHLC structures
+- Efficient rolling and expanding spread estimators
+
+These improvements make the estimator suitable for large-scale usage in backtesting, live monitoring, and production pipelines.
+
+### 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.
+
+### What's the difference between edge() and edge_rolling()?
+- `edge()` computes a point estimate over a static sample.
+- `edge_rolling()` computes rolling window estimates, optimized for speed.
+
+Both use the same core logic and yield identical results on valid, complete data.
+
 ## Installation
 
 Install the library via pip:
@@ -178,10 +240,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 +255,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
+│   └── testestimators.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 +305,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 +353,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
@@ -312,9 +369,9 @@ python examples/spread_estimator.py
 - `edge_rolling(df, window, min_periods=None)`: Rolling window estimation  
 - `edge_expanding(df, min_periods=3)`: Expanding window estimation
 
-### Data Fetching (`data/fetch.py`)
+### Data Fetching (`data/fetch.py`) - Examples & Demos
 
-- `DataFetcher()`: Main data fetcher class
+- `DataFetcher()`: Simplified data fetcher class for examples
 - `get_stock_data(ticker, period, interval)`: Fetch stock data from Yahoo Finance
 - `get_crypto_data(symbol, exchange, timeframe, limit)`: Fetch crypto data via CCXT (async)
 - `stream_btc_data(duration_seconds)`: Stream BTC data via websocket (async)
@@ -370,7 +427,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.3 → quantjourney_bidask-1.0}/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,62 @@ 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 includes a heavily optimized and enhanced implementation of the estimator proposed by Ardia, Guidotti, and Kroencke (2024). It features:
+
+- Robust numerical handling of non-positive or missing prices
+- Floating-point-safe comparisons using configurable epsilon
+- Vectorized log-return computations for faster evaluation
+- Improved error detection and early exits for invalid OHLC structures
+- Efficient rolling and expanding spread estimators
+
+These improvements make the estimator suitable for large-scale usage in backtesting, live monitoring, and production pipelines.
+
+### 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.
+
+### What's the difference between edge() and edge_rolling()?
+- `edge()` computes a point estimate over a static sample.
+- `edge_rolling()` computes rolling window estimates, optimized for speed.
+
+Both use the same core logic and yield identical results on valid, complete data.
+
 ## Installation
 
 Install the library via pip:
@@ -137,10 +199,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 +214,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
+│   └── testestimators.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 +264,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 +312,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
@@ -271,9 +328,9 @@ python examples/spread_estimator.py
 - `edge_rolling(df, window, min_periods=None)`: Rolling window estimation  
 - `edge_expanding(df, min_periods=3)`: Expanding window estimation
 
-### Data Fetching (`data/fetch.py`)
+### Data Fetching (`data/fetch.py`) - Examples & Demos
 
-- `DataFetcher()`: Main data fetcher class
+- `DataFetcher()`: Simplified data fetcher class for examples
 - `get_stock_data(ticker, period, interval)`: Fetch stock data from Yahoo Finance
 - `get_crypto_data(symbol, exchange, timeframe, limit)`: Fetch crypto data via CCXT (async)
 - `stream_btc_data(duration_seconds)`: Stream BTC data via websocket (async)
@@ -329,7 +386,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