UC3 → paper integration proposal (differential ATAC-seq, issue #14)

What this is: ideas for integrating the UC3 work into the Galaxy Notebooks paper (vault/papers/galaxy-notebooks/manuscript.md), generated by feeding the UC3 debrief pair (UC3_DEBRIEF.md + UC3_DEBRIEF_2.md) and the paper draft to a review subagent. The paper itself was not modified. Line numbers reference manuscript.md as of 2026-06-14.

Why UC3 earns a place

UC3 is the only use case that turns an abstract design claim — “reuse Galaxy’s existing markdown renderer” / “reference artifacts, not just describe them” — into a falsifiable, before/after, code-backed story. It is the sharpest evidence for three things the draft asserts but doesn’t yet demonstrate: (1) display is what seeds extraction, (2) the markdown renderer is an extensible reproducibility surface, (3) a notebook full of plausible figures can still seed nothing.

Calibration (state explicitly so UC3 isn’t over-claimed)

• UC1 = cleanest “narrative seeds reuse” showcase (14-step map-over, byte-identical, no code change) → lead evidence for the extraction section’s main claim.
• UC2 = robustness/correctness case (forced the _original_hda fix; the 2-way-comparison limit) → lead evidence for “robust and improvable” + the honest limit.
• UC3 = the figure-rendering / display-is-what-seeds-extraction case → best (and only) evidence for the display anti-pattern, renderer-as-extensible-surface, and “real outputs vs re-uploaded screenshots.” Do not use UC3 as the primary extraction-completeness exemplar (UC1 is cleaner); use it as the cautionary mechanism proving why references must be on-graph.

MUST-INCLUDE

1. The display anti-pattern (Extraction section)

Where: after the paragraph ending “…recover the computational closure needed to produce them” (~lines 84–86).

A reference seeds extraction only if it points at an output the history actually produced — easy to violate. In one differential ATAC-seq analysis, the entire pipeline (a five-step DESeq2 → filter → volcano chain) ran as real Galaxy tool jobs, yet the first notebook seeded nothing: it displayed only PNG screenshots that had been exported, re-uploaded, and embedded. Walking backward from those uploads reached the upload boundary immediately — extraction recovered two dead inputs and zero tools. Rewriting the notebook to reference the on-graph tool outputs (the actual volcano and DESeq2 PDFs) seeded the full pipeline: a five-step workflow, zero dangling inputs, three outputs. The analysis never changed; only what the notebook displayed did.

Converts “references seed extraction” from claim to demonstrated mechanism with a sharp negative control (0 tools) and positive result (5 steps).

2. The cross-cutting lesson (Discussion/Limits)

Where: strengthen the “embedded artifact references can become misleading” limits paragraph (~line 176).

A notebook’s reproducibility value is bounded by what it displays. An analysis can be entirely tool-driven yet yield a notebook from which nothing reusable can be recovered, if its figures are pasted-in or re-uploaded copies rather than genuine on-graph outputs. The discipline Galaxy Notebooks reward is specific: every embedded figure/result should be a real history artifact on the provenance path. This is both a limit (the system cannot rescue a notebook showing only off-graph artifacts) and a design pressure in the right direction (the most reproducible way to document a result is also the easiest way to seed its workflow).

The paper’s strongest single sentence of earned insight from the use-case work.

3. Renderer-as-extensible-surface (Implementation → API/Content Pipeline)

Where: new paragraph (~lines 107–112); cross-ref the Abstract’s “reuses Galaxy’s existing… markdown renderer” (~line 5) and Methods “reuse Galaxy markdown rendering utilities” (~line 182). Upgrades “we touched nothing” to “the renderer is a deliberate extension point.”

The markdown rendering pipeline is not only reused but extensible. A large class of R/Bioconductor plotting tools (e.g. volcano-plot, DESeq2) emit figures as PDF, while the image directive expected a raster — forcing users to export, convert, and re-upload PNGs, breaking provenance and extraction. We addressed this at the renderer: the PDF datatype rasterizes a chosen page to PNG server-side (via PyMuPDF) and the renderer delegates format-specific rendering to the datatype, so a referenced PDF output both displays in the baked report and is recorded by the extraction collector (which already tracked image references regardless of format). We also added a history_dataset_as_pdf(history_dataset_id, page=N) directive with page selection, so a multi-page diagnostic PDF (e.g. a five-page DESeq2 report) can surface a single chosen page (PCA on page 1) as a figure. Both changes carry unit and Selenium tests. One renderer change retires the entire “tool emits PDF → cannot display → re-upload screenshot → break provenance” class.

Frame as “reuse and extend,” disclose the PyMuPDF dependency (see Tension C).

4. Figure — before/after extraction (degenerate vs full pipeline)

Where: new figure in the Extraction section or a panel of planned Figure 3. Same analysis, two panels:

• (a) off-graph notebook → 2 inputs, 0 tools (degenerate workflow);
• (b) on-graph notebook → the 5-step DAG (counts collection + sample sheet → DESeq2 → tp_awk NA-filter → volcanoplot), 0 dangling, 3 outputs.

Caption seed: “The notebook content determines what can be reused. Top: a notebook displaying re-uploaded screenshots seeds a degenerate two-input, zero-tool workflow. Bottom: the identical analysis, re-documented to reference its on-graph outputs, seeds the complete five-step pipeline.” The most persuasive single visual UC3 offers.

NICE-TO-HAVE

• 5. Rendered-notebook figure (inline PCA + volcano): could serve the planned “polished notebook” screenshot; UC1’s heatmaps are an alternative. If used, caption honestly (see Tension B). Doubles as evidence for idea 3.
• 6. Evaluation-plan naming: the “third evidence layer is workflow handoff” (~line 146) is exactly UC3’s before/after; name UC3’s numbers as the concrete instance and add UC3 as the figure-heavy vignette (~line 144) complementing UC1’s clean map-over.

Tensions / honesty (frame proactively)

• A. “Reuse” vs “extend”: the reuse claim is about architecture (one model/API/pipeline serve notebooks and reports — unchanged); UC3 shows that pipeline is a deliberate extension point and the extension was small/localized (one datatype branch + one directive + tests). Stronger than inert reuse — don’t bury it.
• B. Live vs baked-report rendering differ: the baked report rasterizes the exact page server-side (clean; this is what extraction consumes); the live Vue view embeds via <embed> with chrome hidden and, for multi-page PDFs, peeks the next page below the chosen one. Single-page PDFs (volcano) are clean live. For a clean live shot use the single-page volcano; for a multi-page (PCA) figure use the baked-report render. Honest one-liner: “the baked report rasterizes the exact page; the live view’s multi-page isolation is a known residual addressed by a planned rasterize-to-<img> endpoint.”
• C. PyMuPDF dependency add (optional import with fallback, declared + pinned in packages/data): disclose in Implementation/Methods; mitigating framing = optional/graceful + retires a whole class of provenance-breaking workarounds. A reproducibility paper adding a silent dependency undercuts itself.
• D. Scope of “fixes the whole class”: true for the display+seed path extraction consumes (baked report + collector); qualify that full live-view parity for multi-page PDFs is the noted follow-up. Claim “for extraction and the baked report,” not “everywhere, live, today.”
• E. Don’t overstate UC3 as the extraction exemplar: UC3’s clean 5-step workflow is real, but UC1 (14-step, byte-identical) is the cleaner showcase. Keep UC3 in its lane (display/renderer); its DAG belongs in the before/after contrast (idea 4), where the degenerate-vs-full pairing is uniquely valuable.

Priority summary

Cross-references the edits must stay consistent with: Abstract ~line 5 (renderer reuse), Design Goals “reference artifacts, not just describe them” (~line 29), Extraction “references are not natural-language guesses” (~line 84), Discussion limits (~line 176), Methods “reuse Galaxy markdown rendering utilities” (~line 182).