Visualization and Narrative: Chart Code, Captions, and Insight Summaries with Numbers Pinned

Tier: Foundation · Workflow area: Visualization & communication

This playbook covers both halves: generating publication-quality matplotlib/plotly code fast, and drafting narrative with the numbers-pinned method, where every figure in the prose is injected by you from verified tables and the model is never the source of a single number.

When to use

• •
  Turning validated analysis (pb-02's memo tables, pb-07's experiment results) into decks, reports, or dashboards.
• •
  Polishing charts to house style without hand-tweaking rcParams for an hour.
• •
  Drafting insight summaries, chart captions, and TL;DRs for stakeholders.

Skip elaborate generation for quick-look plots — df.plot() needs no assistant.

Prerequisites

• •
  matplotlib and/or plotly; your verified result tables as DataFrames or CSV — the numbers must already be trusted (verification happened upstream, in pb-02/pb-03).
• •
  An assistant; multimodal helps (it can critique rendered charts).
• •
  A house style, even minimal: fonts, brand colors, label conventions, number formats (₹ lakh/crore vs $M matters).

The workflow

1. 1.

   Generate chart code from a chart spec, not a vibe:

   Copy

   Matplotlib chart from df_conv (columns: month, channel, conversion_rate,
   n_trials). Spec:
   - Line chart, one line per channel, monthly conversion (already 0-1 floats;
     format axis as %). Annotate the March-2026 pricing change with a vertical
     reference line + label.
   - Suppress months where n_trials < 100 (draw as gap, note in caption).
   - Style: 900x500, no top/right spines, direct line labels at right edge
     instead of a legend, title states the takeaway ("Paid-social conversion
     fell 6pp after March"), subtitle states the population and window.
   - Return a function make_conversion_chart(df) -> Figure. No plt.show().
   

   Takeaway-as-title and small-n suppression are the two spec habits that most improve real-world charts.

2. 2.

   Render and critique in a loop. Show the rendered chart (paste the image to a multimodal model or describe issues): overlapping labels, unreadable rotation, misleading truncated axis. Two or three critique rounds beats one mega-prompt. For axis choices, be explicit: bar charts start at zero; line-chart y-ranges are a judgment you make, stated in the caption if truncated.

3. 3.

   Build the numbers block — the only source of truth for prose. From your verified tables, assemble every number the narrative may use:

   Copy

   NUMBERS (verified, use ONLY these; if a claim needs a number not listed,
   write [MISSING] instead of computing or estimating it):
   - overall trial→paid conversion: Mar 18.2% → Jun 14.1% (−4.1pp)
   - mix-shift contribution: −3.2pp; within-channel: −0.9pp
   - paid-social share of signups: 22% → 41%
   - n = 48,300 trials, Mar-Jun 2026
   

4. 4.

   Draft narrative against the block:

   Copy

   Using ONLY the numbers block, draft: (1) a 3-sentence executive TL;DR,
   (2) a caption for each chart (1-2 sentences: what it shows, the takeaway,
   the population/window), (3) a 200-word findings section ordered by decision
   relevance. Plain language, no "delve", no unexplained jargon; state
   uncertainty where the block does (n, windows). Every numeric claim must
   match the block verbatim.
   

5. 5.

   Audit the draft mechanically. Check every number in the prose against the block (a regex for digits makes this fast: each match must appear in the block). Hunt the subtler failures: derived numbers the model computed itself ("a 23% relative decline" — did you verify that division?), causal language exceeding the analysis ("caused" vs "coincided with"), and superlatives with no basis ("dramatic"). Any [MISSING] markers route back to you for a verified value or deletion of the claim.

6. 6.

   Package per audience. Same numbers block, different renderings: 3 bullets for the exec channel, the full memo for the team, speaker notes for the review meeting. Regenerating per audience from the same block keeps versions consistent — the block is your single source of truth.

Tool variants

• matplotlib (static/report): the default for papers, PDFs, and decks; the function-returning-Figure pattern slots into report builds.
• plotly (interactive/dashboards): same spec discipline; additionally pin hover-template formats and axis tick formats in the spec, since defaults are ugly in both.
• Chat vs in-notebook assistant: in-notebook (Cursor, Jupyter AI) shortens the render-critique loop; chat-with-vision is better at critiquing composition and readability of the rendered image.

Verification

• •
  Every number in prose and captions exists verbatim in the numbers block; every derived figure (deltas, relative changes) was computed by you, not the model.
• •
  Charts pass the cold-reader test: a colleague states the takeaway of each chart in one sentence without you explaining it.
• •
  Axes honest: zero-based bars, stated truncations, suppressed small-n cells noted.
• •
  Captions state population and time window — the two omissions that most mislead.
• •
  The TL;DR contains no causal claim the analysis cannot support.

Pitfalls

• Letting the model summarize from raw data. Pasting a table and asking for "insights" produces smooth prose with invented aggregates. The numbers block exists to make this impossible.
• Chart-junk drift. Assistants add gradients, dual axes, and 3D unprompted. Dual y-axes in particular smuggle in fake correlations — ban unless explicitly justified.
• Confident captions on noisy data. A caption asserting a trend across three noisy points; require n and window in captions so weakness is visible.
• Silent unit mangling. Paise vs rupees, rates as 0.14 vs 14% — pin formats in both chart spec and numbers block; this is the most common generated-chart bug.
• One prompt, one giant chart. Complex multi-panel figures generate badly; build panel functions separately and compose with subplots yourself.

Restricted-environment variant

• Aggregates only: the workflow already isolates data — only aggregate result tables and the numbers block reach the assistant, usually acceptable on hosted models even in conservative orgs. Suppress small cells (n < 20) before sharing aggregates.
• Air-gapped: local models draft captions and narrative from a numbers block credibly (constrained generation is their strength); chart-code generation works with local code models, with more critique rounds.
• Client-branded outputs: keep brand assets and client names out of prompts; apply branding locally via a style module.

Success criteria

• •
  Deck/report-quality charts and narrative produced in under an hour from verified tables.
• •
  The mechanical number audit finds zero unpinned digits in the final draft.
• •
  A stakeholder reads the TL;DR and asks a decision question, not a clarification question.
• •
  Your chart-spec and numbers-block templates get reused across projects — the compounding asset.