"""SOURCE render logic for TI-H-03 (REFERENCE ONLY).
This is the exact function from our pipeline. It is DB-coupled — you cannot run it without our database.
The query result it produces is materialized for you in data.csv, and the rendered output is figure.json
(load that to display the chart). This file is provided so you can understand / re-theme the logic.
"""
def render_TI_H_03(reg: dict) -> dict:
"""Taste map - the kept per-title exemplar: a title's nearest matches vs a clearly different cluster, color-coded.
(Section 12 per-title cards otherwise consolidated; the real product is an interactive title dashboard.)"""
chart_id = "TI-H-03"
output_dir = THIS_DIR / chart_id / ROLE
conn = lib.connect_readonly()
t0 = time.time()
# HONEST-AXES REDESIGN (round-4): the round-3 version still DREW the result on the 2-D
# flattening, which rendered the 'clearly different' contrast cluster nearly adjacent to the
# anchor cluster (~60px) and visually refuted the headline. The axes are now the similarity
# scores THEMSELVES - x = similarity to the anchor, y = similarity to the contrast seed, both
# cosine in the model's FULL 1024-d space (the same round-3 machinery that picks the
# neighbors) - so the two clusters separate BY CONSTRUCTION and each axis reads aloud
# ('more like The Boys'). No flattening, so the 'positions approximate' disclaimer is retired.
# Pool unchanged from round-3: vote-gated so every labeled proof point is a recognizable title.
pool = lib.run_query(conn, """
SELECT te.imdb_id, te.embedding
FROM title_embeddings te
JOIN categorization_imdb_title_basics b USING (imdb_id)
JOIN categorization_imdb_ratings r USING (imdb_id)
WHERE te.x_2d IS NOT NULL AND te.embedding IS NOT NULL
AND COALESCE(r.num_votes, 0) >= CASE WHEN b.title_type = 'movie' THEN 3000 ELSE 20000 END;
""")
if pool.empty or EXEMPLAR_IMDB not in set(pool["imdb_id"]):
lib.needs_spec_review(output_dir, chart_id, reg["spec_file"], reg["pc_id"], "No embedding pool / anchor")
conn.close(); write_shim(output_dir, chart_id); return {"status": "needs_spec_review"}
E = np.array(pool["embedding"].tolist(), dtype=np.float32)
E /= (np.linalg.norm(E, axis=1, keepdims=True) + 1e-9)
pool = pool.drop(columns=["embedding"]).reset_index(drop=True)
pos = {iid: i for i, iid in enumerate(pool["imdb_id"])}
ai = pos[EXEMPLAR_IMDB]
sims_a = E @ E[ai]
nn_a = [int(i) for i in np.argsort(-sims_a) if int(i) != ai][:12]
# contrast seed: the most-watched title LEAST similar to the anchor in TRUE space (recognizable
# by construction - it must clear the same vote floor and a real-audience demand floor)
cand = lib.run_query(conn, """WITH latest AS (SELECT MAX(file_date) AS fd FROM title_metrics_daily
WHERE di IS NOT NULL AND geo_code='US')
SELECT t.imdb_id, t.di::numeric AS di
FROM title_metrics_daily t JOIN latest ON t.file_date=fd
WHERE t.geo_code='US' AND t.di>800
AND t.imdb_id NOT IN (SELECT imdb_id FROM metrics_avail_match_daily
WHERE file_date = (SELECT MAX(file_date) FROM metrics_avail_match_daily)
AND country_code='US' AND flag='ORPHAN' AND imdb_id IS NOT NULL);""")
cand = cand[cand["imdb_id"].isin(pos)].copy()
if cand.empty:
lib.needs_spec_review(output_dir, chart_id, reg["spec_file"], reg["pc_id"], "No contrast candidates")
conn.close(); write_shim(output_dir, chart_id); return {"status": "needs_spec_review"}
cand["sim"] = [float(sims_a[pos[i]]) for i in cand["imdb_id"]]
heavy_ids = set(cand["imdb_id"]) # the heavily-watched candidate pool, flagged in data.csv
seed_id = cand.nsmallest(1, "sim")["imdb_id"].iloc[0]
bi = pos[seed_id]
sims_b = E @ E[bi]
taken = set(int(i) for i in nn_a) | {int(ai), int(bi)}
nn_b = [int(i) for i in np.argsort(-sims_b) if int(i) not in taken][:12]
# every plotted point's coordinates ARE its two similarity scores (exact, not a projection)
pool["x"] = sims_a.astype(float); pool["y"] = sims_b.astype(float)
clA = pool.iloc[nn_a].copy(); clB = pool.iloc[nn_b].copy()
anchor_x, anchor_y = 1.0, float(sims_b[ai]) # the anchor scores 1.0 against itself, by definition
bx, by = float(sims_a[bi]), 1.0
# faint background = the SAME vote-gated pool (deterministic md5-ordered sample for legibility),
# so the chart reads as a real map and every grey dot lives in the same honest coordinates
import hashlib
bg = pool.drop(index=list(taken)).copy()
bg["_k"] = [hashlib.md5(str(s).encode()).hexdigest() for s in bg["imdb_id"]]
bg = bg.sort_values("_k").head(2500)
fdq = lib.run_query(conn, "SELECT MAX(file_date) AS fd FROM title_metrics_daily WHERE di IS NOT NULL AND geo_code='US';")
freshness = str(fdq["fd"].iloc[0]) if not fdq.empty else None
ids = [EXEMPLAR_IMDB, seed_id] + clA["imdb_id"].tolist() + clB["imdb_id"].tolist()
tt = lib.resolve_titles(conn, list(dict.fromkeys(ids))); conn.close()
q_sec = time.time() - t0
nm = dict(zip(tt["imdb_id"], tt["display_title"]))
anchor_name = nm.get(EXEMPLAR_IMDB, EXEMPLAR_IMDB); b_name = nm.get(seed_id, seed_id)
for d in (clA, clB):
d["nm"] = d["imdb_id"].map(nm).fillna("")
fig = go.Figure()
if not bg.empty:
fig.add_trace(go.Scatter(x=bg["x"], y=bg["y"], mode="markers",
name="every other widely-known title",
marker=dict(size=3, color="rgba(150,155,165,0.25)"),
hoverinfo="skip", showlegend=True))
CONTRAST = lib.CATEGORICAL[3] # purple: a non-semantic identity hue, distinct from the grey background
ANCHOR_HUE = "#3E8A77" # teal: the anchor's cluster is a CLASS, so it gets a neutral hue
# (navy stays reserved for the single anchor star - the chart's one leader/subject)
b_short = short_title(b_name, 30)
fig.add_trace(go.Scatter(x=clB["x"], y=clB["y"], mode="markers",
name=f"closest matches to {b_short}",
marker=dict(size=10, color=CONTRAST, opacity=0.9, line=dict(width=0.5, color="white")),
text=clB["nm"], hovertemplate="%{text}"))
fig.add_trace(go.Scatter(x=clA["x"], y=clA["y"], mode="markers",
name=f"closest matches to {short_title(anchor_name, 22)} (shared audiences)",
marker=dict(size=10, color=ANCHOR_HUE, opacity=0.9, line=dict(width=0.5, color="white")),
text=clA["nm"], hovertemplate="%{text}"))
fig.add_trace(go.Scatter(x=[anchor_x], y=[anchor_y], mode="markers", showlegend=False, hoverinfo="skip",
marker=dict(size=20, color=lib.NAVY, symbol="star", line=dict(width=1, color="white"))))
fig.add_trace(go.Scatter(x=[bx], y=[by], mode="markers", showlegend=False, hoverinfo="skip",
marker=dict(size=16, color=CONTRAST, symbol="star", line=dict(width=1, color="white"))))
# label the two seed stars; each sits at the far end of its own axis (x=1 / y=1 by definition),
# so the labels point into the structurally empty regions beside them. The anchor label hangs
# BELOW the lowest dot of its own cluster streak (the streak is vertical, so a fixed offset
# from the star would strike member dots).
fig.add_annotation(x=anchor_x, y=min(float(clA["y"].min()), anchor_y),
text=f"{short_title(anchor_name, 26)}", showarrow=False,
xanchor="right", xshift=10, yshift=-16,
font=dict(size=12, color=lib.NAVY), bgcolor="rgba(255,255,255,0.85)")
fig.add_annotation(x=bx, y=by, text=f"{b_name}", showarrow=False, yshift=22,
font=dict(size=12, color=CONTRAST), bgcolor="rgba(255,255,255,0.85)")
# the NAMES are the proof on a static PNG: each cluster is a tight streak hugging its own
# axis end, so per-dot labels would smear; a compact name list sits in the open area beside
# each cluster with one leader line to the centroid
def _member_list(cluster, color, ax_px, ay_px, n=3):
cl = cluster.reset_index(drop=True)
names = [short_title(t, 30) for t in cl["nm"].head(n) if t]
if not names:
return
fig.add_annotation(x=float(cl["x"].mean()), y=float(cl["y"].mean()),
text="includes " + names[0] + "".join(f"
{t}" for t in names[1:]),
showarrow=True, arrowhead=0, arrowwidth=0.8, arrowcolor=color,
ax=ax_px, ay=ay_px, align="left",
font=dict(size=9.5, color=color), bgcolor="rgba(255,255,255,0.9)")
_member_list(clA, ANCHOR_HUE, ax_px=-130, ay_px=78)
_member_list(clB, CONTRAST, ax_px=130, ay_px=52)
# name the dense grey mass so it never begs an unanswered question
if not bg.empty:
H, xe, ye = np.histogram2d(bg["x"].values, bg["y"].values, bins=24)
ix, iy = np.unravel_index(int(np.argmax(H)), H.shape)
blob_x, blob_y = float((xe[ix] + xe[ix + 1]) / 2), float((ye[iy] + ye[iy + 1]) / 2)
fig.add_annotation(x=blob_x, y=blob_y,
text="the crowded middle: most titles are only
moderately like either one",
showarrow=True, arrowhead=0, arrowwidth=1, arrowcolor=lib.MUTED, ax=-150, ay=85,
font=dict(size=9.5, color=lib.MUTED), bgcolor="rgba(255,255,255,0.9)")
anchor_short = short_title(anchor_name, 24)
anchor_poss = anchor_short + ("'" if anchor_short.endswith("s") else "'s")
title_lesson = (f"How recommendations work: the titles {anchor_poss} audience also watches cluster "
"tightly together - a taste fingerprint - far from a clearly different one")
# the least-overlap superlative is SCOPED to heavily watched titles (grey widely-KNOWN dots can
# sit further left), and the similarity floor is said out loud: overlap scores rarely reach
# zero, so the contrast star visibly keeping some shared audience cannot read as a contradiction
what = (f"Each dot is a title, placed by how closely our recommendation model says its audience matches {anchor_short} "
f"(left to right) and {b_short} (bottom to top) - the heavily watched title whose audience overlaps {anchor_poss} least "
"(overlap rarely reaches zero, so even it keeps some shared viewers). "
f"Teal = {anchor_poss} 12 closest matches (navy star = {anchor_short} itself); purple = the contrast cluster (purple star = {b_short} itself); grey = every other widely-known title.")
why = ("This is the engine behind ‘if you liked this, you'll like that’: a high score on either axis means shared "
"audience behavior - the same viewers watch both - not matching plots, which is why a hit's closest matches "
"are the other titles its fans binge. The same scores power every recommendation and sort a catalog into "
"browseable rows; an illustrative example, not a model-validation metric.")
x_rng = [min(float(bg["x"].min()) if not bg.empty else bx, bx) - 0.05, 1.10]
y_rng = [min(float(bg["y"].min()) if not bg.empty else anchor_y, anchor_y) - 0.05, 1.10]
# NUMERIC TICKS ON BOTH AXES (expert verifiability): every dot's coordinates ARE its two
# shipped similarity scores, so the scale prints in muted 0.0-1.0 ticks and positions can be
# cross-checked against data.csv without trusting the renderer.
fig.update_layout(**lib.layout_v2(title_lesson, what, width=1180, height=780),
xaxis=dict(showticklabels=True, tickformat=".1f", dtick=0.2,
tickfont=dict(size=9, color=lib.MUTED),
showgrid=True, gridcolor=lib.GRID, zeroline=False, range=x_rng),
yaxis=dict(title=dict(text=f"more like {b_short} →", font=dict(size=12, color=lib.MUTED)),
showticklabels=True, tickformat=".1f", dtick=0.2,
tickfont=dict(size=9, color=lib.MUTED),
showgrid=True, gridcolor=lib.GRID, zeroline=False, range=y_rng),
legend=dict(orientation="h", yanchor="bottom", y=1.0, xanchor="left", x=0, font=dict(size=11)))
# x direction label drawn as a paper annotation (an x-axis TITLE rendered at the TOP of the
# canvas in this plotly build when tick labels were hidden; kept as an annotation, dropped a
# little lower now that numeric tick labels occupy the first band under the axis).
fig.add_annotation(xref="paper", yref="paper", x=1.0, y=-0.055, xanchor="right", yanchor="top",
text=f"more like {anchor_short} →", showarrow=False,
font=dict(size=12, color=lib.MUTED))
# footer points at the shipped background sample (the grey cloud used to live only in the
# manifest, so the 'crowded middle' was not reconstructable from the data download)
lib.add_why_and_footer(fig, why, lib.assemble_footer("PC-H-03",
["CL-016 similarity = overlapping audiences, not matching plots"],
freshness, ["PeerLogix recommendation model", "title_metrics_daily"],
"similarity scored in the model's full space, widely-known titles only · contrast seed = lowest "
"anchor-overlap among the heavily watched candidates flagged in the data download · grey background "
"sample included in the data download"))
csv_cols = ["imdb_id", "nm", "grp", "sim_to_anchor", "sim_to_contrast"]
# the ~2,500 grey background dots SHIP in data.csv (grp='background', names unresolved by
# design - the ids are the audit key): the grey cloud and the 'crowded middle' annotation are
# reconstructable from the download, not render-only
bg_csv = bg.assign(nm="", grp="background").rename(
columns={"x": "sim_to_anchor", "y": "sim_to_contrast"})[csv_cols]
csv_df = pd.concat([
pd.DataFrame([{"imdb_id": EXEMPLAR_IMDB, "nm": anchor_name, "grp": "anchor",
"sim_to_anchor": 1.0, "sim_to_contrast": anchor_y},
{"imdb_id": seed_id, "nm": b_name, "grp": "contrast_seed",
"sim_to_anchor": bx, "sim_to_contrast": 1.0}]),
clA.assign(grp="similar").rename(columns={"x": "sim_to_anchor", "y": "sim_to_contrast"})[csv_cols],
clB.assign(grp="different").rename(columns={"x": "sim_to_anchor", "y": "sim_to_contrast"})[csv_cols],
bg_csv,
], ignore_index=True)
# the subtitle's 'overlaps least' superlative must be reconstructable from this file alone:
# (a) flag the heavily-watched candidate pool the contrast seed was chosen from (the minimum
# sim_to_anchor among flagged rows IS the seed), and (b) ship similarities at 4 decimals AS
# STRINGS - the library csv rounder caps any column whose max reaches 1.0 (the seeds' own
# self-similarity rows) at 2dp, which collapsed the cluster ordering into 0.99 ties and
# printed one member as 1.0, indistinguishable from the anchor itself
csv_df["heavily_watched_candidate"] = csv_df["imdb_id"].isin(heavy_ids)
for _c in ("sim_to_anchor", "sim_to_contrast"):
csv_df[_c] = csv_df[_c].map(lambda v: f"{float(v):.4f}")
n_rows = lib.save_csv(csv_df, output_dir)
lib.export_chart(fig, output_dir, width=1180, height=780)
lib.write_lesson_design(output_dir, chart_id, f"# {chart_id}\n\n{title_lesson}\n\n{what}\n")
write_shim(output_dir, chart_id)
lib.write_manifest(output_dir, chart_id, "ok", reg["spec_file"], pc_id="PC-H-03",
intended_lesson_from_spec="Taste map: similar vs different clusters (kept per-title exemplar)",
rendered_lesson={"reader_title": title_lesson, "reader_subtitle": what,
"claim_strength": "strong",
"rules_applied": "honest axes: x = cosine sim to anchor, y = cosine sim to contrast seed, both in the "
"full 1024-d space (vote-gated pool; round-3 neighbor machinery unchanged); clusters "
"separate by construction; deterministic 2,500-title background sample SHIPPED in "
"data.csv (grp='background', pointed to from the footer); numeric similarity ticks "
"on both axes; member-name lists with one leader line per cluster"},
row_count=n_rows, freshness_date=freshness,
query_seconds=q_sec, render_seconds=time.time() - t0 - q_sec)
return {"status": "ok", "rows": n_rows}