Financial Risk Analyzer
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:
1. 💀 Is this company going bankrupt?
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)
2. 💸 How much money could I lose?
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)
3. 📉 How would my portfolio survive a market crash?
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%
Key Features
- ✅ 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
🚀 Quick Start
Installation
# 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
Common Use Cases
# 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 50000
📖 Detailed Documentation
1. Altman Z-Score Module - “Is this company going bankrupt?”
What 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.csv
Understanding 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!
2. Value at Risk (VaR) Module - “How much could I lose?”
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 50000
Understanding the Results:
Example: You have $100,000 invested in AAPL and MSFT
python main.py var AAPL MSFT --portfolio-value 100000
Output:
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
3. Stress Test Module - “How would I survive a market crash?”
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 100000
Understanding the Results:
Example: Testing $100k TSLA + AAPL portfolio during COVID crash
python main.py stress TSLA AAPL --scenario covid --portfolio-value 100000
Output:
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 |
💱 Multi-Currency Support - “Can I mix international stocks?”
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.
Supported Currencies
| 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 |
How It Works
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.
Real Example
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 50000
What 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
Important Limitations
⚠️ EUR didn’t exist before 1999 - Can’t use EUR for Dot-Com crisis (2000-2002)
⚠️ Limited pre-1990 data - Some currency pairs have sparse historical data
# ❌ 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 USD
📁 Project Structure
financial-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
💡 Use Cases
Risk Management
- Monitor bankruptcy risk across portfolio holdings
- Calculate maximum expected losses
- Test resilience against historical crises
Investment Analysis
- Screen stocks for financial health
- Compare risk profiles across sectors
- Identify distressed companies
Portfolio Construction
- Balance risk across multiple assets
- Stress test allocation strategies
- Optimize risk-adjusted returns
Academic Research
- Financial modeling and analysis
- Crisis impact studies
- Risk assessment methodologies
🛠️ Advanced Examples
Combined Analysis Workflow
# 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 covid
Example 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
Batch Processing from File
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
📋 Requirements
- 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.txt
Note: This toolkit is compatible with the latest yfinance API changes and automatically handles MultiIndex DataFrame structures.
⚠️ Limitations
-
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
--verbose flag 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
🧪 Testing
The project includes comprehensive test coverage with 170 tests covering all modules and functionality.
Running Tests
# 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
Test Coverage
| 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.
🤝 Contributing
Contributions are welcome! Areas for improvement:
How to Contribute
- 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
📚 Background
Altman Z-Score
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”
Value at Risk (VaR)
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
Stress testing evaluates portfolio performance under extreme but plausible adverse scenarios. Required by regulators for financial institutions post-2008 crisis.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- 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
📞 Support
⭐ Star History
If you find this tool useful, please consider giving it a star! ⭐
Made with ❤️ for the quantitative finance community
评论