# Topic 06 — Language & Terms — Visuals (Final)

This script generates the **human-readable** Topic 06 visual outputs from the CSV exports produced by your Topic 06 SQL pack.

---

## Inputs

The script expects these CSVs to exist:

- `reports/06_language_and_terms/06_exclusive_terms_doc_concentration.csv`
- `reports/06_language_and_terms/06x_font_hash_cluster_counts.csv`
- `reports/06_language_and_terms/06_terms_exclusive_to_focal_plus_3.csv`
- `reports/06_language_and_terms/06x_edges_cluster_font.csv`
- `reports/06_language_and_terms/06x_edges_cluster_term.csv`

If any are missing, re-run your Topic 06 exports SQL first.

---

## Outputs

Images are written here:

`reports/06_language_and_terms/visuals/`

Files generated:

1. `01_doc_concentration_top25.png`  
   **What it shows:** For each cluster, the top documents ranked by the number of **distinct exclusive terms** found in that document.

2. `02_top_tracking_font_hashes_by_docs.png`  
   **What it shows:** The most widely shared **tracking-font object hashes** (by number of distinct documents that contain them).

3. `03_exclusive_terms_presence_heatmap.png`  
   **What it shows:** A heatmap showing whether each exclusive term is present in each cluster.
   - Term labels are throttled (every Nth row) for readability.

4. `04_graph_cluster_to_font_edges.png`  
   **What it shows:** A bipartite graph connecting **cluster → tracking-font hash**.
   - Left side: clusters (by name)
   - Right side: `object_sha256` (short form)
   - Left clusters span the full height (**PETER LEHMEYER at top**) to make connectors easy to trace.

5. `05_graph_cluster_to_term_edges.png`  
   **What it shows:** A bipartite graph connecting **cluster → exclusive term**.
   - Left side: clusters (by name)
   - Right side: `string_norm` (truncated)

---

## Install dependencies

Ubuntu-native install:

```bash
sudo apt update
sudo apt install -y python3-pip
python3 -m pip install pandas matplotlib networkx
```

> `networkx` is required for graphs 04 and 05.

---

## Run

From project root:

```bash
cd ~/DB
python3 sql/topics/06_language_and_terms/06_language_and_terms__visuals.py
```

---

## Optional: run only certain figures

Run only 04 and 05:

```bash
python3 sql/topics/06_language_and_terms/06_language_and_terms__visuals.py --only 04,05
```

---

## Optional tuning knobs

Examples:

```bash
# More heatmap rows + label more often
python3 sql/topics/06_language_and_terms/06_language_and_terms__visuals.py \
  --heatmap-rows 220 --heatmap-label-every 3

# Smaller graphs (fewer right-side nodes)
python3 sql/topics/06_language_and_terms/06_language_and_terms__visuals.py \
  --only 04 --graph-font-top-right 18 --graph-font-top-edges 120
```

---

## Cluster mapping used

- 1570 → MATTHEW GUERTIN (focal cluster)
- 674 → MUAD ABDULKADIR
- 290 → ADRIAN WESLEY
- 696 → PETER LEHMEYER