stock-screener

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

多指标筛选：支持P/E、P/B、市值、股息率等指标
自定义筛选器：保存并复用筛选条件组合
对比分析：股票的横向对比
行业分析：按行业分组分析
排名功能：按指定标准对股票评分并排名
导出功能：支持CSV、JSON格式及格式化报告

Quick Start

快速开始

python

from stock_screener import StockScreener

screener = StockScreener()

python

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)

undefined

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

print(results)

undefined

CLI Usage

命令行使用

bash

undefined

bash

undefined

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

undefined

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

undefined

Input Format

输入格式

Stock CSV

股票CSV格式

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

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

API参考

StockScreener Class

StockScreener类

python

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

python

class StockScreener:
    def __init__(self)

    # 数据加载
    def load_csv(self, filepath: str) -> 'StockScreener'
    def load_dataframe(self, df: pd.DataFrame) -> 'StockScreener'

    # 筛选功能
    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'

    # 预设筛选器
    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

    # 分析功能
    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

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

    # 导出功能
    def to_csv(self, filepath: str) -> str
    def to_json(self, filepath: str) -> str
    def summary_report(self) -> str

Filtering Criteria

筛选条件

Valuation Metrics

估值指标

python

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
)

python

screener.filter(
    pe_ratio=(5, 20),      # P/E介于5到20之间
    pb_ratio_max=3.0,      # P/B比率低于3
    ps_ratio_max=5.0,      # 市销率低于5
    peg_ratio_max=1.5      # PEG比率低于1.5
)

Size Metrics

规模指标

python

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

python

screener.filter(
    market_cap_min=1e9,    # 最低市值10亿美元
    market_cap_max=10e9,   # 最高市值100亿美元（中型股）
    revenue_min=500e6      # 最低营收5亿美元
)

Income Metrics

收益指标

python

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
)

python

screener.filter(
    dividend_yield_min=2.0,  # 最低股息率2%
    dividend_yield_max=8.0,  # 最高股息率8%（避免高股息陷阱）
    payout_ratio_max=75      # 派息率合理（不超过75%）
)

Growth Metrics

增长指标

python

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
)

python

screener.filter(
    revenue_growth_min=10,   # 最低营收增长率10%
    earnings_growth_min=15,  # 最低盈利增长率15%
    eps_growth_min=10        # 最低EPS增长率10%
)

Quality Metrics

质量指标

python

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
)

python

screener.filter(
    profit_margin_min=15,    # 最低利润率15%
    roe_min=15,              # 最低净资产收益率15%
    debt_to_equity_max=1.0,  # 最高负债权益比1.0
    current_ratio_min=1.5    # 最低流动比率1.5
)

Preset Screens

预设筛选器

Value Screen

价值股筛选

python

results = screener.value_screen()

python

results = screener.value_screen()

Finds undervalued stocks:

寻找被低估的股票：

- P/E < 15

- P/B < 2

- Dividend yield > 2%

- 股息率 > 2%

- Profit margin > 10%

- 利润率 > 10%

undefined

undefined

Growth Screen

成长股筛选

python

results = screener.growth_screen()

python

results = screener.growth_screen()

Finds growth stocks:

寻找成长型股票：

- Revenue growth > 15%

- 营收增长率 > 15%

- Earnings growth > 20%

- 盈利增长率 > 20%

- PEG ratio < 2

- PEG比率 < 2

undefined

undefined

Dividend Screen

股息股筛选

python

results = screener.dividend_screen()

python

results = screener.dividend_screen()

Finds dividend stocks:

寻找股息型股票：

- Dividend yield 2-8%

- 股息率 2-8%

- Payout ratio < 75%

- 派息率 < 75%

- 5+ years dividend history

- 连续5年以上派息记录

undefined

undefined

Quality Screen

优质股筛选

python

results = screener.quality_screen()

python

results = screener.quality_screen()

Finds high-quality stocks:

寻找高质量股票：

- ROE > 15%

- Profit margin > 15%

- 利润率 > 15%

- D/E < 0.5

- 负债权益比 < 0.5

- Current ratio > 2

- 流动比率 > 2

undefined

undefined

Stock Comparison

股票对比

python

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

python

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

...

undefined

undefined

Ranking and Scoring

排名与评分

Rank by Single Metric

单指标排名

python

undefined

python

undefined

Top 20 by dividend yield

股息率前20的股票

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

undefined

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

undefined

Composite Scoring

综合评分

python

undefined

python

undefined

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 })

scores = screener.score_stocks({ "pe_ratio": -0.2, # 数值越低越好 "dividend_yield": 0.3, # 数值越高越好 "profit_margin": 0.3, # 数值越高越好 "revenue_growth": 0.2 # 数值越高越好 })

Returns stocks ranked by composite score

返回按综合评分排名的股票

undefined

undefined

Percentile Ranking

百分位排名

python

undefined

python

undefined

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

返回每个指标的百分位排名（0-100）

undefined

undefined

Sector Analysis

行业分析

python

sector_stats = screener.sector_summary()

python

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

undefined

undefined

Example Workflows

示例工作流

Find Undervalued Dividend Stocks

寻找被低估的股息股

python

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

python

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"]])

undefined

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

undefined

Growth at Reasonable Price (GARP)

合理价格成长股（GARP）

python

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

python

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

Sector Comparison

行业对比

python

undefined

python

undefined

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())

undefined

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

undefined

Output Format

输出格式

CSV Export

CSV导出

python

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

python

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

JSON Export

JSON导出

python

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

python

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

Summary Report

汇总报告

python

report = screener.summary_report()

python

report = screener.summary_report()

Returns formatted text summary of screening results

返回筛选结果的格式化文本汇总

undefined

undefined

Dependencies

依赖项

pandas>=2.0.0
numpy>=1.24.0

pandas>=2.0.0
numpy>=1.24.0