A Python command-line tool that analyzes financial risk for stocks and portfolios using real data from Yahoo Finance.
This tool helps you answer three critical investment questions:
Altman Z-Score Module - Analyzes a company's financial health using balance sheet data (assets, liabilities, earnings). Gives you a score that predicts bankruptcy risk.
Example: "Is Tesla financially healthy?"
python main.py zscore TSLA
# Result: Z-Score = 18.79 → Safe (Low bankruptcy risk)Value at Risk (VaR) Module - Calculates the maximum amount you could lose on an investment with 95% confidence over a specific time period, based on historical price volatility.
Example: "If I invest $100,000 in Apple and Microsoft, what's my worst-case loss over 1 day?"
python main.py var AAPL MSFT --portfolio-value 100000
# Result: VaR = $2,602 → You won't lose more than $2,602 in a day (95% confidence)Stress Test Module - Shows exactly how your portfolio would have performed during real historical crises (COVID-19 crash, 2008 Financial Crisis, Dot-Com bubble).
Example: "How would my Tesla + Apple portfolio have performed during COVID crash?"
python main.py stress TSLA AAPL --scenario covid
# Result: Portfolio lost -21.35%, Max Drawdown: -41.19%- ✅ Automatic Data Fetching - Pulls real financial data from Yahoo Finance
- 🌍 Multi-Currency Support - Mix US stocks ($), European stocks (€), UK stocks (£), etc. in one portfolio
- 📊 Three Risk Analysis Methods - Bankruptcy prediction, loss calculation, crisis simulation
- 🎯 Portfolio Analysis - Analyze multiple stocks together with proper correlations
- 💾 CSV Export - All results saved to spreadsheet-friendly CSV files
# 1. Clone the repository
git clone https://github.com/vdamov/financial-risk-analyzer.git
cd financial-risk-analyzer
# 2. Install dependencies (requires Python 3.8+)
pip install -r requirements.txt
# 3. Run your first analysis
python main.py zscore TSLA# Check if a company is financially healthy
python main.py zscore TSLA AAPL MSFT
# Calculate potential losses for a $100k portfolio
python main.py var AAPL MSFT --portfolio-value 100000 --days 1
# See how your portfolio would perform in a market crash
python main.py stress AAPL MSFT --scenario covid
# Analyze an international portfolio (EUR portfolio with US + European stocks)
python main.py var AAPL ASML.AS --currency EUR --portfolio-value 50000What it does: Analyzes a company's financial statements (balance sheet, income statement) and calculates a single score that predicts bankruptcy risk. Scores above 3 are safe, below 1.8 indicate high bankruptcy risk.
When to use it: Before investing in a stock, checking financial health of holdings, screening for distressed companies.
How it works: Uses 5 financial ratios (working capital/assets, retained earnings/assets, EBIT/assets, market value/liabilities, sales/assets) combined with a proven formula developed by Dr. Edward Altman in 1968.
# Basic usage
python main.py zscore TSLA AAPL MSFT
# European stocks
python main.py zscore ASML.AS SOLB.BR SAP.DE
# With verbose classification reasoning
python main.py zscore NVDA AMD INTC --verbose
# Save to custom file
python main.py zscore TSLA --out my_results.csvUnderstanding the Results:
| Your Score | What It Means | Action |
|---|---|---|
| Above 3.0 | 🟢 Safe Zone | Company is financially healthy |
| 1.8 - 3.0 | 🟡 Grey Zone | Moderate risk, watch carefully |
| Below 1.8 | 🔴 Distress | High bankruptcy risk, avoid or sell |
Example Output:
Ticker Company ZScore Zone
TSLA Tesla, Inc. 18.79 Safe ← Healthy company
AAPL Apple Inc. 1.87 Grey Zone ← Moderate concern
XYZ Struggling Corp. 0.45 Distress ← High risk!
What it does: Calculates the maximum amount of money you're likely to lose on an investment over a specific time period (e.g., 1 day, 10 days) with a given confidence level (typically 95%).
When to use it: Portfolio risk assessment, position sizing, setting stop losses, regulatory compliance, comparing risk across investments.
How it works: Analyzes historical price movements to estimate future volatility. Three calculation methods available:
- Historical: Uses actual past returns (most conservative)
- Parametric: Assumes normal distribution (fastest)
- Monte Carlo: Simulates 10,000 possible scenarios (most comprehensive)
# Single stock VaR
python main.py var TSLA --confidence 95 --days 1
# Portfolio VaR with equal weights
python main.py var TSLA AAPL MSFT --confidence 99 --days 10
# Custom portfolio weights (must sum to 1.0)
python main.py var TSLA AAPL MSFT --weights 0.5 0.3 0.2
# Use dollar values instead of weights
python main.py var TSLA AAPL MSFT --values 50000 30000 20000
# Different methods
python main.py var TSLA --method parametric
python main.py var TSLA --method historical
python main.py var TSLA --method monte_carlo
# Custom portfolio value
python main.py var TSLA AAPL --portfolio-value 500000
# Multi-currency portfolio (EUR portfolio with US and European stocks)
python main.py var AAPL ASML.AS SAP.DE --currency EUR --portfolio-value 100000
# GBP portfolio with London and US stocks
python main.py var AAPL HSBA.L --currency GBP --values 50000 50000Understanding the Results:
Example: You have $100,000 invested in AAPL and MSFT
python main.py var AAPL MSFT --portfolio-value 100000Output:
Ticker Position Value VaR (95.0%) VaR %
AAPL $50,000.00 $1,283.04 2.57%
MSFT $50,000.00 $1,104.59 2.21%
PORTFOLIO $100,000.00 $2,387.63 2.39%
What this means:
- With 95% confidence, your portfolio won't lose more than $2,387.63 tomorrow
- In plain English: "On 95 out of 100 days, your losses will be less than $2,388"
- Only on 5 out of 100 days (the worst 5%) would you lose more than this
- Portfolio VaR is less than the sum of individual VaRs due to diversification benefits
Available Confidence Levels:
- 95% (default) - Standard for risk management
- 99% - Very conservative, captures extreme events
- 90% - Less conservative, for aggressive strategies
What it does: Shows exactly how your portfolio would have performed during actual historical market crashes (COVID-19, 2008 Financial Crisis, Dot-Com bubble). Gives you real numbers: how much you would have lost, maximum drawdown, and recovery.
When to use it: Testing portfolio resilience, understanding worst-case scenarios, comparing different allocation strategies, preparing for market volatility.
How it works: Uses actual historical price data from crisis periods. Calculates your portfolio returns day-by-day through the crash, including correlations between stocks (how they move together).
# Test against COVID-19 crash
python main.py stress TSLA AAPL --scenario covid
# Test against 2008 Financial Crisis
python main.py stress TSLA AAPL --scenario gfc
# Test against Dot-Com bubble
python main.py stress TSLA AAPL --scenario dotcom
# Run all crisis scenarios
python main.py stress TSLA AAPL --scenario all
# Custom portfolio using weights
python main.py stress TSLA AAPL MSFT --weights 0.4 0.4 0.2 --portfolio-value 250000
# Custom portfolio using dollar values
python main.py stress TSLA AAPL MSFT --values 100000 100000 50000
# Multi-currency portfolio (EUR portfolio in COVID crash)
python main.py stress AAPL ASML.AS --scenario covid --currency EUR --portfolio-value 100000Understanding the Results:
Example: Testing $100k TSLA + AAPL portfolio during COVID crash
python main.py stress TSLA AAPL --scenario covid --portfolio-value 100000Output:
COVID-19 Crash (Feb 2020 - Mar 2020)
Ticker Start Price End Price Return Gain/Loss Max Drawdown
TSLA $52.00 $33.48 -35.62% -$17,810 -60.63%
AAPL $74.55 $61.69 -17.25% -$8,625 -31.43%
Portfolio Impact (with correlations):
Return: -21.35%
Loss: -$21,354
Max Drawdown: -41.19%
Final Value: $78,645
What this means:
- Your $100k portfolio would have dropped to $78,645 (lost $21,354)
- Tesla dropped 35.6%, Apple dropped 17.2%
- At the worst point, your portfolio was down 41.2% (max drawdown)
- Diversification helped: portfolio lost 21.4% vs 26.4% simple average
Available Crisis Scenarios:
| Scenario | Period | Market Drop | What Happened |
|---|---|---|---|
| covid | Feb-Mar 2020 | -34% (S&P 500) | COVID-19 pandemic crash, fastest bear market in history |
| gfc | 2007-2009 | -57% (S&P 500) | 2008 Financial Crisis, housing bubble burst |
| dotcom | 2000-2002 | -49% (NASDAQ) | Tech bubble burst, 9/11 attacks |
| all | All three | Varies | Tests all scenarios sequentially |
Yes! You can analyze portfolios with US stocks ($), European stocks (€), UK stocks (£), Japanese stocks (¥), etc. all together.
Why this matters: If you have a portfolio in EUR but own Apple (USD) and ASML (EUR), the tool automatically converts Apple's prices to EUR using historical exchange rates. This gives you accurate returns that include both stock performance AND currency movements.
| Currency | Symbol | Example Stocks |
|---|---|---|
| USD ($) | US Dollar | AAPL, MSFT, GOOGL |
| EUR (€) | Euro | ASML.AS, SAP.DE, SOLB.BR |
| GBP (£) | British Pound | HSBA.L, BP.L |
| JPY (¥) | Japanese Yen | 7203.T (Toyota) |
| CAD (C$) | Canadian Dollar | SHOP.TO |
| AUD (A$) | Australian Dollar | BHP.AX |
| CHF | Swiss Franc | NESN.SW |
Step 1: Automatic Detection The tool detects each stock's currency from its ticker suffix:
AAPL → USD (no suffix = US)
ASML.AS → EUR (Amsterdam)
HSBA.L → GBP (London)
7203.T → JPY (Tokyo)
Step 2: Historical Conversion Uses actual forex rates from each date in history, not just today's rate. This is crucial for accurate historical analysis.
Step 3: Calculation Calculates returns in your chosen currency, accounting for both stock price changes AND currency movements.
You're in Europe with a EUR portfolio containing Apple (USD) and ASML (EUR):
python main.py var AAPL ASML.AS --currency EUR --values 50000 50000What happens:
- Tool fetches AAPL prices in USD, ASML prices in EUR
- Converts AAPL to EUR using historical USD/EUR exchange rates
- Calculates VaR in EUR for your 100k EUR portfolio
Your output includes currency info:
💱 Currency Conversion:
Portfolio Currency: EUR
EUR stocks: ASML.AS (no conversion needed)
USD→EUR: AAPL converted at avg rate 0.9126
# ❌ This FAILS (EUR introduced in 1999)
python main.py stress AAPL --scenario dotcom --currency EUR
# ✅ This WORKS
python main.py stress AAPL --scenario dotcom --currency USDfinancial-risk-analyzer/
├── main.py # CLI entry point
├── modules/
│ ├── __init__.py
│ ├── zscore.py # Altman Z-Score module
│ ├── var.py # Value at Risk module
│ └── stress_test.py # Stress testing module
├── utils/
│ ├── __init__.py
│ ├── data_fetcher.py # Yahoo Finance data fetching
│ ├── portfolio_utils.py # Portfolio utilities
│ ├── currency_converter.py # Currency conversion & forex rates
│ └── helpers.py # Classification & utilities
├── tests/
│ ├── test_currency_converter.py # Currency conversion tests (40 tests)
│ ├── test_zscore.py # Z-Score calculation tests (34 tests)
│ ├── test_var.py # VaR calculation tests (54 tests)
│ ├── test_stress_test.py # Stress test logic tests (31 tests)
│ └── test_integration.py # CLI integration tests (51 tests)
├── config.py # Configuration constants
├── requirements.txt
└── README.md
- Monitor bankruptcy risk across portfolio holdings
- Calculate maximum expected losses
- Test resilience against historical crises
- Screen stocks for financial health
- Compare risk profiles across sectors
- Identify distressed companies
- Balance risk across multiple assets
- Stress test allocation strategies
- Optimize risk-adjusted returns
- Financial modeling and analysis
- Crisis impact studies
- Risk assessment methodologies
# 1. Check financial health
python main.py zscore TSLA AAPL MSFT --verbose
# 2. Measure current risk with value-based allocation
python main.py var TSLA AAPL MSFT --values 40000 35000 25000
# 3. Test historical resilience with same allocation
python main.py stress TSLA AAPL MSFT --values 40000 35000 25000 --scenario covidExample Output:
Ticker Company Region Classification Model ZScore Zone Industry
TSLA Tesla, Inc. US Mfg Original 18.79 Safe Auto Manufacturers
AAPL Apple Inc. US Non-Mfg Modified 1.87 Grey Zone Consumer Electronics
MSFT Microsoft Corporation US Non-Mfg Modified 4.46 Safe Software - Infrastructure
================================================================================
Ticker Method Position Value VaR (95.0%) VaR % Days
TSLA Historical $40,000.00 $2,221.27 5.55% 1
AAPL Historical $35,000.00 $946.98 2.71% 1
MSFT Historical $25,000.00 $539.14 2.16% 1
PORTFOLIO Historical $100,000.00 $2,602.41 2.60% 1
================================================================================
💡 Interpretation:
Portfolio VaR: With 95.0% confidence, you will not lose more than
$2,602.41 (2.60%) over 1 day(s).
================================================================================
📉 COVID-19 Crash (2020-02-01 to 2020-03-31)
Global pandemic market crash
Historical Market Drop: -33.9%
================================================================================
Ticker Start Price End Price Return Gain/Loss Max Drawdown
TSLA $52.00 $33.48 -35.62% -$14,249.74 -60.63%
AAPL $74.55 $61.69 -17.25% -$6,037.65 -31.43%
MSFT $165.88 $152.84 -7.86% -$1,965.88 -28.04%
📊 Portfolio Impact:
Portfolio Return (with correlations): -21.35%
Portfolio Gain/Loss: -$21,354.64
Portfolio Max Drawdown: -41.19%
Final Portfolio Value: $78,645.36
Create portfolio.txt:
TSLA
AAPL
MSFT
GOOGL
AMZN
Run analysis:
# Z-Score for all stocks
python main.py zscore $(cat portfolio.txt)
# VaR for portfolio (equal weights)
python main.py var $(cat portfolio.txt) --weights 0.2 0.2 0.2 0.2 0.2
# Or use dollar amounts
python main.py var $(cat portfolio.txt) --values 20000 20000 20000 20000 20000
# Stress test
python main.py stress $(cat portfolio.txt) --scenario all- Python 3.8+
- yfinance >= 0.2.0 (tested with latest versions)
- pandas >= 1.5.0
- numpy >= 1.23.0
- scipy >= 1.9.0
pip install -r requirements.txtNote: This toolkit is compatible with the latest yfinance API changes and automatically handles MultiIndex DataFrame structures.
-
Data Availability
- Requires complete financial data from Yahoo Finance
- Some European stocks may have limited historical data
- Stress tests require data during crisis periods
-
Classification Accuracy
- Automated classification is highly accurate but not perfect
- Use
--verboseflag to review reasoning - Edge cases exist for complex business models
-
VaR Assumptions
- Parametric method assumes normal distribution
- Historical method limited by available data
- Past performance doesn't guarantee future results
-
Not Financial Advice
- Educational and research purposes only
- Always conduct thorough due diligence
- Consider multiple risk factors
The project includes comprehensive test coverage with 170 tests covering all modules and functionality.
# Run all tests
python -m unittest discover -s tests -p "test_*.py"
# Run specific test file
python tests/test_currency_converter.py
python tests/test_zscore.py
python tests/test_var.py
python tests/test_stress_test.py
python tests/test_integration.py
# Run with verbose output
python -m unittest discover -s tests -p "test_*.py" -v| Module | Tests | Coverage |
|---|---|---|
| Currency Converter | 40 tests | 100% - Detection, formatting, spot rates, historical rates, caching |
| Z-Score Module | 34 tests | 100% - Original/Modified formulas, risk zones, validation |
| VaR Module | 54 tests | 100% - All 3 methods (Parametric, Historical, Monte Carlo) |
| Stress Test Module | 31 tests | 100% - Crisis scenarios, drawdown, portfolio stress |
| CLI Integration | 51 tests | 100% - All commands, validation, error handling |
| Total | 170 tests | Complete functional coverage |
All tests pass successfully in ~15 seconds.
Contributions are welcome! Areas for improvement:
- Add more crisis scenarios (1987 crash, 2011 European debt crisis)
- Implement Conditional VaR (CVaR/Expected Shortfall)
- Add more bankruptcy prediction models (Merton, KMV)
- Create visualization dashboard
- Add API for programmatic access
- Machine learning classification improvements
-
Unit tests and integration tests✅ COMPLETED - 170 tests
- Fork the repository
- Create a feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Run tests to ensure nothing breaks:
python -m unittest discover -s tests - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Developed by Edward Altman in 1968, the Z-Score predicts corporate bankruptcy with ~80-90% accuracy up to two years before failure.
Key Papers:
- Altman, E. I. (1968). "Financial Ratios, Discriminant Analysis and the Prediction of Corporate Bankruptcy"
- Altman, E. I. (2000). "Predicting Financial Distress of Companies: Revisiting the Z-Score and ZETA Models"
VaR quantifies the maximum expected loss at a given confidence level over a specified time horizon. Widely used by financial institutions for risk management.
Stress testing evaluates portfolio performance under extreme but plausible adverse scenarios. Required by regulators for financial institutions post-2008 crisis.
This project is licensed under the MIT License - see the LICENSE file for details.
- Edward Altman for developing the Z-Score model
- Yahoo Finance for providing free financial data
- The quantitative finance community for VaR methodologies
- The open-source community
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: See module-specific help with
python main.py [module] --help
If you find this tool useful, please consider giving it a star! ⭐
Made with ❤️ for the quantitative finance community