"""SOURCE render logic for TI-DP-04 (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_DP_04(reg: dict) -> dict: """Tail-Diagnostic Lorenz and Pareto - DI distribution.""" chart_id = "TI-DP-04" output_dir = THIS_DIR / chart_id / ROLE conn = lib.connect_readonly() t0 = time.time() df = lib.run_query(conn, """ WITH latest AS (SELECT MAX(file_date) AS file_date FROM title_metrics_daily WHERE demand_score IS NOT NULL AND geo_code='US') SELECT demand_score::numeric AS demand, file_date FROM title_metrics_daily JOIN latest USING (file_date) WHERE demand_score IS NOT NULL AND geo_code='US' ORDER BY demand_score DESC; """) q_sec = time.time() - t0 conn.close() if df.empty: lib.needs_spec_review(output_dir, chart_id, reg["spec_file"], reg["pc_id"], "No demand data") write_shim(output_dir, chart_id); return {"status": "needs_spec_review"} freshness = str(df["file_date"].iloc[0]) df["demand"] = df["demand"].astype(float) # universe = titles with measurable demand that day (zeros dropped) - the SAME universe rule as # companion TI-I-02, so the two charts' N and top-1% figures agree df = df[df["demand"] > 0] di_sorted = np.sort(df["demand"].values)[::-1] n = len(di_sorted) ranks = np.arange(1, n + 1) top1_share = df["demand"].nlargest(max(1, int(n * 0.01))).sum() / df["demand"].sum() # The chart floor IS the visible cutoff: the curve is drawn only down to Demand Score = 1 (the # y-axis floor), the x-axis stops at that rank, and the on-chart note states the same computed # rank - so no sub-floor tail is silently clipped mid-panel. FLOOR = 1.0 n_floor = int((di_sorted >= FLOOR).sum()) n_below = n - n_floor # downsample for a light line (drawn portion only) idx = sorted(set(list(range(0, min(1000, n_floor))) + list(range(0, n_floor, max(1, n_floor // 600))) + [n_floor - 1])) fig = go.Figure() fig.add_trace(go.Scatter(x=ranks[idx], y=di_sorted[idx], mode="lines", line=dict(color=lib.NAVY, width=3), showlegend=False, hovertemplate="rank #%{x:,}
Demand Score that day %{y:,.0f}")) # concrete callouts at rank 1/10/100/1000 - make the multiplicative drop visible to a layman marks = [(1, "#1"), (10, "#10"), (100, "#100"), (1000, "#1,000")] mx = [r for r, _ in marks if r <= n]; my = [di_sorted[r - 1] for r in mx] fig.add_trace(go.Scatter(x=mx, y=my, mode="markers", showlegend=False, hoverinfo="skip", marker=dict(size=10, color=lib.NAVY, line=dict(width=1, color="white")))) drop = di_sorted[0] / di_sorted[9] if n > 10 else 0 # per-decade decay factors, computed: the curve is near-straight through the head but bends # steeper toward the tail, so the headline claims the drop-off honestly (no 'same drop repeats') decs = [di_sorted[lo - 1] / di_sorted[hi - 1] for lo, hi in [(1, 10), (10, 100), (100, 1000)] if n > hi] d_lo = min(decs) if decs else drop # honest rounding convention: one decimal below 10x (a 4.66x printed as ~5x overstates by ~7%) fmt_mult = lambda v: f"~{v:.1f}x" if v < 10 else f"~{v:.0f}x" title_lesson = (f"Streaming demand collapses down the rankings: #1 pulls {fmt_mult(drop)} the #10, and every " f"further ten-fold step down cuts a title's Demand Score by {fmt_mult(d_lo)} or more") # subtitle stands ALONE (no cross-reference a standalone PNG cannot resolve - the companion # pointer lives in the footer's ref clause) and the ranking basis is named, not a bare noun what = (f"Every US-tracked title ranked by its Demand Score that day, most-watched first, on logarithmic axes. " f"The curve runs close to a straight line (a power law) through the head, " f"then bends steeper toward the tail, where readings approach the panel's reliable floor.") why = (f"Power-law demand is why a catalog can't live on hits alone: the top 1% of titles hold ~{top1_share:.0%} of the day's total Demand Score, but the " "endless tail is most of the library. It sets the whole strategy - a few tentpoles to lead, deep catalog and discovery to monetize the rest.") fig.update_layout(**lib.layout_v2(title_lesson, what, width=1180, height=640)) # Declared, humanized log axes (explicit decade ticks; no bare minor digits, no ',d' on log). # The x-axis ends WHERE THE CURVE ENDS (the floor rank) - it must not run on past the data. xtv = [v for v in [1, 10, 100, 1000, 10000] if v <= n_floor] xtt = ["#1", "#10", "#100", "#1,000", "#10,000"][:len(xtv)] lib.set_log_axis(fig, "x", "Title rank (most-watched first)", tickvals=xtv, ticktext=xtt) lib.set_log_axis(fig, "y", "Demand Score", data_min=max(FLOOR, float(di_sorted[n_floor - 1])), data_max=float(di_sorted[0])) fig.update_xaxes(range=[-0.05, float(np.log10(n_floor)) + 0.05]) fig.update_yaxes(range=[float(np.log10(max(FLOOR, di_sorted[n_floor - 1]))) - 0.05, float(np.log10(di_sorted[0])) + 0.08]) # Rank callouts AFTER the axes are log: log_annotation converts data coords to log10 exponents. for r, lab in marks: if r <= n_floor: lib.log_annotation(fig, x=float(r), y=float(di_sorted[r - 1]), text=f" rank {lab}: {di_sorted[r-1]:,.0f}", showarrow=False, xanchor="left", yanchor="bottom", font=dict(size=10.5, color=lib.INK)) # honest-tail note: COMPUTED from the same floor that ends the curve, so the stated floor and the # visible cutoff always coincide. Placed in the structurally empty BOTTOM-LEFT region (below the # descending curve) - at bottom-right the curve struck through the words. if n_below > 0: fig.add_annotation(xref="paper", yref="paper", x=0.03, y=0.06, xanchor="left", yanchor="bottom", text=(f"the curve stops at rank {n_floor:,}: the remaining {n_below:,} titles read below " f"Demand Score {FLOOR:.0f}, under the panel's reliable floor"), showarrow=False, font=dict(size=10, color=lib.MUTED), bgcolor="rgba(255,255,255,0.85)") lib.add_why_and_footer(fig, why, lib.assemble_footer(reg.get("pc_id", "PC-DP-06"), ["CL-006 viewer panel (distinct viewers), not census"], freshness, ["title_metrics_daily"], f"N = {n:,} US-tracked titles with a measurable Demand Score that day; curve drawn to the Demand Score {FLOOR:.0f} floor; rank-frequency (Pareto) view · plain-view companion: the attention-share curve, ref PC-I-02")) lib.save_csv(pd.DataFrame({"rank": ranks[idx], "demand_score": di_sorted[idx]}), output_dir) lib.export_chart(fig, output_dir, width=1180, height=640) 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=reg.get("pc_id", "PC-DP-06"), intended_lesson_from_spec="Demand power-law (Pareto, layman-clear)", rendered_lesson={"reader_title": title_lesson, "reader_subtitle": what, "claim_strength": "strong", "rules_applied": "rank-frequency log-log + log10-safe callouts; Demand Score basis"}, row_count=n, freshness_date=freshness, query_seconds=q_sec, render_seconds=time.time() - t0 - q_sec) return {"status": "ok", "rows": n} def render_TI_I_01(reg: dict) -> dict: """Evergreen Rank Ladder - top 30 by rank.""" chart_id = "TI-I-01" output_dir = THIS_DIR / chart_id / ROLE conn = lib.connect_readonly() t0 = time.time() df = lib.run_query(conn, """ WITH latest AS (SELECT MAX(file_date) AS file_date FROM metrics_evergreen_population_daily) SELECT imdb_id, evergreen_score::numeric AS eg, rank, age_factor::numeric AS age_f, eshare_pctl::numeric AS eshare_p, quality_pctl::numeric AS quality_p, (SELECT file_date FROM latest) AS file_date FROM metrics_evergreen_population_daily JOIN latest USING (file_date) WHERE rank <= 30 ORDER BY rank; """) pop = lib.run_query(conn, """ SELECT COUNT(*) AS n FROM metrics_evergreen_population_daily WHERE file_date = (SELECT MAX(file_date) FROM metrics_evergreen_population_daily); """) q_sec = time.time() - t0 if df.empty: lib.needs_spec_review(output_dir, chart_id, reg["spec_file"], reg["pc_id"], "No evergreen rank") conn.close(); write_shim(output_dir, chart_id); return {"status": "needs_spec_review"} titles = lib.resolve_titles(conn, df["imdb_id"].tolist()) conn.close() df = df.merge(titles[["imdb_id", "display_title"]], on="imdb_id", how="left") df["display_title"] = df["display_title"].fillna(df["imdb_id"]) df["eg"] = df["eg"].astype(float) freshness = str(df["file_date"].iloc[0]) n_pop = int(pop["n"].iloc[0]) if not pop.empty else 0 df_s = df.sort_values("eg", ascending=True) eg_max = float(df_s["eg"].max()) # Dot plot on a declared, range-framed axis: a zero-based bar wall makes 30 scores within ~15 points # visually identical; the truncation is declared in the footer. fig = go.Figure() fig.add_trace(go.Scatter(x=df_s["eg"], y=[short_title(t, 42) for t in df_s["display_title"]], mode="markers+text", marker=dict(size=10, color=lib.NAVY, line=dict(width=1, color="white")), text=[f" {v:.0f}" for v in df_s["eg"]], textposition="middle right", textfont=dict(size=10, color=lib.MUTED), cliponaxis=False, showlegend=False, hovertemplate="%{y}
timelessness score %{x:.0f}")) top1 = df_s.iloc[-1] if lib.near_tie(df_s["eg"].iloc[-2:], fmt=lambda v: f"{v:.0f}"): t2 = df_s.iloc[-2]["display_title"] title_lesson = (f"{short_title(top1['display_title'], 30)} and {short_title(t2, 30)} are tied as the catalog's most timeless titles - " "both keep drawing audiences decade after decade") else: title_lesson = f"The catalog's most timeless title is {short_title(top1['display_title'], 34)} - it keeps drawing an audience decade after decade" what = (f"Each dot = a title's evergreen score, a ‘timelessness’ index that tops out ≈ {eg_max:.0f} today (higher = more " f"steadily watched year after year); a model score, not a viewer count. Top 30 of {n_pop:,} scored titles.") why = ("Evergreen titles are a catalog's annuities - they earn attention with no marketing push, year after year. " "They're the safest licensing bets and the backbone of a deep, durable library.") fig.update_layout(**lib.layout_v2(title_lesson, what, width=1200, height=900), xaxis=lib.standard_xaxis("Evergreen score (timelessness index)"), yaxis=lib.standard_yaxis(showgrid=False)) fig.update_xaxes(range=[105, eg_max + 2.5]) # axis hugs the leader (no dead band past the top dot) lib.add_why_and_footer(fig, why, lib.assemble_footer("PC-I-01", ["CL-006 viewer panel (distinct viewers), not census"], freshness, ["metrics_evergreen_population_daily"], f"M046 V4.1: age × (baseline + engagement + quality percentiles), decline/crash-penalized; " f"axis spans 105-{eg_max + 2.5:.0f} to spread a tightly packed top 30 (scores ~111-{eg_max:.0f})")) lib.save_csv(df, output_dir); lib.export_chart(fig, output_dir, width=1200, height=900) 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-I-01", intended_lesson_from_spec="Evergreen ladder (timelessness index defined)", rendered_lesson={"reader_title": title_lesson, "reader_subtitle": what, "claim_strength": "strong", "rules_applied": f"rank<=30; dot plot, declared 105-{eg_max + 2.5:.0f} range frame"}, row_count=len(df), freshness_date=freshness, query_seconds=q_sec, render_seconds=time.time() - t0 - q_sec) return {"status": "ok", "rows": len(df)}