A quantitative trading research platform powered by Microsoft's Qlib, designed for systematic alpha generation and backtesting.
π Full Documentation | π Quick Start Guide | π API Reference
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
β
βββ system/ # System-level configuration
β βββ system_profile.yaml # Qlib system settings
β
βββ qlib_repo/ # Qlib source (gitignored, 828MB)
βββ (Microsoft qlib clone)
# Install from PyPI
pip install quantlabs
# Or using uv (recommended)
uv pip install quantlabs
# Verify installation
quantlab --version
quantlab --help# 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 .# 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# 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# Update the experiment ID in visualize_results.py, then:
uv run python scripts/analysis/visualize_results.pyResults will be saved to results/visualizations/backtest_visualization.png
QuantLab includes a powerful CLI for portfolio management, market analysis, and data queries.
Scenario: Create and manage a diversified tech portfolio with FAANG+ stocks.
# 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%Scenario: Track actual shares purchased at specific cost basis.
# 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.50Scenario: Deep-dive analysis on ORCL before adding to portfolio.
# 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 ORCLScenario: Analyze all positions in your tech portfolio.
# 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.htmlScenario: Research historical price patterns for backtesting.
# 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 availableScenario: Keep company info and analyst ratings up-to-date.
# 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:15Scenario: Manage multiple portfolios for different strategies.
# 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: 15Scenario: Research options opportunities for covered calls.
# 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.70Scenario: Monthly portfolio review workflow.
# 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.jsonScenario: Monitor portfolio risk daily.
# 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- 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
- File:
configs/lightgbm_fixed_dates.yaml - Universe: All stocks
- Period: July 2024 - Dec 2024
- Best for: Testing on stable period
- 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)
| 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
QuantLab includes comprehensive interactive visualization tools powered by Plotly.
# 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 lineFeatures:
- 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:
# Compare normalized performance
quantlab visualize compare AAPL GOOGL MSFT --period 90d --normalize
# Absolute price comparison
quantlab visualize compare AAPL GOOGL MSFT --period 1yearExample Chart:
# 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 200Available 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:
# 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
- BACKTEST_SUMMARY.md - Comprehensive analysis of backtest results, root cause analysis, and recommendations
- ALPHA158_SUMMARY.md - Overview of Alpha158 features used
- USE_QLIB_ALPHA158.md - How to use Alpha158 in your strategies
- CLI_VISUALIZATION_GUIDE.md - Complete guide to visualization features
/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)
# See scripts/data/ for examples
# Filter by:
# - Market cap
# - Average volume
# - Exclude warrants/units
# - Sector/industry# 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- Fix Rank IC - Try ensemble models (XGBoost, TabNet, LSTM)
- Better features - Add momentum, volatility, cross-sectional features
- Risk controls - Add position limits, volatility weighting
- Validate corporate actions (splits, dividends)
- Check for survivorship bias
- Add liquidity filters (min volume, market cap)
- Market-neutral long-short
- Factor-based weighting
- Multi-timeframe approaches
- 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
- Unrealistic backtest returns - Investigating data quality and backtest engine
- Rank IC near zero - Model can predict returns but not rank stocks well
- High volatility - Some instruments show extreme price movements
- See BACKTEST_SUMMARY.md for detailed analysis
This is a research project. Key areas for improvement:
- Better universe filters
- Alternative features
- Improved ranking models
- Risk management strategies
Research and educational purposes.