Stock Screener

Filter stocks by financial metrics and perform comparative analysis.

Features

Multi-Metric Filtering: P/E, P/B, market cap, dividend yield, etc.
Custom Screens: Save and reuse filter combinations
Comparative Analysis: Side-by-side stock comparison
Sector Analysis: Group and analyze by sector
Ranking: Score and rank stocks by criteria
Export: CSV, JSON, formatted reports

Quick Start

from stock_screener import StockScreener

screener = StockScreener()

Load stock data

screener.load_csv("stocks.csv")

Apply filters

results = screener.filter( pe_ratio=(0, 20), market_cap_min=1e9, dividend_yield_min=2.0 )

print(results)

CLI Usage

Basic screening

python stock_screener.py --input stocks.csv --pe-max 20 --div-min 2.0

Multiple filters

python stock_screener.py --input stocks.csv --pe 5 25 --pb-max 3 --cap-min 1B

Sector filter

python stock_screener.py --input stocks.csv --sector Technology --pe-max 30

Rank by metric

python stock_screener.py --input stocks.csv --rank-by dividend_yield --top 20

Compare specific stocks

python stock_screener.py --input stocks.csv --compare AAPL MSFT GOOGL

Export results

python stock_screener.py --input stocks.csv --pe-max 15 --output screened.csv

Input Format

Stock CSV

symbol,name,sector,price,pe_ratio,pb_ratio,market_cap,dividend_yield,eps,revenue_growth,profit_margin AAPL,Apple Inc,Technology,175.50,28.5,45.2,2.8e12,0.5,6.16,8.5,25.3 MSFT,Microsoft,Technology,380.00,35.2,12.8,2.8e12,0.8,10.79,12.3,36.7 JNJ,Johnson & Johnson,Healthcare,155.00,15.2,5.8,3.8e11,2.9,10.20,5.2,22.1

API Reference

StockScreener Class

class StockScreener: def init(self)

# Data Loading
def load_csv(self, filepath: str) -> 'StockScreener'
def load_dataframe(self, df: pd.DataFrame) -> 'StockScreener'

# Filtering
def filter(self, **criteria) -> pd.DataFrame
def filter_by_sector(self, sectors: List[str]) -> 'StockScreener'
def filter_by_metric(self, metric: str, min_val: float = None,
                     max_val: float = None) -> 'StockScreener'

# Screening Presets
def value_screen(self) -> pd.DataFrame
def growth_screen(self) -> pd.DataFrame
def dividend_screen(self) -> pd.DataFrame
def quality_screen(self) -> pd.DataFrame
def custom_screen(self, criteria: Dict) -> pd.DataFrame

# Analysis
def compare(self, symbols: List[str]) -> pd.DataFrame
def rank_by(self, metric: str, ascending: bool = True) -> pd.DataFrame
def sector_summary(self) -> pd.DataFrame
def metric_distribution(self, metric: str) -> Dict

# Scoring
def score_stocks(self, weights: Dict[str, float] = None) -> pd.DataFrame
def percentile_rank(self, metrics: List[str]) -> pd.DataFrame

# Export
def to_csv(self, filepath: str) -> str
def to_json(self, filepath: str) -> str
def summary_report(self) -> str

Filtering Criteria

Valuation Metrics

screener.filter( pe_ratio=(5, 20), # P/E between 5 and 20 pb_ratio_max=3.0, # P/B ratio under 3 ps_ratio_max=5.0, # Price/Sales under 5 peg_ratio_max=1.5 # PEG ratio under 1.5 )

Size Metrics

screener.filter( market_cap_min=1e9, # Min $1B market cap market_cap_max=10e9, # Max $10B (mid-cap) revenue_min=500e6 # Min $500M revenue )

Income Metrics

screener.filter( dividend_yield_min=2.0, # Min 2% dividend dividend_yield_max=8.0, # Max 8% (avoid yield traps) payout_ratio_max=75 # Sustainable payout )

Growth Metrics

screener.filter( revenue_growth_min=10, # Min 10% revenue growth earnings_growth_min=15, # Min 15% earnings growth eps_growth_min=10 # Min 10% EPS growth )

Quality Metrics

screener.filter( profit_margin_min=15, # Min 15% profit margin roe_min=15, # Min 15% return on equity debt_to_equity_max=1.0, # Max 1.0 D/E ratio current_ratio_min=1.5 # Min 1.5 current ratio )

Preset Screens

Value Screen

results = screener.value_screen()

Finds undervalued stocks:

- P/E < 15

- P/B < 2

- Dividend yield > 2%

- Profit margin > 10%

Growth Screen

results = screener.growth_screen()

Finds growth stocks:

- Revenue growth > 15%

- Earnings growth > 20%

- PEG ratio < 2

Dividend Screen

results = screener.dividend_screen()

Finds dividend stocks:

- Dividend yield 2-8%

- Payout ratio < 75%

- 5+ years dividend history

Quality Screen

results = screener.quality_screen()

Finds high-quality stocks:

- ROE > 15%

- Profit margin > 15%

- D/E < 0.5

- Current ratio > 2

Stock Comparison

comparison = screener.compare(["AAPL", "MSFT", "GOOGL"])

Returns:

AAPL MSFT GOOGL

price 175.50 380.00 140.00

pe_ratio 28.50 35.20 25.30

market_cap 2.8T 2.8T 1.7T

dividend_yield 0.50 0.80 0.00

profit_margin 25.30 36.70 22.50

...

Ranking and Scoring

Rank by Single Metric

Top 20 by dividend yield

top_dividend = screener.rank_by("dividend_yield", ascending=False).head(20)

Composite Scoring

Score stocks with custom weights

scores = screener.score_stocks({ "pe_ratio": -0.2, # Lower is better "dividend_yield": 0.3, # Higher is better "profit_margin": 0.3, # Higher is better "revenue_growth": 0.2 # Higher is better })

Returns stocks ranked by composite score

Percentile Ranking

See where each stock ranks on multiple metrics

ranked = screener.percentile_rank(["pe_ratio", "dividend_yield", "profit_margin"])

Returns percentile (0-100) for each metric

Sector Analysis

sector_stats = screener.sector_summary()

Returns:

sector | count | avg_pe | avg_div | avg_margin

Technology | 45 | 28.5 | 1.2 | 22.3

Healthcare | 32 | 18.2 | 2.1 | 18.7

Financials | 28 | 12.5 | 3.2 | 25.1

Example Workflows

Find Undervalued Dividend Stocks

screener = StockScreener() screener.load_csv("sp500.csv")

Apply filters

results = screener.filter( pe_ratio=(5, 15), dividend_yield_min=3.0, payout_ratio_max=70, profit_margin_min=10 )

Rank by dividend yield

top = results.sort_values("dividend_yield", ascending=False).head(10) print(top[["symbol", "name", "pe_ratio", "dividend_yield", "payout_ratio"]])

Growth at Reasonable Price (GARP)

results = screener.filter( revenue_growth_min=15, earnings_growth_min=15, peg_ratio_max=1.5, pe_ratio_max=25 )

Sector Comparison

Filter to technology sector

tech = screener.filter_by_sector(["Technology"]).filter( market_cap_min=10e9, profit_margin_min=15 )

Compare top tech stocks

comparison = screener.compare(tech["symbol"].head(5).tolist())

Output Format

CSV Export

screener.filter(pe_ratio_max=20).to_csv("value_stocks.csv")

JSON Export

screener.filter(dividend_yield_min=3).to_json("dividend_stocks.json")

Summary Report

report = screener.summary_report()

Returns formatted text summary of screening results

Dependencies

pandas>=2.0.0
numpy>=1.24.0

stock-screener

Safety Notice

Copy this and send it to your AI assistant to learn

Load stock data

Apply filters

Basic screening

Multiple filters

Sector filter

Rank by metric

Compare specific stocks

Export results

Finds undervalued stocks:

- P/E < 15

- P/B < 2

- Dividend yield > 2%

- Profit margin > 10%

Finds growth stocks:

- Revenue growth > 15%

- Earnings growth > 20%

- PEG ratio < 2

Finds dividend stocks:

- Dividend yield 2-8%

- Payout ratio < 75%

- 5+ years dividend history

Finds high-quality stocks:

- ROE > 15%

- Profit margin > 15%

- D/E < 0.5

- Current ratio > 2

Returns:

AAPL MSFT GOOGL

price 175.50 380.00 140.00

pe_ratio 28.50 35.20 25.30

market_cap 2.8T 2.8T 1.7T

dividend_yield 0.50 0.80 0.00

profit_margin 25.30 36.70 22.50

...

Top 20 by dividend yield

Score stocks with custom weights

Returns stocks ranked by composite score

See where each stock ranks on multiple metrics

Returns percentile (0-100) for each metric

Returns:

sector | count | avg_pe | avg_div | avg_margin

Technology | 45 | 28.5 | 1.2 | 22.3

Healthcare | 32 | 18.2 | 2.1 | 18.7

Financials | 28 | 12.5 | 3.2 | 25.1

Apply filters

Rank by dividend yield

Filter to technology sector

Compare top tech stocks

Returns formatted text summary of screening results

Source Transparency

Related Skills

a-share-analysis

market-environment-analysis

hk-stock-analysis

us-stock-analysis