cassionData Analysis

Back to the lessonLesson 6 of 8The page it must survive

The caption is the only part that travels

The same deck as the downloads, rendered as a page. Start the slideshow to present it full screen — arrow keys or a click advance one slide, Escape leaves.

Slides · PDFSlides · PowerPoint

  1. Slide 1 / 20

    What this lesson covers

    • Assume it will be lifted
    • Four things a caption has to carry
    • The title and the caption do different jobs
    • Labelling inside the chart
    • Numbers in a bilingual caption
    • The five-second test
    • Report it whole
    • What comes next
    Speaker notes
    Someone will paste your figure into a situation report without the paragraph that explained it. Whatever the caption says is what the figure will mean from then on, so the caption has to carry the finding, the denominator and the thing the chart cannot support.

  2. Slide 2 / 20

    Assume it will be lifted

    • Write for the second life — The caption is the only part of the analysis that travels with the picture, so it has to be…
    Speaker notes
    A figure in a programme report has a second life. It is screenshotted into a situation report, pasted into a cluster presentation, forwarded as an image, and reproduced in a donor update — every time without the paragraph above it. Write for the second life. The caption is the only part of the analysis that travels with the picture, so it has to be self-contained.

  3. Slide 3 / 20

    Assume it will be lifted

    CaptionWhat survives the paste
    "GAM by commune"The chart, with no interpretation
    "Figure 3"Nothing
    "GAM by commune with 95% CIs. The three highlighted communes are the only ones whose interval clears the district median."The finding, the uncertainty and the limit

  4. Slide 4 / 20

    Four things a caption has to carry

    • The finding, as a sentence — Not what the chart shows — what it says
    • The denominator, or where to find it — 1,955 households, 1,850 cases, 24 schools
    • The uncertainty, if the chart has any — "with 95% confidence intervals" is four words and it stops the chart being read…
    • What the chart does not support — One clause, and it is the one that gets removed first when someone edits for length
    Speaker notes
    The finding, as a sentence. Not what the chart shows — what it says. "Counting improved sources overstates coverage in every district" is a finding; "Improved source against basic service by district" is a file name. The denominator, or where to find it. 1,955 households, 1,850 cases, 24 schools. A percentage with no denominator is a number a reader cannot weigh. The uncertainty, if the chart has any. "with 95% confidence intervals" is four words and it stops the chart being read as twelve exact values. What the chart does not support. One clause, and it is the one that gets removed first when someone edits for length. "The bars do not sum" or "the comparison is observational" or "a ranking of one commune against its neighbour is not supported".

  5. Slide 5 / 20

    Four things a caption has to carry — In Python

    CAPTION = (
    "Four food security instruments applied to the same 1,955 households. "     # denominator
    "The highest prevalence is seven times the lowest, "                        # finding
    "so the instrument chosen decides the caseload before any analysis begins." # implication
)

  6. Slide 6 / 20

    Four things a caption has to carry — In R

    labs(caption = str_wrap(CAPTION, 90))

  7. Slide 7 / 20

    The title and the caption do different jobs

    ElementJobLength
    TitleNames the comparison3–6 words
    CaptionStates the finding and its limits2–3 sentences
    Axis labelNames the quantity and its unit2–4 words
    Direct labelIdentifies a series in place1–3 words
    Speaker notes
    A chart that has both should not say the same thing twice.

  8. Slide 8 / 20

    The title and the caption do different jobs

    • If the title states the finding, delete the caption or the title — Two headings competing is the commonest layout fault…
    • On this platform the title names and the caption tells — Every figure in build.py carries both, in both languages,…
    Speaker notes
    If the title states the finding, delete the caption or the title. Two headings competing is the commonest layout fault in a programme report, and the one that makes a page look busy without adding anything. On this platform the title names and the caption tells. Every figure in build.py carries both, in both languages, and the split is enforced by the two fields being separate.

  9. Slide 9 / 20

    Labelling inside the chart

    • Direct labels beat legends — A legend makes the reader match a colour to a name and carry it back to the chart; a label…
    Speaker notes
    Four decisions that decide whether a reader has to look away from the data. Direct labels beat legends. A legend makes the reader match a colour to a name and carry it back to the chart; a label at the end of the line does not.

  10. Slide 10 / 20

    Labelling inside the chart — In Python

    for name, series in lines.items():
    ax.plot(series.index, series.values)
    ax.annotate(name, (series.index[-1], series.iloc[-1]),
                xytext=(6, 0), textcoords="offset points", va="center")

  11. Slide 11 / 20

    Labelling inside the chart — In R

    # ggrepel::geom_text_repel() on the last point of each series.

  12. Slide 12 / 20

    Labelling inside the chart

    • Label the values only when the reader needs them exactly — A bar chart with a value on every bar is a table wearing a…
    • Never label a value to more precision than the interval justifies — 42.9% on a bar whose interval is ±3 points, not…
    • Put the unit on the axis, once — "Households flagged (%)" and then bare numbers, not "%" repeated on every tick
    Speaker notes
    Label the values only when the reader needs them exactly. A bar chart with a value on every bar is a table wearing a chart's clothes. Label the emphasised bars, or none. Never label a value to more precision than the interval justifies. 42.9% on a bar whose interval is ±3 points, not 42.94%. Put the unit on the axis, once. "Households flagged (%)" and then bare numbers, not "%" repeated on every tick.

  13. Slide 13 / 20

    Numbers in a bilingual caption — In Python

    caption={
    "en": "Counting improved sources overstates coverage in every district. "
          "The difference is households whose source is improved and more than "
          "thirty minutes away.",
    "fr": "Compter les sources améliorées surestime la couverture dans chaque "
          "district. L'écart correspond aux ménages dont la source est améliorée "
          "et située à plus de trente minutes.",
}
    Speaker notes
    This platform ships every figure in two languages, and the caption is where the two diverge most.

  14. Slide 14 / 20

    Numbers in a bilingual caption — In R

    # One figure, two captions, written together rather than translated later.

  15. Slide 15 / 20

    Numbers in a bilingual caption

    • The decimal separator changes — 42,9 % in French, 42.9% in English — and the renderer handles it, which is why the…
    • The space before the percent sign changes too — and French uses a narrow no-break space
    • Translate the finding, not the words — A French caption that reads as a translation has failed the same test as a…
    Speaker notes
    The decimal separator changes — 42,9 % in French, 42.9% in English — and the renderer handles it, which is why the figure carries values rather than formatted strings. The space before the percent sign changes too, and French uses a narrow no-break space. Get it from the formatter rather than typing it. Translate the finding, not the words. A French caption that reads as a translation has failed the same test as a French lesson that does.

  16. Slide 16 / 20

    The five-second test

    • If they describe the chart, the caption is a title — "It's a bar chart of communes" means the caption did no work
    • If they state the finding, it works — "Three communes are clearly above the others" is the caption having done its job
    • If they state a finding you did not make, fix the chart — A reader who says "so Dessalines is the safest" has read a…
    Speaker notes
    Show the figure and its caption to someone who was not in the analysis, and ask them what it says. If they describe the chart, the caption is a title. "It's a bar chart of communes" means the caption did no work. If they state the finding, it works. "Three communes are clearly above the others" is the caption having done its job. If they state a finding you did not make, fix the chart. A reader who says "so Dessalines is the safest" has read a ranking the intervals do not support, and the caption needs the clause that forecloses it.

  17. Slide 17 / 20

    Report it whole — Example

    Figure captions in this report

  Every figure caption states the finding as a sentence, names the
  denominator, and names one thing the figure does not support.

  Captions are written to be self-contained: a figure reproduced without its
  surrounding text should still carry its own interpretation and its own
  limits.

  Values are labelled to the precision the confidence interval supports and
  no further.

  Figures and captions exist in English and French. The captions are written
  in both languages rather than translated, so the finding rather than the
  wording is what is shared.

  18. Slide 18 / 20

    Report it whole

    • The second paragraph is the whole lesson — and it is a claim about the report's own robustness rather than about its…
    Speaker notes
    The second paragraph is the whole lesson, and it is a claim about the report's own robustness rather than about its style.

  19. Slide 19 / 20

    What comes next

    • Everything so far has been about what the chart says.
    Speaker notes
    Everything so far has been about what the chart says. The next lesson is about the axis, where a chart can say something different from its own data without a single number being wrong.

  20. Slide 20 / 20

    Where this goes next

    Read the full lesson, with runnable code Back to the lesson