Add intro / how-to-read / glossary prose to HTML reports

The HTML report ships to manuscript reviewers, conference
attendees, and collaborators who haven't run tecap themselves.
Until now the only prose in the report was the mechanism legend
and the bucket legend; outside readers had no top-level intro,
no guide for reading the multi-sample comparison plots, and no
glossary for the domain acronyms used throughout (TE, UTR, CDS,
polyA, PAS, APA, oligo-dT).

Three new constants in tecap/constants.py:
- REPORT_INTRO: per-mode (single, compare) intro paragraph.
- HOW_TO_READ_COMPARE: reading guide for multi-sample reports.
- GLOSSARY: 7 acronyms with definitions.

Three new render helpers in tecap/report.py (_intro_html,
_how_to_read_html, _glossary_html) wired into both
build_single_report and build_compare_report. Two new CSS
classes (.intro, .howto) for framing.

Tests cover both report modes (47/47 passing).

CHANGELOG: added under [Unreleased]; no version bump.

Author: FullLengthFanatic

CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+- Self-explanatory prose blocks in HTML reports for non-expert
+  readers (manuscript reviewers, conference attendees, collaborators
+  who haven't run tecap themselves). Three additions, sourced from
+  new constants in `tecap/constants.py`:
+  - `REPORT_INTRO`: top-level intro paragraph rendered above every
+    single-sample and multi-sample report. Names what the report is,
+    what was measured, and where the input came from.
+  - `HOW_TO_READ_COMPARE`: reading guide rendered only in
+    multi-sample comparison reports. Maps polylines / grouped bars /
+    colours back to samples.
+  - `GLOSSARY`: two-column glossary table at the bottom of every
+    report. Defines TE, UTR, CDS, polyA, PAS, APA, oligo-dT.
+- New report helpers `_intro_html`, `_how_to_read_html`,
+  `_glossary_html` in `tecap/report.py`. Wired into both
+  `build_single_report` and `build_compare_report`.
+- New CSS classes `.intro` and `.howto` for visually framed prose
+  callouts (matches existing `.tile` styling).
+
 ## [0.3.2] — 2026-05-04
 
 Prose-only patch. No code, schema, CLI, or behavior change.

src/tecap/constants.py

@@ -218,3 +218,95 @@
         "protocol-specific mispriming."
     ),
 }
+
+
+# Top-of-page intro paragraph rendered above every report. Tells the
+# reader what the report is, what was measured, and where the input
+# came from. Two variants because single-sample and multi-sample
+# reports answer different questions.
+REPORT_INTRO = {
+    "single": (
+        "This report summarises 3' terminal exon capture diagnostics for one "
+        "long-read RNA-seq sample. Every multi-exon read is classified into "
+        "one of nine mechanism buckets based on where its 3' end falls "
+        "relative to the terminal exon, the 3' UTR, and a polyA cluster atlas. "
+        "Reference base composition in a short window downstream of each "
+        "cleavage site is then summarised per bucket to flag internal-priming "
+        "artefacts. The mechanism legend below names every bucket; the plots "
+        "and tables that follow break the sample down by bucket, by polyA "
+        "hexamer status, and by 3' UTR length."
+    ),
+    "compare": (
+        "This report compares 3' terminal exon capture diagnostics across "
+        "multiple long-read RNA-seq samples. Every multi-exon read in every "
+        "sample is classified into one of nine mechanism buckets based on "
+        "where its 3' end falls relative to the terminal exon, the 3' UTR, "
+        "and a polyA cluster atlas. Reference base composition in a short "
+        "window downstream of each cleavage site is summarised per bucket "
+        "to flag internal-priming artefacts. The plots and tables below put "
+        "the samples side-by-side so that protocol-specific differences "
+        "(capture rate, read length, mispriming pattern) are directly "
+        "comparable. See the 'How to read this report' block before the "
+        "first plot."
+    ),
+}
+
+
+# Reading guide rendered only in multi-sample comparison reports. Tells
+# the reader how to map plot elements (polylines, grouped bars, colors)
+# back to samples, and where to look for what.
+HOW_TO_READ_COMPARE = (
+    "Each sample is assigned one colour, used consistently across every "
+    "plot and table in the report. In the mechanism breakdown plot, the "
+    "left panel is a grouped horizontal bar chart: each row is one of the "
+    "nine mechanism buckets, and within each row there is one bar per "
+    "sample (read top-to-bottom in the same order as the report's title "
+    "line). The middle and right panels of that plot are line charts: "
+    "each polyline is one sample, x-axis is 3' UTR length bin, y-axis is "
+    "the per-bin rate of MechA-correct (middle) or Captured (right). "
+    "Track one colour across all three panels to follow one sample. "
+    "In the basecomp plot, each subplot is one bucket; within a subplot "
+    "each step-line is one sample's %A distribution in the downstream "
+    "window. Per-sample tables under each plot give the underlying "
+    "counts and fractions. Acronyms used throughout (UTR, TE, CDS, APA, "
+    "polyA, oligo-dT, PAS) are defined in the glossary at the end."
+)
+
+
+# Glossary rendered at the bottom of every report. Covers every domain
+# acronym that appears in the legends, captions, or tables. Two-column
+# table; ordered roughly by where the term first appears in the report.
+GLOSSARY = [
+    ("TE",
+     "Terminal exon. The last exon of a transcript, where the 3' UTR "
+     "and the canonical polyA site live. tecap classifies reads by "
+     "where their 3' end lands relative to the TE."),
+    ("UTR",
+     "Untranslated region. The 3' UTR is the part of the terminal "
+     "exon downstream of the stop codon, between the CDS end and the "
+     "polyA site. Most real polyA cleavage happens here."),
+    ("CDS",
+     "Coding sequence. The protein-coding portion of a transcript. "
+     "Reads with 3' end inside the terminal exon's CDS portion (i.e. "
+     "before the UTR begins) are flagged as IP-TE-CDS, a strong "
+     "internal-priming signal."),
+    ("polyA",
+     "Polyadenylation. The 3' processing step that cleaves the pre-mRNA "
+     "and adds a poly(A) tail. tecap uses the PolyASite atlas to know "
+     "where real polyA cleavage clusters are located."),
+    ("PAS",
+     "Polyadenylation signal. The canonical AAUAAA-like hexamer found "
+     "10-30 nt upstream of a real polyA cleavage site. tecap splits "
+     "MechA-correct and MechB-APA reads into PAS+ (cluster carries the "
+     "hexamer) and PAS- (no hexamer) for higher-confidence calling."),
+    ("APA",
+     "Alternative polyadenylation. Production of mRNA isoforms that "
+     "differ in their 3' end through use of upstream polyA sites on "
+     "earlier exons. MechB-APA captures these biological events and "
+     "distinguishes them from internal-priming artefacts."),
+    ("oligo-dT",
+     "A short DNA oligo of consecutive deoxythymidines, used in cDNA "
+     "library prep to capture poly(A)-tailed mRNA. Internal priming "
+     "happens when oligo-dT anneals to A-rich genomic stretches "
+     "instead of the real poly(A) tail."),
+]

src/tecap/report.py

@@ -16,10 +16,13 @@
     BUCKETS,
     CATEGORIES,
     COLORS,
+    GLOSSARY,
+    HOW_TO_READ_COMPARE,
     MECH_A_CORRECT,
     MECH_B_APA,
     MECHANISM_DEFINITIONS,
     PLOT_CAPTIONS,
+    REPORT_INTRO,
     SCHEMA_VERSION,
 )
 from tecap.io import read_json
@@ -60,6 +63,11 @@
        background: #f6f8fa; padding: .5em .8em; border-radius: 3px;
        font-size: 0.85em; overflow-x: auto; white-space: pre-wrap;
        word-break: break-all; }
+.intro { background: #f6f8fa; border-left: 4px solid #3498db;
+         padding: 1em 1.2em; border-radius: 4px; margin: 1em 0 1.5em; }
+.howto { background: #fdf6e3; border-left: 4px solid #f39c12;
+         padding: 1em 1.2em; border-radius: 4px; margin: 1em 0 1.5em; }
+.intro p, .howto p { margin: 0; }
 footer { color: #777; font-size: 0.85em; margin-top: 3em;
          border-top: 1px solid #eee; padding-top: 1em; }
 """
@@ -140,6 +148,34 @@ def _bucket_legend_html():
     )
 
 
+def _intro_html(mode):
+    return (
+        f"<section class='intro'><p>{escape(REPORT_INTRO[mode])}</p></section>"
+    )
+
+
+def _how_to_read_html():
+    return (
+        f"<section class='howto'><h2 style='margin-top:0;border:none'>"
+        f"How to read this report</h2>"
+        f"<p>{escape(HOW_TO_READ_COMPARE)}</p></section>"
+    )
+
+
+def _glossary_html():
+    rows = []
+    for term, definition in GLOSSARY:
+        rows.append(
+            f"<tr><td><strong>{escape(term)}</strong></td>"
+            f"<td>{escape(definition)}</td></tr>"
+        )
+    return (
+        "<table><thead><tr><th style='width:8em'>Term</th>"
+        "<th>Definition</th></tr></thead><tbody>"
+        + "".join(rows) + "</tbody></table>"
+    )
+
+
 def _classify_table(summary):
     counts = summary["counts"]
     fractions = summary["fractions"]
@@ -318,6 +354,7 @@ def build_single_report(classify_json, basecomp_json=None, out_dir=None):
 
     parts = [
         f"<h1>tecap report — {escape(sample)}</h1>",
+        _intro_html("single"),
         "<table><tbody>",
         f"<tr><th>Sample</th><td>{escape(sample)}</td></tr>",
         f"<tr><th>Platform</th><td>{escape(summary.get('platform','?'))}</td></tr>",
@@ -366,6 +403,8 @@ def build_single_report(classify_json, basecomp_json=None, out_dir=None):
     parts += [
         "<h2>Run command</h2>",
         f"<pre class='cmd'>{escape(cmd_line)}</pre>",
+        "<h2>Glossary</h2>",
+        _glossary_html(),
     ]
 
     body = "\n".join(parts)
@@ -398,6 +437,8 @@ def build_compare_report(classify_jsons, basecomp_jsons=None, out_dir=None):
 
     parts = [
         f"<h1>tecap comparison report — {escape(', '.join(samples))}</h1>",
+        _intro_html("compare"),
+        _how_to_read_html(),
         "<h2>Mechanism legend</h2>",
         _mechanism_legend_html(),
         "<h2>Mechanism breakdown across samples</h2>",
@@ -425,6 +466,8 @@ def build_compare_report(classify_jsons, basecomp_jsons=None, out_dir=None):
             parts.append(f"<h4>{escape(s.get('sample','?'))}</h4>")
             parts.append(_basecomp_table(s))
 
+    parts += ["<h2>Glossary</h2>", _glossary_html()]
+
     body = "\n".join(parts)
     return _TEMPLATE.substitute(
         title=f"tecap comparison — {', '.join(samples)}",

tests/test_report.py

@@ -135,3 +135,34 @@ def test_compare_report_with_basecomp(tmp_path):
     html = build_compare_report(cpaths, bpaths, out_dir=str(tmp_path))
     assert "Base composition" in html
     assert (tmp_path / "comparison_basecomp.png").exists()
+
+
+def test_single_report_has_intro_and_glossary(tmp_path):
+    cj = tmp_path / "S1_terminal_exon.json"
+    write_json(str(cj), _classify_summary("S1"))
+    html = build_single_report(str(cj))
+
+    assert "class='intro'" in html
+    assert "summarises" in html and "terminal exon capture diagnostics" in html
+    assert "How to read this report" not in html
+    assert "<h2>Glossary</h2>" in html
+    assert "Untranslated region" in html
+    assert "Polyadenylation signal" in html
+
+
+def test_compare_report_has_intro_howto_and_glossary(tmp_path):
+    cpaths = []
+    for s in ("S1", "S2"):
+        p = tmp_path / f"{s}_terminal_exon.json"
+        write_json(str(p), _classify_summary(s))
+        cpaths.append(str(p))
+
+    html = build_compare_report(cpaths, out_dir=str(tmp_path))
+
+    assert "class='intro'" in html
+    assert "compares" in html and "terminal exon capture diagnostics" in html
+    assert "class='howto'" in html
+    assert "How to read this report" in html
+    assert "Each sample is assigned one colour" in html
+    assert "<h2>Glossary</h2>" in html
+    assert "Polyadenylation" in html