Screener Module Documentation

Screener

A class representing a Screener object for querying financial instruments.

__new__

Create a new Screener object.

Parameters:

  • quote_type (str): The type of financial instrument to screen. Options are:

    • "EQUITY"
    • "MUTUALFUND"
    • "ETF"
    • "INDEX"
    • "FUTURE"
    • "CRYPTO"
  • filters (List[str]): A list of JSON strings specifying filter criteria. Each filter should follow the format:

    {
        "operator": "<op>",
        "operands": ["<metric>", <value>[, <value2>]]
    }

    Where <op> can be one of:

    • "eq"
    • "gte"
    • "lte"
    • "gt"
    • "lt"
    • "btwn"
  • sort_field (str, optional): The metric to sort by.

  • sort_descending (bool, default=True): Whether to sort in descending order.

  • offset (int, default=0): The starting index of results to return.

  • size (int, default=250): The maximum number of results to return.

Returns:

  • Screener: A Screener object.

Example:

from finalytics import Screener

screener = Screener(
    quote_type="EQUITY",
    filters=[
        '{"operator": "eq", "operands": ["exchange", "NMS"]}'
    ],
    sort_field="intradaymarketcap",
    sort_descending=True,
    offset=0,
    size=100
)

Note: A full list of screener metrics for each category can be found at: https://github.com/Nnamdi-sys/finalytics/tree/main/rust/src/data/yahoo/screeners/screeners.json

symbols

Get the list of ticker symbols matching the screener criteria.

Returns:

  • List[str]: A list of ticker symbols, e.g., ["AAPL", "MSFT", "GOOGL"].

Example:

symbols = screener.symbols()
print(symbols)
['NVDA', 'MSFT', 'AAPL', 'GOOGL', 'GOOG', 'AMZN', 'META', 'AVGO', 'TSLA', 'NFLX', 'COST', 'PLTR', 'ASML', 'TMUS', 'CSCO', 'AMD', 'AZN', 'LIN', 'PEP', 'INTU', 'SHOP', 'BKNG', 'TXN', 'ISRG', 'QCOM', 'PDD', 'AMAT', 'APP', 'AMGN', 'ARM', 'GILD', 'ADBE', 'HON', 'MU', 'LRCX', 'KLAC', 'ADP', 'CMCSA', 'MELI', 'SNY', 'ADI', 'DASH', 'CRWD', 'CEG', 'SBUX', 'HOOD', 'CME', 'VRTX', 'CDNS', 'SNPS', 'MSTR', 'INTC', 'CTAS', 'NTES', 'MDLZ', 'COIN', 'TRI', 'ABNB', 'EQIX', 'MAR', 'PYPL', 'CSX', 'MRVL', 'MNST', 'REGN', 'ADSK', 'AXON', 'AEP', 'FTNT', 'PANW', 'WDAY', 'ROP', 'ALNY', 'NDAQ', 'NXPI', 'GSAT', 'IDXX', 'JD', 'PCAR', 'PAYX', 'ROST', 'KDP', 'EA', 'EBAY', 'CPRT', 'EXC', 'KMB', 'DDOG', 'CCEP', 'BKR', 'TEAM', 'ZS', 'XEL', 'FANG', 'TTWO', 'MPWR', 'TCOM', 'ARGX', 'FER', 'CSGP']
overview

Get a Polars DataFrame containing the overview of screened instruments.

Returns:

  • DataFrame: A Polars DataFrame with overview data.

Example:

overview_df = screener.overview()
print(overview_df)
shape: (100, 18)
┌─────────┬────────────┬────────────┬────────┬───┬────────────┬───────────┬────────────┬───────────┐
│ Symbol  ┆ Name       ┆ Exchange   ┆ Region ┆ … ┆ EPS        ┆ Price/EPS ┆ Price/Book ┆ Analyst   │
│ ---     ┆ ---        ┆ ---        ┆ ---    ┆   ┆ (Current   ┆ ---       ┆ ---        ┆ Rating    │
│ str     ┆ str        ┆ str        ┆ str    ┆   ┆ Year)      ┆ f64       ┆ f64        ┆ ---       │
│         ┆            ┆            ┆        ┆   ┆ ---        ┆           ┆            ┆ str       │
│         ┆            ┆            ┆        ┆   ┆ f64        ┆           ┆            ┆           │
╞═════════╪════════════╪════════════╪════════╪═══╪════════════╪═══════════╪════════════╪═══════════╡
│ "NVDA"  ┆ "NVIDIA    ┆ "NasdaqGS" ┆ "US"   ┆ … ┆ 4.31337    ┆ 41.91852  ┆ 52.591656  ┆ "1.4 -    │
│         ┆ Corporatio ┆            ┆        ┆   ┆            ┆           ┆            ┆ Strong    │
│         ┆ n"         ┆            ┆        ┆   ┆            ┆           ┆            ┆ Buy"      │
│ "MSFT"  ┆ "Microsoft ┆ "NasdaqGS" ┆ "US"   ┆ … ┆ 15.48363   ┆ 33.918888 ┆ 11.366711  ┆ "1.3 -    │
│         ┆ Corporatio ┆            ┆        ┆   ┆            ┆           ┆            ┆ Strong    │
│         ┆ n"         ┆            ┆        ┆   ┆            ┆           ┆            ┆ Buy"      │
│ "AAPL"  ┆ "Apple     ┆ "NasdaqGS" ┆ "US"   ┆ … ┆ 7.38523    ┆ 30.948935 ┆ 51.58316   ┆ "1.9 -    │
│         ┆ Inc."      ┆            ┆        ┆   ┆            ┆           ┆            ┆ Buy"      │
│ "GOOGL" ┆ "Alphabet  ┆ "NasdaqGS" ┆ "US"   ┆ … ┆ 9.93323    ┆ 20.328733 ┆ 6.734816   ┆ "1.5 -    │
│         ┆ Inc."      ┆            ┆        ┆   ┆            ┆           ┆            ┆ Buy"      │
│ "GOOG"  ┆ "Alphabet  ┆ "NasdaqGS" ┆ "US"   ┆ … ┆ 9.93083    ┆ 20.408092 ┆ 6.759474   ┆ "1.5 -    │
│         ┆ Inc."      ┆            ┆        ┆   ┆            ┆           ┆            ┆ Buy"      │
│ …       ┆ …          ┆ …          ┆ …      ┆ … ┆ …          ┆ …         ┆ …          ┆ …         │
│ "MPWR"  ┆ "Monolithi ┆ "NasdaqGS" ┆ "US"   ┆ … ┆ 17.49634   ┆ 47.18201  ┆ 11.621044  ┆ "1.8 -    │
│         ┆ c Power    ┆            ┆        ┆   ┆            ┆           ┆            ┆ Buy"      │
│         ┆ Systems,   ┆            ┆        ┆   ┆            ┆           ┆            ┆           │
│         ┆ Inc…       ┆            ┆        ┆   ┆            ┆           ┆            ┆           │
│ "TCOM"  ┆ "Trip.com  ┆ "NasdaqGS" ┆ "US"   ┆ … ┆ 25.26272   ┆ 2.3623743 ┆ 0.269895   ┆ "1.3 -    │
│         ┆ Group      ┆            ┆        ┆   ┆            ┆           ┆            ┆ Strong    │
│         ┆ Limited"   ┆            ┆        ┆   ┆            ┆           ┆            ┆ Buy"      │
│ "ARGX"  ┆ "argenx    ┆ "NasdaqGS" ┆ "US"   ┆ … ┆ 13.346     ┆ 48.460964 ┆ 6.4897304  ┆ "1.3 -    │
│         ┆ SE"        ┆            ┆        ┆   ┆            ┆           ┆            ┆ Strong    │
│         ┆            ┆            ┆        ┆   ┆            ┆           ┆            ┆ Buy"      │
│ "FER"   ┆ "Ferrovial ┆ "NasdaqGS" ┆ "US"   ┆ … ┆ 0.72677    ┆ 72.98045  ┆ 6.469871   ┆ "1.0 -    │
│         ┆ SE"        ┆            ┆        ┆   ┆            ┆           ┆            ┆ Strong    │
│         ┆            ┆            ┆        ┆   ┆            ┆           ┆            ┆ Buy"      │
│ "CSGP"  ┆ "CoStar    ┆ "NasdaqGS" ┆ "US"   ┆ … ┆ 0.79539    ┆ 114.89471 ┆ 4.4971266  ┆ "2.1 -    │
│         ┆ Group,     ┆            ┆        ┆   ┆            ┆           ┆            ┆ Buy"      │
│         ┆ Inc."      ┆            ┆        ┆   ┆            ┆           ┆            ┆           │
└─────────┴────────────┴────────────┴────────┴───┴────────────┴───────────┴────────────┴───────────┘
metrics

Get a Polars DataFrame containing detailed metrics for screened instruments.

Returns:

  • DataFrame: A Polars DataFrame with detailed metrics.

Example:

metrics_df = screener.metrics()
print(metrics_df)
shape: (100, 51)
┌────────┬──────────┬────────────┬────────────┬───┬────────────┬───────────┬───────────┬───────────┐
│ Symbol ┆ Currency ┆ Current    ┆ Day Range  ┆ … ┆ Analyst    ┆ Average   ┆ High/Low  ┆ Analyst   │
│ ---    ┆ ---      ┆ Price      ┆ ---        ┆   ┆ Consensus  ┆ Target    ┆ Target    ┆ Count     │
│ str    ┆ str      ┆ ---        ┆ str        ┆   ┆ ---        ┆ ---       ┆ ---       ┆ ---       │
│        ┆          ┆ str        ┆            ┆   ┆ str        ┆ str       ┆ str       ┆ str       │
╞════════╪══════════╪════════════╪════════════╪═══╪════════════╪═══════════╪═══════════╪═══════════╡
│ NVDA   ┆ USD      ┆ 180.83     ┆ 182.99 -   ┆ … ┆ strong_buy ┆ Median:   ┆ 250.00 -  ┆ 56        │
│        ┆          ┆            ┆ 179.46     ┆   ┆            ┆ 187.50,   ┆ 100.00    ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ Mean:     ┆           ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ 184.38    ┆           ┆           │
│ MSFT   ┆ USD      ┆ 525.19     ┆ 527.59 -   ┆ … ┆ strong_buy ┆ Median:   ┆ 700.00 -  ┆ 51        │
│        ┆          ┆            ┆ 522.71     ┆   ┆            ┆ 630.00,   ┆ 470.00    ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ Mean:     ┆           ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ 608.33    ┆           ┆           │
│ AAPL   ┆ USD      ┆ 228.60     ┆ 229.94 -   ┆ … ┆ buy        ┆ Median:   ┆ 300.00 -  ┆ 37        │
│        ┆          ┆            ┆ 227.10     ┆   ┆            ┆ 237.00,   ┆ 175.00    ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ Mean:     ┆           ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ 234.03    ┆           ┆           │
│ GOOGL  ┆ USD      ┆ 201.94     ┆ 204.50 -   ┆ … ┆ buy        ┆ Median:   ┆ 248.00 -  ┆ 52        │
│        ┆          ┆            ┆ 200.59     ┆   ┆            ┆ 220.00,   ┆ 166.00    ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ Mean:     ┆           ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ 216.59    ┆           ┆           │
│ GOOG   ┆ USD      ┆ 202.65     ┆ 205.13 -   ┆ … ┆ buy        ┆ Median:   ┆ 237.00 -  ┆ 19        │
│        ┆          ┆            ┆ 201.41     ┆   ┆            ┆ 220.00,   ┆ 185.00    ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ Mean:     ┆           ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ 217.19    ┆           ┆           │
│ …      ┆ …        ┆ …          ┆ …          ┆ … ┆ …          ┆ …         ┆ …         ┆ …         │
│ MPWR   ┆ USD      ┆ 825.51     ┆ 827.49 -   ┆ … ┆ buy        ┆ Median:   ┆ 940.00 -  ┆ 13        │
│        ┆          ┆            ┆ 803.00     ┆   ┆            ┆ 825.00,   ┆ 750.00    ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ Mean:     ┆           ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ 843.23    ┆           ┆           │
│ TCOM   ┆ USD      ┆ 59.68      ┆ 60.38 -    ┆ … ┆ strong_buy ┆ Median:   ┆ 96.13 -   ┆ 28        │
│        ┆          ┆            ┆ 59.46      ┆   ┆            ┆ 76.37,    ┆ 64.27     ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ Mean:     ┆           ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ 76.58     ┆           ┆           │
│ ARGX   ┆ USD      ┆ 646.76     ┆ 646.93 -   ┆ … ┆ strong_buy ┆ Median:   ┆ 1,090.84  ┆ 21        │
│        ┆          ┆            ┆ 637.24     ┆   ┆            ┆ 796.67,   ┆ - 565.62  ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ Mean:     ┆           ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ 806.25    ┆           ┆           │
│ FER    ┆ USD      ┆ 53.04      ┆ 53.04 -    ┆ … ┆ strong_buy ┆ Median:   ┆ 57.69 -   ┆ 2         │
│        ┆          ┆            ┆ 52.73      ┆   ┆            ┆ 53.39,    ┆ 49.09     ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ Mean:     ┆           ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ 53.39     ┆           ┆           │
│ CSGP   ┆ USD      ┆ 91.39      ┆ 92.99 -    ┆ … ┆ buy        ┆ Median:   ┆ 107.00 -  ┆ 15        │
│        ┆          ┆            ┆ 90.88      ┆   ┆            ┆ 100.00,   ┆ 70.00     ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ Mean:     ┆           ┆           │
│        ┆          ┆            ┆            ┆   ┆            ┆ 96.13     ┆           ┆           │
└────────┴──────────┴────────────┴────────────┴───┴────────────┴───────────┴───────────┴───────────┘