> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bigdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Thematic Screeners

> Identify companies aligned with investment themes using REST search, smart-batching, and LLM labeling.

## Why It Matters

Thematic investing requires systematic identification of companies aligned with structural trends, but manually tracking exposure across thousands of documents is inefficient and inconsistent. As mega-trends like AI and decarbonization reshape markets, investors need scalable ways to quantify which companies are genuinely positioned to benefit.

## What It Does

The [`Thematic_Screener_CLI`](https://github.com/Bigdata-com/bigdata-cookbook/tree/main/Thematic_Screener_CLI) cookbook combines the Bigdata.com REST API, [`bigdata-smart-batching`](https://docs.bigdata.com/use-cases/search-service/smart-batching), and OpenAI to screen a CSV company universe against an investment theme. Designed for analysts, PMs, and strategists, it systematically connects companies to themes using unstructured data from news, earnings calls, and filings.

<Note>
  The legacy [`Thematic_Screener`](https://github.com/Bigdata-com/bigdata-cookbook/tree/main/Thematic_Screener) notebook used the removed `bigdata-research-tools` SDK and platform watchlists. Use **Thematic\_Screener\_CLI** for new work.
</Note>

## How It Works

The CLI runs a four-stage pipeline:

1. **Generate labels** — LLM builds a theme taxonomy (mindmap) from your main theme and optional focus
2. **Build search plans** — one `plan_search` per sub-theme over your company universe
3. **Execute search** — retrieve and deduplicate documents via `bigdata-smart-batching`
4. **Label sentences** — classify relevance, summarize company exposure, export JSON/Excel/HTML

Each run is isolated under `runs/<run_name>/`.

## A Real-World Use Case

This workflow screens a company universe for **Supply Chain Reshaping** exposure — logistics automation, nearshoring, and supply-chain digitalization — and ranks companies by thematic score.

**Ready to get started? Let's dive in!**

<div style={{display: 'flex', gap: '10px', alignItems: 'center', margin: '0', lineHeight: '1'}}>
  <a href="https://github.com/Bigdata-com/bigdata-cookbook/tree/main/Thematic_Screener_CLI" target="_blank" style={{textDecoration: 'none'}}>
    <img alt="Open in GitHub" noZoom src="https://img.shields.io/badge/GitHub-View%20Repository-black?style=flat&logo=github" />
  </a>
</div>

## Prerequisites

* 💻 **GitHub cookbook** — clone [`Thematic_Screener_CLI`](https://github.com/Bigdata-com/bigdata-cookbook/tree/main/Thematic_Screener_CLI)

* Copy `.env.example` to `.env` and set:
  * `BIGDATA_API_KEY` — your [Bigdata.com API key](https://docs.bigdata.com/api-reference/introduction#api-key)
  * `OPENAI_API_KEY` — required for taxonomy generation and labeling

* Install with [uv](https://docs.astral.sh/uv/): `uv sync` (add `uv sync --group jupyter` for notebooks)

* 🐳 **Docker** — deploy via [`bigdata-thematic-screener`](https://github.com/Bigdata-com/bigdata-thematic-screener) or see [Deploy Your Thematic Screener](/use-cases/docker-services/thematic-screener)

## Setup

Load credentials from `.env` and define your universe as a CSV with `RP_ENTITY_ID` and `COMPANY_NAME` columns (see `40_companies.csv` in [`Thematic_Screener_CLI`](https://github.com/Bigdata-com/bigdata-cookbook/tree/main/Thematic_Screener_CLI) or [`Thematic_Screener_CLI/40_companies.csv`](https://github.com/Bigdata-com/bigdata-cookbook/blob/main/Thematic_Screener_CLI/40_companies.csv)).

Default LLM: **`gpt-5.6-luna`** (luna models omit `temperature` / `top_p`).

## Quick start

```bash theme={null}
cd Thematic_Screener_CLI

# Full pipeline (uses default universe CSV)
uv run python -m src.cli run-all \
  --run-name supply_chain_demo \
  --theme "Supply Chain Reshaping" \
  --focus "Logistics automation, nearshoring, supply chain digitalization" \
  --universe-path 40_companies.csv

# Or step by step
uv run python -m src.cli generate-labels --run-name supply_chain_demo --theme "Supply Chain Reshaping"
uv run python -m src.cli plans --run-name supply_chain_demo
uv run python -m src.cli search --run-name supply_chain_demo
uv run python -m src.cli label-sentences --run-name supply_chain_demo
uv run python -m src.cli export-excel --run-name supply_chain_demo
```

| Step | Subcommand                     | Description                                        |
| ---- | ------------------------------ | -------------------------------------------------- |
| 1    | `generate-labels`              | Build sub-theme taxonomy from main theme + focus   |
| 2    | `plans`                        | Create one search plan per label over the universe |
| 3    | `search`                       | Execute plans and store deduplicated documents     |
| 4    | `label-sentences`              | Label sentences and summarize company exposure     |
| 5    | `export-json` / `export-excel` | Export structured results (no API calls)           |

Use `summarize-plans` to preview chunk counts before retrieval, and `bigdata-approx-cost` to estimate cost presets.

## Notebook walkthrough

For a guided derivatives example (TSX Top 150, oil-price theme chain):

```bash theme={null}
uv sync --group jupyter
uv run jupyter lab notebooks/01_derivative_thematic_screener.ipynb
```

Notebook runs write to the same `runs/` layout as the CLI.

## Example output

After labeling and scoring, the pipeline produces company- and industry-level exposure tables and interactive charts:

<Frame>
  <img src="https://mintcdn.com/ravenpackinternational/CNBS3sA25r4pc1xD/images/screeners/thematic_exposure_heatmap.png?fit=max&auto=format&n=CNBS3sA25r4pc1xD&q=85&s=3ace3821d554db1d08b14325d6e3c3e8" alt="thematic exposure heatmap" width="1200" height="600" data-path="images/screeners/thematic_exposure_heatmap.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/ravenpackinternational/CNBS3sA25r4pc1xD/images/screeners/thematic_exposure_score.png?fit=max&auto=format&n=CNBS3sA25r4pc1xD&q=85&s=4253bd7b628647113020f6956c5e6d6d" alt="thematic exposure score" width="1200" height="600" data-path="images/screeners/thematic_exposure_score.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/ravenpackinternational/CNBS3sA25r4pc1xD/images/screeners/top_3_thematic.png?fit=max&auto=format&n=CNBS3sA25r4pc1xD&q=85&s=ad0cf8160a4f724f55ec718dc9a36979" alt="top thematics" width="1200" height="600" data-path="images/screeners/top_3_thematic.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/ravenpackinternational/CNBS3sA25r4pc1xD/images/screeners/total_thematic_scores.png?fit=max&auto=format&n=CNBS3sA25r4pc1xD&q=85&s=739124768cc15d03345a61bc5d5603e1" alt="thematics scores" width="1200" height="600" data-path="images/screeners/total_thematic_scores.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/ravenpackinternational/CNBS3sA25r4pc1xD/images/screeners/industry_heatmap_visualization.png?fit=max&auto=format&n=CNBS3sA25r4pc1xD&q=85&s=5d4ff736572966c1871cef14c26f424a" alt="Industry-level thematic exposure heatmap" width="1200" height="500" data-path="images/screeners/industry_heatmap_visualization.png" />
</Frame>

## Extract Key Insights

The visualizations reveal key insights about how companies are positioning themselves within the supply chain reshaping theme:

<Card title="AI and Machine Learning Emerges as the Core Enabler" icon="robot" color="#6fa8dc">
  With the highest cumulative score across all companies, AI and Machine Learning is the most dominant theme, highlighting its foundational role in predictive analytics, automation, and optimization within modern supply chains.
</Card>

<Card title="Automation and Robotics Drive Operational Efficiency" icon="gears" color="#93c47d">
  Automation and Robotics rank highly, underscoring the push toward warehouse automation, autonomous logistics, and process optimization as companies seek to reduce costs and improve resilience.
</Card>

<Card title="IoT Enables Real-Time Supply Chain Visibility" icon="wifi" color="#f6b26b">
  IoT's high ranking shows its critical role in connecting assets, enabling real-time visibility, and facilitating advanced automation, especially for manufacturers and hardware-driven firms.
</Card>

### Industry Polarisation

#### Sector Engagement

* **Semiconductors and Computer Services** industries show the strongest average exposure, reflecting their integral role in enabling supply chain tech (e.g., sensors, connectivity, software).
* **Traditional Sectors** like Diversified Industrials show broader but shallower engagement, suggesting they are still in earlier phases of thematic adoption.

#### Strategic Focus

**Concentration vs. Diversification in Exposure**

Most companies exhibit thematic concentration, focusing efforts on a few high-impact areas rather than spreading across all themes—likely reflecting strategic prioritization rather than lack of alignment.

## Conclusion

Thematic screening provides a powerful way to identify companies most aligned with or exposed to specific investment themes. By combining Bigdata.com REST search, smart-batching, and LLM-based classification, you can:

1. **Discover thematic leaders** — Find companies with the strongest strategic alignment to emerging trends
2. **Compare across industries** — Identify which sectors are most proactive in addressing thematic challenges and opportunities
3. **Identify investment opportunities** — Spot companies that may be undervalued relative to their thematic positioning
4. **Monitor thematic evolution** — Track how themes gain or lose prominence across your universe over time

Whether you're building thematic portfolios, conducting sector research, or seeking alpha through theme-based strategies, the Thematic Screener CLI transforms unstructured data into structured, decision-ready intelligence.