README.md
# Estimate Analysis
Deep-dive into analyst estimates and revision trends for any stock using Yahoo Finance data.
## What it does
- Shows EPS and revenue estimate distributions across all periods (current/next quarter, current/next year)
- Tracks estimate revision trends over 7, 30, 60, and 90-day windows
- Counts upward vs downward revisions to measure revision breadth
- Compares growth estimates against industry, sector, and S&P 500 benchmarks
- Assesses historical estimate accuracy with beat/miss patterns
## Triggers
`estimate analysis for AAPL`, `analyst estimate trends for NVDA`, `EPS revisions for TSLA`, `how have estimates changed for MSFT`, `estimate revisions`, `EPS trend`, `revenue estimates`, `consensus changes`, `analyst estimates`, `growth estimates`, `are estimates going up or down`, `estimate momentum`, `revision trend`, `forward estimates`, `bull case vs bear case estimates`, `estimate spread`
## Prerequisites
- Python 3.8+
- `yfinance` (auto-installed if missing)
## Platform
All platforms (Claude Code, Claude.ai, other agents)
## Setup
No setup required — yfinance pulls data from Yahoo Finance without authentication.
## Reference Files
- `references/api_reference.md` — yfinance API reference for all estimate-related methods
references/api_reference.md
# Estimate Analysis — yfinance API Reference
Detailed reference for the yfinance estimate and analysis methods.
---
## Earnings Estimate
```python
ticker.earnings_estimate
```
Returns a DataFrame indexed by period with columns:
- `numberOfAnalysts` — analyst count
- `avg` — consensus average EPS
- `low` — lowest EPS estimate
- `high` — highest EPS estimate
- `yearAgoEps` — EPS from same period last year
- `growth` — expected growth rate (decimal: 0.127 = 12.7%)
Periods:
- `0q` — current quarter
- `+1q` — next quarter
- `0y` — current fiscal year
- `+1y` — next fiscal year
---
## Revenue Estimate
```python
ticker.revenue_estimate
```
Same period structure as earnings_estimate. Columns:
- `numberOfAnalysts`
- `avg` — consensus revenue
- `low`, `high` — range
- `yearAgoRevenue` — revenue from same period last year
- `growth` — expected growth rate (decimal)
**Note**: Revenue figures are in raw numbers. Format for display:
```python
def format_revenue(val):
if val >= 1e12: return f"${val/1e12:.1f}T"
if val >= 1e9: return f"${val/1e9:.1f}B"
if val >= 1e6: return f"${val/1e6:.1f}M"
return f"${val:,.0f}"
```
---
## EPS Trend
```python
ticker.eps_trend
```
Shows how the EPS consensus has changed over time. Returns a DataFrame with:
Index: same periods (0q, +1q, 0y, +1y)
Columns:
- `current` — current estimate
- `7daysAgo` — estimate 7 days ago
- `30daysAgo` — estimate 30 days ago
- `60daysAgo` — estimate 60 days ago
- `90daysAgo` — estimate 90 days ago
**Usage**: Calculate the change over each window to identify revision momentum:
```python
trend = ticker.eps_trend
for period in trend.index:
row = trend.loc[period]
change_90d = row['current'] - row['90daysAgo']
change_30d = row['current'] - row['30daysAgo']
pct_change_90d = change_90d / abs(row['90daysAgo']) * 100
print(f"{period}: {change_90d:+.2f} ({pct_change_90d:+.1f}%) over 90 days")
```
---
## EPS Revisions
```python
ticker.eps_revisions
```
Shows the count of upward and downward estimate revisions. Returns a DataFrame with:
Index: periods (0q, +1q, 0y, +1y)
Columns:
- `upLast7days` — number of upward revisions in last 7 days
- `upLast30days` — number of upward revisions in last 30 days
- `downLast7days` — number of downward revisions in last 7 days
- `downLast30days` — number of downward revisions in last 30 days
**Revision ratio** (useful metric):
```python
revisions = ticker.eps_revisions
for period in revisions.index:
row = revisions.loc[period]
total_30d = row['upLast30days'] + row['downLast30days']
if total_30d > 0:
ratio = row['upLast30days'] / total_30d
print(f"{period}: {ratio:.0%} bullish ({row['upLast30days']} up, {row['downLast30days']} down)")
```
---
## Growth Estimates
```python
ticker.growth_estimates
```
Returns a DataFrame comparing the company's growth rates to benchmarks.
Index (rows): growth periods
- `Current Qtr` or `0q`
- `Next Qtr` or `+1q`
- `Current Year` or `0y`
- `Next Year` or `+1y`
- `Past 5 Years (per annum)` — historical annual growth
- `Next 5 Years (per annum)` — projected annual growth (PEG ratio basis)
Columns: entity names
- The ticker symbol (e.g., `AAPL`)
- `Industry` — industry average
- `Sector` — sector average
- `S&P 500` — market average (may appear as `S&P 500` or `index`)
Values are in decimal form (0.127 = 12.7%). Some cells may be NaN if data is unavailable.
---
## Earnings History
```python
ticker.earnings_history
```
Returns a DataFrame with the last 4 quarters:
Columns:
- `epsEstimate` — consensus at time of reporting
- `epsActual` — reported EPS
- `epsDifference` — actual minus estimate
- `surprisePercent` — in decimal form (0.037 = 3.7%)
Index: earnings report dates (datetime)
---
## Combining Estimate Data
For a comprehensive analysis, fetch all estimate data together:
```python
import yfinance as yf
import pandas as pd
t = yf.Ticker("AAPL")
# All estimate data
data = {
'earnings_estimate': t.earnings_estimate,
'revenue_estimate': t.revenue_estimate,
'eps_trend': t.eps_trend,
'eps_revisions': t.eps_revisions,
'growth_estimates': t.growth_estimates,
'earnings_history': t.earnings_history,
}
# Check what's available
for name, df in data.items():
if df is not None and not (hasattr(df, 'empty') and df.empty):
print(f"{name}: {df.shape}")
else:
print(f"{name}: NO DATA")
```
---
## Error Handling
```python
try:
est = ticker.earnings_estimate
if est is None or (hasattr(est, 'empty') and est.empty):
print("No earnings estimates — may lack analyst coverage")
except Exception as e:
print(f"Error: {e}")
```
Common issues:
- **No estimates**: Small-cap or foreign stocks may have no analyst coverage
- **Partial data**: Some periods may have data while others are NaN
- **Stale data**: Yahoo Finance may not reflect the most recent revision; note lag to user
- **Growth estimates missing benchmarks**: Industry/sector/S&P columns may be NaN for some companies
- **EPS trend columns**: Column names may vary slightly — check `df.columns` if expected names don't match
SKILL.md
---
name: estimate-analysis
description: >
Deep-dive into analyst estimates and revision trends for any stock using Yahoo Finance data.
Use when the user wants to understand analyst estimate direction,
how EPS or revenue forecasts changed over time, compare estimate distributions,
or analyze growth projections across periods.
Triggers: "estimate analysis for AAPL", "analyst estimate trends for NVDA",
"EPS revisions for TSLA", "how have estimates changed for MSFT",
"estimate revisions", "EPS trend", "revenue estimates",
"consensus changes", "analyst estimates", "estimate distribution",
"growth estimates for", "estimate momentum", "revision trend",
"forward estimates", "next quarter estimates", "annual estimates",
"estimate spread", "bull vs bear estimates", "estimate range",
or any request about tracking or comparing analyst estimates/revisions.
Use this skill when the user asks about estimates beyond a simple lookup —
if they want context, trends, or analysis, this is the right skill.
---
# Estimate Analysis Skill
Deep-dives into analyst estimates and revision trends using Yahoo Finance data via [yfinance](https://github.com/ranaroussi/yfinance). Covers EPS and revenue estimate distributions, revision momentum, growth projections, and multi-period comparisons — the full picture of where the street thinks a company is heading.
**Important**: Data is for research and educational purposes only. Not financial advice. yfinance is not affiliated with Yahoo, Inc.
---
## Step 1: Ensure yfinance Is Available
**Current environment status:**
```
!`python3 -c "exec('try:\n import yfinance\n print(\'yfinance \' + yfinance.__version__ + \' installed\')\nexcept Exception:\n print(\'YFINANCE_NOT_INSTALLED\')')"`
```
If `YFINANCE_NOT_INSTALLED`, install it:
```python
import subprocess, sys
subprocess.check_call([sys.executable, "-m", "pip", "install", "-q", "yfinance"])
```
If already installed, skip to the next step.
---
## Step 2: Identify the Ticker and Gather Estimate Data
Extract the ticker from the user's request. Fetch all estimate-related data in one script.
```python
import yfinance as yf
import pandas as pd
ticker = yf.Ticker("AAPL") # replace with actual ticker
# --- Estimate data ---
earnings_est = ticker.earnings_estimate # EPS estimates by period
revenue_est = ticker.revenue_estimate # Revenue estimates by period
eps_trend = ticker.eps_trend # EPS estimate changes over time
eps_revisions = ticker.eps_revisions # Up/down revision counts
growth_est = ticker.growth_estimates # Growth rate estimates
# --- Historical context ---
earnings_hist = ticker.earnings_history # Track record
info = ticker.info # Company basics
quarterly_income = ticker.quarterly_income_stmt # Recent actuals
```
### What each data source provides
| Data Source | What It Shows | Why It Matters |
|---|---|---|
| `earnings_estimate` | Current EPS consensus by period (0q, +1q, 0y, +1y) | The estimate levels — what analysts expect |
| `revenue_estimate` | Current revenue consensus by period | Top-line expectations |
| `eps_trend` | How the EPS estimate has changed (7d, 30d, 60d, 90d ago) | Revision direction — rising or falling expectations |
| `eps_revisions` | Count of upward vs downward revisions (7d, 30d) | Revision breadth — are most analysts raising or cutting? |
| `growth_estimates` | Growth rate estimates vs peers and sector | Relative positioning |
| `earnings_history` | Actual vs estimated for last 4 quarters | Calibration — how good are these estimates historically? |
---
## Step 3: Route Based on User Intent
The user might want different levels of analysis. Route accordingly:
| User Request | Focus Area | Key Sections |
|---|---|---|
| General estimate analysis | Full analysis | All sections |
| "How have estimates changed" | Revision trends | EPS Trend + Revisions |
| "What are analysts expecting" | Current consensus | Estimate overview |
| "Growth estimates" | Growth projections | Growth Estimates |
| "Bull vs bear case" | Estimate range | High/low spread analysis |
| Compare estimates across periods | Multi-period | Period comparison table |
When in doubt, provide the full analysis — more context is better.
---
## Step 4: Build the Estimate Analysis
### Section 1: Estimate Overview
Present the current consensus for all available periods from `earnings_estimate` and `revenue_estimate`:
**EPS Estimates:**
| Period | Consensus | Low | High | Range Width | # Analysts | YoY Growth |
|---|---|---|---|---|---|---|
| Current Qtr (0q) | $1.42 | $1.35 | $1.50 | $0.15 (10.6%) | 28 | +12.7% |
| Next Qtr (+1q) | $1.58 | $1.48 | $1.68 | $0.20 (12.7%) | 25 | +8.3% |
| Current Year (0y) | $6.70 | $6.50 | $6.95 | $0.45 (6.7%) | 30 | +10.2% |
| Next Year (+1y) | $7.45 | $7.10 | $7.85 | $0.75 (10.1%) | 28 | +11.2% |
**Revenue Estimates:**
| Period | Consensus | Low | High | # Analysts | YoY Growth |
|---|---|---|---|---|---|
| Current Qtr | $94.3B | $92.1B | $96.8B | 25 | +5.4% |
| Next Qtr | $102.1B | $99.5B | $105.0B | 22 | +6.1% |
Calculate and flag:
- **Range width** as % of consensus — wide ranges (>15%) signal high uncertainty
- **Analyst coverage** — fewer than 5 analysts means thin coverage, note this
- **Growth trajectory** — is growth accelerating or decelerating across periods?
### Section 2: Revision Trends (EPS Trend)
This is often the most actionable section. From `eps_trend`, show how estimates have moved:
| Period | Current | 7 Days Ago | 30 Days Ago | 60 Days Ago | 90 Days Ago |
|---|---|---|---|---|---|
| Current Qtr | $1.42 | $1.41 | $1.40 | $1.38 | $1.35 |
| Next Qtr | $1.58 | $1.57 | $1.56 | $1.55 | $1.54 |
| Current Year | $6.70 | $6.68 | $6.65 | $6.58 | $6.50 |
| Next Year | $7.45 | $7.43 | $7.40 | $7.35 | $7.28 |
Summarize the trend: "Current quarter EPS estimates have risen 5.2% over the last 90 days, with most of the increase in the last 30 days — accelerating upward revision momentum."
**Key interpretation:**
- Rising estimates ahead of earnings = positive setup (the bar is rising)
- Falling estimates = analysts cutting numbers, often a negative signal
- Flat estimates = no new information being priced in
- Recent acceleration/deceleration matters more than the total move
### Section 3: Revision Breadth (EPS Revisions)
From `eps_revisions`, show the up vs. down count:
| Period | Up (last 7d) | Down (last 7d) | Up (last 30d) | Down (last 30d) |
|---|---|---|---|---|
| Current Qtr | 5 | 1 | 12 | 3 |
| Next Qtr | 3 | 2 | 8 | 5 |
Calculate a revision ratio: Up / (Up + Down). Ratios above 0.7 are strongly bullish; below 0.3 are bearish.
### Section 4: Growth Estimates
From `growth_estimates`, compare the company's expected growth to benchmarks:
| Entity | Current Qtr | Next Qtr | Current Year | Next Year | Past 5Y Annual |
|---|---|---|---|---|---|
| AAPL | +12.7% | +8.3% | +10.2% | +11.2% | +14.5% |
| Industry | +9.1% | +7.0% | +8.5% | +9.0% | — |
| Sector | +11.3% | +8.8% | +10.0% | +10.5% | — |
| S&P 500 | +7.5% | +6.2% | +8.0% | +8.5% | — |
Highlight whether the company is expected to grow faster or slower than its peers.
### Section 5: Historical Estimate Accuracy
From `earnings_history`, assess how reliable estimates have been:
| Quarter | Estimate | Actual | Surprise % | Direction |
|---|---|---|---|---|
| Q3 2024 | $1.35 | $1.40 | +3.7% | Beat |
| Q2 2024 | $1.30 | $1.33 | +2.3% | Beat |
| Q1 2024 | $1.52 | $1.53 | +0.7% | Beat |
| Q4 2023 | $2.10 | $2.18 | +3.8% | Beat |
Calculate:
- **Beat rate**: X of 4 quarters
- **Average surprise**: magnitude and direction
- **Trend in surprise**: Are beats getting bigger or smaller? A shrinking surprise with rising estimates could mean the bar is catching up to reality.
---
## Step 5: Synthesize and Respond
Present the analysis with clear structure:
1. **Lead with the key insight**: "AAPL estimates are trending higher across all periods, with positive revision breadth (80% of recent revisions are upward)."
2. **Show the tables** for each section the user cares about
3. **Provide interpretive context**:
- Is the revision trend confirming or contradicting the stock's recent price action?
- How does the growth outlook compare to what's priced into the current P/E?
- What's the relationship between estimate accuracy history and current estimate levels?
4. **Flag risks and nuances**:
- Estimates cluster around consensus — the "real" distribution of outcomes is wider than low/high suggests
- Revision momentum can reverse quickly on a single data point (guidance change, macro event)
- Yahoo Finance estimates may lag behind real-time consensus providers by hours or days
- Growth estimates for out-years (+1y) are inherently less reliable
### Caveats to always include
- Analyst estimates reflect a consensus view, not certainty
- Estimate revisions are a signal but not a guarantee of future performance
- This is not financial advice
---
## Reference Files
- `references/api_reference.md` — Detailed yfinance API reference for all estimate-related methods
Read the reference file when you need exact return formats or edge case handling.