Galaxy Brain

UC2_PAPER_INTEGRATION

UC2 → paper integration proposal (TAL1 differential ChIP, issue #13)

What this is: ideas for integrating the UC2 work into the Galaxy Notebooks paper (vault/papers/galaxy-notebooks/manuscript.md), generated by feeding the UC2 debrief pair (UC2_DEBRIEF.md + UC2_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.

Orienting context

The manuscript has no use cases written in yet — they are planned vignettes. The extraction section (~lines 80–90) describes the intended flow and hedges (~line 90) that graph-backed extraction evidence “should be presented as implemented behavior only once the end-to-end vignette has been captured.” UC2 doesn’t strengthen existing UC-prose; it fills the empty vignette slot as the second, contrast vignette: UC1/UC3 is the happy-path showcase; UC2 is the case that bounds and hardens the extraction claim. That division of labor is what earns UC2 a place rather than redundancy.

MUST-INCLUDE

1. Topology-limit + split resolution (Extraction section)

Where: new paragraph after “…not a second workflow editor.” (~line 88), before the implementation-status hedge (~line 90). Answers the reviewer’s “when does this break?” honestly.

Not every documented analysis reduces to a single reusable workflow, and the notebook surface makes the boundary explicit. A differential two-condition analysis — identifying TAL1 binding sites that differ between two blood-cell lineages — contains an irreducible two-way comparison: a step that selects two specific named elements (one per condition) out of a collection and compares them. A collection-element selection feeding a single-dataset tool input has no representation as a workflow edge, so this seam cannot be made sample-agnostic inside one workflow. Galaxy resolves this by extracting two workflows: a map-over peak caller (read collections in, per-condition peak sets out) and a pairwise comparator (any two peak sets in, differential result out). Each is independently reusable; only their composition — which two conditions to contrast — remains analyst-supplied.

Real numbers: single-workflow extract = 34 steps, 0 dangling, 3 outputs, comparison seam condition-pinned (identifier=G1E/mega) but runnable; split = WF1 caller 5 steps (two list:list reads → Bowtie2 ×2 map-over → one mapped MACS2 → condition peaks list) + WF2 comparator 29 steps (4 inputs → 3-way intersect → Group gene lists + datamash figure → 3 outputs), no condition-name pinning.

2. The robustness vignette (Evaluation Plan / dedicated subsection)

Where: expand “the second evidence layer is a worked notebook vignette” (~line 144); pair explicitly with the happy-path vignette.

3. The _original_hda correctness fix (Implementation → Test Coverage)

Where: strengthen the Test Coverage subsection (~lines 132–136), which currently only promises regenerated counts. This is the paper’s strongest “robust and improvable” evidence — the only place a real use case demonstrably found, root-caused, and fixed a correctness bug in the extraction machinery.

Exercising extraction against a real differential analysis surfaced and fixed a correctness bug in the backward-closure walk. Collection-operation tools (e.g. Extract Dataset) produce outputs carrying both a copied_from link to their source element and their own creating job. _original_hda followed copied_from unconditionally, normalizing such an output back to its source and dropping the collection-operation step; a workflow extracted through the UI came out with a dangling input-less downstream step. The fix stops walking copied_from when a content item has its own creating_job_associations — passive copies still normalize, while any DatabaseOperationTool output is retained as a genuine step — covered by a unit test and a Selenium end-to-end test.

Cross-ref: this de-risks the ~line 90 hedge — post-fix the UI extract genuinely produces a complete workflow (34 steps, 0 dangling), so the extraction path can move toward “implemented behavior.”

4. Figure — caller + comparator split diagram

Where: extends planned Figure 3, or a new figure. Two boxes: WF1 (list:list reads → map-over Bowtie2 → single mapped MACS2 → per-condition peaks); WF2 (two peak sets → 3-way intersect → promoter/nearest-gene → gene lists + figure); a dashed arrow “analyst picks the two conditions” marks the irreducible seam. Carries idea 1 visually.

NICE-TO-HAVE

Tensions / honesty

  1. State the 2-way limit plainly, then resolve it (split = positive engineering answer, not a concession).
  2. Condition-pinning still runs (34 steps, 0 dangling) — say “runnable but condition-pinned,” not “broken”; the split is the route to full reusability.
  3. The _original_hda fix belongs in Implementation/Test-Coverage, framed as routine maturation (“a real use case surfaced and fixed a correctness bug”), not alarm.
  4. Avoid over-claiming: the figure tail + (post-fix) alignment map extract cleanly; the single workflow extracts complete-but-condition-pinned; full sample-agnostic reuse needs the split. Match this layered truth (the debrief walked back an earlier “the whole UC2 extracts” overstatement).
  5. The GATA1-null reframing shows the notebook+revision system catching/recording a real interpretive correction — reinforces a core claim and protects against a domain reviewer.

Where UC2 is best vs UC1/UC3

Priority: ideas 1–4 must-include; 5–7 nice-to-have. Keep UC2 positioned as the contrast/robustness vignette paired against a happy-path UC1/UC3.