Open-source portfolio analysis tools for DIY investors and finance enthusiasts. This repository aims to provide a comprehensive suite of tools to analyze and optimize investment portfolios, with an emphasis on transparency, flexibility, and extensibility.
Read the Full Documentation - Comprehensive guides, API reference, and examples.
Google Colab Notebooks:
- Basic Portfolio Analysis - Core analysis tutorial
- Interactive Portfolio Analysis - Widget-based interface
- Factor Analysis Demo - Fama-French factor models
pip install engineer-investor-portfolioOr install from source with all features:
git clone https://github.com/engineerinvestor/Portfolio-Analysis.git
cd Portfolio-Analysis
pip install -e ".[all]"pip install -r requirements-streamlit.txt
streamlit run streamlit_app/app.py- Performance Metrics: Annual return, volatility, Sharpe ratio, Sortino ratio, max drawdown, VaR
- Portfolio Analysis: Weighted returns, covariance-based volatility, cumulative returns
- Monte Carlo Simulation: Project future portfolio values with confidence intervals
- Benchmark Comparison: Alpha, beta, tracking error, information ratio, capture ratios
- Maximum Sharpe Ratio portfolio
- Minimum Volatility portfolio
- Risk Parity (equal risk contribution)
- Target Return optimization
- Efficient Frontier visualization
- Fama-French Models: CAPM, FF3, FF5, and Carhart 4-factor regressions
- Factor Data: Auto-fetch from Kenneth French Data Library with local caching
- Return Attribution: Decompose returns into factor contributions + alpha
- Risk Attribution: Variance decomposition by systematic factor
- Rolling Analysis: Time-varying factor exposures
- Characteristic Tilts: Size, value, momentum, quality, investment tilts
- Factor Optimization: Target specific factor exposures or neutralize factors
- Professional portfolio reports inspired by QuantStats
- Embedded charts (cumulative returns, drawdowns, monthly heatmap)
- Comprehensive metrics tables (risk, return, ratios)
- Optional benchmark comparison section
- Self-contained HTML files with no external dependencies
- Jupyter widgets for Colab/notebook analysis
- Streamlit web application
- Preset portfolios (60/40, Three-Fund, All-Weather, etc.)
from portfolio_analysis import DataLoader, PortfolioAnalysis, MonteCarloSimulation
# Load data
loader = DataLoader(['VTI', 'VXUS', 'BND'], '2018-01-01', '2024-01-01')
data = loader.fetch_data()
# Analyze portfolio
portfolio = PortfolioAnalysis(data, weights=[0.4, 0.2, 0.4])
portfolio.print_summary()
# Run Monte Carlo simulation
mc = MonteCarloSimulation(data, weights=[0.4, 0.2, 0.4], num_simulations=1000)
mc.print_summary()
mc.plot_simulation()from portfolio_analysis import PortfolioOptimizer
optimizer = PortfolioOptimizer(data, risk_free_rate=0.04)
optimal = optimizer.optimize_max_sharpe()
print(f"Optimal weights: {optimal['weights']}")
# Visualize efficient frontier
optimizer.plot_efficient_frontier()from portfolio_analysis import DataLoader, PortfolioAnalysis, BenchmarkComparison
from portfolio_analysis.reporting import ReportBuilder
# Load data and create portfolio
loader = DataLoader(['VTI', 'BND'], '2020-01-01', '2024-01-01')
data = loader.fetch_data()
portfolio = PortfolioAnalysis(data, [0.6, 0.4])
# Generate basic report
report = ReportBuilder(portfolio, title="60/40 Portfolio")
report.generate("tearsheet.html")
# With benchmark comparison
benchmark = BenchmarkComparison(data, [0.6, 0.4], benchmark_ticker='SPY')
report = ReportBuilder(portfolio, benchmark=benchmark, title="60/40 Portfolio")
report.generate("tearsheet_with_benchmark.html")from portfolio_analysis import DataLoader, PortfolioAnalysis
from portfolio_analysis.factors import FactorDataLoader, FactorRegression, FactorAttribution
# Load portfolio data
loader = DataLoader(['VTI', 'VBR', 'VTV', 'BND'], '2019-01-01', '2024-01-01')
data = loader.fetch_data()
portfolio = PortfolioAnalysis(data, [0.4, 0.2, 0.2, 0.2])
returns = portfolio.calculate_portfolio_returns()
# Load Fama-French factors
factor_loader = FactorDataLoader()
ff3 = factor_loader.get_ff3_factors('2019-01-01', '2024-01-01')
# Run factor regression
regression = FactorRegression(returns, ff3)
results = regression.run_regression('ff3')
print(results.summary())
# Output: Alpha, Market Beta, SMB, HML with t-stats and p-values
# Decompose returns by factor
attribution = FactorAttribution(returns, ff3)
decomp = attribution.decompose_returns()
print(f"Market contribution: {decomp['Mkt-RF']:.2%}")
print(f"Alpha: {decomp['alpha']:.2%}")
# Compare all factor models
comparison = regression.compare_models()
print(comparison) # CAPM vs FF3 vs FF5 vs Carhart
Portfolio-Analysis/
├── portfolio_analysis/ # Python package
│ ├── data/ # Data loading
│ ├── metrics/ # Performance & benchmark metrics
│ ├── analysis/ # Portfolio & Monte Carlo analysis
│ ├── factors/ # Factor analysis (Fama-French, etc.)
│ ├── visualization/ # Plotting & interactive widgets
│ ├── reporting/ # HTML tear sheet generation
│ └── utils/ # Helper functions
├── streamlit_app/ # Web application
│ └── app.py # Main Streamlit app
├── tests/ # pytest test suite
├── docs/images/ # Documentation images
├── Tutorials/ # Additional notebooks
├── Visualization/ # Visualization notebooks
├── Basic_Portfolio_Analysis.ipynb
├── Interactive_Portfolio_Analysis.ipynb
├── Factor_Analysis_Demo.ipynb # Factor analysis tutorial
├── pyproject.toml # Package configuration
└── requirements*.txt # Dependencies
pip install engineer-investor-portfoliopip install "engineer-investor-portfolio[optimization]"pip install "engineer-investor-portfolio[interactive]"pip install "engineer-investor-portfolio[factors]"pip install "engineer-investor-portfolio[streamlit]"pip install "engineer-investor-portfolio[all]"We welcome contributions from the community. Please read the following guidelines:
- Fork the repository
- Create a new branch (
git checkout -b feature-name) - Commit your changes (
git commit -m 'Add feature') - Push to the branch (
git push origin feature-name) - Create a Pull Request
See also: Beginner's Guide to Contributing
- Core portfolio analysis classes
- Monte Carlo simulation (fixed)
- Benchmark comparison
- Interactive widgets for Colab
- Python package (PyPI-ready)
- Portfolio optimization
- Streamlit web application
- HTML tear sheet reports
- Factor analysis (Fama-French, Carhart, return/risk attribution)
- Time-varying risk-free rate (T-bill data)
- Tax-loss harvesting tools
- Comprehensive test coverage
- Awesome Quant - Curated quant finance resources
- QuantStats - Portfolio analytics
- PyPortfolioOpt - Portfolio optimization
- Riskfolio-Lib - Portfolio optimization and risk management
If you use this package in academic work, please cite:
@software{engineer_investor_portfolio_analysis,
author = {Engineer Investor},
title = {Portfolio-Analysis: Open-source portfolio analysis tools for DIY investors},
year = {2026},
publisher = {GitHub},
url = {https://github.com/engineerinvestor/Portfolio-Analysis}
}This project is licensed under the MIT License - see the LICENSE file for details.
This is not investment advice. These tools are for educational purposes only. Past performance does not guarantee future results. Always do your own research and consider consulting a qualified financial advisor.
- Twitter: @egr_investor
- GitHub: engineerinvestor
- Email: egr.investor (gmail)