# QuantLab - Quantitative Trading Research Platform
[](https://pypi.org/project/quantlabs/)
[](https://quantlabs.readthedocs.io/en/latest/?badge=latest)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://github.com/nittygritty-zzy/quantlab/releases)
A quantitative trading research platform powered by Microsoft's Qlib, designed for systematic alpha generation and backtesting.
📚 **[Full Documentation](https://quantlabs.readthedocs.io)** | 🚀 **[Quick Start Guide](https://quantlabs.readthedocs.io/en/latest/quickstart.html)** | 📖 **[API Reference](https://quantlabs.readthedocs.io/en/latest/api/core.html)**
## 📁 Project Structure
```
quantlab/
├── README.md # This file
├── .gitignore # Git ignore rules
├── .venv/ # Python virtual environment (uv)
│
├── docs/ # Documentation
│ ├── BACKTEST_SUMMARY.md # Backtest results analysis
│ ├── ALPHA158_SUMMARY.md # Alpha158 features documentation
│ ├── ALPHA158_CORRECTED.md # Alpha158 corrections
│ ├── USE_QLIB_ALPHA158.md # Guide for using Alpha158
│ └── QUANTMINI_README.md # QuantMini data setup
│
├── scripts/ # Utility scripts
│ ├── data/ # Data processing
│ │ ├── convert_to_qlib.py # Convert data to qlib format
│ │ ├── refresh_today_data.py # Update latest data
│ │ └── quantmini_setup.py # QuantMini data setup
│ ├── analysis/ # Analysis tools
│ │ └── visualize_results.py # Backtest visualization
│ └── tests/ # Test scripts
│ ├── test_qlib_alpha158.py # Test Alpha158 features
│ ├── test_stocks_minute_fix.py
│ └── enable_alpha158.py
│
├── configs/ # Qlib workflow configurations
│ ├── lightgbm_external_data.yaml # Full universe (all stocks)
│ ├── lightgbm_fixed_dates.yaml # 2024 only (date filter)
│ └── lightgbm_liquid_universe.yaml # Filtered liquid stocks
│
├── results/ # Backtest outputs
│ ├── visualizations/ # Charts and plots
│ │ └── backtest_visualization.png
│ └── mlruns/ # MLflow experiment tracking
│ └── 489214785307856385/ # Experiment runs
│
├── data/ # Local data storage
│ ├── parquet/ # Raw parquet files
│ └── metadata/ # Metadata files
│
├── notebooks/ # Jupyter notebooks
│ └── workflow_by_code.ipynb # Qlib workflow examples
│
├── config/ # System configuration
│ └── system_profile.yaml # System settings
│
└── qlib_repo/ # Qlib source (gitignored, 828MB)
└── (Microsoft qlib clone)
```
## 🚀 Quick Start
### Installation from PyPI
```bash
# Install from PyPI
pip install quantlabs
# Or using uv (recommended)
uv pip install quantlabs
# Verify installation
quantlab --version
quantlab --help
```
### Development Setup
```bash
# Clone the repository
git clone https://github.com/nittygritty-zzy/quantlab.git
cd quantlab
# Using uv (recommended)
uv venv
source .venv/bin/activate
uv sync
# Or using pip
python -m venv .venv
source .venv/bin/activate
pip install -e .
```
### 2. Prepare Data
```bash
# Option A: Use external data (QuantMini on /Volumes/sandisk)
# Data is already at: /Volumes/sandisk/quantmini-data/data/qlib/stocks_daily
# Option B: Download community data
wget https://github.com/chenditc/investment_data/releases/latest/download/qlib_bin.tar.gz
mkdir -p ~/.qlib/qlib_data/cn_data
tar -zxvf qlib_bin.tar.gz -C ~/.qlib/qlib_data/cn_data --strip-components=1
```
### 3. Run a Backtest
```bash
# Navigate to qlib examples (if using qlib_repo)
cd qlib_repo/examples
# Run workflow with external data
uv run qrun ../../configs/lightgbm_liquid_universe.yaml
```
### 4. Visualize Results
```bash
# Update the experiment ID in visualize_results.py, then:
uv run python scripts/analysis/visualize_results.py
```
Results will be saved to `results/visualizations/backtest_visualization.png`
## 💼 QuantLab CLI - Real-World Use Cases
QuantLab includes a powerful CLI for portfolio management, market analysis, and data queries.
### 🎬 Use Case 1: Building a Tech Portfolio
**Scenario**: Create and manage a diversified tech portfolio with FAANG+ stocks.
```bash
# Initialize QuantLab
quantlab init
# Create a tech portfolio
quantlab portfolio create tech_giants --name "FAANG+ Portfolio" \
--description "Large-cap tech companies"
# Add positions with target weights
quantlab portfolio add tech_giants AAPL GOOGL MSFT --weight 0.20
quantlab portfolio add tech_giants META AMZN --weight 0.15
quantlab portfolio add tech_giants NVDA --weight 0.10
# View your portfolio
quantlab portfolio show tech_giants
# Expected output:
# 📊 Portfolio: FAANG+ Portfolio
# 📈 Positions: 6
# ├─ AAPL │ Weight: 20.00% │ Shares: - │ Cost Basis: -
# ├─ GOOGL │ Weight: 20.00% │ Shares: - │ Cost Basis: -
# ├─ MSFT │ Weight: 20.00% │ Shares: - │ Cost Basis: -
# ├─ META │ Weight: 15.00% │ Shares: - │ Cost Basis: -
# ├─ AMZN │ Weight: 15.00% │ Shares: - │ Cost Basis: -
# └─ NVDA │ Weight: 10.00% │ Shares: - │ Cost Basis: -
# Total Weight: 100.00%
```
### 📊 Use Case 2: Real Position Tracking
**Scenario**: Track actual shares purchased at specific cost basis.
```bash
# Update positions with real trade data
quantlab portfolio update tech_giants AAPL \
--shares 50 \
--cost-basis 178.25 \
--notes "Bought on Q4 dip"
quantlab portfolio update tech_giants GOOGL \
--shares 30 \
--cost-basis 142.50 \
--notes "Post-earnings entry"
quantlab portfolio update tech_giants NVDA \
--shares 20 \
--cost-basis 485.00 \
--notes "AI boom position"
# View updated portfolio
quantlab portfolio show tech_giants
# Expected output:
# 📊 Portfolio: FAANG+ Portfolio
# 📈 Positions: 6
# ├─ AAPL │ Weight: 20.00% │ Shares: 50 │ Cost: $178.25 │ "Bought on Q4 dip"
# ├─ GOOGL │ Weight: 20.00% │ Shares: 30 │ Cost: $142.50 │ "Post-earnings entry"
# ├─ NVDA │ Weight: 10.00% │ Shares: 20 │ Cost: $485.00 │ "AI boom position"
# Total Investment: $22,812.50
```
### 🔍 Use Case 3: Analyzing a Stock Before Purchase
**Scenario**: Deep-dive analysis on ORCL before adding to portfolio.
```bash
# Comprehensive analysis with all data sources
quantlab analyze ticker ORCL \
--include-fundamentals \
--include-options \
--include-sentiment \
--include-technicals \
--output results/orcl_analysis.json
# Expected output:
# 🔍 Analyzing ORCL (Oracle Corporation)
#
# 📈 Price Information:
# Current: $145.50
# Change: +2.3% ($3.25)
# Volume: 5,234,567
#
# 💰 Fundamentals:
# Market Cap: $401.2B
# P/E Ratio: 28.5
# Forward P/E: 21.2
# Revenue Growth: 7.2%
# Profit Margin: 21.5%
# Debt/Equity: 2.84
#
# 📊 Options Activity:
# Put/Call Ratio: 0.78 (Bullish)
# Implied Volatility: 22.5%
# Next Earnings: 2025-03-15 (30 days)
#
# 📰 Sentiment Analysis:
# Score: 0.72 (Positive)
# Articles: 45 (7 days)
# Buzz: High
#
# 🎯 Analyst Consensus:
# Rating: Buy (12) / Hold (8) / Sell (2)
# Target Price: $165.00 (+13.4%)
#
# ✅ Analysis complete → results/orcl_analysis.json
# Visualize price action
quantlab visualize price ORCL --period 90d --chart-type candlestick
quantlab visualize price ORCL --period 1year --chart-type line
# Quick decision check
quantlab lookup get company ORCL
quantlab lookup get ratings ORCL
```
### 📈 Use Case 4: Portfolio-Wide Analysis
**Scenario**: Analyze all positions in your tech portfolio.
```bash
# Analyze entire portfolio
quantlab analyze portfolio tech_giants \
--include-options \
--aggregate-metrics \
--output results/tech_giants_analysis.json
# Expected output:
# 📊 Analyzing Portfolio: FAANG+ Portfolio (6 positions)
#
# Processing: [████████████████████] 6/6
#
# Individual Analyses:
# ✓ AAPL │ Score: 82/100 │ Sentiment: Positive │ Analysts: 85% Buy
# ✓ GOOGL │ Score: 78/100 │ Sentiment: Positive │ Analysts: 80% Buy
# ✓ MSFT │ Score: 88/100 │ Sentiment: Very Positive │ Analysts: 90% Buy
# ✓ META │ Score: 75/100 │ Sentiment: Neutral │ Analysts: 75% Buy
# ✓ AMZN │ Score: 81/100 │ Sentiment: Positive │ Analysts: 82% Buy
# ⚠ NVDA │ Score: 68/100 │ Sentiment: Mixed │ Analysts: 70% Buy
#
# Portfolio Metrics:
# Total Value: $52,450
# Avg P/E: 32.5
# Avg Sentiment: 0.68 (Positive)
# Portfolio Beta: 1.15
# Weighted Analyst Rating: 80% Buy
#
# ⚠️ Alerts:
# - NVDA showing weakness (consider reducing position)
# - MSFT strongest performer (98% of analysts bullish)
# Visualize portfolio performance comparison
quantlab visualize compare AAPL GOOGL MSFT META AMZN NVDA \
--period 90d \
--normalize \
--output results/tech_giants_comparison.html
```
### 🔎 Use Case 5: Querying Historical Data
**Scenario**: Research historical price patterns for backtesting.
```bash
# Query daily stock data
quantlab data query AAPL GOOGL MSFT \
--start 2024-01-01 \
--end 2025-01-15 \
--type stocks_daily \
--limit 100
# Expected output:
# 📊 Querying data for 3 tickers...
#
# AAPL (Apple Inc.)
# Date Range: 2024-01-01 to 2025-01-15 (252 trading days)
#
# Recent Data (last 5 days):
# Date │ Open │ High │ Low │ Close │ Volume
# 2025-01-15 │ $180.25 │ $182.50 │ $179.80 │ $181.75 │ 52.3M
# 2025-01-14 │ $179.50 │ $181.25 │ $178.90 │ $180.25 │ 48.7M
# ...
#
# Performance: +15.3% YTD
# Volatility: 18.5% (annualized)
# Visualize historical price patterns
quantlab visualize price AAPL --period 2year --chart-type candlestick
quantlab visualize price AAPL --interval 5min --period 5d --chart-type line
# Check available data coverage
quantlab data check
# Expected output:
# 📁 Parquet Data Availability
# ✓ stocks_daily │ 13,187 tickers │ 2024-09-01 to 2025-10-15 (442 days)
# ✓ stocks_minute │ 8,523 tickers │ Last 90 days
# ✓ options_daily │ 3,245 tickers │ 2024-09-01 to 2025-10-15
# ✗ options_minute │ Not available
```
### 🏦 Use Case 6: Maintaining Reference Data
**Scenario**: Keep company info and analyst ratings up-to-date.
```bash
# Initialize lookup tables
quantlab lookup init
# Refresh data for your portfolio
quantlab lookup refresh portfolio tech_giants
# Expected output:
# 🔄 Refreshing data for 6 tickers in tech_giants...
#
# Company Info:
# ✓ AAPL - Apple Inc. (Technology - Consumer Electronics)
# ✓ GOOGL - Alphabet Inc. (Technology - Internet Services)
# ✓ MSFT - Microsoft Corporation (Technology - Software)
# ✓ META - Meta Platforms Inc. (Technology - Social Media)
# ✓ AMZN - Amazon.com Inc. (Consumer Cyclical - Internet Retail)
# ✓ NVDA - NVIDIA Corporation (Technology - Semiconductors)
#
# Analyst Ratings:
# ✓ AAPL - 35 analysts (Buy: 28, Hold: 6, Sell: 1) Target: $210
# ✓ GOOGL - 42 analysts (Buy: 35, Hold: 6, Sell: 1) Target: $165
# ✓ MSFT - 48 analysts (Buy: 43, Hold: 4, Sell: 1) Target: $450
# ✓ META - 38 analysts (Buy: 28, Hold: 8, Sell: 2) Target: $520
# ✓ AMZN - 45 analysts (Buy: 38, Hold: 6, Sell: 1) Target: $215
# ✓ NVDA - 40 analysts (Buy: 32, Hold: 7, Sell: 1) Target: $850
#
# ✅ Refresh complete (6/6 successful)
# View stored data
quantlab lookup stats
# Expected output:
# 📊 Lookup Tables Statistics
#
# Company Information: 6 companies
# Analyst Ratings: 6 tickers (248 total analysts)
# Treasury Rates: Current (updated: 2025-10-15)
# Last Updated: 2025-10-15 14:32:15
```
### 🎯 Use Case 7: Multi-Portfolio Strategy
**Scenario**: Manage multiple portfolios for different strategies.
```bash
# Create portfolios for different strategies
quantlab portfolio create growth --name "High Growth" \
--description "Growth stocks with P/E > 30"
quantlab portfolio create value --name "Value Plays" \
--description "Undervalued stocks with P/E < 15"
quantlab portfolio create dividend --name "Dividend Income" \
--description "High dividend yield stocks"
# Add different stocks to each
quantlab portfolio add growth NVDA TSLA SNOW --weight 0.33
quantlab portfolio add value BAC JPM WFC --weight 0.33
quantlab portfolio add dividend T VZ SO --weight 0.33
# View all portfolios
quantlab portfolio list
# Expected output:
# 📊 Your Portfolios
#
# Portfolio ID │ Name │ Positions │ Total Weight │ Last Updated
# ────────────────┼───────────────────┼───────────┼──────────────┼─────────────
# tech_giants │ FAANG+ Portfolio │ 6 │ 100.00% │ 2025-10-15
# growth │ High Growth │ 3 │ 99.00% │ 2025-10-15
# value │ Value Plays │ 3 │ 99.00% │ 2025-10-15
# dividend │ Dividend Income │ 3 │ 99.00% │ 2025-10-15
#
# Total Portfolios: 4
# Total Unique Positions: 15
```
### 🔬 Use Case 8: Options Strategy Research
**Scenario**: Research options opportunities for covered calls.
```bash
# Analyze ticker specifically for options
quantlab analyze ticker AAPL \
--include-options \
--no-fundamentals \
--no-sentiment \
--output results/aapl_options.json
# Expected output:
# 🔍 Options Analysis: AAPL
#
# Current Price: $181.75
#
# Near-Term Expiration (30 days):
# Call Options (Covered Call Candidates):
# Strike │ Premium │ IV │ Delta │ Break-even │ Return
# ───────┼─────────┼───────┼───────┼────────────┼────────
# $185 │ $3.85 │ 21.2% │ 0.45 │ $185.00 │ 2.1%
# $190 │ $2.15 │ 19.8% │ 0.28 │ $190.00 │ 4.6%
# $195 │ $0.95 │ 18.5% │ 0.15 │ $195.00 │ 7.3%
#
# Put Options (Cash-Secured Put Candidates):
# Strike │ Premium │ IV │ Delta │ Net Cost │ Yield
# ───────┼─────────┼───────┼───────┼────────────┼────────
# $175 │ $2.80 │ 22.5% │ -0.35 │ $172.20 │ 1.6%
# $170 │ $1.45 │ 20.1% │ -0.20 │ $168.55 │ 0.9%
#
# Volatility Metrics:
# Current IV: 21.2%
# Historical Vol (30d): 18.5%
# IV Percentile: 62% (Elevated)
#
# 💡 Suggestion: Good conditions for selling premium
# IV elevated vs historical - consider covered calls at $190 strike
# Visualize options payoff diagrams
quantlab visualize options long_call --current-price 181.75 --strike 190 --premium 2.15
quantlab visualize options bull_call_spread \
--current-price 181.75 --strike1 185 --strike2 195 --premium 1.70
```
### 📅 Use Case 9: Regular Portfolio Review
**Scenario**: Monthly portfolio review workflow.
```bash
# Step 1: Refresh all market data
quantlab lookup refresh portfolio tech_giants
# Step 2: Get comprehensive analysis
quantlab analyze portfolio tech_giants --aggregate-metrics
# Step 3: Visualize portfolio performance
quantlab visualize compare AAPL GOOGL MSFT META AMZN NVDA --period 30d --normalize
# Step 4: Review individual positions
quantlab visualize price AAPL --period 90d --chart-type candlestick
quantlab visualize price NVDA --period 90d --chart-type candlestick
# Step 5: Check for rebalancing needs
quantlab portfolio show tech_giants
# Step 6: Look for new opportunities
quantlab data tickers --type stocks_daily | grep -E "^[A-Z]{1,4}$" | head -20
quantlab analyze ticker CRM --include-fundamentals
quantlab visualize price CRM --period 90d --chart-type candlestick
# Step 7: Update positions based on analysis
quantlab portfolio update tech_giants NVDA --weight 0.05 --notes "Reduced - valuation concerns"
quantlab portfolio add tech_giants CRM --weight 0.05 --notes "New position - cloud growth"
# Step 8: Export for records
quantlab analyze portfolio tech_giants --output results/monthly_review_2025_10.json
```
### 🚨 Use Case 10: Risk Monitoring
**Scenario**: Monitor portfolio risk daily.
```bash
# Create a monitoring script
cat > scripts/daily_monitor.sh << 'EOF'
#!/bin/bash
DATE=$(date +%Y-%m-%d)
echo "🔍 Daily Portfolio Monitor - $DATE"
echo "=================================="
# Analyze each portfolio
for portfolio in tech_giants growth value dividend; do
echo ""
echo "📊 Portfolio: $portfolio"
quantlab analyze portfolio $portfolio \
--include-options \
--output "results/monitoring/${portfolio}_${DATE}.json" 2>&1 | \
grep -E "(Score:|Sentiment:|Analysts:|⚠|❌)"
done
# Check treasury rates for risk-free rate
echo ""
echo "📈 Current Treasury Rates:"
quantlab lookup get treasury 10y
echo ""
echo "✅ Monitoring complete"
EOF
chmod +x scripts/daily_monitor.sh
# Run daily monitoring
./scripts/daily_monitor.sh
# Expected output:
# 🔍 Daily Portfolio Monitor - 2025-10-15
# ==================================
#
# 📊 Portfolio: tech_giants
# ✓ AAPL │ Score: 82/100 │ Sentiment: Positive
# ✓ GOOGL │ Score: 78/100 │ Sentiment: Positive
# ⚠ NVDA │ Score: 68/100 │ Sentiment: Mixed
#
# 📈 Current Treasury Rates:
# 10-Year Treasury: 4.25% (as of 2025-10-15)
#
# ✅ Monitoring complete
```
## 📊 Available Configurations
### 1. **Liquid Universe** (Recommended)
- **File**: `configs/lightgbm_liquid_universe.yaml`
- **Universe**: 13,187 stocks (filtered - no warrants, units)
- **Period**: Sept 2024 - Sept 2025
- **Best for**: Realistic backtesting with tradable stocks
### 2. **Fixed Dates**
- **File**: `configs/lightgbm_fixed_dates.yaml`
- **Universe**: All stocks
- **Period**: July 2024 - Dec 2024
- **Best for**: Testing on stable period
### 3. **Full Universe**
- **File**: `configs/lightgbm_external_data.yaml`
- **Universe**: All 14,310 instruments (includes warrants, penny stocks)
- **Period**: Sept 2024 - Sept 2025
- **Best for**: Maximum alpha discovery (but risky)
## 🎯 Key Metrics from Latest Runs
| Configuration | IC | Rank IC | Sharpe | Max DD | Universe Size |
|--------------|-----|---------|--------|--------|---------------|
| Liquid Universe | 0.066 | -0.006 | 3.94 | -39.2% | 13,187 |
| Fixed Dates | 0.079 | -0.008 | 4.54 | -35.3% | 14,310 |
| Full Universe | 0.080 | -0.004 | 2.98 | -41.7% | 14,310 |
**IC (Information Coefficient)**: 0.06-0.08 is good - shows predictive power
**Rank IC**: Near zero - model struggles with relative ranking
**Sharpe Ratio**: 2.98-4.54 - excellent risk-adjusted returns
## 📊 Visualization Capabilities
QuantLab includes comprehensive interactive visualization tools powered by Plotly.
### Price Charts
```bash
# Candlestick charts (daily data)
quantlab visualize price AAPL --period 90d --chart-type candlestick
# Line charts with volume
quantlab visualize price AAPL --period 1year --chart-type line
# Intraday charts (5min, 15min, 1hour intervals)
quantlab visualize price AAPL --interval 5min --period 5d --chart-type candlestick
quantlab visualize price NVDA --interval 1hour --period 30d --chart-type line
```
**Features:**
- Multiple timeframes: 1d, 5d, 30d, 90d, 1year, 2year
- Intraday intervals: 1min, 5min, 15min, 1hour
- Categorical x-axis for gap-free intraday charts
- Timezone-aware (US Eastern Time)
- Regular market hours filtering (9:30 AM - 4:00 PM ET)
**Example Charts:**
- [Daily Candlestick (90d)](docs/images/price_candlestick_90d.html)
- [Intraday 5-minute Line](docs/images/price_intraday_5min.html)
### Multi-Ticker Comparison
```bash
# Compare normalized performance
quantlab visualize compare AAPL GOOGL MSFT --period 90d --normalize
# Absolute price comparison
quantlab visualize compare AAPL GOOGL MSFT --period 1year
```
**Example Chart:**
- [Normalized Comparison (90d)](docs/images/comparison_normalized.html)
### Options Payoff Diagrams
```bash
# Single leg strategies
quantlab visualize options long_call --current-price 180 --strike 190 --premium 2.15
quantlab visualize options long_put --current-price 180 --strike 175 --premium 2.80
# Spread strategies
quantlab visualize options bull_call_spread \
--current-price 180 --strike1 185 --strike2 195 --premium 1.70
quantlab visualize options iron_condor \
--current-price 180 --strike1 170 --strike2 175 --strike3 195 --strike4 200
```
**Available Strategies:**
- Single: `long_call`, `long_put`, `short_call`, `short_put`
- Spreads: `bull_call_spread`, `bear_put_spread`, `iron_condor`, `butterfly`
- Volatility: `long_straddle`, `short_straddle`, `long_strangle`, `short_strangle`
**Example Chart:**
- [Bull Call Spread Payoff](docs/images/options_bull_call_spread.html)
### Backtest Results
```bash
# Visualize backtest performance
quantlab visualize backtest results/mlruns/[experiment_id]
```
**Metrics Displayed:**
- Cumulative returns vs benchmark
- Drawdown analysis
- Rolling Sharpe ratio
- Win/loss distribution
- Monthly returns heatmap
## 📚 Documentation
- **[BACKTEST_SUMMARY.md](docs/BACKTEST_SUMMARY.md)** - Comprehensive analysis of backtest results, root cause analysis, and recommendations
- **[ALPHA158_SUMMARY.md](docs/ALPHA158_SUMMARY.md)** - Overview of Alpha158 features used
- **[USE_QLIB_ALPHA158.md](docs/USE_QLIB_ALPHA158.md)** - How to use Alpha158 in your strategies
- **[CLI_VISUALIZATION_GUIDE.md](docs/CLI_VISUALIZATION_GUIDE.md)** - Complete guide to visualization features
## 🔧 Data Setup
### External Data Location
```
/Volumes/sandisk/quantmini-data/data/qlib/stocks_daily/
├── calendars/day.txt # Trading calendar (442 days)
├── instruments/
│ ├── all.txt # All 14,310 instruments
│ └── liquid_stocks.txt # Filtered 13,187 instruments
└── features/ # Stock price data (OHLCV)
```
### Creating Custom Universe Filters
```python
# See scripts/data/ for examples
# Filter by:
# - Market cap
# - Average volume
# - Exclude warrants/units
# - Sector/industry
```
## 🧪 Testing
```bash
# Test Alpha158 features
python scripts/tests/test_qlib_alpha158.py
# Test data conversion
python scripts/data/convert_to_qlib.py
# Refresh latest data
python scripts/data/refresh_today_data.py
```
## 🔍 Next Steps
### Improve Model Performance
1. **Fix Rank IC** - Try ensemble models (XGBoost, TabNet, LSTM)
2. **Better features** - Add momentum, volatility, cross-sectional features
3. **Risk controls** - Add position limits, volatility weighting
### Data Quality
1. Validate corporate actions (splits, dividends)
2. Check for survivorship bias
3. Add liquidity filters (min volume, market cap)
### Alternative Strategies
1. Market-neutral long-short
2. Factor-based weighting
3. Multi-timeframe approaches
## 📝 Notes
- **Data Source**: External data from QuantMini (US stocks, daily, 2024-2025)
- **ML Framework**: Qlib by Microsoft Research
- **Models Tested**: LightGBM with Alpha158 features
- **Tracking**: MLflow for experiment management
## ⚠️ Known Issues
1. **Unrealistic backtest returns** - Investigating data quality and backtest engine
2. **Rank IC near zero** - Model can predict returns but not rank stocks well
3. **High volatility** - Some instruments show extreme price movements
4. See [BACKTEST_SUMMARY.md](docs/BACKTEST_SUMMARY.md) for detailed analysis
## 🤝 Contributing
This is a research project. Key areas for improvement:
- Better universe filters
- Alternative features
- Improved ranking models
- Risk management strategies
## 📄 License
Research and educational purposes.
## 🔗 Resources
- [Qlib Documentation](https://qlib.readthedocs.io/)
- [Qlib GitHub](https://github.com/microsoft/qlib)
- [Alpha158 Paper](https://arxiv.org/abs/2107.08321)
Raw data
{
"_id": null,
"home_page": null,
"name": "quantlabs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "nittygritty-zzy <nittygritty-zzy@users.noreply.github.com>",
"keywords": "algorithmic-trading, backtesting, data-visualization, financial-analysis, machine-learning, options-trading, portfolio-management, qlib, quantitative-finance",
"author": null,
"author_email": "nittygritty-zzy <nittygritty-zzy@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/4c/35/e5ff0c7e9fcc338d5f1ebbd987f6ae02725565e1b2069fdd27858c19491a/quantlabs-0.2.1.tar.gz",
"platform": null,
"description": "# QuantLab - Quantitative Trading Research Platform\n\n[](https://pypi.org/project/quantlabs/)\n[](https://quantlabs.readthedocs.io/en/latest/?badge=latest)\n[](https://www.python.org/downloads/)\n[](LICENSE)\n[](https://github.com/nittygritty-zzy/quantlab/releases)\n\nA quantitative trading research platform powered by Microsoft's Qlib, designed for systematic alpha generation and backtesting.\n\n\ud83d\udcda **[Full Documentation](https://quantlabs.readthedocs.io)** | \ud83d\ude80 **[Quick Start Guide](https://quantlabs.readthedocs.io/en/latest/quickstart.html)** | \ud83d\udcd6 **[API Reference](https://quantlabs.readthedocs.io/en/latest/api/core.html)**\n\n## \ud83d\udcc1 Project Structure\n\n```\nquantlab/\n\u251c\u2500\u2500 README.md # This file\n\u251c\u2500\u2500 .gitignore # Git ignore rules\n\u251c\u2500\u2500 .venv/ # Python virtual environment (uv)\n\u2502\n\u251c\u2500\u2500 docs/ # Documentation\n\u2502 \u251c\u2500\u2500 BACKTEST_SUMMARY.md # Backtest results analysis\n\u2502 \u251c\u2500\u2500 ALPHA158_SUMMARY.md # Alpha158 features documentation\n\u2502 \u251c\u2500\u2500 ALPHA158_CORRECTED.md # Alpha158 corrections\n\u2502 \u251c\u2500\u2500 USE_QLIB_ALPHA158.md # Guide for using Alpha158\n\u2502 \u2514\u2500\u2500 QUANTMINI_README.md # QuantMini data setup\n\u2502\n\u251c\u2500\u2500 scripts/ # Utility scripts\n\u2502 \u251c\u2500\u2500 data/ # Data processing\n\u2502 \u2502 \u251c\u2500\u2500 convert_to_qlib.py # Convert data to qlib format\n\u2502 \u2502 \u251c\u2500\u2500 refresh_today_data.py # Update latest data\n\u2502 \u2502 \u2514\u2500\u2500 quantmini_setup.py # QuantMini data setup\n\u2502 \u251c\u2500\u2500 analysis/ # Analysis tools\n\u2502 \u2502 \u2514\u2500\u2500 visualize_results.py # Backtest visualization\n\u2502 \u2514\u2500\u2500 tests/ # Test scripts\n\u2502 \u251c\u2500\u2500 test_qlib_alpha158.py # Test Alpha158 features\n\u2502 \u251c\u2500\u2500 test_stocks_minute_fix.py\n\u2502 \u2514\u2500\u2500 enable_alpha158.py\n\u2502\n\u251c\u2500\u2500 configs/ # Qlib workflow configurations\n\u2502 \u251c\u2500\u2500 lightgbm_external_data.yaml # Full universe (all stocks)\n\u2502 \u251c\u2500\u2500 lightgbm_fixed_dates.yaml # 2024 only (date filter)\n\u2502 \u2514\u2500\u2500 lightgbm_liquid_universe.yaml # Filtered liquid stocks\n\u2502\n\u251c\u2500\u2500 results/ # Backtest outputs\n\u2502 \u251c\u2500\u2500 visualizations/ # Charts and plots\n\u2502 \u2502 \u2514\u2500\u2500 backtest_visualization.png\n\u2502 \u2514\u2500\u2500 mlruns/ # MLflow experiment tracking\n\u2502 \u2514\u2500\u2500 489214785307856385/ # Experiment runs\n\u2502\n\u251c\u2500\u2500 data/ # Local data storage\n\u2502 \u251c\u2500\u2500 parquet/ # Raw parquet files\n\u2502 \u2514\u2500\u2500 metadata/ # Metadata files\n\u2502\n\u251c\u2500\u2500 notebooks/ # Jupyter notebooks\n\u2502 \u2514\u2500\u2500 workflow_by_code.ipynb # Qlib workflow examples\n\u2502\n\u251c\u2500\u2500 config/ # System configuration\n\u2502 \u2514\u2500\u2500 system_profile.yaml # System settings\n\u2502\n\u2514\u2500\u2500 qlib_repo/ # Qlib source (gitignored, 828MB)\n \u2514\u2500\u2500 (Microsoft qlib clone)\n```\n\n## \ud83d\ude80 Quick Start\n\n### Installation from PyPI\n\n```bash\n# Install from PyPI\npip install quantlabs\n\n# Or using uv (recommended)\nuv pip install quantlabs\n\n# Verify installation\nquantlab --version\nquantlab --help\n```\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/nittygritty-zzy/quantlab.git\ncd quantlab\n\n# Using uv (recommended)\nuv venv\nsource .venv/bin/activate\nuv sync\n\n# Or using pip\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\n```\n\n### 2. Prepare Data\n\n```bash\n# Option A: Use external data (QuantMini on /Volumes/sandisk)\n# Data is already at: /Volumes/sandisk/quantmini-data/data/qlib/stocks_daily\n\n# Option B: Download community data\nwget https://github.com/chenditc/investment_data/releases/latest/download/qlib_bin.tar.gz\nmkdir -p ~/.qlib/qlib_data/cn_data\ntar -zxvf qlib_bin.tar.gz -C ~/.qlib/qlib_data/cn_data --strip-components=1\n```\n\n### 3. Run a Backtest\n\n```bash\n# Navigate to qlib examples (if using qlib_repo)\ncd qlib_repo/examples\n\n# Run workflow with external data\nuv run qrun ../../configs/lightgbm_liquid_universe.yaml\n```\n\n### 4. Visualize Results\n\n```bash\n# Update the experiment ID in visualize_results.py, then:\nuv run python scripts/analysis/visualize_results.py\n```\n\nResults will be saved to `results/visualizations/backtest_visualization.png`\n\n## \ud83d\udcbc QuantLab CLI - Real-World Use Cases\n\nQuantLab includes a powerful CLI for portfolio management, market analysis, and data queries.\n\n### \ud83c\udfac Use Case 1: Building a Tech Portfolio\n\n**Scenario**: Create and manage a diversified tech portfolio with FAANG+ stocks.\n\n```bash\n# Initialize QuantLab\nquantlab init\n\n# Create a tech portfolio\nquantlab portfolio create tech_giants --name \"FAANG+ Portfolio\" \\\n --description \"Large-cap tech companies\"\n\n# Add positions with target weights\nquantlab portfolio add tech_giants AAPL GOOGL MSFT --weight 0.20\nquantlab portfolio add tech_giants META AMZN --weight 0.15\nquantlab portfolio add tech_giants NVDA --weight 0.10\n\n# View your portfolio\nquantlab portfolio show tech_giants\n\n# Expected output:\n# \ud83d\udcca Portfolio: FAANG+ Portfolio\n# \ud83d\udcc8 Positions: 6\n# \u251c\u2500 AAPL \u2502 Weight: 20.00% \u2502 Shares: - \u2502 Cost Basis: -\n# \u251c\u2500 GOOGL \u2502 Weight: 20.00% \u2502 Shares: - \u2502 Cost Basis: -\n# \u251c\u2500 MSFT \u2502 Weight: 20.00% \u2502 Shares: - \u2502 Cost Basis: -\n# \u251c\u2500 META \u2502 Weight: 15.00% \u2502 Shares: - \u2502 Cost Basis: -\n# \u251c\u2500 AMZN \u2502 Weight: 15.00% \u2502 Shares: - \u2502 Cost Basis: -\n# \u2514\u2500 NVDA \u2502 Weight: 10.00% \u2502 Shares: - \u2502 Cost Basis: -\n# Total Weight: 100.00%\n```\n\n### \ud83d\udcca Use Case 2: Real Position Tracking\n\n**Scenario**: Track actual shares purchased at specific cost basis.\n\n```bash\n# Update positions with real trade data\nquantlab portfolio update tech_giants AAPL \\\n --shares 50 \\\n --cost-basis 178.25 \\\n --notes \"Bought on Q4 dip\"\n\nquantlab portfolio update tech_giants GOOGL \\\n --shares 30 \\\n --cost-basis 142.50 \\\n --notes \"Post-earnings entry\"\n\nquantlab portfolio update tech_giants NVDA \\\n --shares 20 \\\n --cost-basis 485.00 \\\n --notes \"AI boom position\"\n\n# View updated portfolio\nquantlab portfolio show tech_giants\n\n# Expected output:\n# \ud83d\udcca Portfolio: FAANG+ Portfolio\n# \ud83d\udcc8 Positions: 6\n# \u251c\u2500 AAPL \u2502 Weight: 20.00% \u2502 Shares: 50 \u2502 Cost: $178.25 \u2502 \"Bought on Q4 dip\"\n# \u251c\u2500 GOOGL \u2502 Weight: 20.00% \u2502 Shares: 30 \u2502 Cost: $142.50 \u2502 \"Post-earnings entry\"\n# \u251c\u2500 NVDA \u2502 Weight: 10.00% \u2502 Shares: 20 \u2502 Cost: $485.00 \u2502 \"AI boom position\"\n# Total Investment: $22,812.50\n```\n\n### \ud83d\udd0d Use Case 3: Analyzing a Stock Before Purchase\n\n**Scenario**: Deep-dive analysis on ORCL before adding to portfolio.\n\n```bash\n# Comprehensive analysis with all data sources\nquantlab analyze ticker ORCL \\\n --include-fundamentals \\\n --include-options \\\n --include-sentiment \\\n --include-technicals \\\n --output results/orcl_analysis.json\n\n# Expected output:\n# \ud83d\udd0d Analyzing ORCL (Oracle Corporation)\n#\n# \ud83d\udcc8 Price Information:\n# Current: $145.50\n# Change: +2.3% ($3.25)\n# Volume: 5,234,567\n#\n# \ud83d\udcb0 Fundamentals:\n# Market Cap: $401.2B\n# P/E Ratio: 28.5\n# Forward P/E: 21.2\n# Revenue Growth: 7.2%\n# Profit Margin: 21.5%\n# Debt/Equity: 2.84\n#\n# \ud83d\udcca Options Activity:\n# Put/Call Ratio: 0.78 (Bullish)\n# Implied Volatility: 22.5%\n# Next Earnings: 2025-03-15 (30 days)\n#\n# \ud83d\udcf0 Sentiment Analysis:\n# Score: 0.72 (Positive)\n# Articles: 45 (7 days)\n# Buzz: High\n#\n# \ud83c\udfaf Analyst Consensus:\n# Rating: Buy (12) / Hold (8) / Sell (2)\n# Target Price: $165.00 (+13.4%)\n#\n# \u2705 Analysis complete \u2192 results/orcl_analysis.json\n\n# Visualize price action\nquantlab visualize price ORCL --period 90d --chart-type candlestick\nquantlab visualize price ORCL --period 1year --chart-type line\n\n# Quick decision check\nquantlab lookup get company ORCL\nquantlab lookup get ratings ORCL\n```\n\n### \ud83d\udcc8 Use Case 4: Portfolio-Wide Analysis\n\n**Scenario**: Analyze all positions in your tech portfolio.\n\n```bash\n# Analyze entire portfolio\nquantlab analyze portfolio tech_giants \\\n --include-options \\\n --aggregate-metrics \\\n --output results/tech_giants_analysis.json\n\n# Expected output:\n# \ud83d\udcca Analyzing Portfolio: FAANG+ Portfolio (6 positions)\n#\n# Processing: [\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588] 6/6\n#\n# Individual Analyses:\n# \u2713 AAPL \u2502 Score: 82/100 \u2502 Sentiment: Positive \u2502 Analysts: 85% Buy\n# \u2713 GOOGL \u2502 Score: 78/100 \u2502 Sentiment: Positive \u2502 Analysts: 80% Buy\n# \u2713 MSFT \u2502 Score: 88/100 \u2502 Sentiment: Very Positive \u2502 Analysts: 90% Buy\n# \u2713 META \u2502 Score: 75/100 \u2502 Sentiment: Neutral \u2502 Analysts: 75% Buy\n# \u2713 AMZN \u2502 Score: 81/100 \u2502 Sentiment: Positive \u2502 Analysts: 82% Buy\n# \u26a0 NVDA \u2502 Score: 68/100 \u2502 Sentiment: Mixed \u2502 Analysts: 70% Buy\n#\n# Portfolio Metrics:\n# Total Value: $52,450\n# Avg P/E: 32.5\n# Avg Sentiment: 0.68 (Positive)\n# Portfolio Beta: 1.15\n# Weighted Analyst Rating: 80% Buy\n#\n# \u26a0\ufe0f Alerts:\n# - NVDA showing weakness (consider reducing position)\n# - MSFT strongest performer (98% of analysts bullish)\n\n# Visualize portfolio performance comparison\nquantlab visualize compare AAPL GOOGL MSFT META AMZN NVDA \\\n --period 90d \\\n --normalize \\\n --output results/tech_giants_comparison.html\n```\n\n### \ud83d\udd0e Use Case 5: Querying Historical Data\n\n**Scenario**: Research historical price patterns for backtesting.\n\n```bash\n# Query daily stock data\nquantlab data query AAPL GOOGL MSFT \\\n --start 2024-01-01 \\\n --end 2025-01-15 \\\n --type stocks_daily \\\n --limit 100\n\n# Expected output:\n# \ud83d\udcca Querying data for 3 tickers...\n#\n# AAPL (Apple Inc.)\n# Date Range: 2024-01-01 to 2025-01-15 (252 trading days)\n#\n# Recent Data (last 5 days):\n# Date \u2502 Open \u2502 High \u2502 Low \u2502 Close \u2502 Volume\n# 2025-01-15 \u2502 $180.25 \u2502 $182.50 \u2502 $179.80 \u2502 $181.75 \u2502 52.3M\n# 2025-01-14 \u2502 $179.50 \u2502 $181.25 \u2502 $178.90 \u2502 $180.25 \u2502 48.7M\n# ...\n#\n# Performance: +15.3% YTD\n# Volatility: 18.5% (annualized)\n\n# Visualize historical price patterns\nquantlab visualize price AAPL --period 2year --chart-type candlestick\nquantlab visualize price AAPL --interval 5min --period 5d --chart-type line\n\n# Check available data coverage\nquantlab data check\n\n# Expected output:\n# \ud83d\udcc1 Parquet Data Availability\n# \u2713 stocks_daily \u2502 13,187 tickers \u2502 2024-09-01 to 2025-10-15 (442 days)\n# \u2713 stocks_minute \u2502 8,523 tickers \u2502 Last 90 days\n# \u2713 options_daily \u2502 3,245 tickers \u2502 2024-09-01 to 2025-10-15\n# \u2717 options_minute \u2502 Not available\n```\n\n### \ud83c\udfe6 Use Case 6: Maintaining Reference Data\n\n**Scenario**: Keep company info and analyst ratings up-to-date.\n\n```bash\n# Initialize lookup tables\nquantlab lookup init\n\n# Refresh data for your portfolio\nquantlab lookup refresh portfolio tech_giants\n\n# Expected output:\n# \ud83d\udd04 Refreshing data for 6 tickers in tech_giants...\n#\n# Company Info:\n# \u2713 AAPL - Apple Inc. (Technology - Consumer Electronics)\n# \u2713 GOOGL - Alphabet Inc. (Technology - Internet Services)\n# \u2713 MSFT - Microsoft Corporation (Technology - Software)\n# \u2713 META - Meta Platforms Inc. (Technology - Social Media)\n# \u2713 AMZN - Amazon.com Inc. (Consumer Cyclical - Internet Retail)\n# \u2713 NVDA - NVIDIA Corporation (Technology - Semiconductors)\n#\n# Analyst Ratings:\n# \u2713 AAPL - 35 analysts (Buy: 28, Hold: 6, Sell: 1) Target: $210\n# \u2713 GOOGL - 42 analysts (Buy: 35, Hold: 6, Sell: 1) Target: $165\n# \u2713 MSFT - 48 analysts (Buy: 43, Hold: 4, Sell: 1) Target: $450\n# \u2713 META - 38 analysts (Buy: 28, Hold: 8, Sell: 2) Target: $520\n# \u2713 AMZN - 45 analysts (Buy: 38, Hold: 6, Sell: 1) Target: $215\n# \u2713 NVDA - 40 analysts (Buy: 32, Hold: 7, Sell: 1) Target: $850\n#\n# \u2705 Refresh complete (6/6 successful)\n\n# View stored data\nquantlab lookup stats\n\n# Expected output:\n# \ud83d\udcca Lookup Tables Statistics\n#\n# Company Information: 6 companies\n# Analyst Ratings: 6 tickers (248 total analysts)\n# Treasury Rates: Current (updated: 2025-10-15)\n# Last Updated: 2025-10-15 14:32:15\n```\n\n### \ud83c\udfaf Use Case 7: Multi-Portfolio Strategy\n\n**Scenario**: Manage multiple portfolios for different strategies.\n\n```bash\n# Create portfolios for different strategies\nquantlab portfolio create growth --name \"High Growth\" \\\n --description \"Growth stocks with P/E > 30\"\n\nquantlab portfolio create value --name \"Value Plays\" \\\n --description \"Undervalued stocks with P/E < 15\"\n\nquantlab portfolio create dividend --name \"Dividend Income\" \\\n --description \"High dividend yield stocks\"\n\n# Add different stocks to each\nquantlab portfolio add growth NVDA TSLA SNOW --weight 0.33\nquantlab portfolio add value BAC JPM WFC --weight 0.33\nquantlab portfolio add dividend T VZ SO --weight 0.33\n\n# View all portfolios\nquantlab portfolio list\n\n# Expected output:\n# \ud83d\udcca Your Portfolios\n#\n# Portfolio ID \u2502 Name \u2502 Positions \u2502 Total Weight \u2502 Last Updated\n# \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n# tech_giants \u2502 FAANG+ Portfolio \u2502 6 \u2502 100.00% \u2502 2025-10-15\n# growth \u2502 High Growth \u2502 3 \u2502 99.00% \u2502 2025-10-15\n# value \u2502 Value Plays \u2502 3 \u2502 99.00% \u2502 2025-10-15\n# dividend \u2502 Dividend Income \u2502 3 \u2502 99.00% \u2502 2025-10-15\n#\n# Total Portfolios: 4\n# Total Unique Positions: 15\n```\n\n### \ud83d\udd2c Use Case 8: Options Strategy Research\n\n**Scenario**: Research options opportunities for covered calls.\n\n```bash\n# Analyze ticker specifically for options\nquantlab analyze ticker AAPL \\\n --include-options \\\n --no-fundamentals \\\n --no-sentiment \\\n --output results/aapl_options.json\n\n# Expected output:\n# \ud83d\udd0d Options Analysis: AAPL\n#\n# Current Price: $181.75\n#\n# Near-Term Expiration (30 days):\n# Call Options (Covered Call Candidates):\n# Strike \u2502 Premium \u2502 IV \u2502 Delta \u2502 Break-even \u2502 Return\n# \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n# $185 \u2502 $3.85 \u2502 21.2% \u2502 0.45 \u2502 $185.00 \u2502 2.1%\n# $190 \u2502 $2.15 \u2502 19.8% \u2502 0.28 \u2502 $190.00 \u2502 4.6%\n# $195 \u2502 $0.95 \u2502 18.5% \u2502 0.15 \u2502 $195.00 \u2502 7.3%\n#\n# Put Options (Cash-Secured Put Candidates):\n# Strike \u2502 Premium \u2502 IV \u2502 Delta \u2502 Net Cost \u2502 Yield\n# \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n# $175 \u2502 $2.80 \u2502 22.5% \u2502 -0.35 \u2502 $172.20 \u2502 1.6%\n# $170 \u2502 $1.45 \u2502 20.1% \u2502 -0.20 \u2502 $168.55 \u2502 0.9%\n#\n# Volatility Metrics:\n# Current IV: 21.2%\n# Historical Vol (30d): 18.5%\n# IV Percentile: 62% (Elevated)\n#\n# \ud83d\udca1 Suggestion: Good conditions for selling premium\n# IV elevated vs historical - consider covered calls at $190 strike\n\n# Visualize options payoff diagrams\nquantlab visualize options long_call --current-price 181.75 --strike 190 --premium 2.15\nquantlab visualize options bull_call_spread \\\n --current-price 181.75 --strike1 185 --strike2 195 --premium 1.70\n```\n\n### \ud83d\udcc5 Use Case 9: Regular Portfolio Review\n\n**Scenario**: Monthly portfolio review workflow.\n\n```bash\n# Step 1: Refresh all market data\nquantlab lookup refresh portfolio tech_giants\n\n# Step 2: Get comprehensive analysis\nquantlab analyze portfolio tech_giants --aggregate-metrics\n\n# Step 3: Visualize portfolio performance\nquantlab visualize compare AAPL GOOGL MSFT META AMZN NVDA --period 30d --normalize\n\n# Step 4: Review individual positions\nquantlab visualize price AAPL --period 90d --chart-type candlestick\nquantlab visualize price NVDA --period 90d --chart-type candlestick\n\n# Step 5: Check for rebalancing needs\nquantlab portfolio show tech_giants\n\n# Step 6: Look for new opportunities\nquantlab data tickers --type stocks_daily | grep -E \"^[A-Z]{1,4}$\" | head -20\nquantlab analyze ticker CRM --include-fundamentals\nquantlab visualize price CRM --period 90d --chart-type candlestick\n\n# Step 7: Update positions based on analysis\nquantlab portfolio update tech_giants NVDA --weight 0.05 --notes \"Reduced - valuation concerns\"\nquantlab portfolio add tech_giants CRM --weight 0.05 --notes \"New position - cloud growth\"\n\n# Step 8: Export for records\nquantlab analyze portfolio tech_giants --output results/monthly_review_2025_10.json\n```\n\n### \ud83d\udea8 Use Case 10: Risk Monitoring\n\n**Scenario**: Monitor portfolio risk daily.\n\n```bash\n# Create a monitoring script\ncat > scripts/daily_monitor.sh << 'EOF'\n#!/bin/bash\nDATE=$(date +%Y-%m-%d)\n\necho \"\ud83d\udd0d Daily Portfolio Monitor - $DATE\"\necho \"==================================\"\n\n# Analyze each portfolio\nfor portfolio in tech_giants growth value dividend; do\n echo \"\"\n echo \"\ud83d\udcca Portfolio: $portfolio\"\n quantlab analyze portfolio $portfolio \\\n --include-options \\\n --output \"results/monitoring/${portfolio}_${DATE}.json\" 2>&1 | \\\n grep -E \"(Score:|Sentiment:|Analysts:|\u26a0|\u274c)\"\ndone\n\n# Check treasury rates for risk-free rate\necho \"\"\necho \"\ud83d\udcc8 Current Treasury Rates:\"\nquantlab lookup get treasury 10y\n\necho \"\"\necho \"\u2705 Monitoring complete\"\nEOF\n\nchmod +x scripts/daily_monitor.sh\n\n# Run daily monitoring\n./scripts/daily_monitor.sh\n\n# Expected output:\n# \ud83d\udd0d Daily Portfolio Monitor - 2025-10-15\n# ==================================\n#\n# \ud83d\udcca Portfolio: tech_giants\n# \u2713 AAPL \u2502 Score: 82/100 \u2502 Sentiment: Positive\n# \u2713 GOOGL \u2502 Score: 78/100 \u2502 Sentiment: Positive\n# \u26a0 NVDA \u2502 Score: 68/100 \u2502 Sentiment: Mixed\n#\n# \ud83d\udcc8 Current Treasury Rates:\n# 10-Year Treasury: 4.25% (as of 2025-10-15)\n#\n# \u2705 Monitoring complete\n```\n\n## \ud83d\udcca Available Configurations\n\n### 1. **Liquid Universe** (Recommended)\n- **File**: `configs/lightgbm_liquid_universe.yaml`\n- **Universe**: 13,187 stocks (filtered - no warrants, units)\n- **Period**: Sept 2024 - Sept 2025\n- **Best for**: Realistic backtesting with tradable stocks\n\n### 2. **Fixed Dates**\n- **File**: `configs/lightgbm_fixed_dates.yaml`\n- **Universe**: All stocks\n- **Period**: July 2024 - Dec 2024\n- **Best for**: Testing on stable period\n\n### 3. **Full Universe**\n- **File**: `configs/lightgbm_external_data.yaml`\n- **Universe**: All 14,310 instruments (includes warrants, penny stocks)\n- **Period**: Sept 2024 - Sept 2025\n- **Best for**: Maximum alpha discovery (but risky)\n\n## \ud83c\udfaf Key Metrics from Latest Runs\n\n| Configuration | IC | Rank IC | Sharpe | Max DD | Universe Size |\n|--------------|-----|---------|--------|--------|---------------|\n| Liquid Universe | 0.066 | -0.006 | 3.94 | -39.2% | 13,187 |\n| Fixed Dates | 0.079 | -0.008 | 4.54 | -35.3% | 14,310 |\n| Full Universe | 0.080 | -0.004 | 2.98 | -41.7% | 14,310 |\n\n**IC (Information Coefficient)**: 0.06-0.08 is good - shows predictive power\n**Rank IC**: Near zero - model struggles with relative ranking\n**Sharpe Ratio**: 2.98-4.54 - excellent risk-adjusted returns\n\n## \ud83d\udcca Visualization Capabilities\n\nQuantLab includes comprehensive interactive visualization tools powered by Plotly.\n\n### Price Charts\n\n```bash\n# Candlestick charts (daily data)\nquantlab visualize price AAPL --period 90d --chart-type candlestick\n\n# Line charts with volume\nquantlab visualize price AAPL --period 1year --chart-type line\n\n# Intraday charts (5min, 15min, 1hour intervals)\nquantlab visualize price AAPL --interval 5min --period 5d --chart-type candlestick\nquantlab visualize price NVDA --interval 1hour --period 30d --chart-type line\n```\n\n**Features:**\n- Multiple timeframes: 1d, 5d, 30d, 90d, 1year, 2year\n- Intraday intervals: 1min, 5min, 15min, 1hour\n- Categorical x-axis for gap-free intraday charts\n- Timezone-aware (US Eastern Time)\n- Regular market hours filtering (9:30 AM - 4:00 PM ET)\n\n**Example Charts:**\n- [Daily Candlestick (90d)](docs/images/price_candlestick_90d.html)\n- [Intraday 5-minute Line](docs/images/price_intraday_5min.html)\n\n### Multi-Ticker Comparison\n\n```bash\n# Compare normalized performance\nquantlab visualize compare AAPL GOOGL MSFT --period 90d --normalize\n\n# Absolute price comparison\nquantlab visualize compare AAPL GOOGL MSFT --period 1year\n```\n\n**Example Chart:**\n- [Normalized Comparison (90d)](docs/images/comparison_normalized.html)\n\n### Options Payoff Diagrams\n\n```bash\n# Single leg strategies\nquantlab visualize options long_call --current-price 180 --strike 190 --premium 2.15\nquantlab visualize options long_put --current-price 180 --strike 175 --premium 2.80\n\n# Spread strategies\nquantlab visualize options bull_call_spread \\\n --current-price 180 --strike1 185 --strike2 195 --premium 1.70\n\nquantlab visualize options iron_condor \\\n --current-price 180 --strike1 170 --strike2 175 --strike3 195 --strike4 200\n```\n\n**Available Strategies:**\n- Single: `long_call`, `long_put`, `short_call`, `short_put`\n- Spreads: `bull_call_spread`, `bear_put_spread`, `iron_condor`, `butterfly`\n- Volatility: `long_straddle`, `short_straddle`, `long_strangle`, `short_strangle`\n\n**Example Chart:**\n- [Bull Call Spread Payoff](docs/images/options_bull_call_spread.html)\n\n### Backtest Results\n\n```bash\n# Visualize backtest performance\nquantlab visualize backtest results/mlruns/[experiment_id]\n```\n\n**Metrics Displayed:**\n- Cumulative returns vs benchmark\n- Drawdown analysis\n- Rolling Sharpe ratio\n- Win/loss distribution\n- Monthly returns heatmap\n\n## \ud83d\udcda Documentation\n\n- **[BACKTEST_SUMMARY.md](docs/BACKTEST_SUMMARY.md)** - Comprehensive analysis of backtest results, root cause analysis, and recommendations\n- **[ALPHA158_SUMMARY.md](docs/ALPHA158_SUMMARY.md)** - Overview of Alpha158 features used\n- **[USE_QLIB_ALPHA158.md](docs/USE_QLIB_ALPHA158.md)** - How to use Alpha158 in your strategies\n- **[CLI_VISUALIZATION_GUIDE.md](docs/CLI_VISUALIZATION_GUIDE.md)** - Complete guide to visualization features\n\n## \ud83d\udd27 Data Setup\n\n### External Data Location\n```\n/Volumes/sandisk/quantmini-data/data/qlib/stocks_daily/\n\u251c\u2500\u2500 calendars/day.txt # Trading calendar (442 days)\n\u251c\u2500\u2500 instruments/\n\u2502 \u251c\u2500\u2500 all.txt # All 14,310 instruments\n\u2502 \u2514\u2500\u2500 liquid_stocks.txt # Filtered 13,187 instruments\n\u2514\u2500\u2500 features/ # Stock price data (OHLCV)\n```\n\n### Creating Custom Universe Filters\n\n```python\n# See scripts/data/ for examples\n# Filter by:\n# - Market cap\n# - Average volume\n# - Exclude warrants/units\n# - Sector/industry\n```\n\n## \ud83e\uddea Testing\n\n```bash\n# Test Alpha158 features\npython scripts/tests/test_qlib_alpha158.py\n\n# Test data conversion\npython scripts/data/convert_to_qlib.py\n\n# Refresh latest data\npython scripts/data/refresh_today_data.py\n```\n\n## \ud83d\udd0d Next Steps\n\n### Improve Model Performance\n1. **Fix Rank IC** - Try ensemble models (XGBoost, TabNet, LSTM)\n2. **Better features** - Add momentum, volatility, cross-sectional features\n3. **Risk controls** - Add position limits, volatility weighting\n\n### Data Quality\n1. Validate corporate actions (splits, dividends)\n2. Check for survivorship bias\n3. Add liquidity filters (min volume, market cap)\n\n### Alternative Strategies\n1. Market-neutral long-short\n2. Factor-based weighting\n3. Multi-timeframe approaches\n\n## \ud83d\udcdd Notes\n\n- **Data Source**: External data from QuantMini (US stocks, daily, 2024-2025)\n- **ML Framework**: Qlib by Microsoft Research\n- **Models Tested**: LightGBM with Alpha158 features\n- **Tracking**: MLflow for experiment management\n\n## \u26a0\ufe0f Known Issues\n\n1. **Unrealistic backtest returns** - Investigating data quality and backtest engine\n2. **Rank IC near zero** - Model can predict returns but not rank stocks well\n3. **High volatility** - Some instruments show extreme price movements\n4. See [BACKTEST_SUMMARY.md](docs/BACKTEST_SUMMARY.md) for detailed analysis\n\n## \ud83e\udd1d Contributing\n\nThis is a research project. Key areas for improvement:\n- Better universe filters\n- Alternative features\n- Improved ranking models\n- Risk management strategies\n\n## \ud83d\udcc4 License\n\nResearch and educational purposes.\n\n## \ud83d\udd17 Resources\n\n- [Qlib Documentation](https://qlib.readthedocs.io/)\n- [Qlib GitHub](https://github.com/microsoft/qlib)\n- [Alpha158 Paper](https://arxiv.org/abs/2107.08321)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Professional quantitative trading research platform with ML-powered backtesting, multi-source options analysis, portfolio management, and interactive Plotly visualizations",
"version": "0.2.1",
"project_urls": {
"Bug Tracker": "https://github.com/nittygritty-zzy/quantlab/issues",
"Changelog": "https://github.com/nittygritty-zzy/quantlab/releases",
"Documentation": "https://quantlabs.readthedocs.io",
"Homepage": "https://github.com/nittygritty-zzy/quantlab",
"Repository": "https://github.com/nittygritty-zzy/quantlab"
},
"split_keywords": [
"algorithmic-trading",
" backtesting",
" data-visualization",
" financial-analysis",
" machine-learning",
" options-trading",
" portfolio-management",
" qlib",
" quantitative-finance"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6d6a02291a1fcc7bb86f391ae14e3cf6496995ba9ed94dd9f8eac21c68be41c9",
"md5": "56ea79a9cf6966ad6269676aeb023738",
"sha256": "d67048cc3c814fe7cf11538f90c5770472e6ea54b3222ec551a240a5df4f518f"
},
"downloads": -1,
"filename": "quantlabs-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "56ea79a9cf6966ad6269676aeb023738",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 107649,
"upload_time": "2025-10-16T22:11:06",
"upload_time_iso_8601": "2025-10-16T22:11:06.929039Z",
"url": "https://files.pythonhosted.org/packages/6d/6a/02291a1fcc7bb86f391ae14e3cf6496995ba9ed94dd9f8eac21c68be41c9/quantlabs-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4c35e5ff0c7e9fcc338d5f1ebbd987f6ae02725565e1b2069fdd27858c19491a",
"md5": "4423a0c25bac46e63789319eeec438a4",
"sha256": "8aa8700495097fee6aca82c1bd4e1e6b617b8187f10b397df99354a1627818f5"
},
"downloads": -1,
"filename": "quantlabs-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "4423a0c25bac46e63789319eeec438a4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 771597,
"upload_time": "2025-10-16T22:11:08",
"upload_time_iso_8601": "2025-10-16T22:11:08.805937Z",
"url": "https://files.pythonhosted.org/packages/4c/35/e5ff0c7e9fcc338d5f1ebbd987f6ae02725565e1b2069fdd27858c19491a/quantlabs-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-16 22:11:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nittygritty-zzy",
"github_project": "quantlab",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "quantlabs"
}
JSON
