Stock Screening System

Progressive multi-stage fundamental analysis screener to identify exceptional investment opportunities.

Philosophy

Based on Warren Buffett-style value investing principles:

• Quality over quantity - Only 0.22% of stocks pass Stage 1
• Strong fundamentals - High ROE, margins, and profitability
• Financial health - Low debt, strong cash flow
• Long-term excellence - Sustained performance over time

Features

• ✅ Stage 1: Current Snapshot (IMPLEMENTED)

  • Stage 1A: 11 quality metrics (ROE ≥20%, margins, ratios)
  • Stage 1B: 4 financial health checks (interest coverage, asset quality)
  • Results: 41 survivors from 18,376 stocks (0.22%)

• 🚧 Stage 2: 3-Year Consistency (PLANNED)

  • Revenue growth trends
  • Margin stability
  • Cash flow consistency

• 🚧 Stage 3: 10-Year Excellence (PLANNED)

  • Book value CAGR ≥10%
  • Sustained profitability
  • Long-term ROIC

Quick Start

Installation

# Clone repository
git clone https://github.com/yourusername/stock-screening-system
cd stock-screening-system

# Install dependencies
pip install -e .

Basic Usage

# Screen stocks from CSV
python scripts/run_stage1.py --input data/inputs/us_common_stocks.csv

# Generate comprehensive report
python scripts/generate_report.py

# Monitor progress (in another terminal)
./scripts/monitor.sh

Using as Python Library

from screener.stage1.orchestrator_checkpoints import Stage1OrchestratorWithCheckpoints

# Run screening with checkpoint/resume
survivors = run_stage1_screening(
    input_file='data/inputs/my_stocks.csv',
    output_dir='data/outputs/stage1/',
    checkpoint_dir='data/outputs/stage1/checkpoints/'
)

print(f"Found {len(survivors)} survivors!")

Input Data Format

Requires CSV with financial metrics. See docs/INPUT_DATA_FORMAT.md for complete schema.

Minimum required columns:

• Ticker, Market Cap, ROE, ROA, Net Profit Margin, Gross Margin, Operating Margin
• Current Ratio, Quick Ratio, Debt to Equity, Debt to EBITDA
• Free Cash Flow, Operating Cash Flow, EBIT, Interest Expense
• Total Assets, Long-term Assets, Total Liabilities, Long-term Liabilities
• Net Income, Capital Expenditure

You can generate this data from:

• Financial APIs (yfinance, Alpha Vantage, Finnhub, etc.)
• Bloomberg Terminal exports
• Manual research/spreadsheets
• Third-party screening tools

Screening Criteria

Stage 1A: Fast Filter (11 criteria)

Stage 1B: Detailed Filter (4 criteria)

Current Results

Date: November 30 - December 1, 2025

Statistics:

• Total screened: 18,376 US common stocks
• Stage 1A survivors: 106 (0.58%)
• Final Stage 1 survivors: 41 (0.22%)

Survivor Quality Metrics (Averages):

• ROE: 35.1% (vs 20% threshold)
• ROA: 17.0% (vs 10% threshold)
• Net Margin: 24.5% (vs 10% threshold)
• Operating Margin: 33.1% (vs 15% threshold)

Notable Survivor Companies:

• MRK - Merck ($262B) - Pharmaceuticals
• LRCX - Lam Research ($197B) - Semiconductor Equipment
• SCCO - Southern Copper ($110B) - Copper Mining
• CDNS - Cadence Design ($85B) - Software
• CTAS - Cintas ($75B) - Business Services

See docs/ANALYSIS_SUMMARY.md for full analysis.

Documentation

• Getting Started - Installation & setup
• Screening Philosophy - Methodology & principles
• Criteria Reference - All screening criteria explained
• Input Data Format - CSV schema specification
• Analysis Summary - Stage 1 results analysis

Advanced Features

Checkpoint/Resume System

Process 18K+ stocks without data loss:

# Start screening (saves progress every 100 tickers)
python scripts/run_stage1.py --input data/inputs/us_common_stocks.csv

# If interrupted, resume automatically
python scripts/run_stage1.py --input data/inputs/us_common_stocks.csv
# Picks up where it left off!

Custom Screening Criteria

Modify thresholds to suit your investment philosophy:

from screener.stage1.screener_1a import Stage1AScreener

# Create custom screener with stricter criteria
screener = Stage1AScreener(
    min_roe=25.0,          # Even higher ROE requirement
    min_roa=15.0,          # Higher ROA
    min_net_margin=15.0,   # Higher profit margin
    max_debt_equity=0.5    # Lower debt tolerance
)

# Run screening
survivors = screener.screen(df)

Architecture

Progressive BFS-Style Filtering

18,376 stocks
    ↓
Stage 1A (Fast Filter - 11 criteria)
    ↓ 0.58%
106 survivors
    ↓
Stage 1B (Detailed Filter - 4 criteria)
    ↓ 0.22%
41 final survivors

Benefits:

• Efficiency: Early rejection minimizes API calls
• Resilience: Checkpoint system prevents data loss
• Scalability: Process 18K+ stocks in ~7 hours
• Accuracy: 52% fewer API calls vs naive approach

Development

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run specific test
pytest tests/test_screener_1a.py -v

Code Quality

# Format code
black screener/ scripts/ examples/

# Lint code
flake8 screener/ scripts/ examples/

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - See LICENSE file

Disclaimer

This tool is for research purposes only. Not financial advice. Always conduct thorough due diligence before making investment decisions.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: your.email@example.com