engineer-investor-portfolio 0.2.0

Professional portfolio analysis tools for DIY investors

Portfolio-Analysis

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.

Documentation

Read the Full Documentation - Comprehensive guides, API reference, and examples.

Quick Start

Try Online (No Installation)

Google Colab Notebooks:

• Basic Portfolio Analysis - Core analysis tutorial
• Interactive Portfolio Analysis - Widget-based interface
• Factor Analysis Demo - Fama-French factor models

Install as Python Package

pip install engineer-investor-portfolio

Or install from source with all features:

git clone https://github.com/engineerinvestor/Portfolio-Analysis.git
cd Portfolio-Analysis
pip install -e ".[all]"

Run the Streamlit Web App

pip install -r requirements-streamlit.txt
streamlit run streamlit_app/app.py

Or Use the Live App

Launch Streamlit App

Features

Core Analysis

• 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

Optimization

• Maximum Sharpe Ratio portfolio
• Minimum Volatility portfolio
• Risk Parity (equal risk contribution)
• Target Return optimization
• Efficient Frontier visualization

Factor Analysis

• 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

HTML Tear Sheet Reports

• 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

Interactive Tools

• Jupyter widgets for Colab/notebook analysis
• Streamlit web application
• Preset portfolios (60/40, Three-Fund, All-Weather, etc.)

Usage Examples

Python Package

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()

Optimization

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()

HTML Tear Sheet

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")

Factor Analysis

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

Repository Structure

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

Installation Options

Minimal (Core Analysis)

pip install engineer-investor-portfolio

With Optimization

pip install "engineer-investor-portfolio[optimization]"

With Interactive Widgets

pip install "engineer-investor-portfolio[interactive]"

With Factor Analysis

pip install "engineer-investor-portfolio[factors]"

For Streamlit App

pip install "engineer-investor-portfolio[streamlit]"

Full Development

pip install "engineer-investor-portfolio[all]"

Contributing

We welcome contributions from the community. Please read the following guidelines:

1. Fork the repository
2. Create a new branch (git checkout -b feature-name)
3. Commit your changes (git commit -m 'Add feature')
4. Push to the branch (git push origin feature-name)
5. Create a Pull Request

See also: Beginner's Guide to Contributing

Roadmap

• 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

Related Resources

• Awesome Quant - Curated quant finance resources
• QuantStats - Portfolio analytics
• PyPortfolioOpt - Portfolio optimization
• Riskfolio-Lib - Portfolio optimization and risk management

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

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.

Contact

• Twitter: @egr_investor
• GitHub: engineerinvestor
• Email: egr.investor (gmail)