Stock Data Analyser

A deterministic financial analysis engine that implements Benjamin Graham's value investing methodology with mathematical precision.

Overview

The Stock Data Analyser fetches historical financial data from EODHD API, performs strict calculations based on Graham's formulas, detects statistical anomalies, and generates a structured Markdown dossier optimized for downstream LLM analysis.

Features

• Multi-Exchange Support: Analyze stocks from US, UK, Canadian, European, and Asian markets
• Graham Methodology: Calculate Graham Number, Net-Net Value, and Earnings Power Value (EPV)
• TTM (Trailing Twelve Months) Analysis: More current valuations using the most recent 12 months of periodic data
• Defensive Investor Tests: Evaluate stocks against Graham's seven criteria
• Historical Trend Analysis: 20-year financial history with debt trends, dilution tracking, and historical valuations
• Anomaly Detection: Statistical analysis using Z-Score to identify data quality issues
• Structured Output: Generate Markdown dossiers optimized for LLM parsing

20-Year Financial History Table

The dossier includes an expanded financial history table with 11 columns designed for Graham-style trend analysis:

Core Financials:

• Revenue, Net Income, EPS, Dividend per Share, Book Value per Share

Graham Trend Analysis (New):

• Total Debt - Track debt trends to distinguish companies that grow through retained earnings vs leverage
• Shares Outstanding - Detect shareholder dilution or buyback programs over time
• Year-End Price - Historical stock prices at fiscal year end (from Yahoo Finance)
• Historical P/E - How the market has valued earnings power over time (shows "Negative" for loss years)
• Historical P/B - How the market has valued net assets over time

Example Output:

| Year | Revenue | Net Income | EPS | Div/Share | BVPS | Total Debt | Shares (B) | Price | P/E | P/B |
|------|---------|------------|-----|-----------|------|------------|------------|-------|-----|-----|
| 2025 | 281.7B | 101.8B | 13.64 | 3.40 | 46.01 | USD43.15B | 7.465B | USD495.67 | 36.3 | 10.8 |
| 2024 | 245.1B | 88.1B | 11.80 | 3.08 | 35.95 | USD51.63B | 7.469B | USD441.99 | 37.5 | 12.3 |

Graham's Reasoning: Benjamin Graham didn't just look at current financials; he analyzed trends in financial strength. Rising debt may indicate financial stress, increasing shares signal dilution, and historical P/E ratios reveal if current valuations are historically cheap or expensive.

TTM (Trailing Twelve Months) Analysis

The dossier includes a TTM analysis section that provides more current financial metrics than annual calculations. This is especially valuable when analyzing companies several months after their fiscal year end.

What is TTM? TTM calculations use the most recent 12 months of periodic data (quarterly or semi-annual reports) to provide up-to-date financial metrics. For example, if analyzing a company in December 2025 whose fiscal year ends in June, annual calculations would be based on June 2025 data (6 months old), while TTM calculations would include data through September 2025 (only 3 months old).

Automatic Reporting Frequency Detection: The system automatically detects whether a company reports quarterly (4 periods) or semi-annually (2 periods) by analyzing the intervals between reporting dates:

• ~90 days (±15 days) → Quarterly reporter
• ~180 days (±30 days) → Semi-annual reporter

TTM Metrics Calculated:

• TTM Graham Number
• TTM Tangible Book Value Per Share (TBVPS)
• TTM Net-Net Working Capital Value
• TTM Margin of Safety
• TTM P/E Ratio
• TTM P/B Ratio

Example TTM Section Output:

## SECTION 1.5: TTM (TRAILING TWELVE MONTHS) ANALYSIS

**Reporting Frequency Detected**: Quarterly (4 periods)
**Date Range Covered**: Q4 2024 through Q3 2025

**TTM Graham Calculations:**
- TTM Graham Number: USD 285.43 (vs Annual: USD 267.89, +6.6%)
- TTM TBVPS: USD 29.87 (vs Annual: USD 28.45, +5.0%)
- TTM Net-Net Value: USD 15.23 (vs Annual: USD 14.67, +3.8%)
- TTM Margin of Safety: 12.5% (vs Annual: 8.3%, +4.2pp)
- TTM P/E Ratio: 28.5 (vs Annual: 23.4, +21.8%)
- TTM P/B Ratio: 13.6 (vs Annual: 12.8, +6.3%)

Key Differences from Annual Calculations:

• Income Statement Items (Revenue, Net Income, EPS): Summed over the selected periods
• EPS Calculation: TTM EPS = Sum(Net Income) / Most Recent Shares Outstanding (not sum of EPS values)
• Balance Sheet Items (Assets, Liabilities, Equity): Use the most recent period value only
• Currency Conversion: Uses current FX rates (same as annual data)

Graceful Degradation: If periodic data is unavailable or insufficient, the system continues with annual calculations only and adds a warning explaining why TTM analysis was skipped.

Installation

1. Clone the repository
2. Install dependencies:

pip install -r requirements.txt

3. Configure your EODHD API key in .env:

EODHD_API_KEY=your_api_key_here

Note: yfinance (Yahoo Finance) is used for real-time price data and does not require an API key. Only the EODHD API key is required for fundamental financial data.

EODHD API Package Requirements

To use this tool, you need to purchase the following EODHD API packages:

• Fundamentals Package (Required) - Provides balance sheet, income statement, cash flow, and company fundamentals data
• EOD Historical Data - All World Package (Optional) - Provides more accurate and complete dividend history across all exchanges

Without the Fundamentals Package, the tool will not be able to fetch the necessary financial data. The All World Package is recommended for investors who need comprehensive dividend data, but the tool can function with the Fundamentals Package alone (using forward dividend rates as fallback).

Usage

python stock_data_analyser.py AAPL.US
python stock_data_analyser.py YU.LSE
python stock_data_analyser.py RY.TO

Supported Stock Exchanges

The Stock Data Analyser supports 50+ stock exchanges worldwide through EODHD API. When EODHD price data is unavailable, the system automatically falls back to yfinance (Yahoo Finance) with automatic exchange code translation.

Ticker Format

Use the format SYMBOL.EXCHANGE where:

• SYMBOL is the stock ticker (e.g., "AAPL", "YU", "RY")
• EXCHANGE is the EODHD exchange code (see below)

Examples:

• AAPL.US - Apple Inc. on US exchanges
• YU.LSE - Yu Group on London Stock Exchange
• RY.TO - Royal Bank of Canada on Toronto Stock Exchange
• VOD.LSE - Vodafone on London Stock Exchange

Exchange Codes by Region

North America

• US - United States (NYSE, NASDAQ, AMEX)
• TO - Toronto Stock Exchange (Canada)
• V - TSX Venture Exchange (Canada)
• MX - Mexican Stock Exchange

Europe

• LSE - London Stock Exchange (UK) ⭐ Most commonly used
• IL - London International Exchange
• XETRA - XETRA (Germany) ⭐ Most commonly used
• F - Frankfurt Stock Exchange
• BE - Berlin Stock Exchange
• PA - Euronext Paris (France) ⭐ Most commonly used
• AS - Euronext Amsterdam (Netherlands)
• BR - Euronext Brussels (Belgium)
• LS - Euronext Lisbon (Portugal)
• MC - Madrid Stock Exchange (Spain)
• MI - Milan Stock Exchange (Italy)
• SW - SIX Swiss Exchange (Switzerland)
• VI - Vienna Stock Exchange (Austria)
• IR - Irish Stock Exchange
• ST - Stockholm Stock Exchange (Sweden)
• OL - Oslo Stock Exchange (Norway)
• CO - Copenhagen Stock Exchange (Denmark)
• HE - Helsinki Stock Exchange (Finland)
• IC - Iceland Stock Exchange
• WAR - Warsaw Stock Exchange (Poland)
• BUD - Budapest Stock Exchange (Hungary)
• PR - Prague Stock Exchange (Czech Republic)
• MCX - Moscow Exchange (Russia)
• IS - Istanbul Stock Exchange (Turkey)
• AT - Athens Stock Exchange (Greece)

Asia Pacific

• AU - Australian Securities Exchange ⭐ Most commonly used
• TSE - Tokyo Stock Exchange (Japan)
• HK - Hong Kong Stock Exchange ⭐ Most commonly used
• SHG - Shanghai Stock Exchange (China)
• SHE - Shenzhen Stock Exchange (China)
• NSE - National Stock Exchange of India
• BSE - Bombay Stock Exchange (India)
• KO - Korea Stock Exchange
• KQ - KOSDAQ (Korea)
• TW - Taiwan Stock Exchange
• SG - Singapore Exchange
• BK - Stock Exchange of Thailand (Bangkok)
• JK - Indonesia Stock Exchange (Jakarta)
• KLSE - Bursa Malaysia (Kuala Lumpur)

Other Regions

• SA - B3 (Brazil)
• JSE - Johannesburg Stock Exchange (South Africa)
• SR - Saudi Stock Exchange (Tadawul)
• TA - Tel Aviv Stock Exchange (Israel)

⭐ Most Commonly Used Exchanges: US, LSE, TO, XETRA, PA, HK, AU

Price Data Fallback

The system uses a two-tier approach for price data:

1. Primary Source: yfinance (Yahoo Finance - real-time prices, no API key required)
2. Fallback Source: EODHD API (extracted from fundamentals data)

Exchange code translation between EODHD and yfinance formats is handled automatically. yfinance provides current market prices without requiring API keys or rate limits.

Output

The system generates a structured Markdown file ([TICKER]_DOSSIER.md) containing:

• Executive Summary with intrinsic values and margin of safety
• Critical Alerts for data quality issues
• Graham Defensive Tests results
• 20-Year Financial History table with 11 columns (including debt trends, dilution tracking, and historical valuations)
• Comprehensive methodology documentation explaining all calculations

Requirements

• Python 3.9+
• EODHD API key with Fundamentals Package (get one at https://eodhd.com?via=patrick)
  • Required: Fundamentals Package
  • Optional: EOD Historical Data - All World Package (for enhanced dividend history)