A comprehensive Python framework for quantitative factor investing, portfolio optimization, and risk management. Built for researchers, portfolio managers, and quantitative analysts who need professional-grade tools for factor-based investment strategies.
- Multiple Data Providers: Yahoo Finance, OpenBB Platform, Financial Modeling Prep (FMP)
- Real Fundamental Data: Integrated FMP API with 6/8 financial ratios working (ROE, ROA, Debt/Equity, Current Ratio, Operating/Net Margins)
- Look-Ahead Bias Prevention: Time-aware data processing with acceptedDate filtering
- Fiscal Quarter Support: Handles company-specific fiscal calendars correctly
- Data Quality: Comprehensive validation, cleaning, and quality scoring
- Technical Factors: Momentum (1M, 3M, 6M, 12M), volatility, mean reversion, RSI, Bollinger Bands, MACD, Beta
- Fundamental Factors: Real P/E, P/B, ROE, Debt/Equity ratios from FMP integration
- Factor Processing: Z-score, rank-based, and percentile normalization with cross-sectional analysis
- Factor Analysis: Correlation matrices, autocorrelation analysis, Information Coefficient calculations
- Factor Risk Model: Market, size, momentum, volatility, and sector factors
- Multiple Methods: Mean-variance, risk parity, minimum variance, factor-based optimization
- Robust Solvers: OSQP, CLARABEL, SCS, ECOS with automatic fallback mechanisms
- Professional Features: Transaction costs, weight constraints, covariance shrinkage
- Risk Management: Factor attribution, risk budgeting, concentration analysis
- Advanced Analytics: Efficient frontier, risk contribution decomposition
- Strategy Simulation: Factor strategies, momentum strategies, multi-factor models
- Realistic Modeling: Transaction costs, slippage, flexible rebalancing frequencies
- Performance Analytics: Sharpe ratio, Calmar ratio, max drawdown, VaR, rolling metrics
- Benchmark Comparison: Alpha, beta, tracking error, information ratio analysis
- Factor Attribution: Risk decomposition and performance attribution
- Dynamic Hedging: Correlation-based hedge ratios with tradeable ETFs (VIXY, VXX, TLT, GLD, UUP, SHY)
- Stress Testing: Market crash scenarios, sector-specific shocks, historical event analysis
- Risk Attribution: Factor exposure analysis, sector allocation, concentration metrics
- Scenario Analysis: COVID crash, tech selloff, banking crisis historical performance
- Interactive Charts: Plotly-based cumulative returns, drawdown analysis, rolling performance
- Professional Dashboards: Factor analysis, correlation heatmaps, efficient frontier plots
- Risk Visualizations: Portfolio composition, risk contribution breakdowns, factor exposures
- Export Capabilities: HTML dashboards, CSV results, comprehensive reporting
- Python 3.11 or higher
- Poetry (recommended) or pip
# Clone the repository
git clone https://github.com/jlancaster7/factor-lab.git
cd factor-lab
# Install dependencies
poetry install
poetry shell# Clone the repository
git clone https://github.com/jlancaster7/factor-lab.git
cd factor-lab
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\\Scripts\\activate
# Install dependencies
pip install -r requirements.txt- Copy the example configuration:
cp config/environments.yaml.example config/environments.yaml- Add your API keys to
config/environments.yaml:
api_keys:
financial_modeling_prep:
api_key: "your_fmp_api_key_here"
openbb:
fmp_token: "your_openbb_token_here"Note: Most features work with Yahoo Finance (no API key required). FMP key enables real fundamental data.
from factor_lab import DataManager, FactorCalculator, PortfolioOptimizer
# Initialize components
data_manager = DataManager()
factor_calc = FactorCalculator()
# Get data
universe = ['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'TSLA']
prices = data_manager.get_prices(universe, "2022-01-01", "2024-01-01")
returns = data_manager.get_returns(universe, "2022-01-01", "2024-01-01")
# Calculate technical factors
momentum_12m = factor_calc.momentum(prices, lookback=252)
volatility = factor_calc.volatility(returns, lookback=60)
# Get real fundamental data (if FMP configured)
fmp_provider = data_manager.providers['fmp']
fundamental_data = fmp_provider.get_fundamental_factors(
symbols=universe,
start_date='2022-01-01',
end_date='2024-01-01'
)from factor_lab import PortfolioOptimizer
# Initialize optimizer with returns data
optimizer = PortfolioOptimizer(returns)
# Multiple optimization methods
mv_result = optimizer.mean_variance_optimization()
rp_result = optimizer.risk_parity_optimization()
minvol_result = optimizer.minimum_variance_optimization()
print(f"Mean-Variance Sharpe: {mv_result['sharpe_ratio']:.3f}")
print(f"Risk Parity Sharpe: {rp_result['sharpe_ratio']:.3f}")from factor_lab import Backtester
def momentum_strategy(factor_data, price_data, top_n=5, **kwargs):
latest_factors = factor_data.iloc[-1]
top_stocks = latest_factors.nlargest(top_n)
weights = pd.Series(index=latest_factors.index, data=0.0)
weights[top_stocks.index] = 1.0 / len(top_stocks)
return weights
# Run backtest
backtester = Backtester("2022-01-01", "2024-01-01")
results = backtester.run_factor_strategy_backtest(
price_data=prices,
factor_data=momentum_12m,
strategy_func=momentum_strategy,
top_n=10
)
print(f"Strategy Return: {results['performance_metrics']['Annualized Return']:.2%}")
print(f"Sharpe Ratio: {results['performance_metrics']['Sharpe Ratio']:.2f}")Explore the complete framework through detailed notebooks:
-
Getting Started: Complete walkthrough with 50-stock S&P 500 universe
- Data acquisition and factor calculation
- Portfolio optimization comparison (Equal Weight, Mean-Variance, Risk Parity)
- Strategy backtesting with momentum factors
- Performance analysis and benchmark comparison
-
Fundamental Factors: Real fundamental data integration
- FMP API integration with 40-stock multi-sector universe
- Combined technical and fundamental factor strategies
- Real financial ratios (ROE, Debt/Equity, Current Ratio, Margins)
- Multi-factor model with 65% fundamental / 35% technical allocation
-
Risk Management: Advanced portfolio risk analysis
- Factor risk model with market, size, momentum, volatility factors
- Stress testing and scenario analysis
- Dynamic hedging with tradeable ETFs
- Risk attribution and concentration analysis
- Data Management: Yahoo Finance, OpenBB, FMP integration with rate limiting
- Technical Factors: 11+ factors with comprehensive normalization and analysis
- Portfolio Optimization: 4 methods with multiple solver fallbacks
- Backtesting: Complete framework with transaction costs and performance analytics
- Risk Management: Factor models, stress testing, dynamic hedging
- Visualization: Interactive Plotly dashboards with HTML export
- FMP Integration: Real fundamental data with look-ahead bias prevention
- Advanced caching system for API optimization
- Performance improvements for large universes
- PE/PB ratios (requires market cap data integration)
- Machine learning factor models
- Alternative data sources (ESG, sentiment)
- Real-time portfolio monitoring
From comprehensive testing across multiple notebooks:
- Momentum Strategy: 114% total return, 1.85 Sharpe ratio
- Portfolio Optimization: Mean-variance outperformed equal weight
- Risk Management: Max drawdown -20.6%, VaR analysis
- Multi-Factor Strategy: 50.8% total return, 1.33 Sharpe ratio
- Data Coverage: 92.3% (32,580 data points)
- Real Fundamentals: 6/8 ratios working with actual company data
- Optimization Comparison: Risk parity vs mean-variance analysis
- Stress Testing: Market crash, sector shock scenarios
- Dynamic Hedging: Correlation-based hedge ratios with VIX/TLT/GLD
factor-lab/
├── src/factor_lab/ # Production-ready source code
│ ├── data/ # Multi-provider data management
│ ├── factors/ # Comprehensive factor library
│ ├── portfolio/ # Advanced optimization methods
│ ├── backtesting/ # Professional backtesting framework
│ ├── visualization/ # Interactive Plotly dashboards
│ └── utils/ # Mathematical and utility functions
├── notebooks/ # Comprehensive example notebooks
│ ├── getting_started.ipynb # 50-stock S&P 500 analysis
│ ├── fundamental_factors.ipynb # Real FMP data integration
│ └── risk_management.ipynb # Advanced risk analysis
├── tests/ # Comprehensive test suite (8 test files)
├── config/ # Configuration management
├── data/figures/ # Generated visualizations
└── results/ # Backtest results and analysis
# Verify installation and API connectivity
poetry run python verify_setup.py# Run all tests (8 test files covering core functionality)
poetry run pytest
# Test specific components
poetry run python tests/test_fmp_methods.py # FMP API integration
poetry run python tests/test_core.py # Core functionality
poetry run python tests/test_validation_methods.py # Data validation- Real FMP API testing with rate limiting
- Portfolio optimization solver fallbacks
- Factor calculation accuracy
- Look-ahead bias prevention
- Data quality validation
data:
default_provider: yahoo
cache_dir: "./data/cache"
portfolio:
optimization:
default_method: "mean_variance"
max_weight: 0.1
backtesting:
transaction_cost: 0.001
rebalance_frequency: "monthly"api_keys:
financial_modeling_prep:
api_key: ${FMP_API_KEY}
openbb:
fmp_token: ${OPENBB_TOKEN}- Momentum: 1M, 3M, 6M, 12M price momentum
- Mean Reversion: Short-term reversal signals
- Volatility: Realized volatility measures
- Market: Beta relative to market
- Technical Indicators: RSI, Bollinger Band position, Price-to-SMA
- Value: P/E ratio, P/B ratio (PE/PB pending market cap data)
- Quality: ROE, debt ratios (working with real company data)
- Leverage: Debt/Equity, Current Ratio (real balance sheet data)
- Profitability: Operating margins, net margins (real income statement data)
- Normalization: Z-score, rank-based, percentile methods
- Combination: Multi-factor models with configurable weights
- Analysis: Correlation matrices, Information Coefficient calculations
- Risk Models: Factor attribution and exposure analysis
- Multiple optimization methods with robust solver fallbacks
- Transaction cost modeling and turnover analysis
- Risk budgeting and factor attribution
- Benchmark comparison and alpha generation analysis
- Stress testing under market crash scenarios
- Dynamic hedging with tradeable instruments
- Factor risk decomposition and attribution
- Concentration risk analysis
- Rate limiting for API compliance (750 calls/minute)
- Comprehensive error handling and logging
- Data validation and quality scoring
- Look-ahead bias prevention for historical analysis
- Project Overview: Comprehensive technical documentation
- Implementation Plan: Development roadmap and progress
- Jupyter Notebooks: Interactive tutorials with real examples
- API Documentation: Inline docstrings and type hints throughout
We welcome contributions! The codebase follows professional standards:
- Type hints and comprehensive docstrings
- Robust error handling and logging
- Multiple fallback mechanisms
- Comprehensive test coverage
MIT License - see LICENSE file for details.
- Financial Modeling Prep for fundamental data
- Yahoo Finance for reliable price data
- OpenBB Platform for financial data integration
- CVXPY for convex optimization
- Plotly for interactive visualizations
Factor Lab - Professional quantitative factor investing framework with real fundamental data integration 🚀
A comprehensive toolkit for factor research, portfolio construction, and risk management
Last updated: June 1, 2025