Canslim Screener

CANSLIM Stock Screener - Phase 3 (Full CANSLIM)

Overview

This skill screens US stocks using William O'Neil's proven CANSLIM methodology, a systematic approach for identifying growth stocks with strong fundamentals and price momentum. CANSLIM analyzes 7 key components: Current Earnings, Annual Growth, Newness/New Highs, Supply/Demand, Leadership/RS Rank, Institutional Sponsorship, and Market Direction.

Phase 3 implements all 7 of 7 components (C, A, N, S, L, I, M), representing 100% of the full methodology.

Two-Stage Approach:

1. Stage 1 (FMP API + Finviz): Analyze stock universe with all 7 CANSLIM components
2. Stage 2 (Reporting): Rank by composite score and generate actionable reports

Key Features:

• Composite scoring (0-100 scale) with weighted components
• Finviz fallback for institutional ownership data (automatic when FMP data incomplete)
• Progressive filtering to optimize API usage
• JSON + Markdown output formats
• Interpretation bands: Exceptional+ (90+), Exceptional (80-89), Strong (70-79), Above Average (60-69)
• Bear market protection (M component gating)

Phase 3.1 Component Weights (Original O'Neil weights):

• C (Current Earnings): 15%
• A (Annual Growth): 20%
• N (Newness): 15%
• S (Supply/Demand): 15%
• L (Leadership/RS Rank): 20% — multi-period weighted RS (3m/6m/12m vs configurable benchmark)
• I (Institutional): 10%
• M (Market Direction): 5%

Weighted RS Formula:

Weighted RS = 0.40 × rel_3m + 0.30 × rel_6m + 0.30 × rel_12m

Available periods are re-normalized when some are missing. Default benchmark is ^GSPC; override with --rs-benchmark SPY/QQQ/IWM/....

Fallback hierarchy when multi-period data is incomplete:

1. No benchmark → weighted absolute stock performance + 20% penalty.
2. All multi-period windows missing but >=50 bars of price history → fall back to the legacy 365-day full-window absolute return as the scoring input (20% penalty if no benchmark).
3. <50 bars of price history → score=0 with error set.

Future Phases:

• Phase 4: FINVIZ Elite integration → 10x faster execution

When to Use This Skill

Explicit Triggers:

• "Find CANSLIM stocks"
• "Screen for growth stocks using O'Neil's method"
• "Which stocks have strong earnings and momentum?"
• "Identify stocks near 52-week highs with accelerating earnings"
• "Run a CANSLIM screener on [sector/universe]"

Implicit Triggers:

• User wants to identify multi-bagger candidates
• User is looking for growth stocks with proven fundamentals
• User wants systematic stock selection based on historical winners
• User needs a ranked list of stocks meeting O'Neil's criteria

When NOT to Use:

• Value investing focus (use value-dividend-screener instead)
• Income/dividend focus (use dividend-growth-pullback-screener instead)
• Bear market conditions (M component will flag - consider raising cash)

Prerequisites

API Requirements:

• FMP API key (free tier: 250 calls/day, sufficient for 35 stocks; Starter tier $29.99/mo for 40+ stocks)
  • Sign up: https://site.financialmodelingprep.com/developer/docs
  • Set via environment variable: export FMP_API_KEY=your_key_here

Python Dependencies:

• Python 3.9+
• requests (FMP API calls)
• beautifulsoup4 (Finviz web scraping)
• lxml (HTML parsing)

Installation:

pip install requests beautifulsoup4 lxml

Output

Output Directory: reports/ (default) or custom via --output-dir

Generated Files:

• canslim_screener_YYYY-MM-DD_HHMMSS.json - Structured data for programmatic use
• canslim_screener_YYYY-MM-DD_HHMMSS.md - Human-readable report

Report Contents:

• Market Condition Summary (trend, M score, warnings)
• Top N CANSLIM Candidates (ranked by composite score)
• Component Breakdown for each stock (C, A, N, S, L, I, M scores with details)
• Rating interpretation (Exceptional+/Exceptional/Strong/Above Average)
• Quality warnings and data source notes
• Summary statistics (rating distribution)

Rating Bands:

• Exceptional+ (90-100): All components near-perfect, aggressive buy
• Exceptional (80-89): Outstanding fundamentals + momentum, strong buy
• Strong (70-79): Solid across components, standard buy
• Above Average (60-69): Meets thresholds with minor weaknesses, buy on pullback

Workflow

Step 1: Verify API Access and Requirements

Check if user has FMP API key configured:

# Check environment variable
echo $FMP_API_KEY

# If not set, prompt user to provide it

Requirements:

• FMP API key (free tier: 250 calls/day, sufficient for 40 stocks)
• Python 3.9+ with required libraries:
  • requests (FMP API calls)
  • beautifulsoup4 (Finviz web scraping)
  • lxml (HTML parsing)

Installation:

pip install requests beautifulsoup4 lxml

If API key is missing, guide user to:

1. Sign up at https://site.financialmodelingprep.com/developer/docs
2. Get free API key (250 calls/day)
3. Set environment variable: export FMP_API_KEY=your_key_here

Step 2: Determine Stock Universe

Option A: Default Universe (Recommended) Use top 40 S&P 500 stocks by market cap (predefined in script):

python3 skills/canslim-screener/scripts/screen_canslim.py

Option B: Custom Universe User provides specific symbols or sector:

python3 skills/canslim-screener/scripts/screen_canslim.py \
  --universe AAPL MSFT GOOGL AMZN NVDA META TSLA

Option C: Sector-Specific User can provide sector-focused list (Technology, Healthcare, etc.)

API Budget Considerations (Phase 3):

• 40 stocks × 7 FMP calls/stock = 280 API calls
  • FMP: 7 calls/stock (profile, quote, income×2, historical_90d, historical_365d, institutional)
  • Finviz: ~1.8 calls/stock (institutional ownership fallback, 2s rate limit, not counted in FMP budget)
• Market data (^GSPC quote, ^VIX quote, ^GSPC 52-week history): 3 FMP calls
• Total: ~283 FMP calls per screening run (exceeds 250 free tier)
• Recommendation: Use --max-candidates 35 for free tier (35 × 7 + 3 = 248 calls), or upgrade to FMP Starter tier ($29.99/mo, 750 calls/day) for full 40-stock screening

Step 3: Execute CANSLIM Screening Script

Run the main screening script with appropriate parameters:

cd skills/canslim-screener/scripts

# Basic run (40 stocks, top 20 in report)
python3 screen_canslim.py --api-key $FMP_API_KEY

# Custom parameters
python3 screen_canslim.py \
  --api-key $FMP_API_KEY \
  --max-candidates 40 \
  --top 20 \
  --output-dir ../../../

# Custom RS benchmark (Phase 3.1)
python3 screen_canslim.py --rs-benchmark SPY

# Disable L component (saves per-stock 365-day fetch; L fixed at neutral 50)
python3 screen_canslim.py --disable-rs

Script Workflow (Phase 3 - Full CANSLIM):

1. Market Direction (M): Analyze S&P 500 trend vs 50-day EMA (using real historical data for accurate EMA)
   • If bear market detected (M=0), warn user to raise cash
2. S&P 500 Historical Data: Fetch 52-week data for M component EMA and L component RS calculation
3. Stock Analysis: For each stock, calculate:
   • C Component: Quarterly EPS/revenue growth (YoY)
   • A Component: 3-year EPS CAGR and stability
   • N Component: Distance from 52-week high, breakout detection
   • S Component: Volume-based accumulation/distribution (up-day vs down-day volume)
   • L Component: 52-week Relative Strength vs S&P 500
   • I Component: Institutional holder count + ownership % (with Finviz fallback)
4. Composite Scoring: Weighted average with all 7 component breakdown
5. Ranking: Sort by composite score (highest first)
6. Reporting: Generate JSON + Markdown outputs

Expected Execution Time (Phase 3):

• 40 stocks: ~2 minutes (additional 52-week history fetch per stock for L component)
• Finviz fallback adds ~2 seconds per stock (rate limiting)
• L component requires 365-day historical data for each stock

Finviz Fallback Behavior:

• Triggers automatically when FMP sharesOutstanding unavailable
• Scrapes institutional ownership % from Finviz.com (free, no API key)
• Increases I component accuracy from 35/100 (partial data) to 60-100/100 (full data)
• User sees: ✅ Using Finviz institutional ownership for NVDA: 68.3%

Step 4: Read and Parse Screening Results

The script generates two output files:

• canslim_screener_YYYY-MM-DD_HHMMSS.json - Structured data
• canslim_screener_YYYY-MM-DD_HHMMSS.md - Human-readable report

Read the Markdown report to identify top candidates:

# Find the latest report
ls -lt canslim_screener_*.md | head -1

# Read the report
cat canslim_screener_YYYY-MM-DD_HHMMSS.md

Report Structure (Phase 3 - Full CANSLIM):

• Market Condition Summary (trend, M score, warnings)
• Top N CANSLIM Candidates (ranked, N = --top parameter)
• For each stock:
  • Composite Score and Rating (Exceptional+/Exceptional/Strong/etc.)
  • Component Breakdown (C, A, N, S, L, I, M scores with details)
  • Interpretation (rating description, guidance, weakest component)
  • Warnings (quality issues, market conditions, data source notes)
• Summary Statistics (rating distribution)
• Methodology note (Phase 3: 7 components, 100% coverage)

Component Details in Report:

• S Component: "Up/Down Volume Ratio: 1.06 ✓ Accumulation"
• L Component (Phase 3.1): "3m/6m/12m: +12.4%/+18.7%/+44.1% (rel +5.2%/+8.3%/+22.0%) | RS: 88 (Strong)"
• I Component: "6199 holders, 68.3% ownership ⭐ Superinvestor"

A new Summary Table appears above the candidate list in Phase 3.1 reports, showing rank, symbol, composite score, rating, RS rating, and RS percentile for quick scanning.

Step 5: Analyze Top Candidates and Provide Recommendations

Review the top-ranked stocks and cross-reference with knowledge bases:

Reference Documents to Consult:

1. references/interpretation_guide.md - Understand rating bands and portfolio sizing
2. references/canslim_methodology.md - Deep dive into component meanings (now includes S and I)
3. references/scoring_system.md - Understand scoring formulas (Phase 3 weights)

Analysis Framework:

For Exceptional+ stocks (90-100 points):

• All components near-perfect (C≥85, A≥85, N≥85, S≥80, L≥85, I≥80, M≥80)
• Guidance: Immediate buy, aggressive position sizing (15-20% of portfolio)
• Example: "NVDA scores 97.2 - explosive quarterly earnings (100), strong 3-year growth (95), at new highs (98), volume accumulation (85), RS leader (92), strong institutional support (90), uptrend market (100)"

For Exceptional stocks (80-89 points):

• Outstanding fundamentals + strong momentum
• Guidance: Strong buy, standard sizing (10-15% of portfolio)

For Strong stocks (70-79 points):

• Solid across all components, minor weaknesses
• Guidance: Buy, standard sizing (8-12% of portfolio)
• Phase 3 Example: "Stock scores 77.5 - strong earnings (85), solid growth (80), near high (70), accumulation (60), RS leader (75), good institutions (60), uptrend (90)"

For Above Average stocks (60-69 points):

• Meets thresholds, one component weak
• Guidance: Buy on pullback, conservative sizing (5-8% of portfolio)

Bear Market Override:

• If M component = 0 (bear market detected), do NOT buy regardless of other scores
• Guidance: Raise 80-100% cash, wait for market recovery
• CANSLIM does not work in bear markets (3 out of 4 stocks follow market trend)

Step 6: Generate User-Facing Report

Create a concise, actionable summary for the user:

Report Format:

# CANSLIM Stock Screening Results (Phase 3 - Full CANSLIM)
**Date:** YYYY-MM-DD
**Market Condition:** [Trend] - M Score: [X]/100
**Stocks Analyzed:** [N]
**Components:** C, A, N, S, L, I, M (7 of 7, 100% coverage)

## Market Summary
[2-3 sentences on current market environment based on M component]
[If bear market: WARNING - Consider raising cash allocation]

## Top 5 CANSLIM Candidates

### 1. [SYMBOL] - [Company Name] ⭐⭐⭐
**Score:** [X.X]/100 ([Rating])
**Price:** $[XXX.XX] | **Sector:** [Sector]

**Component Breakdown:**
- C (Earnings): [X]/100 - [EPS growth]% QoQ, [Revenue growth]% revenue
- A (Growth): [X]/100 - [CAGR]% 3yr EPS CAGR
- N (Newness): [X]/100 - [Distance]% from 52wk high
- S (Supply/Demand): [X]/100 - Up/Down Volume Ratio: [X.XX]
- L (Leadership): [X]/100 - 52wk: [+X.X]% ([+X.X]% vs S&P) RS: [XX]
- I (Institutional): [X]/100 - [N] holders, [X.X]% ownership [⭐ Superinvestor if present]
- M (Market): [X]/100 - [Trend]

**Interpretation:** [Rating description and guidance]
**Weakest Component:** [X] ([score])
**Data Source Note:** [If Finviz used: "Institutional data from Finviz"]

[Repeat for top 5 stocks]

## Investment Recommendations

**Immediate Buy List (90+ score):**
- [List stocks with exceptional+ ratings]
- Position sizing: 15-20% each

**Strong Buy List (80-89 score):**
- [List stocks with exceptional ratings]
- Position sizing: 10-15% each

**Watchlist (70-79 score):**
- [List stocks with strong ratings]
- Buy on pullback

## Risk Factors
- [Identify any quality warnings from components]
- [Market condition warnings]
- [Sector concentration risks if applicable]
- [Data source reliability notes if Finviz heavily used]

## Next Steps
1. Conduct detailed fundamental analysis on top 3 candidates
2. Check earnings calendars for upcoming reports
3. Review technical charts for entry timing
4. [If bear market: Wait for market recovery before deploying capital]

---
**Note:** This is Phase 3 (Full CANSLIM: C, A, N, S, L, I, M - 100% coverage).

Resources

Scripts Directory (scripts/)

Main Scripts:

• screen_canslim.py - Main orchestrator script

  • Entry point for screening workflow
  • Handles argument parsing, API coordination, ranking, reporting
  • Usage: python3 screen_canslim.py --api-key KEY [options]

• fmp_client.py - FMP API client wrapper

  • Rate limiting (0.3s between calls)
  • 429 error handling with 60s retry
  • Session-based caching
  • Methods: get_income_statement(), get_quote(), get_historical_prices(), get_institutional_holders()

• finviz_stock_client.py - Finviz web scraping client ← NEW

  • BeautifulSoup-based HTML parsing
  • Fetches institutional ownership % from Finviz.com
  • Rate limiting (2.0s between calls)
  • No API key required (free web scraping)
  • Methods: get_institutional_ownership(), get_stock_data()

Calculators (scripts/calculators/):

• earnings_calculator.py - C component (Current Earnings)

  • Quarterly EPS/revenue growth (YoY)
  • Scoring: 50%+ = 100pts, 30-49% = 80pts, 18-29% = 60pts

• growth_calculator.py - A component (Annual Growth)

  • 3-year EPS CAGR calculation
  • Stability check (no negative growth years)
  • Scoring: 40%+ = 90pts, 30-39% = 70pts, 25-29% = 50pts

• new_highs_calculator.py - N component (Newness)

  • Distance from 52-week high
  • Volume-confirmed breakout detection
  • Scoring: 5% of high + breakout = 100pts, 10% + breakout = 80pts

• supply_demand_calculator.py - S component (Supply/Demand) ← NEW

  • Volume-based accumulation/distribution analysis
  • Up-day volume vs down-day volume ratio (60-day lookback)
  • Scoring: ratio ≥2.0 = 100pts, 1.5-2.0 = 80pts, 1.0-1.5 = 60pts

• leadership_calculator.py - L component (Leadership/Relative Strength)

  • 52-week stock performance vs S&P 500 benchmark
  • RS Rank estimation (1-99 scale, O'Neil style)
  • Scoring: RS 90+ outperforming market = 100pts, RS 80-89 = 80pts

• institutional_calculator.py - I component (Institutional)

  • Institutional holder count (from FMP)
  • Ownership % (from FMP or Finviz fallback)
  • Superinvestor detection (Berkshire Hathaway, Baupost, etc.)
  • Scoring: 50-100 holders + 30-60% ownership = 100pts

• market_calculator.py - M component (Market Direction)

  • S&P 500 vs 50-day EMA
  • VIX-adjusted scoring
  • Scoring: Strong uptrend = 100pts, Uptrend = 80pts, Bear market = 0pts

Supporting Modules:

• scorer.py - Composite score calculation

  • Phase 3 weighted average: C×15% + A×20% + N×15% + S×15% + L×20% + I×10% + M×5%
  • Rating interpretation (Exceptional+/Exceptional/Strong/etc.)
  • Minimum threshold validation (all 7 components must meet baseline)

• report_generator.py - Output generation

  • JSON export (programmatic use)
  • Markdown export (human-readable)
  • Phase 3 component breakdown tables (all 7 components)
  • Summary statistics calculation