quantjourney-bidask 0.5.0__tar.gz → 0.6.0__tar.gz

quantjourney_bidask-0.6.0/.gitignore

@@ -0,0 +1,233 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be added to the global gitignore or merged into this project gitignore.
+.idea/
+
+# VS Code
+.vscode/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+
+# Linux
+*~
+
+# PyPI credentials
+.pypirc
+
+# Temporary files
+*.tmp
+*.temp
+*.swp
+*.swo
+
+# Log files
+*.log
+
+# Database files
+*.db
+*.sqlite
+
+# Configuration files with secrets
+config.ini
+secrets.json
+.secrets
+
+# Backup files
+*.bak
+*.backup
+
+# Editor files
+*.sublime-project
+*.sublime-workspace
+
+# Pytest
+.pytest_cache/
+
+# Coverage
+.coverage
+htmlcov/
+
+# Ruff
+.ruff_cache/
+
+# Black
+.black/
+
+# isort
+.isort.cfg
+
+# Local development
+local/
+scratch/
+playground/
+
+# Documentation builds
+docs/build/
+docs/_build/
+
+# Example outputs
+examples/output/
+examples/plots/
+examples/*.png
+examples/*.jpg
+examples/*.pdf
+
+# Data files (if any)
+data/
+*.csv
+*.json
+*.xlsx
+*.parquet
+
+# Model files
+*.pkl
+*.pickle
+*.joblib
+*.h5
+*.hdf5
+
+# Jupyter notebook outputs
+*.ipynb_checkpoints/ 
+
+# Archive
+@archive/
+data_full/

{quantjourney_bidask-0.5.0 → quantjourney_bidask-0.6.0}/MANIFEST.in

@@ -6,4 +6,5 @@ include requirements.txt
 include docs/usage_examples.ipynb
 include examples/*.py
 include tests/*.py
+include data/*.py
 recursive-include quantjourney_bidask *.py

{quantjourney_bidask-0.5.0/quantjourney_bidask.egg-info → quantjourney_bidask-0.6.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: quantjourney-bidask
-Version: 0.5.0
-Summary: Efficient bid-ask spread estimator from OHLC prices
+Version: 0.6.0
+Summary: Efficient bid-ask spread estimator from OHLC prices with simplified data fetching for stocks and crypto
 Author-email: Jakub Polec <jakub@quantjourney.pro>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/QuantJourneyOrg/qj_bidask
@@ -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: ccxt>=4.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.10; extra == "dev"
@@ -54,7 +55,10 @@ This library is designed for quantitative finance professionals, researchers, an
 ## 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).
+- **Real-Time Data**: Websocket support for live cryptocurrency data from Binance and other exchanges.
+- **Data Integration**: Fetch OHLC data from Yahoo Finance and generate synthetic data for testing.
+- **Live Monitoring**: Real-time spread monitoring with animated visualizations.
+- **Local Development**: Works completely locally without cloud dependencies.
 - **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.
@@ -67,6 +71,14 @@ Install the library via pip:
 pip install quantjourney-bidask
 ```
 
+For development (local setup):
+
+```bash
+git clone https://github.com/QuantJourneyOrg/qj_bidask
+cd qj_bidask
+pip install -e .
+```
+
 ## Quick Start
 
 ### Basic Usage
@@ -89,42 +101,106 @@ print(f"Estimated bid-ask spread: {spread:.6f}")
 
 ```python
 from quantjourney_bidask import edge_rolling
+import pandas as pd
+
+# Create DataFrame with OHLC data
+df = pd.DataFrame({
+    'open': open_prices,
+    'high': high_prices,
+    'low': low_prices,
+    'close': close_prices
+})
 
 # Calculate rolling spreads with a 20-period window
-rolling_spreads = edge_rolling(
-    open_prices, high_prices, low_prices, close_prices, 
-    window=20
-)
+rolling_spreads = edge_rolling(df, window=20)
 print(f"Rolling spreads: {rolling_spreads}")
 ```
 
 ### Data Fetching Integration
 
 ```python
-from quantjourney_bidask import fetch_yfinance_data, edge
+from data.fetch import get_stock_data, get_crypto_data
+from quantjourney_bidask import edge_rolling
+import asyncio
+
+# Fetch stock data
+stock_df = get_stock_data("AAPL", period="1mo", interval="1d")
+stock_spreads = edge_rolling(stock_df, window=20)
+print(f"AAPL average spread: {stock_spreads.mean():.6f}")
+
+# Fetch crypto data (async)
+async def get_crypto_spreads():
+    crypto_df = await get_crypto_data("BTC/USDT", "binance", "1h", 168)
+    crypto_spreads = edge_rolling(crypto_df, window=24)
+    return crypto_spreads.mean()
+
+crypto_avg_spread = asyncio.run(get_crypto_spreads())
+print(f"BTC average spread: {crypto_avg_spread:.6f}")
+```
+
+### Real-time Data Streaming
+
+```python
+from data.fetch import DataFetcher
+import asyncio
+
+async def stream_btc_spreads():
+    fetcher = DataFetcher()
+    # Stream BTC data for 60 seconds
+    btc_stream = await fetcher.get_btc_1m_websocket(duration_seconds=60)
+    
+    # Calculate spread from real-time data
+    if not btc_stream.empty:
+        avg_spread_pct = (btc_stream['spread'] / btc_stream['price']).mean() * 100
+        print(f"Real-time BTC average spread: {avg_spread_pct:.4f}%")
+
+asyncio.run(stream_btc_spreads())
+```
+
+### Real-Time Spread Monitoring
+
+```python
+from data.fetch import create_spread_monitor
 
-# Fetch OHLC data for a stock
-data = fetch_yfinance_data("AAPL", period="1mo", interval="1h")
+# Create real-time spread monitor
+monitor = create_spread_monitor(["BTCUSDT", "ETHUSDT"], window=20)
 
-# Calculate spread from fetched data
-spread = edge(data['Open'], data['High'], data['Low'], data['Close'])
-print(f"AAPL spread estimate: {spread:.6f}")
+# Add callback for spread updates
+def print_spread_update(spread_data):
+    print(f"{spread_data['symbol']}: {spread_data['spread_bps']:.2f} bps")
+
+monitor.add_spread_callback(print_spread_update)
+
+# Start monitoring (uses websockets for live data)
+monitor.start_monitoring("1m")
 ```
 
-### Live Monitoring
+### Animated Real-Time Dashboard
 
 ```python
-from quantjourney_bidask import LiveSpreadMonitor
+# Run the real-time dashboard
+python examples/realtime_spread_monitor.py --mode dashboard
+
+# Or console mode
+python examples/realtime_spread_monitor.py --mode console
+```
+
+## Examples
 
-# Monitor live spreads for cryptocurrency
-monitor = LiveSpreadMonitor("BTCUSDT", window=100)
-monitor.start()
+The `examples/` directory contains comprehensive examples:
 
-# Get current spread estimate
-current_spread = monitor.get_current_spread()
-print(f"Current BTC/USDT spread: {current_spread:.6f}")
+- `spread_estimator.py` - Basic spread estimation examples
+- `spread_monitor.py` - Spread monitoring with threshold alerts
+- `realtime_spread_monitor.py` - Live websocket monitoring with animation
+- `crypto_spread_comparison.py` - Multi-asset spread comparison
+- `liquidity_risk_monitor.py` - Liquidity risk monitoring
+- `stock_liquidity_risk.py` - Stock-specific liquidity analysis
 
-monitor.stop()
+Run any example:
+
+```bash
+python examples/spread_estimator.py
+python examples/realtime_spread_monitor.py
 ```
 
 ## API Reference
@@ -132,25 +208,45 @@ monitor.stop()
 ### 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
+- `edge_rolling(df, window, min_periods=None)`: Rolling window estimation  
+- `edge_expanding(df, min_periods=3)`: Expanding window estimation
 
-### Data Fetching
+### Data Fetching (`data/fetch.py`)
 
-- `fetch_yfinance_data(symbol, period, interval)`: Fetch data from Yahoo Finance
-- `fetch_binance_data(symbol, interval, limit)`: Fetch data from Binance API
+- `fetch_yfinance_data(tickers, period, interval)`: Fetch real market data from Yahoo Finance
+- `generate_synthetic_crypto_data(symbols, hours, interval_minutes)`: Generate synthetic crypto data
+- `fetch_binance_data(*args, **kwargs)`: Compatibility function (returns synthetic data)
+- `create_realtime_stream(symbols, exchange)`: Create websocket data stream
+- `create_spread_monitor(symbols, window)`: Create real-time spread monitor
 
-### Live Monitoring
+### Real-Time Classes
 
-- `LiveSpreadMonitor(symbol, window)`: Real-time spread monitoring via WebSocket
+- `RealTimeDataStream`: Websocket data streaming for live market data
+- `RealTimeSpreadMonitor`: Real-time spread calculation and monitoring
+- `AnimatedSpreadMonitor`: Animated real-time visualization
 
 ## Requirements
 
-- Python >= 3.8
+- Python >= 3.11
 - numpy >= 1.20
 - pandas >= 1.5
 - requests >= 2.28
 - yfinance >= 0.2
+- matplotlib >= 3.5
+- websocket-client >= 1.0
+
+## WebSocket Support
+
+The library supports real-time data via websockets:
+
+- **Binance**: `wss://stream.binance.com:9443/ws/` (cryptocurrency data)
+- **Fallback**: Synthetic data generation for testing when websockets unavailable
+
+Real-time features:
+- Live spread calculation
+- Animated visualizations
+- Threshold alerts
+- Multi-symbol monitoring
 
 ## Academic Citation
 
@@ -176,6 +272,20 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 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.
 
+### Development Setup
+
+```bash
+git clone https://github.com/QuantJourneyOrg/qj_bidask
+cd qj_bidask
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run examples
+python examples/realtime_spread_monitor.py
+```
+
 ## Support
 
 - **Documentation**: [GitHub Repository](https://github.com/QuantJourneyOrg/qj_bidask)