# Effective Scientific Figure Design

> **Primary source**: Brunner et al., "Designing effective figures for
> scientific communication." *Nat Hum Behav* (2026).
> DOI: 10.1038/s41562-026-02466-9 — communication-context strategies.
>
> **Companion sources** (cite in figure legends / Methods when used):
> - Rougier et al., "Ten simple rules for better figures." *PLoS Comput
>   Biol* 2014;10:e1003833 (PMID 25210732). General-purpose, foundational
>   ten-item checklist.
> - Crameri F., "Choosing the right colors: a perceptually uniform,
>   colorblind-safe approach." *Curr Protoc* 2024;4:e1126
>   (DOI 10.1002/cpz1.1126). Definitive 2024 reference for `viridis`,
>   `cividis`, `batlow` palettes and redundant encoding.
>
> **Triggered from**: SKILL.md Step 1 ("Specify"). Read this file **before**
> choosing a figure type — it shifts focus from "which chart fits the data" to
> "what message should the reader walk away with."

Most figure-design guidance focuses on technical execution (axis ranges,
palettes, DPI). This file complements that by adding a communication-first
layer: who reads the figure, under what time pressure, and what should they
remember 10 seconds later. Apply these strategies in Step 1 when specifying a
figure; revisit during Step 4 / 4b when reviewing.

---

## The 5 strategies (read in order)

### 1. Identify the key message *(most important)*

Before opening a plotting library, write **one sentence** describing what the
figure must convey. If you cannot, the figure is premature. Examples:

- "Model A outperforms Model B at every operating threshold."
- "Adverse-event rates differ by route of administration but not by dose."
- "The proposed pipeline runs end-to-end in under 30 seconds per case."

Pin that sentence as a comment at the top of the generation script. Every
panel, color, annotation, and label exists to support that message; anything
that does not should be removed or moved to supplementary material.

### 2. Consider time and interaction (audience-aware)

Different reading contexts allow different amounts of inspection time:

| Context | Reading time | Implication |
|---|---|---|
| Journal article (specialist) | 30–120 s per figure | Dense detail acceptable; legend lookups OK |
| Conference slide | 15–30 s, narrated | Direct labels mandatory; one message per slide |
| Visual / graphical abstract | 5–10 s, no narration | One panel; minimal text; readable thumbnail |
| Social-media share | 2–5 s | Self-contained; large fonts; high contrast |
| Public lecture / press | 10–30 s, narrated | Plain-language axis labels; analogy via icon |

Set the **reading-time budget** in Step 1, then design backwards. If the same
result will appear in a journal article *and* a conference talk, build two
distinct versions — the conference version usually drops half of what the
journal version contains.

### 3. Choose the right graph type and use color intentionally

The graph type should match the structure of the data, not aesthetic
preference.

| Data structure | Default | Avoid |
|---|---|---|
| One continuous variable, one group | Histogram, density | Pie chart |
| Two continuous variables | Scatter (+ regression line if appropriate) | Bar chart |
| Continuous over time | Line | Stacked bar |
| Categorical proportions | Bar (sorted), waffle | 3-D pie |
| Distribution by group | Box / violin / strip | Bar with SD error |
| Diagnostic performance | ROC, PR curve | Single accuracy bar |
| Effect size with CI | Forest plot, dot-and-whisker | Bar with asterisks |
| Workflow / cohort | Flow diagram (PRISMA / CONSORT / STARD) | Free-form arrows |

Color rules (compatible with this skill's `figure_specs.md`; full
justification in Crameri 2024):

- **Categorical groups**: Wong palette (8 colorblind-safe colors).
- **Sequential magnitude**: `viridis` or `cividis` (perceptually uniform,
  colorblind-safe). Avoid `jet` and `rainbow` — they introduce false
  perceptual edges.
- **Diverging around zero**: `RdBu`, `PuOr`, or `vik` (Crameri).
- **Encode meaning, not decoration.** If the same conclusion holds in
  grayscale, color is decorative — remove or use neutral grays.
- **Redundant encoding** when color carries diagnostic information: pair
  color with line style, marker shape, or direct label so the figure
  survives a deuteranopia simulation and a black-and-white print.
- **Maximum 3 colors per panel** unless the data structure genuinely demands
  more (and then label each directly, not via legend).

### 4. Reduce cognitive load

Every visual element competes for attention. The reader's working memory is
roughly 7 items; design under that ceiling.

- ≤7 distinct visual elements per panel (curves, boxes, annotations).
- ≤3 distinct shapes (e.g., square, circle, triangle).
- ≤3 colors as above.
- **Direct labels on series > legend.** Legend lookups cost ~2 seconds each.
- No 3-D, drop-shadow, gradient fill, or rotated axis labels unless they
  encode data.
- Sans-serif font ≥ 9 pt at print size; ≥ 18 pt for slides; ≥ 24 pt for
  posters.
- Whitespace is not wasted space — it groups related elements.

If a panel violates two or more of these, split it into multiple panels or
move detail to supplementary material.

### 5. Ask whether a figure is really needed

Sometimes a table, a single sentence, or a caption-only number conveys the
result more clearly. Use a figure when **at least one** of the following is
true:

- The reader needs to perceive a *shape* (trend, distribution, threshold).
- The reader needs to *compare* across many groups simultaneously.
- The result depends on a *spatial* or *anatomical* relationship.
- The audience will not read the prose carefully and needs a visual hook.

Otherwise, prefer a small table or in-line text. A 3-row × 2-column results
table beats a bar chart of two values.

---

## Decision: figure vs table

| Use a **figure** when… | Use a **table** when… |
|---|---|
| Trend or shape matters | Exact values matter (e.g., baseline characteristics) |
| ≥4 groups / conditions | ≤3 groups *and* ≤8 metrics |
| Distribution shape conveys meaning | Categorical labels with counts |
| Comparison across many dimensions | Reader will reuse the numbers (re-analysis, replication) |
| Visual-abstract / hero panel | Supplementary detail |

When in doubt, sketch both on paper for 60 seconds and decide which the eye
finishes first.

---

## Cognitive load checklist (Step 4 quick scan)

- [ ] One sentence describes the key message in the script comment.
- [ ] Reading-time budget matches the deployment context.
- [ ] ≤7 visual elements per panel.
- [ ] ≤3 colors carrying meaning (not decoration).
- [ ] No 3-D / shadow / gradient unless data-driven.
- [ ] Direct labels on series; legend has ≤4 entries.
- [ ] Font size meets context minimum (9 pt print / 18 pt slide / 24 pt poster).
- [ ] Same figure works in grayscale (run a `convert -colorspace Gray` test).

If two or more boxes are unchecked, return to Step 1 before exporting.

---

## Anti-patterns (drawn from this skill's critic rubrics)

These compose with the more granular checks in
`critic_rubrics/data_plot.md` and `critic_rubrics/flow_diagram.md`:

- **Default-palette syndrome** — using the matplotlib `tab10` palette without
  thought. Reads as a quick draft, not a finished figure.
- **Legend-dependence** — colored series without direct labels, forcing
  back-and-forth between legend and data.
- **Decorative 3-D** — bars or pies in 3-D with no third data dimension.
- **Chart-of-three-values** — figure where a sentence would be clearer.
- **Caption-as-Methods** — caption explains how the data were generated
  rather than what to look at; methodology belongs in the Methods section.
- **Mismatched detail** — slide-deck figure rendered at 6 pt because it was
  copied from the manuscript without adjustment.

---

## Cross-references

- `critic_rubrics/data_plot.md` — quantitative critic checks for non-flow figures
- `critic_rubrics/flow_diagram.md` — extended checks for flow diagrams
- `figure_specs.md` — journal-specific dimensions and DPI
- `flow_diagram_lessons.md` — production lessons specific to PRISMA / CONSORT / STARD
- `reporting_guideline_figure_map.md` — which figures CONSORT-AI / TRIPOD+AI / CLAIM 2024 / STARD-AI mandate
- `pipeline_concepts_medical_ai.md` — DICOM workflow, annotation, federated learning, model architecture conventions

# `figures/_figure_manifest.md` — format and field definitions

Load-on-demand companion to `/make-figures`. SKILL.md states that the manifest is
mandatory and who consumes it; this file is the literal format.

Read it when you are writing the manifest.

After generating all figures, create a structured manifest file at `figures/_figure_manifest.md`:

```markdown
# Figure Manifest
Generated: {YYYY-MM-DD}
Study type: {study type or "custom"}

| Figure | Path | Type | Tool | Critic | Rounds | Description |
|--------|------|------|------|--------|--------|-------------|
| Figure 1 | figures/fig1_stard_flow.svg | flow-diagram | D2 | yes | 2 | STARD participant flow diagram |
| Figure 2 | figures/fig2_roc.pdf | roc-curve | matplotlib | yes | 1 | ROC curves for Model A vs B |
| Figure 3 | figures/fig3_calibration.pdf | calibration | matplotlib | partial | 3 | Calibration plot; legend still crowded (see notes) |

## Critic notes
- Figure 3: after 3 rounds, legend placement remains crowded at the
  double-column width. Candidate remediations documented but not applied
  to avoid reducing data-point visibility.
```

**Manifest field definitions:**
- **Path**: Relative path from project root
- **Type**: One of: `flow-diagram`, `roc-curve`, `forest-plot`, `funnel-plot`, `calibration`, `km-curve`, `bland-altman`, `confusion-matrix`, `box-violin`, `bar-chart`, `heatmap`, `pipeline`, `visual-abstract`, `sroc-curve`, `other`
- **Tool**: Tool used to generate (`matplotlib`, `D2`, `python-pptx`, `seaborn`, etc.)
- **Critic**: `yes` (all rubric items PASS) / `partial` (some PARTIAL after max rounds) / `no` (never critiqued — avoid for submission figures) / `skip` (deliberately bypassed, e.g., panel figure assembled externally)
- **Rounds**: Number of Critic Loop rounds executed (0 if skipped)
- **Description**: One-line description suitable for figure legend context

A `## Critic notes` section at the bottom of the manifest records any
residual PARTIAL items and the rationale for accepting them.

This manifest is consumed by `/write-paper` Phase 2 (figure embedding) and Phase 7 (DOCX build). It **MUST** exist after figure generation completes. Verify the file is non-empty before finishing.

# Figure Specifications Reference

## Journal Dimension Requirements

| Journal | Single Column | 1.5 Column | Double Column | Full Page | Max Height |
|---------|--------------|------------|---------------|-----------|------------|
| AJR | 3.3 in (84 mm) | 5.0 in (127 mm) | 6.83 in (174 mm) | 6.83 x 9.19 in | 9.19 in |
| Radiology | 3.37 in (85.6 mm) | 5.04 in (128 mm) | 6.83 in (173.5 mm) | 6.83 x 9.19 in | 9.19 in |
| Radiology: AI | 3.37 in (85.6 mm) | 5.04 in (128 mm) | 6.83 in (173.5 mm) | 6.83 x 9.19 in | 9.19 in |
| European Radiology | 3.35 in (85 mm) | -- | 6.85 in (174 mm) | 6.85 x 9.13 in | 9.13 in |
| KJR | 3.27 in (83 mm) | -- | 6.89 in (175 mm) | 6.89 x 9.21 in | 9.21 in |
| **Default** | **3.5 in (88 mm)** | **5.0 in (127 mm)** | **7.0 in (178 mm)** | **7.0 x 9.5 in** | **9.5 in** |

### Notes

- Dimensions are the maximum printable area; figures should not exceed these.
- When in doubt, use single-column width (3.5 in) for simple plots and double-column (7.0 in) for complex or multi-panel figures.
- Height is flexible but should not exceed the max height listed above.

---

## DPI Requirements

| Content Type | Minimum DPI | Recommended DPI | Notes |
|-------------|-------------|-----------------|-------|
| Line art (diagrams, flow charts) | 600 | 1200 | Vector PDF preferred |
| Halftone (photographs, medical images) | 300 | 300 | TIFF or PNG |
| Combination (line art + halftone) | 600 | 600 | |
| Color figures | 300 | 300 | |
| Review/presentation | 150 | 300 | PNG acceptable |

---

## File Format Requirements by Journal

| Journal | Preferred Format | Accepted Formats | Notes |
|---------|-----------------|------------------|-------|
| AJR | TIFF | TIFF, EPS, PDF, JPEG | TIFF LZW compression; JPEG only for photos |
| Radiology | TIFF | TIFF, EPS, PDF, PNG | EPS for vector; TIFF for raster |
| Radiology: AI | PDF | PDF, TIFF, EPS, PNG | PDF preferred for vector graphics |
| European Radiology | TIFF | TIFF, EPS, PDF | EPS or PDF for line art |
| KJR | TIFF | TIFF, JPEG, PPT | PPT accepted but not recommended |
| **Default** | **PDF + PNG** | PDF (vector), PNG (raster) | Always produce both |

---

## Color Palettes

### Wong Colorblind-Safe Palette (Default)

| Index | Name | Hex | Use |
|-------|------|-----|-----|
| 0 | Black | `#000000` | Text, axes, reference lines |
| 1 | Orange | `#E69F00` | Primary category 1 |
| 2 | Sky Blue | `#56B4E9` | Primary category 2 |
| 3 | Bluish Green | `#009E73` | Primary category 3 |
| 4 | Yellow | `#F0E442` | Highlight (use sparingly) |
| 5 | Blue | `#0072B2` | Primary model/group |
| 6 | Vermillion | `#D55E00` | Secondary model/group |
| 7 | Reddish Purple | `#CC79A7` | Tertiary model/group |

```python
WONG = ['#000000', '#E69F00', '#56B4E9', '#009E73',
        '#F0E442', '#0072B2', '#D55E00', '#CC79A7']
```

### Sequential Palettes (Heatmaps)

| Use Case | Matplotlib Colormap | Direction |
|----------|-------------------|-----------|
| Positive values only | `Blues`, `Greens`, `Oranges` | Light to dark |
| Diverging (centered at 0) | `coolwarm`, `RdBu_r` | Negative=blue, positive=red |
| Correlation matrix | `coolwarm` | -1 to +1 centered |
| Agreement matrix | `YlOrRd` | Low=yellow, high=red |
| Confusion matrix | `Blues` | Low=white, high=blue |
| p-value heatmap | `Reds_r` | Significant=dark |

### Rules

- Never rely on color alone; combine with line style, marker shape, or hatching.
- Test figures in grayscale to ensure readability.
- Avoid pure red (#FF0000) and pure green (#00FF00) adjacent to each other.

---

## Font Size Table

| Element | Size (pt) | Weight | Font Family |
|---------|-----------|--------|-------------|
| Figure title (rare, prefer caption) | 10 | Bold | Arial / Helvetica |
| Axis label | 9 | Regular | Arial / Helvetica |
| Tick label | 8 | Regular | Arial / Helvetica |
| Legend text | 8 | Regular | Arial / Helvetica |
| Annotation text | 8 | Regular | Arial / Helvetica |
| Panel label (A, B, C) | 12 | Bold | Arial / Helvetica |
| Inset text | 7 | Regular | Arial / Helvetica |
| Table text (in figure) | 7-8 | Regular | Arial / Helvetica |

### Rules

- Minimum readable size after print: 6 pt.
- All text in figures must be embedded (not rasterized) for vector formats.
- Use `plt.rcParams['font.family'] = 'sans-serif'` and `plt.rcParams['font.sans-serif'] = ['Arial', 'Helvetica']`.

---

## Common Figure Layouts

### Single Panel

```
+-----------+
|           |
|   Plot    |
|           |
+-----------+
```
- Width: single column (3.5 in) or double column (7.0 in)
- Height: proportional, typically 1:1 or 4:3 aspect ratio
- Use: ROC curve, calibration plot, KM curve, Bland-Altman

### 2-Panel Horizontal

```
+-----+-----+
|  A  |  B  |
+-----+-----+
```
- Width: double column (7.0 in), each panel ~3.3 in
- Height: 3.0-3.5 in
- Use: comparing two related plots (e.g., ROC for two endpoints)

### 2-Panel Vertical

```
+-----+
|  A  |
+-----+
|  B  |
+-----+
```
- Width: single column (3.5 in)
- Height: 6.0-7.0 in
- Use: same variable, different conditions (e.g., training vs test set)

### 2x2 Grid

```
+-----+-----+
|  A  |  B  |
+-----+-----+
|  C  |  D  |
+-----+-----+
```
- Width: double column (7.0 in), each panel ~3.3 in
- Height: 6.0-7.0 in
- Use: four related analyses (e.g., subgroup comparisons)

### 3-Panel Horizontal

```
+---+---+---+
| A | B | C |
+---+---+---+
```
- Width: double column (7.0 in), each panel ~2.1 in
- Height: 2.5-3.0 in
- Use: three conditions or progressive stages

### Unequal Panels (GridSpec)

```
+---------+----+
|         | B  |
|    A    +----+
|         | C  |
+---------+----+
```
- Use `matplotlib.gridspec.GridSpec` for custom layouts
- Use: main result (A) with supporting details (B, C)

---

## Caption Writing Guidelines

### Structure

1. **Sentence 1**: What the figure shows -- figure type and key finding.
2. **Sentences 2-3**: Define symbols, abbreviations, colors, and line styles.
3. **Sentence 3-4**: State sample sizes, statistical tests, significance levels.
4. **Final sentence**: Interpretation aid (if not self-evident from the plot).

### Format

```
Figure {N}. {Description starting with capital letter, ending with period.}
```

- No bold title. No title case (except proper nouns and abbreviations).
- Use sentence case throughout.
- Spell out abbreviations on first use in the caption.

### Multi-Panel Captions

```
Figure {N}. {Overall description.} (A) {Panel A description.} (B) {Panel B description.}
```

### Examples

**ROC Curve:**
> Figure 2. Receiver operating characteristic curves for the multi-agent validation pipeline. The area under the curve was 0.92 (95% CI: 0.89-0.95) for the full pipeline and 0.84 (95% CI: 0.80-0.88) for the single-agent baseline (DeLong test, p = 0.003). The dashed diagonal line represents chance performance (AUC = 0.5). AUC = area under the curve, CI = confidence interval.

**Flow Diagram:**
> Figure 1. Study flow diagram following the Standards for Reporting Diagnostic Accuracy Studies (STARD) 2015 guidelines. Numbers in each box represent the count of Anki flashcards at each stage of the validation pipeline.

**Multi-Panel:**
> Figure 3. Agreement analysis between human reviewers and the multi-agent pipeline. (A) Bland-Altman plot showing the difference in quality scores between reviewer 1 and the pipeline against their mean. Horizontal dashed lines indicate the mean difference and 95% limits of agreement. (B) Scatter plot of reviewer 1 versus pipeline scores with the line of identity (dashed).

---

## Figure Numbering Conventions

- Number figures sequentially as they appear in the text (Figure 1, Figure 2, ...).
- Supplemental figures: Figure S1, Figure S2, ...
- Reference every figure at least once in the main text.
- Place figures after first mention (or at end, per journal preference).
- Do not include a figure title inside the plot area; use the caption below instead.

---

## Flow Diagram Tool Selection (STROBE / CONSORT / PRISMA / STARD)

All reporting-guideline flow diagrams use a single canonical pipeline: `scripts/generate_flow_diagram.R` (DiagrammeR DOT → DiagrammeRsvg → rsvg).

### Why this stack

| Requirement | Requirement detail | DiagrammeR + rsvg |
|---|---|---|
| Vector PDF (editable, journal-grade) | Radiology/NEJM/Eur Radiol require EPS/AI/PDF | **True vector via `rsvg_pdf()`** |
| 300 / 600 / 1200 dpi PNG | RSNA line-art = 1200 dpi; Eur Radiol = 300–1000 | **Arbitrary DPI via `rsvg_png(width=...)`** |
| Arial font embedded | AMA/RSNA style | `fontname="Arial"` enforced in DOT header |
| Single-color monochrome outline | BMJ/Annals IM convention | `color=black, fillcolor=white, style=filled` |
| Auto-overlap resolution | Labels change size; manual coords fail | Graphviz `dot` hierarchical engine |
| 4 reporting guidelines in one tool | Avoid stack sprawl | Generic DOT template switch |

### Why not the obvious alternatives

| Rejected tool | Reason |
|---|---|
| matplotlib `FancyBboxPatch` (manual coords) | Overlap on label change; DOCX embed distortion. Root cause of an STROBE Figure 1 rework. |
| D2 + post-processing | Weak Arial enforcement; PNG needs 85% vertical compression hack; font-size must be manually set 20–24. Retained as legacy fallback only. |
| R `consort` v1.2.2 | CONSORT/STROBE only; STARD/PRISMA not covered; box style parameters not officially exposed (requires gpar override). |
| R `PRISMA2020` v1.1.1 | `PRISMA_save()` uses webshot → PDF rasterized; no DPI parameter. Not suitable for journal submission. |
| Mermaid / PlantUML | Font control weak; hard to enforce Arial + monochrome outline. |

### PRISMA 2020 compliance

The generic DOT template in `generate_flow_diagram.R` implements the PRISMA 2020 structure (two identification streams, duplicates-removed box, title/abstract screening, full-text retrieval, full-text assessment, final inclusion) and can reproduce the official template shape. When a journal explicitly requires use of the PRISMA2020 R package or Shiny app for provenance, run that tool separately; the DiagrammeR pipeline is the default for all other submissions.

### File outputs

Every render emits three files at the same prefix:

```
<prefix>.pdf        true vector (journal submission, figure_manifest primary)
<prefix>.png        300 dpi (2400 px wide; review copy, DOCX embed)
<prefix>_600.png    600 dpi (4800 px wide; RSNA/Eur Radiol line-art)
```

### System dependency

`brew install librsvg` (macOS; one-time). On Linux: `apt-get install librsvg2-bin`.

## Central Illustration Dimensions

Used by the JACC family and all journals that distinguish a Central Illustration from a Visual Abstract (Fuster V, Mann DL. *JACC.* 2019;74(22):2816–2820). See `references/jacc_central_illustration_principles.md`.

| Spec | Value |
|---|---|
| PPTX slide size | 10 × 7.5 in (4:3 standard) |
| Content figure area | ~4 × 4.2 in (top-center of slide) |
| Citation textbox | 9.4 × 0.5 in at (0.4, 5.3) |
| Content figure resolution | ≥ 600 DPI PNG; PDF vector preferred |
| Font | Sans-serif (Arial or equivalent), ≥ 9 pt at print scale |
| Color | Color allowed; figure should remain interpretable in grayscale |
| Visual zones in content figure | 1–3 (enforced by `--type central-illustration`) |
| Total label word count | ≤ 30 |
| Numerical highlights | ≤ 4 |

**Do not pre-render**: the red outer border and the blue "CENTRAL ILLUSTRATION:" header bar visible in published JACC issues are applied by JACC editorial after acceptance. Authors submit only the content figure and citation footer.

# Flow Diagram Production — Hard-Earned Lessons

> **Triggered from**: SKILL.md Step 4b (Critic Loop). Read this file when
> generating PRISMA / CONSORT / STARD / STROBE diagrams, especially before a
> circulation round with senior co-authors.
>
> **Source**: Distilled from a multi-revision meta-analysis project where
> Figure 1 (PRISMA flow) went through four major iterations before clearing
> a senior reviewer round. Each lesson maps to a concrete failure mode.

Flow diagrams look simple but consume disproportionate revision time. The
underlying causes are rarely "wrong numbers" — they are template fidelity,
PDF export fidelity, and version drift between the diagram and the
manuscript. The five lessons below address each in turn.

---

## Lesson 1: Use the official template once a senior reviewer is in the loop

**Failure mode**: Custom Graphviz / DiagrammeR layout offers more freedom
(left-aligned bullets via `\l`, `penwidth=1.8` highlights on the analytic
cohort, free positioning of side-boxes). Senior systematic-review reviewers,
however, expect the **PRISMA 2020 standard layout** as published by the
PRISMA Statement group. A custom layout reads as "the authors did not follow
the guideline," even when every count is correct.

**Resolution**:

- Prototype freely with Graphviz / DiagrammeR for early drafts.
- **Switch to an official template before circulation.** The R package
  `PRISMA2020` (Haddaway et al.) renders the canonical layout from a CSV.
  Equivalent canonical templates exist for CONSORT 2010, STARD 2015, and
  STROBE.
- If the official template lacks a feature you need (e.g., a third
  exclusion sub-branch), prefer to fold the detail into the existing slots
  rather than restructure.

**Cross-link**: `critic_rubrics/flow_diagram.md` — "Official template
fidelity" check.

---

## Lesson 2: PDF export — the VML fallback breaks under headless converters

**Failure mode**: The official PRISMA 2020 docx contains VML (Vector Markup
Language) fallback pairs that older Word versions render. When converted to
PDF via headless LibreOffice (`soffice --headless --convert-to pdf`), the
phase labels can shift by several pixels, columns misalign, and on some
systems text reflows out of its box. The PDF looks "almost right" — the
kind of bug that survives a quick visual scan.

**Resolution by platform**:

| Platform | Approach | Notes |
|---|---|---|
| **macOS** | AppleScript driving Microsoft Word for Mac | Deterministic native render; can be invoked headlessly via `osascript`. |
| **Windows** | PowerShell / VBScript COM driving Word | `Word.Application` object → `.SaveAs2` with `wdFormatPDF`. |
| **Linux / CI** | Office Online Server (paid), or commit a pre-rendered PDF produced on macOS / Windows | Headless LibreOffice is **not** safe for VML-heavy templates. |
| Any platform (fallback) | Open in desktop Word → "Save As PDF" manually | Slow but always correct; document the manual step in the manifest. |

**Verify visually**: After export, open the PDF and the source docx
side-by-side. Compare phase-label positions, column widths, and the Y
position of every numeric box. If anything has shifted, do not submit that
PDF.

---

## Lesson 3: docx XML editing requires entity escape

**Failure mode**: A docx file is a ZIP archive containing
`word/document.xml`. Programmatic placeholder substitution (e.g., replacing
`{{n_screened}}` with `1,234` plus a comment, or `{{study_title}}` with a
title containing `&`) by raw `str.replace` produces invalid XML. Word then
shows "We're sorry, we can't open the file because there's a problem with
the contents." dialog on next open, or — worse — opens with a "repair"
prompt that silently drops content.

**Resolution**:

- Use an entity-escaping helper before injecting any user-provided string.
  Python: `xml.sax.saxutils.escape(value)`. JavaScript: `he.encode` or a
  small regex (`& → &amp;`, `< → &lt;`, `> → &gt;`).
- High-risk fields:
  - Study titles containing `&` (`Smith & Jones, 2020`).
  - Range strings containing `<` or `>` (`age <5 years`, `loss >50%`).
  - Author lists with apostrophes (`O'Brien`).
- After substitution, validate with `python -c "import zipfile,
  xml.etree.ElementTree as E;
  E.fromstring(zipfile.ZipFile('out.docx').read('word/document.xml'))"`.
  An exception means the docx is broken.

---

## Lesson 4: VML fallback templates need sequential placeholder maps

**Failure mode**: The official PRISMA 2020 docx duplicates each numeric box
as a `<w:t>` pair: a primary text element plus a VML fallback. Branch
ordering in XML DOM does **not** match rendering order — the "Other"
identification branch and the "Database" branch are interleaved in the
document, and the VML fallbacks appear elsewhere again. A naive
"replace each placeholder with the next number" loop misaligns most boxes.

**Resolution**:

1. Dump every `<w:t>` in document order with a script
   (`python -c "from docx import Document; ..."` or direct XML walk).
2. Annotate each `<w:t>` with column / branch / role
   (`identification.databases.records_n`, `identification.databases.records_n.fallback`).
3. Build a static `VALUES` list with one entry per `<w:t>` slot, **with a
   comment per slot** documenting what it represents.
4. Validate by filling all slots with a sentinel value (e.g., `999`) and
   visually checking that all 60+ boxes show `999` in the rendered PDF
   before re-running with real data.

This sentinel-render is cheap (one extra `999` pass) and catches mapping
errors before they propagate into a circulation round.

---

## Lesson 5: Freeze figure versions alongside manuscript versions

**Failure mode**: A reviewer asks about Figure 1 in revision round 2, but
the figure file in `manuscript/figures/figure_1.pdf` was edited in place
between rounds. The version visible in v3 of the manuscript no longer
exists, and tracing what changed requires diffing PDFs (lossy and slow).

**Resolution**:

- Treat figures as part of the manuscript artifact — they freeze with each
  manuscript version under the **`v_N` rule** (manuscript-versioning
  protocol).
- Maintain `figures/v{N}/` directories. Each contains the source script
  (`generate_figure_1.R`), the input data CSV, and the rendered docx + PDF
  pair.
- An `INDEX.md` at `figures/INDEX.md` maps figure version ↔ manuscript
  version, e.g.:
  ```
  | Manuscript | Figure 1 | Figure 2 | Figure 3 |
  |---|---|---|---|
  | v3 (circulated 2025-09-01) | figures/v3/figure_1.pdf | figures/v3/figure_2.pdf | figures/v2/figure_3.pdf |
  | v4 (submitted 2025-10-15)  | figures/v4/figure_1.pdf | figures/v3/figure_2.pdf | figures/v3/figure_3.pdf |
  ```
- **Never edit `figures/v3/*.pdf` after circulation.** Branch to
  `figures/v4/` and rebuild.

---

## Lesson 6: Any flowchart-shaped figure uses the monochrome Graphviz convention — not colorful boxes-and-arrows

**Failure mode**: A study-design / reader-flow / pipeline schematic (i.e. NOT a
reporting-guideline flow) gets hand-built in matplotlib (or slides) with filled
color boxes, accent palettes, and manually positioned text. It reads as
"AI-generated", text is poorly aligned inside the boxes (matplotlib anchors text
by point, not to the box geometry, so multi-line bodies overflow the border), and
it does not match the journal house style of the group's accepted papers.

**Resolution** — treat *every* flowchart-shaped figure (CONSORT/PRISMA/STARD/STROBE
**and** study-design, reader-flow, cohort-assembly, MRMC/reader-study, generation-
pipeline schematics) as the same object and render it with `scripts/generate_flow_diagram.R`
(DiagrammeR → Graphviz `dot`). The house convention, already encoded in that
script's `STYLE_HEADER`, is the journal standard:

- `fillcolor=white, color=black` (white fill, **black outline only — no color**)
- `fontname="Arial"`, `fontsize` 10–11
- `shape=box, style="rounded,filled"`, `penwidth=1.2` (emphasis boxes `penwidth=1.8`)
- `splines=ortho` (right-angle edges), `nodesep`/`ranksep` ≈ 0.4–0.55
- left-aligned sub-lists with `\l` and `•` (`•`); side panels / exclusions via
  `{ rank=same; main; side }` and an invisible edge to anchor them
- Graphviz lays text out *relative to the node box*, so alignment and centering are
  automatic — this is why it beats hand-positioned matplotlib/slide boxes.

Reconcile every count to the manuscript with `stopifnot()` assertions in the script
header (e.g. `stopifnot(N_auth + N_v16 + N_v12 == N_pool)`); leave data-dependent
counts as a single find-replaceable token (e.g. `[N_COMPLETED]`) filled at data lock.

**Do not** reach for matplotlib/PowerPoint/AI-image tools for a box-and-arrow figure.
matplotlib is for *data* figures (ROC, forest, calibration, KM); Graphviz is for
*flow/structure* figures. Mixing them produces the colorful, misaligned look this
lesson exists to prevent.

> Motivation: a reader-study Figure 1 was first built in colorful matplotlib and
> rejected by the author as "too AI-looking, text not aligned in the boxes." Rebuilt
> with `generate_flow_diagram.R` in the monochrome house style — matching the same
> style used across the group's accepted meta-analysis, cohort, and reader-study flow
> figures — it passed immediately.

---

## When to use which approach

| Stage | Tool | Output | Risk if you skip |
|---|---|---|---|
| Early draft | DiagrammeR + Graphviz custom | PNG, fast iteration | None — flexibility wins here |
| Internal QC | R `PRISMA2020` package or equivalent | Official-template PNG / PDF | Custom layout will be flagged in circulation |
| Circulation | Filled official-template docx + native-Word PDF (macOS AppleScript / Windows COM) | Frozen docx + PDF pair | Headless export drift; reviewer notices misaligned labels |
| Submission | `figures/v_N/` frozen pair | Immutable docx + PDF | Edit-in-place breaks the manuscript-figure version map |

---

## Quick cross-references

- `critic_rubrics/flow_diagram.md` — extended critic checklist (rounds T=1…3)
- `design_principles.md` — communication-first design strategies
- `figure_specs.md` — journal-specific dimensions and DPI
- `exemplar_diagrams/{prisma,consort,stard,strobe}/` — reference layouts

# Flow diagrams (STARD / CONSORT / PRISMA / STROBE) — the R recipe

Load-on-demand companion to `/make-figures`. SKILL.md states the mandatory rule (the
standardized R pipeline, never matplotlib `FancyBboxPatch`, never D2 for new diagrams);
this file is the recipe: the YAML schema, the fixed style, the per-project
`create_figure1.R` pattern, and the legacy D2 fallback.

Read it when you are actually generating a reporting-guideline flow diagram. A figure set
with no flow diagram (a ROC curve, a forest plot, a calibration plot) needs none of it.

**Flow diagram generation rule:** STARD/CONSORT/PRISMA/STROBE flow diagrams **MUST** use the standardized R pipeline `scripts/generate_flow_diagram.R` (DiagrammeR + Graphviz dot + rsvg). This is the single canonical tool for all four reporting-guideline flow diagrams. Do NOT use matplotlib `FancyBboxPatch` (manual coordinates break when text changes, and patches distort when embedded in DOCX). Do NOT use D2 for new flow diagrams (font control is weak, overlap requires manual post-processing). The legacy D2 recipe remains documented below as a fallback only when R is unavailable.

**R flow diagram recipe (mandatory for all flow diagrams):**

The pipeline reads a YAML config describing nodes/edges and produces: a true vector PDF (journal submission), a 300 dpi PNG (review copy), and a 600 dpi PNG (RSNA/Eur Radiol line-art). Default style is single-color black outline with white fill in Arial, overriding D2's colored defaults and matplotlib's manual coordinates.

```bash
# 1. One-time system dependency:
brew install librsvg
Rscript -e 'install.packages(c("DiagrammeR","DiagrammeRsvg","rsvg","yaml"))'

# 2. Author a YAML config. Templates for each type live at
#    references/exemplar_diagrams/{strobe,consort,prisma,stard}/template_input.yaml
# 3. Render:
Rscript ${CLAUDE_SKILL_DIR}/scripts/generate_flow_diagram.R \
    --type   {strobe|consort|prisma|stard} \
    --config path/to/counts.yaml \
    --out    figures/figure1_flow
# Outputs: figure1_flow.pdf, figure1_flow.png (300 dpi), figure1_flow_600.png
```

**YAML schema highlights:**
- `rankdir: TB` (top-down, default) or `LR` (left-to-right).
- `nodes:` list with `id`, `label` (use literal `\n` for line breaks, real Unicode `–`, `≤`, `−`, `•`).
- Optional per-node: `highlight: true` (thicker border), `shape: note` (side boxes), `rank_same_with: <other_id>` (place on same horizontal rank).
- `edges:` list with `from`, `to`, optional `style: dashed`, `arrow: false` (no arrowhead), `constraint: false` (edge ignored by layout engine — use for exclusion side-links).
- Numbers in labels **MUST** be CSV-derived in an upstream R script that emits the YAML, or hand-written only when the value lives in a commit-tracked data artifact. Follow numerical-safety rules.

**Style is fixed (do not override in the YAML):**
- Monochrome: all boxes `color=black, fillcolor=white, fontname="Arial"`.
- Penwidth 1.2 default, 1.8 for highlighted cohort box.
- Arrow style: black solid, arrowsize 0.75. Dashed without arrowhead for exclusion side-links.
- Bullet alignment in multi-item labels: Graphviz `\l` (left-align), never `\n` (center). Each `\l` applies to text preceding it.
- **No HTML-like labels** (`label=<...>` with `<B>`, `<I>`, `&#8226;`). Plain quoted labels with `\l` bullets produce tighter, more readable structure than HTML ragged wrapping. Do not reintroduce without explicit approval.
- To add one emphasis color (e.g., Wong blue `#0072B2` for a single highlighted box), edit `scripts/generate_flow_diagram.R` — do not inline hex colors in YAML.

**Per-project `create_figure1.R` pattern (preferred for complex flows):**

When the flow has derived counts, `stopifnot()` reconciliation, multi-rank `{rank=same; ... }` constraints, or exclusion side-cars that the generic YAML dispatcher cannot express cleanly, write a per-project `create_figure1.R` directly (same DiagrammeR + DiagrammeRsvg + rsvg stack, sprintf'd `dot` string). This is the dominant pattern when the generic YAML dispatcher cannot capture the flow:

- STROBE cohort: `<project>/manuscript/figures/create_figure1.R`
- STARD: `<project>/Analysis/figures/create_figure1.R` or `<project>/figures/v2_monochrome/create_figure1.R`
- PRISMA / PRISMA-DTA: `<project>/5_Figures/create_figure1.R` or `<project>/analysis/create_figure1.R`
- CONSORT-edu (naturalistic allocation): `<project>/figures/v2_monochrome/create_figure1.R`

Copy the `STYLE_HEADER` (graph/node/edge attrs) verbatim from any exemplar; then customise nodes, edges, and `{rank=same}` blocks. Use `read.csv()` for cohort counts when possible; if hardcoded, every number must have a source comment referencing manuscript line / CSV cell / screening log row.

**Legacy D2 fallback (only when R unavailable):**

```bash
d2 --layout elk --theme 0 --pad 20 flow.d2 /tmp/raw.png --scale 2
# Resize + 85% vertical compression via Pillow; then render PDF:
d2 --layout elk --theme 0 --pad 20 flow.d2 figures/fig1_flow.pdf
```

Use `font-size: 20-24`, `stroke: black`, `fill: white`. D2 PDF is vector; D2 PNG needs the resize step to match publication density.

---

# JACC Central Illustration — Principles & Layout Spec

Distilled from Fuster V, Mann DL. **The Art and Challenge of Crafting a Central Illustration or Visual Abstract.** *J Am Coll Cardiol.* 2019;74(22):2816–2820. doi:10.1016/j.jacc.2019.10.035

This document is the canonical reference when generating Central Illustrations for JACC, JACC: Asia, JACC: Cardiovascular Imaging, JACC: Heart Failure, JACC: Basic to Translational Science, JACC: CardioOncology, and JACC: Clinical Electrophysiology.

## CI vs Visual Abstract — they are different artifacts

| Aspect | Central Illustration | Visual Abstract |
|---|---|---|
| Purpose | Single key finding / take-home message | Methods + Results pictorial summary |
| Where referenced in paper | End of Results / start of Discussion | Beginning of paper |
| Methods content | **None** | Required |
| Audience | Cardiovascular clinicians + readers of the journal issue | Broad including non-specialists / social media |
| Used by | All JACC family journals + JACC: Asia | Originally JACC: Basic to Translational Science |
| Text density | Minimal (graphical priority) | More allowed (methods labels) |
| Bar graphs | OK if they capture entire message | Avoid — use ↑↓ arrows |
| Default complexity | Simple (1–3 visual zones) | Simple (Q→M→R three blocks) |

If a paper requires *both* a central illustration and a visual abstract (some JACC sister journals), they must convey complementary content; do not duplicate.

## Five Fuster-Mann rules (must pass all)

1. **Know the message.** Decide one finding the figure must convey. Do not stuff in the study design + multiple findings + take-homes — that "causes confusion and excess that does not inform the reader."
2. **Convey graphically, not textually.** Even a simple Kaplan–Meier curve is acceptable if it captures the entire message. Bar graphs are tolerated if they earn their space.
3. **Avoid using too much text.** Any text that can be replaced by an icon or arrow should be.
4. **Avoid secondary messages.** If a viewer cannot state the main finding within 5 seconds of looking at the figure, the figure has too much.
5. **Simplicity is superior.** Authors "truly struggle with the concept" early; default to fewer panels rather than more.

## CI mode validation rules (enforced by `generate_visual_abstract.py --type central-illustration`)

A submission rejects with a warning if any of the following holds:

| Rule | Threshold | Rationale (Fuster-Mann) |
|---|---|---|
| `n_visual_zones` | ≤ 3 | "Simplicity is superior" |
| `total_label_word_count` | ≤ 30 | "Avoid using too much text" |
| `methods_terms_present` | none of: `cohort flow`, `inclusion`, `exclusion`, `study design`, `enrollment`, `randomized`, `sample size` | CI ≠ VA; methods belong in VA |
| `numerical_data_points` | ≤ 4 | "Avoid incorporating secondary messages" |

Override a single rule with `--allow rule=name` and a justification note recorded in the output PPTX speaker notes.

## JACC PPTX layout (verified from official submission templates)

Reference: 4 official JACC PPTX submission files (Figures 1–4 of Fuster-Mann editorial, doi:10.1016/j.jacc.2019.10.035). All four share an identical layout:

| Slot | Type | Position (left, top) inches | Size (W × H) inches | Content |
|---|---|---|---|---|
| 1 | TEXT_BOX | (0.4, 5.3) | 9.4 × 0.5 | Citation: `"FirstAuthor et al. JACC YYYY; vol(issue):pages."` |
| 2 | PICTURE | (3.0, 0.8) | 4.0 × 4.2 | **Author-provided content figure** (the only thing the author owns) |
| 3 | TEXT_BOX | (0.4, 7.0) | 4.1 × 0.5 | Reserved (often empty in production templates) |
| 4 | PICTURE | (7.3, 6.7) | 2.7 × 0.8 | JACC family logo (placeholder; supplied by editorial) |

Slide size: **10 × 7.5 inches (4:3)**. Background white.

The red border + the blue "CENTRAL ILLUSTRATION:" header bar visible in published JACC issues are **applied by the JACC editorial team after acceptance** — authors should not pre-render those elements in their submission.

Authors submit:
- Slot 1 (citation text)
- Slot 2 (the content figure as PNG/TIFF, ≥600 DPI, content area ~4 × 4.2 in at print)

Slots 3 and 4 stay as placeholders.

## Author-provided content figure spec

| Spec | Value |
|---|---|
| Aspect ratio | ~1:1 to slightly portrait (4 × 4.2 in) |
| Print resolution | 600 DPI for PNG, vector preferred (PDF) |
| Font | Sans-serif; minimum 9 pt at print scale |
| Color | Allowed; high-contrast for grayscale fallback |
| Visual zones | 1–3 (rule above) |
| Total label words | ≤ 30 |
| Numerical highlights | ≤ 4 |
| Photographs | Allowed (Fuster-Mann Figure 4 example) |

Reference good examples cited in the editorial:
- *Moccetti F, et al. J Am Coll Cardiol. 2018;72(9):1015–26.* — heart anatomy + 3 concept boxes + vessel cross-section + brain image. Total ~20 words. (Fuster-Mann Figure 1)
- *Brugada J, et al. J Am Coll Cardiol. 2018;72(9):1046–59.* — 3-column "Diagnosis / Pathophysiology / Management" grid with ECG, sequencing, defibrillator imagery. (Fuster-Mann Figure 2)

## Common author mistakes (rejected examples)

- Embedding the cohort flow / CONSORT-style diagram → that is a study Figure 1 or a Visual Abstract, never a Central Illustration.
- Side-by-side forest plot + KM curve + heat map → too many secondary messages.
- Text-heavy "Clinical takeaway" tile boxes summarizing multiple bullets → reduce to one icon-anchored sentence or move to Discussion narrative.
- Multiple HR/CI/p-value annotations across rows → keep ≤ 4 numerical highlights total.
- Methodology labels ("Inclusion criteria", "N=...") → CI must not look like Methods.

## Adding a non-JACC cardiology CI template

Other journals using a CI-style figure (Circulation family, EHJ, JAHA) tend to follow the same simplicity rules. For these, reuse the Fuster-Mann 5 rules above and the validation thresholds, but adjust the PPTX template to the journal's published submission size and citation footer pattern.

# Medical Illustration Sources

Reference for finding medical illustrations for visual abstracts, graphical abstracts, and
manuscript figures. Consult this file when a standalone illustration (not a data plot) is needed.

## Priority Order

1. **Study's own figures** — ROC curve, flow diagram, representative images from the study.
   Always preferred. No licensing issues. Most relevant to the paper.
2. **Free illustration libraries** — Download and insert into the visual abstract template.
3. **Manual drawing** — Simple shapes in Figma, PowerPoint, or Keynote.
4. **AI generation** — Only if GEMINI_API_KEY is available. Use `generate_image.py --style medical`.

---

## Free Resources (CC BY or Public Domain)

### Servier Medical Art (SMART)

- **URL:** https://smart.servier.com/
- **License:** CC BY 4.0 (attribution required)
- **Assets:** 3000+ medical illustrations
- **Categories:** Anatomy (11 systems), cellular biology, medical specialties, equipment
- **Format:** PowerPoint (editable vectors), PNG
- **Best for:** Organ systems, cells, molecules, medical devices, surgical instruments
- **Attribution:** "Illustrations adapted from Servier Medical Art (https://smart.servier.com/),
  licensed under CC BY 4.0"
- **Access:** Browse categories on website. No API. Download slide sets per category.

### NIAID Visual & Medical Arts (BioArt)

- **URL:** https://bioart.niaid.nih.gov/
- **License:** Public domain (US Government work — no attribution legally required, but recommended)
- **Assets:** 2000+ illustrations
- **Categories:** Viruses, bacteria, parasites, anatomy, cells, lab equipment, animals
- **Format:** SVG, PNG, TIFF (high resolution)
- **Best for:** Infectious disease, pathogens, immune cells, laboratory scenes
- **Access:** Browse/search on website. No API.

### BioIcons

- **URL:** https://bioicons.com/
- **License:** Various CC licenses (check per icon)
- **Format:** SVG
- **Best for:** Schematic diagrams, pathway illustrations, icons for flow diagrams

### Reactome Icon Library

- **URL:** https://reactome.org/icon-lib
- **License:** CC BY 4.0
- **Format:** SVG, PNG
- **Best for:** Molecular pathways, biochemistry, cell signaling

---

## Paid Resources

### BioRender

- **URL:** https://biorender.com/
- **License:** Subscription (academic plans available, ~$99/year student)
- **Best for:** Professional graphical abstracts, pathway diagrams, figure panels
- **Note:** Industry standard. Output must include BioRender watermark on free tier.
  Academic publications require paid license for copyright clearance.

### Medi-Sketch

- **URL:** https://www.medi-sketch.com/
- **License:** Per-illustration purchase
- **Best for:** High-quality Korean medical illustrations, graphical abstract commissions
- **Note:** Korean marketplace connecting researchers with professional medical illustrators

---

## Keyword → Source Mapping

| Need | Recommended Source |
|------|--------------------|
| Organ anatomy (heart, lung, brain, kidney) | Servier Medical Art |
| Cell biology (membrane, organelles, DNA) | Servier Medical Art |
| Infectious agents (virus, bacteria) | NIAID BioArt |
| Lab equipment (microscope, pipette, scanner) | NIAID BioArt or Servier |
| CT/MRI scanner illustration | Servier Medical Art |
| Molecular pathway | Reactome or BioRender |
| Schematic flow icons | BioIcons |
| Custom professional illustration | Medi-Sketch or BioRender |

---

## Usage Notes

- **Editable vectors preferred.** Servier provides PowerPoint files with ungroupable vector shapes.
  Extract individual elements and recolor to match your visual abstract palette.
- **Resolution check.** Ensure downloaded PNGs are ≥300 DPI for print. SVGs scale infinitely.
- **Consistency.** Within one visual abstract, use illustrations from the same source to maintain
  visual coherence (mixing Servier flat style with NIAID 3D renders looks inconsistent).
- **AI generation warning.** See the AI-Generated Figure Warning section in SKILL.md.
  AI-generated medical illustrations are recognizable to reviewers. Use sparingly and customize.

# Pipeline & Architecture Diagrams — Medical AI / Engineering

> **Triggered from**: SKILL.md Step 1 (Specify) when the figure is a
> pipeline / architecture / workflow for a medical AI or imaging
> engineering paper. Read alongside `design_principles.md` (key-message)
> and `flow_diagram_lessons.md` (production lessons).

This file covers the four most common diagram types in medical-imaging AI
and engineering manuscripts that the standard reporting-guideline flows
(PRISMA / CONSORT / STARD / STROBE) do not address: DICOM workflow,
annotation pipeline, federated-learning topology, and model architecture.
For each, this file gives the canonical layout, common pitfalls, and a
preferred tool.

---

## 1. DICOM workflow diagram

**Use when**: the manuscript describes how DICOM images flow from scanner
→ PACS → research environment → preprocessing → model.

**Canonical layout** (left-to-right):

```
[Modality / scanner]  →  [PACS]  →  [Research VNA / mirror]
       ↓                                       ↓
  acquisition                       de-identification
  parameters                        + DICOM tag scrub
                                              ↓
                              [Preprocessed cohort store]
                                              ↓
                              [Train / tune / test split]
                                              ↓
                                     [Model input]
```

**Required annotations**:

- Modality (CT, MR, US, X-ray, OCT) and key acquisition parameters
  (kVp / mAs for CT, sequence and TE/TR for MR).
- De-identification step explicitly named — DICOM tag list (e.g., remove
  PatientName, PatientID, AccessionNumber, InstitutionName) or reference
  to a published profile (DICOM PS3.15 Annex E "Basic Profile").
- Whether pixel-data redaction (burned-in PHI) was performed.
- Cohort filtering criteria with counts at each step (this is also a
  STARD / TRIPOD requirement).

**Common pitfalls**:

- Drawing "PACS → model" with no de-identification box (privacy reviewers
  reject).
- Counts only at the final analytic cohort, not at each filter step
  (reproducibility reviewers reject).
- Using "DICOM" as a single block when the manuscript actually transforms
  to NIfTI / NRRD partway through — show the conversion explicitly.

**Preferred tool**: D2 with `--layout elk` for left-to-right; or Graphviz
`rankdir=LR`. Avoid matplotlib `FancyBboxPatch` (manual coordinates break
when text changes).

---

## 2. Annotation / labeling pipeline

**Use when**: the manuscript reports a labeled dataset built by human
annotators (segmentation, classification, bounding boxes).

**Canonical layout**:

```
[Raw image cohort]
       ↓
[Annotation tool / platform]  ←  [Annotator pool: N readers, expertise]
       ↓
[Round 1 labels]  →  [QC / consensus]  →  [Adjudication: senior reader]
                                                       ↓
                                        [Final reference standard]
                                                       ↓
                                        [Inter-rater agreement: κ / Dice]
```

**Required annotations**:

- Number and expertise level of annotators (e.g., "3 board-certified
  radiologists, 5–18 years of post-board experience").
- Annotation tool (e.g., 3D Slicer, ITK-SNAP, MD.ai, RIL-Contour, custom).
- Consensus rule (majority vote / unanimous / senior arbitration).
- Inter-rater agreement metric and value reported separately.
- Whether annotators were blinded to model output / clinical history.

**Common pitfalls**:

- Drawing "labeled by experts" with no count / qualification (reviewers
  ask for quantification).
- Omitting the QC arrow (looks like single-pass labeling, low quality).
- Conflating "reference standard" with "ground truth" — reference
  standard is the imperfect human label; ground truth is what we wish
  we had.

**Preferred tool**: D2; nodes shaped as rectangles for steps, dashed
border for human-in-the-loop steps to distinguish from automated.

---

## 3. Federated-learning topology

**Use when**: the manuscript trains a model across multiple sites without
centralizing raw data.

**Canonical layout** (radial, central server in middle):

```
              [Site A: cohort A_n, scanner type]
                              ↑↓
                       (model weights only,
                        not images)
                              ↑↓
              [Central aggregator / parameter server]
                              ↑↓
   [Site B: cohort B_n] ←→ [Site C: cohort C_n] ←→ [Site D: cohort D_n]
```

**Required annotations**:

- Per-site cohort size, scanner / vendor, demographic summary.
- What is exchanged (gradients / weights / encrypted updates) — and
  what is **not** (raw images, intermediate features).
- Aggregation algorithm (FedAvg / FedProx / FedBN / etc.).
- Number of communication rounds and local epochs per round.
- Privacy / security mechanism (differential privacy noise, secure
  aggregation) if claimed.

**Common pitfalls**:

- Bidirectional arrows without labeling what flows each way.
- No site-level demographic table — federated claims fall flat without
  evidence of distribution shift across sites.
- Labeling raw images crossing site boundaries — if that happens it is
  not federated learning, it is centralized.

**Preferred tool**: D2 with explicit `near: center` for the aggregator
node, then sites at compass points. Or matplotlib polar layout for
manuscripts that want radial symmetry.

---

## 4. Model architecture diagram

**Use when**: the manuscript proposes or modifies a neural-network
architecture and the message depends on the structural change.

**Canonical layout** (left-to-right block diagram):

```
[Input: 3D volume H×W×D, 1 channel]
                ↓
[Backbone: ResNet-50 / ViT-B / nnU-Net]   (cite + checkpoint)
                ↓
[Neck / feature pyramid / skip connections]
                ↓
[Head: classification / segmentation / detection]
                ↓
[Output: class probability / mask / bounding boxes]
```

**Required annotations**:

- Input shape (H × W × D × C) and modality.
- Backbone family + variant + initialization (random / ImageNet /
  domain-pretrained — cite the pretraining work).
- Output shape and post-processing (softmax / argmax / non-max
  suppression).
- Loss function (cross-entropy / Dice / focal / compound).
- Trainable parameter count.

**Style conventions** (medical-AI / engineering):

- Convolutional / linear blocks: rectangles with channel count below.
- Feature maps: trapezoids that shrink/grow to convey resolution change
  (optional but well-recognized).
- Skip connections: dashed arrows.
- Attention or transformer blocks: rectangles with internal split into
  Q / K / V annotation only when the message depends on attention.

**Common pitfalls**:

- "We used ResNet-50" with no diagram — fine for a methods paper, not
  for an architecture-contribution paper.
- 3-D rendered "Convolution" pictograms with no dimension info — looks
  decorative, says nothing.
- Drawing every layer when only the modified blocks matter — the eye
  cannot tell what changed. Show the modification, abstract the rest as
  "ResNet-50 backbone (frozen)".

**Preferred tools**:

- **Diagrams.net (drawio)** — fastest for one-off architecture figures.
- **NN-SVG** (https://alexlenail.me/NN-SVG/) — generates clean SVG for
  fully-connected, LeNet, AlexNet variants.
- **PlotNeuralNet** (LaTeX/TikZ) — used in the academic CV/ML community
  for publication-quality 3-D block diagrams.
- D2 with `shape: hexagon` / `shape: cylinder` if the architecture is
  unusual enough that custom blocks are needed.

For medical-AI papers targeting *Radiology AI*, *npj Digital Medicine*,
or *Nature Medicine*, prefer NN-SVG or PlotNeuralNet output over
hand-drawn blocks — reviewers in this venue are sensitive to alignment
quality.

---

## When to use which (quick selector)

| The figure is showing… | Use this section |
|---|---|
| How images move from scanner to model input | DICOM workflow |
| How a labeled dataset was built | Annotation pipeline |
| Multi-site training without raw-data sharing | Federated topology |
| The structure of the proposed neural network | Model architecture |
| Cohort filtering with counts at each stage | `flow_diagram_lessons.md` (PRISMA / STARD style) |
| Training / tuning / test data splits | dataset-flow (see `reporting_guideline_figure_map.md` §AI-specific) |

If the figure tries to do two of the above at once, split into two panels
or two figures — combining DICOM workflow + architecture in one panel
violates the cognitive-load budget (`design_principles.md` §4).

---

## Cross-references

- `design_principles.md` — communication-first checks
- `flow_diagram_lessons.md` — production lessons (template fidelity, PDF
  export, version freeze)
- `reporting_guideline_figure_map.md` — which figures CLAIM / TRIPOD+AI
  / STARD-AI mandate
- `critic_rubrics/data_plot.md` — calibration / fairness / colorblind
  checks
- `exemplar_diagrams/pipeline/*_why.md` — design notes (the rendered figures were cropped from published papers and were removed; an MIT-licensed package cannot redistribute them) —
  worked exemplars (multimodal MLLM, contrastive learning, VQA, report
  generation)

# Reporting Guideline → Figure Requirements Map

> **Bridge**: this file connects `/make-figures` to `/check-reporting`
> (49 reporting guidelines). Each row tells you which figures the guideline
> **mandates** and how this skill currently supports them. Use during
> Step 1 (Specify) once the study type is known.

When `/check-reporting` flags missing figures for a target guideline, look
up the row here and either render the supported template or fall back to
the documented manual approach.

---

## Mandatory-figure map

Legend for **Status** column:
- ✅ Official template + R/Python generator shipped with this skill
- ⚠️ Generic flow generator (`generate_flow_diagram.R`) covers the layout
  but no official-template fidelity check
- ❌ No template; user produces with D2 / Graphviz / Inkscape from the
  guideline document, then runs critic_rubric manually

| Guideline (year) | Study type | Mandatory figure(s) | Status | Source / where the official asset lives |
|---|---|---|---|---|
| **PRISMA 2020** | Systematic review | Flow diagram (4-phase: identification → screening → eligibility → included) | ✅ | `templates/official/prisma2020/`; R `PRISMA2020` package |
| **PRISMA-DTA** | DTA systematic review | Modified PRISMA flow + DTA-specific exclusion reasons | ⚠️ | Salameh et al., *BMJ* 2020 (PMID 32312813); use generic flow + extra columns |
| **PRISMA-NMA** | Network MA | PRISMA flow + network plot | ❌ | Hutton et al., *Ann Intern Med* 2015; network plot via R `netmeta::netgraph()` |
| **PRISMA-ScR** | Scoping review | PRISMA-ScR flow diagram (sources of evidence: identification → screening → eligibility → included; item 14) | ⚠️ | Tricco et al., *Ann Intern Med* 2018 (DOI 10.7326/M18-0850); use the generic PRISMA flow with "sources of evidence" wording |
| **PRISMA-P** | Protocol of SR | (none mandated; PRISMA-S search strategy figure recommended) | ❌ | Rethlefsen et al., *Syst Rev* 2021 |
| **CONSORT 2025** | RCT | Participant-flow diagram (enrollment → allocation → follow-up → analysis) | ✅ | `templates/official/consort2010/` (now CONSORT 2025); R generator |
| **CONSORT-AI 2020** | AI intervention RCT | CONSORT flow extended with AI training/validation/deployment dataset boxes | ❌ | Liu et al., *Nat Med* 2020 (PMID 32908283), Fig. 1; D2 / Graphviz custom |
| **STARD 2015** | Diagnostic accuracy | Flow diagram (eligible → index test → reference standard → 2×2) + ROC | ✅ | `templates/official/stard2015/`; R generator |
| **STARD-AI 2025** | AI diagnostic accuracy | STARD flow + dataset-flow (training / tuning / test) + subgroup-overlaid ROC/PR | ❌ | Sounderajah et al., *Nat Med* 2025 (PMID 40954311); produce manually, see `flow_diagram_lessons.md` |
| **STROBE** | Observational cohort/case-control | (Flow diagram **recommended** but not strictly mandated) | ⚠️ | von Elm et al., *Ann Intern Med* 2007; use generic flow generator |
| **TRIPOD 2015** | Prediction model | Calibration plot (mandatory) + discrimination (ROC, c-stat with CI) | ✅ (data plots) | Collins et al., *Ann Intern Med* 2015 |
| **TRIPOD+AI 2024** | AI prediction model | TRIPOD figures + **fairness/subgroup panels** + **dataset-flow** + **decision-curve analysis** | ❌ (subgroup, DCA) | Collins et al., *BMJ* 2024 (PMID 38636956); produce manually |
| **CLAIM 2024** | Medical imaging AI | Architecture diagram (model card style) + dataset-flow + calibration + per-subgroup performance + saliency/attention | ❌ | Tejani et al., *Radiology: AI* 2024 (PMID 38809149); 44 items total |
| **DECIDE-AI 2022** | AI clinical eval (Stage 1–2) | Human-AI interaction diagram + safety-signal plot + override-rate over time | ❌ (uncertain — verify in full text) | Vasey et al., *Nat Med* 2022 (PMID 35585198) |
| **CHEERS 2022** | Economic evaluation | Cost-effectiveness plane + cost-effectiveness acceptability curve | ❌ | Husereau et al., *BMJ* 2022 |
| **SPIRIT 2025** | Trial protocol | Schedule-of-enrollment timeline (Figure 1 in published trials) | ✅ | `templates/official/spirit2013/` (updated to 2025); see also Robinson timeline figures |
| **CARE 2013** | Case report | Timeline of patient course (recommended) | ⚠️ | Gagnier et al., *J Clin Epidemiol* 2014; use `exemplar_plots/clinical_timeline.md` |
| **SQUIRE 2.0** | Quality improvement | Run chart / SPC chart | ❌ | Ogrinc et al., *BMJ Qual Saf* 2016 |

---

## When the status is ⚠️ (generic flow only)

The R `generate_flow_diagram.R` script handles the layout, but the layout
will not match the canonical guideline document exactly. For circulation
to senior co-authors, that is usually acceptable; for reviewer-facing
journals where fidelity is checked (esp. in *BMJ*, *Lancet*, *Ann Intern
Med*, *JAMA*), prefer the official template route documented in
`flow_diagram_lessons.md` Lesson 1.

## When the status is ❌

For AI-extension guidelines (CONSORT-AI, STARD-AI, TRIPOD+AI, CLAIM 2024,
DECIDE-AI), there is no shipped official template **as of 2026-05**.
Production path:

1. Read the original article to extract the canonical figure layout.
2. Sketch in D2 (`flow.d2`) or Graphviz DOT, layout via ELK.
3. Render to PDF with the platform-appropriate exporter
   (`flow_diagram_lessons.md` Lesson 2).
4. Apply the cognitive-load + key-message-visibility checks from
   `critic_rubrics/flow_diagram.md` Section G.
5. Cross-check against the corresponding `/check-reporting` checklist
   (item-by-item).

When 2 or more projects need the same custom guideline figure, propose
adding a new template under `templates/official/{guideline}/` so the
deterministic generator can support it.

---

## AI-specific figures most often missing (priority for new templates)

These are the figures that medical AI manuscripts most often omit, ranked
by how frequently a reviewer-facing checklist (CLAIM 2024 / TRIPOD+AI)
flags them:

1. **Dataset-flow diagram** — patient/image counts at each split
   (training / tuning / internal test / external test). Required by
   STARD-AI, CLAIM 2024, TRIPOD+AI.
2. **Calibration plot** — supported by `critic_rubrics/data_plot.md` §C.
3. **Fairness / subgroup panel** — performance by sex / race / device /
   site. Required by TRIPOD+AI, CLAIM 2024.
4. **Decision-curve analysis** — net benefit vs threshold. Required by
   TRIPOD+AI; recommended by CLAIM 2024.
5. **Architecture diagram** — input modality → preprocessing → backbone →
   head → output. See `pipeline_concepts_medical_ai.md`.
6. **Saliency / attention overlay** — qualitative panels showing model
   attention. Required by CLAIM 2024 §4.

---

## Cross-references

- `/check-reporting` skill — supports all 49 guidelines, item-level audit
- `flow_diagram_lessons.md` — production lessons that apply across all flows
- `pipeline_concepts_medical_ai.md` — DICOM / annotation / federated /
  architecture diagram conventions
- `design_principles.md` — communication-first design (Nat Hum Behav 2026)
- `critic_rubrics/flow_diagram.md` — extended checklist (Sections A–G)
- `critic_rubrics/data_plot.md` — calibration / fairness / colorblind checks

"""Build the JACC Central Illustration PPTX template.

Layout matches official JACC submission templates (verified from
doi:10.1016/j.jacc.2019.10.035 Figures 1–4 PPTX files).

Run once. Output:
  references/visual_abstract_templates/jacc_central_illustration.pptx
"""
from pathlib import Path
from pptx import Presentation
from pptx.util import Inches, Pt, Emu
from pptx.dml.color import RGBColor
from pptx.enum.shapes import MSO_SHAPE

ROOT = Path(__file__).resolve().parents[1]
OUT = ROOT / "references" / "visual_abstract_templates" / "jacc_central_illustration.pptx"

# JACC submission slide is 10 x 7.5 in (4:3 standard PPT)
prs = Presentation()
prs.slide_width = Inches(10)
prs.slide_height = Inches(7.5)

# Blank layout
blank = prs.slide_layouts[6]
slide = prs.slides.add_slide(blank)

# ---- Slot 1: citation text box ----
cite = slide.shapes.add_textbox(Inches(0.4), Inches(5.3), Inches(9.4), Inches(0.5))
tf = cite.text_frame
tf.text = "ARTICLECITATION — replace with: FirstAuthor et al. JACC: Asia YYYY; vol(issue):pages."
p = tf.paragraphs[0]
p.font.size = Pt(11)
p.font.bold = True
p.font.color.rgb = RGBColor(0x1F, 0x4E, 0x79)

# ---- Slot 2: content picture placeholder (rectangle as marker) ----
ph = slide.shapes.add_shape(
    MSO_SHAPE.RECTANGLE, Inches(3.0), Inches(0.8), Inches(4.0), Inches(4.2)
)
ph.fill.solid()
ph.fill.fore_color.rgb = RGBColor(0xF2, 0xF2, 0xF2)
ph.line.color.rgb = RGBColor(0xBF, 0xBF, 0xBF)
ph.line.width = Pt(1.5)
ph.text_frame.text = "VISUALELEMENT — replace this rectangle with the author content figure (PNG/TIFF, 600 DPI, ~4×4.2 in)."
for para in ph.text_frame.paragraphs:
    para.font.size = Pt(10)
    para.font.color.rgb = RGBColor(0x59, 0x59, 0x59)
    para.alignment = 1  # center

# ---- Slot 3: footer text box (reserved; usually empty in JACC templates) ----
foot = slide.shapes.add_textbox(Inches(0.4), Inches(7.0), Inches(4.1), Inches(0.5))
foot.text_frame.text = "FOOTERNOTE — optional secondary caption (often empty)."
for para in foot.text_frame.paragraphs:
    para.font.size = Pt(9)
    para.font.color.rgb = RGBColor(0x80, 0x80, 0x80)
    para.font.italic = True

# ---- Slot 4: logo placeholder (rectangle as marker) ----
logo = slide.shapes.add_shape(
    MSO_SHAPE.RECTANGLE, Inches(7.3), Inches(6.7), Inches(2.7), Inches(0.8)
)
logo.fill.solid()
logo.fill.fore_color.rgb = RGBColor(0xFF, 0xFF, 0xFF)
logo.line.color.rgb = RGBColor(0xBF, 0xBF, 0xBF)
logo.line.width = Pt(0.75)
logo.text_frame.text = "JACCLOGO — JACC family logo (provided by editorial)."
for para in logo.text_frame.paragraphs:
    para.font.size = Pt(8)
    para.font.color.rgb = RGBColor(0x80, 0x80, 0x80)
    para.alignment = 1

# Save
OUT.parent.mkdir(parents=True, exist_ok=True)
prs.save(OUT)
print(f"Saved: {OUT}")
print(f"Slide size: {Emu(prs.slide_width).inches:.2f} x {Emu(prs.slide_height).inches:.2f} in")
print("Placeholders: ARTICLECITATION, VISUALELEMENT, FOOTERNOTE, JACCLOGO")

#!/usr/bin/env python3
"""Build a PRISMA 2020 flow diagram template (.pptx) programmatically.

Why this script exists
----------------------
prismastatement.org serves the official .docx templates behind a Squarespace
JavaScript fingerprint redirect that blocks programmatic download (curl, wget,
WebFetch, Wayback Machine all return the redirect HTML stub, not the file).

We reproduce the published layout from Page MJ et al. *BMJ* 2021;372:n71
(Fig 1, "PRISMA 2020 flow diagram"), which the PRISMA Group releases under
CC-BY 4.0. Box positions, labels, and arrow topology mirror the official
template; only the per-line counts are placeholders that fill_prisma_template.py
populates.

Variants
--------
- ``new``     : new systematic reviews (no "Studies included in previous
                version" branch)
- ``updated`` : updated systematic reviews (adds the previous-version branch
                on the right)

The "registers/databases only" (v1) vs "+ other sources" (v2) distinction is
handled by toggling the ``--include-other-sources`` flag, which adds the
secondary identification column on the left.

Usage
-----
    python3 build_prisma2020_template.py \
        --variant new --include-other-sources \
        --out templates/official/prisma2020/PRISMA_2020_flow_new_v2.pptx
"""
from __future__ import annotations

import argparse
from pathlib import Path

from pptx import Presentation
from pptx.dml.color import RGBColor
from pptx.enum.shapes import MSO_SHAPE
from pptx.util import Emu, Inches, Pt

# ── Layout constants (inches) ────────────────────────────────────────────────
SLIDE_W = 13.33
SLIDE_H = 10.0

BOX_W = 3.4
BOX_H = 0.95
COL_GAP = 0.4
ROW_GAP = 0.45

# Phase column on the far left
PHASE_COL_X = 0.3
PHASE_COL_W = 1.3

# Identification block columns
IDENT_COL1_X = PHASE_COL_X + PHASE_COL_W + 0.2  # registers / databases
IDENT_COL2_X = IDENT_COL1_X + BOX_W + COL_GAP   # other sources (v2 only)

# Vertical positions
TITLE_Y = 0.25
ROW1_Y = 1.1   # records identified
ROW2_Y = ROW1_Y + BOX_H + ROW_GAP  # records removed before screening (right inset)

SCREENING_Y = 3.3
SCREENING_EXCL_X_OFFSET = BOX_W + COL_GAP

ELIGIBILITY_Y = SCREENING_Y + (BOX_H + ROW_GAP) * 2  # reports retrieved + sought
INCLUDED_Y = SLIDE_H - BOX_H - 0.6

# Colors
NAVY = RGBColor(0x1F, 0x3A, 0x68)
LIGHT = RGBColor(0xE8, 0xEE, 0xF7)
BLACK = RGBColor(0x00, 0x00, 0x00)
GREY = RGBColor(0x55, 0x55, 0x55)


# ── Helpers ──────────────────────────────────────────────────────────────────
def add_box(
    slide,
    left: float,
    top: float,
    width: float,
    height: float,
    text: str,
    *,
    fill=LIGHT,
    border=NAVY,
    bold_first_line: bool = True,
    font_size: int = 10,
):
    """Add a rounded rectangle with the given text. Returns the shape."""
    shape = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(left),
        Inches(top),
        Inches(width),
        Inches(height),
    )
    shape.fill.solid()
    shape.fill.fore_color.rgb = fill
    shape.line.color.rgb = border
    shape.line.width = Pt(0.75)

    tf = shape.text_frame
    tf.word_wrap = True
    tf.margin_left = tf.margin_right = Inches(0.06)
    tf.margin_top = tf.margin_bottom = Inches(0.04)

    lines = text.split("\n")
    for i, line in enumerate(lines):
        para = tf.paragraphs[0] if i == 0 else tf.add_paragraph()
        run = para.add_run()
        run.text = line
        run.font.size = Pt(font_size)
        run.font.color.rgb = BLACK
        run.font.bold = bold_first_line and i == 0
    return shape


def add_phase_label(slide, top: float, text: str):
    shape = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(PHASE_COL_X),
        Inches(top),
        Inches(PHASE_COL_W),
        Inches(BOX_H),
    )
    shape.fill.solid()
    shape.fill.fore_color.rgb = NAVY
    shape.line.color.rgb = NAVY
    tf = shape.text_frame
    tf.word_wrap = True
    p = tf.paragraphs[0]
    p.alignment = 2  # center
    run = p.add_run()
    run.text = text
    run.font.size = Pt(12)
    run.font.bold = True
    run.font.color.rgb = RGBColor(0xFF, 0xFF, 0xFF)


def add_arrow(slide, x1, y1, x2, y2):
    line = slide.shapes.add_connector(1, Inches(x1), Inches(y1), Inches(x2), Inches(y2))
    line.line.color.rgb = NAVY
    line.line.width = Pt(1.25)


# ── Builders ─────────────────────────────────────────────────────────────────
def build_template(variant: str, include_other_sources: bool, out_path: Path) -> None:
    prs = Presentation()
    prs.slide_width = Inches(SLIDE_W)
    prs.slide_height = Inches(SLIDE_H)
    blank_layout = prs.slide_layouts[6]
    slide = prs.slides.add_slide(blank_layout)

    # Title
    title_box = slide.shapes.add_textbox(
        Inches(0.3), Inches(TITLE_Y), Inches(SLIDE_W - 0.6), Inches(0.6)
    )
    tf = title_box.text_frame
    p = tf.paragraphs[0]
    run = p.add_run()
    run.text = (
        f"PRISMA 2020 flow diagram for "
        f"{'updated' if variant == 'updated' else 'new'} systematic reviews"
        + (" (databases, registers, and other sources)"
           if include_other_sources else " (databases and registers only)")
    )
    run.font.size = Pt(14)
    run.font.bold = True
    run.font.color.rgb = NAVY

    # Phase labels (left column)
    add_phase_label(slide, ROW1_Y, "Identification")
    add_phase_label(slide, SCREENING_Y, "Screening")
    add_phase_label(slide, INCLUDED_Y, "Included")

    # ── Identification row ───────────────────────────────────────────────────
    add_box(
        slide,
        IDENT_COL1_X,
        ROW1_Y,
        BOX_W,
        BOX_H,
        "Records identified from:\n"
        "  Databases (n = {n_db})\n"
        "  Registers (n = {n_reg})",
        font_size=10,
    )

    # Right inset: records removed before screening
    removed_x = IDENT_COL1_X + BOX_W + COL_GAP + (BOX_W + COL_GAP if include_other_sources else 0)
    add_box(
        slide,
        removed_x,
        ROW1_Y,
        BOX_W,
        BOX_H,
        "Records removed before screening:\n"
        "  Duplicate records removed (n = {n_dup})\n"
        "  Records marked as ineligible by automation tools (n = {n_auto})\n"
        "  Records removed for other reasons (n = {n_other_removed})",
        font_size=9,
    )
    add_arrow(slide, IDENT_COL1_X + BOX_W, ROW1_Y + BOX_H / 2, removed_x, ROW1_Y + BOX_H / 2)

    if include_other_sources:
        add_box(
            slide,
            IDENT_COL2_X,
            ROW1_Y,
            BOX_W,
            BOX_H,
            "Records identified from:\n"
            "  Websites (n = {n_web})\n"
            "  Organisations (n = {n_org})\n"
            "  Citation searching (n = {n_cite})\n"
            "  etc.",
            font_size=9,
        )

    # ── Screening row ────────────────────────────────────────────────────────
    add_box(
        slide,
        IDENT_COL1_X,
        SCREENING_Y,
        BOX_W,
        BOX_H,
        "Records screened\n(n = {n_screened})",
    )
    add_box(
        slide,
        IDENT_COL1_X + SCREENING_EXCL_X_OFFSET,
        SCREENING_Y,
        BOX_W,
        BOX_H,
        "Records excluded\n(n = {n_screen_excluded})",
    )
    add_arrow(slide, IDENT_COL1_X + BOX_W / 2, ROW1_Y + BOX_H, IDENT_COL1_X + BOX_W / 2, SCREENING_Y)
    add_arrow(
        slide,
        IDENT_COL1_X + BOX_W,
        SCREENING_Y + BOX_H / 2,
        IDENT_COL1_X + SCREENING_EXCL_X_OFFSET,
        SCREENING_Y + BOX_H / 2,
    )

    # Reports sought / not retrieved
    add_box(
        slide,
        IDENT_COL1_X,
        SCREENING_Y + BOX_H + ROW_GAP,
        BOX_W,
        BOX_H,
        "Reports sought for retrieval\n(n = {n_sought})",
    )
    add_box(
        slide,
        IDENT_COL1_X + SCREENING_EXCL_X_OFFSET,
        SCREENING_Y + BOX_H + ROW_GAP,
        BOX_W,
        BOX_H,
        "Reports not retrieved\n(n = {n_not_retrieved})",
    )
    add_arrow(
        slide,
        IDENT_COL1_X + BOX_W / 2,
        SCREENING_Y + BOX_H,
        IDENT_COL1_X + BOX_W / 2,
        SCREENING_Y + BOX_H + ROW_GAP,
    )
    add_arrow(
        slide,
        IDENT_COL1_X + BOX_W,
        SCREENING_Y + BOX_H + ROW_GAP + BOX_H / 2,
        IDENT_COL1_X + SCREENING_EXCL_X_OFFSET,
        SCREENING_Y + BOX_H + ROW_GAP + BOX_H / 2,
    )

    # Reports assessed / excluded with reasons
    assess_y = SCREENING_Y + (BOX_H + ROW_GAP) * 2
    add_box(
        slide,
        IDENT_COL1_X,
        assess_y,
        BOX_W,
        BOX_H,
        "Reports assessed for eligibility\n(n = {n_assessed})",
    )
    add_box(
        slide,
        IDENT_COL1_X + SCREENING_EXCL_X_OFFSET,
        assess_y,
        BOX_W,
        BOX_H + 0.4,
        "Reports excluded:\n"
        "  Reason 1 (n = {n_excl_r1})\n"
        "  Reason 2 (n = {n_excl_r2})\n"
        "  Reason 3 (n = {n_excl_r3})\n"
        "  etc.",
        font_size=9,
    )
    add_arrow(
        slide,
        IDENT_COL1_X + BOX_W / 2,
        SCREENING_Y + (BOX_H + ROW_GAP) * 2 - ROW_GAP,
        IDENT_COL1_X + BOX_W / 2,
        assess_y,
    )
    add_arrow(
        slide,
        IDENT_COL1_X + BOX_W,
        assess_y + BOX_H / 2,
        IDENT_COL1_X + SCREENING_EXCL_X_OFFSET,
        assess_y + BOX_H / 2,
    )

    # ── Included row ─────────────────────────────────────────────────────────
    add_box(
        slide,
        IDENT_COL1_X,
        INCLUDED_Y,
        BOX_W * 1.3,
        BOX_H + 0.3,
        "Studies included in review (n = {n_studies})\n"
        "Reports of included studies (n = {n_reports})",
        font_size=11,
    )
    add_arrow(
        slide,
        IDENT_COL1_X + BOX_W / 2,
        assess_y + BOX_H + 0.4,
        IDENT_COL1_X + BOX_W / 2,
        INCLUDED_Y,
    )

    # Footer attribution (CC-BY)
    foot = slide.shapes.add_textbox(
        Inches(0.3), Inches(SLIDE_H - 0.45), Inches(SLIDE_W - 0.6), Inches(0.35)
    )
    fp = foot.text_frame.paragraphs[0]
    r = fp.add_run()
    r.text = (
        "Layout adapted from Page MJ et al. PRISMA 2020 flow diagram, BMJ 2021;372:n71. "
        "Distributed under CC-BY 4.0."
    )
    r.font.size = Pt(8)
    r.font.italic = True
    r.font.color.rgb = GREY

    out_path.parent.mkdir(parents=True, exist_ok=True)
    prs.save(out_path)
    print(f"✓ wrote {out_path}")


def main():
    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    ap.add_argument("--variant", choices=["new", "updated"], default="new")
    ap.add_argument(
        "--include-other-sources",
        action="store_true",
        help="Include the 'other sources' identification column (v2 layout).",
    )
    ap.add_argument("--out", type=Path, required=True)
    args = ap.parse_args()
    build_template(args.variant, args.include_other_sources, args.out)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Build an editable STROBE participant flow diagram (.pptx) from a YAML config.

Why this script exists
----------------------
The Graphviz path (``generate_flow_diagram.R --type strobe``) renders an
auto-fitting monochrome diagram suitable for journal submission, but
co-authors often want to nudge box positions, edit prose, or recolor stage
labels in PowerPoint. This script produces a fully-editable .pptx in the
classical Identification → Screening → Inclusion → Analysis convention used
by the BMJ / Radiology / KJR cohort-study examples (Randolph 2018,
PLoS ONE 2021).

Unlike PRISMA, STROBE flow diagrams have study-specific spine structure
(number of cohort-stage boxes and exclusions varies per study), so this is
a single parametric builder rather than the PRISMA two-step
(``build_prisma2020_template.py`` then ``fill_prisma_template.py``).

YAML schema
-----------
    output_pptx: figures/figure1_strobe.pptx          # required
    slide_size: [10.5, 11.0]                           # inches; auto-computed if omitted
    title: "Figure 1. STROBE participant flow diagram"  # optional

    # `stages:` is OPTIONAL. STROBE itself does not mandate a phase column —
    # most cohort papers omit it (the column is a PRISMA 2020 convention). When
    # `stages:` is present, the script renders a left phase column and merges
    # consecutive same-stage spine rows under one label. When omitted (or empty),
    # the spine shifts left, the slide narrows, and the figure looks like the
    # plainer STROBE convention.
    stages:
      - {name: Identification, color: "#cfe1f5"}      # color = stage box fill
      - {name: Screening,      color: "#cfe1f5"}
      - {name: Inclusion,      color: "#cfe1f5"}
      - {name: Analysis,       color: "#cfe1f5"}
    spine:
      - {id: enrolled,  stage: Identification, text: "..."}
      - {id: screened,  stage: Screening,      text: "..."}
      - {id: eligible,  stage: Inclusion,      text: "..."}
      - {id: primary,   stage: Analysis,       text: "..."}
      - {id: landmark,  stage: Analysis,       text: "..."}  # consecutive same-stage rows share one stage label
    exclusions:
      - {after: enrolled, text: "Excluded (n = 1,200):\\n- did not meet the index finding on any screening"}
      - {after: screened, text: "Excluded (n = 3):\\n- prior outcome event / zero post-baseline follow-up"}

Usage
-----
    python3 build_strobe_template.py \
        --config figures/figure1_strobe.yaml \
        --out    figures/figure1_strobe.pptx

Open the resulting .pptx in PowerPoint to fine-tune positions or styling
before saving as PDF / TIFF for submission.
"""
from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path

from _strobe_cascade import check_cascade

try:
    import yaml
    HAS_YAML = True
except ImportError:
    HAS_YAML = False

from lxml import etree
from pptx import Presentation
from pptx.dml.color import RGBColor
from pptx.enum.shapes import MSO_SHAPE
from pptx.enum.text import MSO_ANCHOR, PP_ALIGN
from pptx.oxml.ns import qn
from pptx.util import Inches, Pt


# ── Defaults ────────────────────────────────────────────────────────────────
DEFAULT_SLIDE_W = 10.5    # default width when slide_size unset; height auto-computed
FALLBACK_SLIDE_H = 11.0   # only used if auto-compute can't fit
ABSOLUTE_MAX_SLIDE_H = 14.0  # PowerPoint hard upper bound for legible single-slide layouts

# Column geometry (inches) — tighter than widescreen; better for vertical flow
PHASE_X = 0.4
PHASE_W = 1.4
SPINE_X = 2.2
SPINE_W = 3.6
EXCL_X  = 6.4
EXCL_W  = 3.7

# Vertical spacing
TITLE_Y = 0.25
TITLE_H = 0.5
TOP_PAD = 0.35           # below title before first row
ROW_GAP = 0.35           # vertical gap between adjacent rows
DEFAULT_ROW_H = 1.20     # slightly taller boxes for better text breathing room
DEFAULT_EXCL_H = 1.05
BOTTOM_PAD = 0.4         # margin below last row

# Colors
NAVY   = RGBColor(0x1F, 0x3A, 0x68)
WHITE  = RGBColor(0xFF, 0xFF, 0xFF)
BLACK  = RGBColor(0x00, 0x00, 0x00)
LBLUE  = RGBColor(0xCF, 0xE1, 0xF5)


# ── Helpers ─────────────────────────────────────────────────────────────────
def _parse_color(hex_str: str | None, default: RGBColor) -> RGBColor:
    if not hex_str:
        return default
    h = hex_str.lstrip("#")
    return RGBColor(int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16))


def _readable_text_color(bg: RGBColor) -> RGBColor:
    """Return BLACK or WHITE depending on background luminance."""
    # Relative luminance per WCAG (sRGB approx without gamma)
    r, g, b = bg[0], bg[1], bg[2]
    lum = 0.299 * r + 0.587 * g + 0.114 * b
    return RGBColor(0x1F, 0x3A, 0x68) if lum > 160 else WHITE


def add_box(slide, x, y, w, h, text, *,
            fill=WHITE, border=BLACK, font_color=BLACK,
            font_size=11, bold_first=True, anchor_middle=True,
            align_center=True, line_pt=1.0, dash=False):
    shape = slide.shapes.add_shape(
        MSO_SHAPE.ROUNDED_RECTANGLE,
        Inches(x), Inches(y), Inches(w), Inches(h),
    )
    shape.fill.solid()
    shape.fill.fore_color.rgb = fill
    shape.line.color.rgb = border
    shape.line.width = Pt(line_pt)
    if dash:
        ln = shape.line._get_or_add_ln()
        # Remove any existing prstDash to keep idempotent
        for existing in ln.findall(qn("a:prstDash")):
            ln.remove(existing)
        prst = etree.SubElement(ln, qn("a:prstDash"))
        prst.set("val", "dash")

    tf = shape.text_frame
    tf.word_wrap = True
    tf.margin_left = tf.margin_right = Inches(0.10)
    tf.margin_top = tf.margin_bottom = Inches(0.06)
    if anchor_middle:
        tf.vertical_anchor = MSO_ANCHOR.MIDDLE

    lines = str(text).split("\n")
    for i, line in enumerate(lines):
        para = tf.paragraphs[0] if i == 0 else tf.add_paragraph()
        para.alignment = PP_ALIGN.CENTER if align_center else PP_ALIGN.LEFT
        run = para.add_run()
        run.text = line
        run.font.size = Pt(font_size)
        run.font.color.rgb = font_color
        run.font.bold = bool(bold_first and i == 0)
    return shape


def add_arrow(slide, x1, y1, x2, y2, *, color=BLACK, width_pt=1.25):
    line = slide.shapes.add_connector(1, Inches(x1), Inches(y1), Inches(x2), Inches(y2))
    line.line.color.rgb = color
    line.line.width = Pt(width_pt)
    # Arrow head on the destination end
    line_xml = line.line._get_or_add_ln()
    tail = etree.SubElement(line_xml, qn("a:tailEnd"))
    tail.set("type", "triangle")
    tail.set("w", "med")
    tail.set("len", "med")


def add_right_angle_arrow(slide, x1, y1, x2, y2, *, color=BLACK, width_pt=1.0):
    """Spine right edge → exclusion left edge with a horizontal stub then arrow."""
    # Use a single straight horizontal connector since both ends share y
    add_arrow(slide, x1, y1, x2, y2, color=color, width_pt=width_pt)


# ── Loader ──────────────────────────────────────────────────────────────────
def load_config(path: Path) -> dict:
    text = path.read_text(encoding="utf-8")
    if path.suffix in (".yaml", ".yml"):
        if not HAS_YAML:
            sys.exit("PyYAML not installed; install or use JSON config.")
        return yaml.safe_load(text)
    if path.suffix == ".json":
        return json.loads(text)
    try:
        return json.loads(text)
    except json.JSONDecodeError:
        if HAS_YAML:
            return yaml.safe_load(text)
        sys.exit("Config not JSON and PyYAML unavailable.")


# ── Builder ────────────────────────────────────────────────────────────────
def build(cfg: dict, out_path: Path) -> None:
    # Layout dimensions decided BEFORE slide creation so we can right-size the
    # canvas to the content (no large empty bottom strip).
    spine = cfg["spine"]
    n_spine = len(spine)
    spine_h = float(cfg.get("spine_box_height", DEFAULT_ROW_H))
    excl_h  = float(cfg.get("exclusion_box_height", DEFAULT_EXCL_H))
    title_text = cfg.get("title")

    # Phase column is optional. STROBE itself does not mandate one (PRISMA does);
    # most cohort papers omit it. Render only when the user supplies a non-empty
    # `stages:` list in the YAML config.
    stages_cfg = cfg.get("stages") or []
    has_phase_column = bool(stages_cfg)

    # Effective horizontal positions (collapse left margin when no phase column)
    if has_phase_column:
        spine_x_eff = SPINE_X
        excl_x_eff  = EXCL_X
    else:
        excl_gap = EXCL_X - SPINE_X - SPINE_W   # preserve the spine→excl gap
        spine_x_eff = PHASE_X
        excl_x_eff  = spine_x_eff + SPINE_W + excl_gap

    avail_top = TITLE_Y + TITLE_H + TOP_PAD if title_text else TITLE_Y
    row_pitch = spine_h + ROW_GAP
    last_row_end = avail_top + (n_spine - 1) * row_pitch + spine_h
    auto_h = last_row_end + BOTTOM_PAD
    auto_w = excl_x_eff + EXCL_W + PHASE_X      # right margin == left margin

    if "slide_size" in cfg:
        slide_w, slide_h = cfg["slide_size"]
    else:
        slide_w = max(auto_w, 4.0)
        slide_h = min(max(auto_h, 4.0), ABSOLUTE_MAX_SLIDE_H)

    # If the user gave a slide_size that's too short for the content, scale boxes down
    needed = last_row_end + BOTTOM_PAD
    if needed > slide_h:
        scale = (slide_h - avail_top - BOTTOM_PAD) / (n_spine * row_pitch - ROW_GAP)
        spine_h = max(0.7, spine_h * scale)
        excl_h  = max(0.6, excl_h * scale)
        row_pitch = spine_h + ROW_GAP

    prs = Presentation()
    prs.slide_width = Inches(slide_w)
    prs.slide_height = Inches(slide_h)
    blank_layout = prs.slide_layouts[6]
    slide = prs.slides.add_slide(blank_layout)

    # Title
    if title_text:
        title_box = slide.shapes.add_textbox(
            Inches(PHASE_X), Inches(TITLE_Y),
            Inches(slide_w - PHASE_X * 2), Inches(TITLE_H),
        )
        tf = title_box.text_frame
        p = tf.paragraphs[0]
        run = p.add_run()
        run.text = title_text
        run.font.size = Pt(13)
        run.font.bold = True
        run.font.color.rgb = NAVY

    spine_y = {}
    for i, b in enumerate(spine):
        spine_y[b["id"]] = avail_top + i * row_pitch

    # Phase column (optional) — group consecutive same-stage rows under one merged label.
    if has_phase_column:
        stage_color_lookup = {s["name"]: _parse_color(s.get("color"), NAVY) for s in stages_cfg}
        stages_seq = [b.get("stage") for b in spine]
        i = 0
        while i < n_spine:
            j = i
            while j + 1 < n_spine and stages_seq[j + 1] == stages_seq[i]:
                j += 1
            sname = stages_seq[i]
            y_top = spine_y[spine[i]["id"]]
            y_bot = spine_y[spine[j]["id"]] + spine_h
            h = y_bot - y_top
            stage_fill = stage_color_lookup.get(sname, NAVY)
            add_box(
                slide, PHASE_X, y_top, PHASE_W, h,
                sname,
                fill=stage_fill,
                border=stage_fill,
                font_color=_readable_text_color(stage_fill),
                font_size=14,
                bold_first=True,
                line_pt=0.0,
            )
            i = j + 1

    # Spine boxes + arrows
    for k, b in enumerate(spine):
        y = spine_y[b["id"]]
        add_box(
            slide, spine_x_eff, y, SPINE_W, spine_h,
            b["text"],
            fill=WHITE, border=BLACK, font_color=BLACK,
            font_size=11, bold_first=True,
        )
        if k > 0:
            prev_y = spine_y[spine[k - 1]["id"]]
            add_arrow(
                slide,
                spine_x_eff + SPINE_W / 2, prev_y + spine_h,
                spine_x_eff + SPINE_W / 2, y,
            )

    # Exclusion boxes + connector arrows
    # Vertically center each exclusion on its spine row's mid-height so the
    # connector arrow can be strictly horizontal (no diagonal segments).
    for excl in cfg.get("exclusions", []):
        after_id = excl["after"]
        y_after = spine_y[after_id]
        y_mid = y_after + spine_h / 2
        y_excl_top = y_mid - excl_h / 2
        add_box(
            slide, excl_x_eff, y_excl_top, EXCL_W, excl_h,
            excl["text"],
            fill=WHITE, border=BLACK, font_color=BLACK,
            font_size=10, bold_first=False,
            align_center=False,  # left-align text in exclusions
            dash=True,           # dashed border to visually distinguish exclusion side-branches
        )
        # Strictly horizontal connector: both endpoints at y_mid
        add_arrow(
            slide,
            spine_x_eff + SPINE_W, y_mid,
            excl_x_eff,            y_mid,
        )

    out_path.parent.mkdir(parents=True, exist_ok=True)
    prs.save(out_path)


# ── CLI ─────────────────────────────────────────────────────────────────────
def main():
    p = argparse.ArgumentParser(description="Build an editable STROBE flow diagram .pptx from a YAML config.")
    p.add_argument("--config", required=True, type=Path, help="YAML/JSON STROBE config")
    p.add_argument("--out",    required=True, type=Path, help="Output .pptx path")
    p.add_argument("--strict-cascade", action="store_true",
                   help="refuse to build if the exclusion cascade does not close "
                        "(A - sum(exclusions after A) != next box)")
    args = p.parse_args()

    cfg = load_config(args.config)
    if not isinstance(cfg, dict):
        sys.exit(f"Config root must be a mapping; got {type(cfg)}")

    # The numbers a reviewer sees are in the figure, not the prose — assert the cascade closes
    # before rendering. Warn loudly by default; refuse under --strict-cascade.
    cascade = check_cascade(cfg)
    for f in cascade:
        sys.stderr.write(f"⚠️  {f['detail']}\n")
    if cascade and args.strict_cascade:
        sys.exit("STROBE cascade does not close; refusing to build (drop --strict-cascade "
                 "to build anyway).")

    build(cfg, args.out)
    print(f"Wrote {args.out}")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""critic_figure.py — Quantitative checks for make-figures skill output.

Part of the medsci-skills Critic Loop (Phase 1). This script runs deterministic
checks that do NOT require a language model:

  - DPI and physical dimensions vs. journal specification
  - Dominant-color analysis against the Wong colorblind-safe palette
  - OCR text extraction for minimum font-size estimation and
    optional coverage comparison against a source-text file

The qualitative side of the Critic Loop (layout balance, hierarchy,
readability, exemplar comparison) is handled by the Claude session afterward
using the rubrics in references/critic_rubrics/.

Usage:
    python critic_figure.py figures/fig1_stard.png \
        --type stard --spec-min-dpi 600 --spec-width-in 7.0 \
        --source-text figures/fig1_stard.txt \
        --out figures/fig1_stard.critique.json
"""
from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path
from typing import Optional

from PIL import Image

WONG_PALETTE: dict[str, tuple[int, int, int]] = {
    "black":          (0, 0, 0),
    "orange":         (230, 159, 0),
    "sky_blue":       (86, 180, 233),
    "bluish_green":   (0, 158, 115),
    "yellow":         (240, 228, 66),
    "blue":           (0, 114, 178),
    "vermillion":     (213, 94, 0),
    "reddish_purple": (204, 121, 167),
}
NEUTRAL_TOLERANCE = 25
PALETTE_DISTANCE_THRESHOLD = 60
DOMINANT_COLOR_TOP_N = 12
DOMINANT_COLOR_MIN_FRACTION = 0.002
OUT_OF_PALETTE_TOLERANCE = 0.15
MIN_READABLE_PX = 14


def color_distance(c1, c2) -> float:
    return sum((a - b) ** 2 for a, b in zip(c1, c2)) ** 0.5


def classify_color(rgb) -> str:
    r, g, b = rgb
    if max(r, g, b) - min(r, g, b) < NEUTRAL_TOLERANCE:
        return "neutral"
    best_name, best_dist = None, float("inf")
    for name, palette_rgb in WONG_PALETTE.items():
        d = color_distance(rgb, palette_rgb)
        if d < best_dist:
            best_name, best_dist = name, d
    if best_dist < PALETTE_DISTANCE_THRESHOLD:
        return f"wong:{best_name}"
    return "out_of_palette"


def check_palette(img: Image.Image) -> dict:
    rgb_img = img.convert("RGB")
    total = rgb_img.size[0] * rgb_img.size[1]
    quant = rgb_img.quantize(colors=64).convert("RGB")
    pixels = quant.getcolors(maxcolors=64 * 64)
    if not pixels:
        return {"passed": None, "note": "too many colors to quantize"}

    dominant = []
    out_frac = 0.0
    for count, rgb in sorted(pixels, key=lambda x: -x[0])[:DOMINANT_COLOR_TOP_N]:
        fraction = count / total
        if fraction < DOMINANT_COLOR_MIN_FRACTION:
            continue
        label = classify_color(rgb)
        dominant.append({"rgb": list(rgb), "fraction": round(fraction, 4), "class": label})
        if label == "out_of_palette":
            out_frac += fraction

    return {
        "passed": out_frac < OUT_OF_PALETTE_TOLERANCE,
        "out_of_palette_fraction": round(out_frac, 4),
        "tolerance": OUT_OF_PALETTE_TOLERANCE,
        "dominant_colors": dominant,
    }


def check_dimensions(img: Image.Image, spec: dict) -> dict:
    w_px, h_px = img.size
    dpi = img.info.get("dpi", (None, None))
    dpi_x = dpi[0] if dpi and dpi[0] else None
    dpi_y = dpi[1] if dpi and dpi[1] else None
    result = {
        "width_px": w_px,
        "height_px": h_px,
        "dpi_x": dpi_x,
        "dpi_y": dpi_y,
    }
    min_dpi = spec.get("min_dpi")
    width_in = spec.get("width_in")
    if min_dpi and dpi_x:
        result["dpi_meets_spec"] = dpi_x >= min_dpi
        result["required_dpi"] = min_dpi
    if width_in and dpi_x:
        actual_width_in = w_px / dpi_x
        result["width_in"] = round(actual_width_in, 2)
        result["width_matches_spec"] = abs(actual_width_in - width_in) < 0.3
        result["required_width_in"] = width_in
    return result


def check_ocr(image_path: Path, source_text: Optional[str] = None) -> dict:
    try:
        import pytesseract
    except ImportError:
        return {"passed": None, "note": "pytesseract not installed; install with `pip install pytesseract` (tesseract binary already at /opt/homebrew/bin/tesseract)"}
    try:
        data = pytesseract.image_to_data(
            str(image_path), output_type=pytesseract.Output.DICT
        )
    except Exception as exc:
        return {"passed": None, "note": f"tesseract failed: {exc}"}

    words = []
    heights = []
    for i, word in enumerate(data.get("text", [])):
        if not word.strip():
            continue
        conf_raw = data["conf"][i]
        try:
            conf = int(conf_raw)
        except (TypeError, ValueError):
            conf = -1
        if conf < 50:
            continue
        words.append(word.strip())
        heights.append(data["height"][i])

    result: dict = {
        "word_count": len(words),
    }
    if heights:
        heights_sorted = sorted(heights)
        result["median_word_height_px"] = heights_sorted[len(heights_sorted) // 2]
        result["min_word_height_px"] = min(heights)
        result["min_readable_threshold_px"] = MIN_READABLE_PX

    if source_text:
        source_words = {w.lower().strip(".,:;()[]") for w in source_text.split() if len(w) > 2}
        ocr_words = {w.lower().strip(".,:;()[]") for w in words if len(w) > 2}
        missing = sorted(source_words - ocr_words)
        result["missing_source_words"] = missing[:20]
        result["missing_source_word_count"] = len(missing)
        result["source_word_coverage"] = round(
            len(source_words & ocr_words) / max(1, len(source_words)), 2
        )
    return result


def critique(
    image_path: Path,
    figure_type: Optional[str] = None,
    journal: Optional[str] = None,
    source_text: Optional[str] = None,
    spec: Optional[dict] = None,
) -> dict:
    img = Image.open(image_path)
    spec = spec or {}
    checks = {
        "dimensions": check_dimensions(img, spec),
        "palette": check_palette(img),
        "ocr": check_ocr(image_path, source_text=source_text),
    }

    flags = []
    dim = checks["dimensions"]
    if dim.get("dpi_meets_spec") is False:
        flags.append(
            f"DPI below journal spec ({dim.get('dpi_x')} < {dim.get('required_dpi')})"
        )
    if dim.get("width_matches_spec") is False:
        flags.append(
            f"Width deviates from journal spec ({dim.get('width_in')} in vs {dim.get('required_width_in')} in)"
        )
    pal = checks["palette"]
    if pal.get("passed") is False:
        flags.append(
            f"{pal['out_of_palette_fraction'] * 100:.1f}% pixels outside Wong palette (tolerance {OUT_OF_PALETTE_TOLERANCE * 100:.0f}%)"
        )
    ocr = checks["ocr"]
    min_h = ocr.get("min_word_height_px")
    if min_h and min_h < MIN_READABLE_PX:
        flags.append(f"Smallest OCR text only {min_h}px tall (<{MIN_READABLE_PX}px threshold)")
    if ocr.get("missing_source_word_count") and ocr["missing_source_word_count"] > 3:
        flags.append(
            f"{ocr['missing_source_word_count']} source words not detected by OCR (possible cropping/truncation)"
        )

    return {
        "image": str(image_path),
        "figure_type": figure_type,
        "journal": journal,
        "checks": checks,
        "flags": flags,
        "summary": "PASS" if not flags else f"{len(flags)} issue(s) flagged",
    }


def main() -> int:
    p = argparse.ArgumentParser(description="Quantitative figure critic (medsci-skills Critic Loop, Phase 1).")
    p.add_argument("image", help="Path to generated figure (PNG)")
    p.add_argument(
        "--type", dest="figure_type",
        choices=[
            "stard", "consort", "prisma", "pipeline",
            "roc", "forest", "km", "calibration",
            "bland_altman", "confusion_matrix",
            "visual_abstract", "other",
        ],
    )
    p.add_argument("--journal", help="Journal key (e.g., radiology, radiology_ai, eur_radiol)")
    p.add_argument("--source-text", help="Path to text file with expected source strings for OCR coverage check")
    p.add_argument("--spec-width-in", type=float, help="Expected figure width in inches (per figure_specs.md)")
    p.add_argument("--spec-min-dpi", type=int, help="Minimum DPI (600 for line art, 300 for halftone)")
    p.add_argument("--out", default=None, help="Path to JSON report (default: {image}.critique.json)")
    args = p.parse_args()

    image_path = Path(args.image)
    if not image_path.exists():
        print(f"ERROR: {image_path} not found", file=sys.stderr)
        return 2

    source_text = None
    if args.source_text:
        source_path = Path(args.source_text)
        if not source_path.exists():
            print(f"WARN: source text {source_path} not found; skipping OCR coverage check", file=sys.stderr)
        else:
            source_text = source_path.read_text(encoding="utf-8", errors="ignore")

    report = critique(
        image_path,
        figure_type=args.figure_type,
        journal=args.journal,
        source_text=source_text,
        spec={"width_in": args.spec_width_in, "min_dpi": args.spec_min_dpi},
    )
    out_path = Path(args.out) if args.out else image_path.with_suffix(image_path.suffix + ".critique.json")
    out_path.write_text(json.dumps(report, indent=2, ensure_ascii=False))

    print(json.dumps({"summary": report["summary"], "flags": report["flags"]}, indent=2, ensure_ascii=False))
    print(f"\nFull report: {out_path}", file=sys.stderr)
    return 0 if not report["flags"] else 1


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Reconcile a flow-diagram figure caption against the flow-diagram SSOT.

A recurring submission error: the Figure 1 caption states participant counts
("n = 1,284 assessed ... n = 998 in the analytic cohort") that disagree with the
boxes of the flow diagram itself. It happens because the flow-diagram config (the
SSOT, e.g. `figure1_strobe_graphviz.yaml` consumed by generate_flow_diagram.R) is
updated for a final cohort lock while the hand-written caption is not. This script
re-derives the counts from the flow config and flags any `n = N` in the caption
that the diagram does not contain.

INPUTS
  --flow-config   the flow-diagram config file (YAML / R / text) whose box labels
                  carry the counts. Parsed as raw text (regex), so no YAML
                  dependency and it works for any flow-tool config.
  --manuscript    manuscript markdown (the Figure 1 caption is located by header)
                  OR --caption to pass the caption text directly.

OUTPUT  (--out path)
  {flow_counts, caption_counts, stale_in_caption, missing_in_caption, verdict}
  `stale_in_caption` (a caption count absent from the flow SSOT) is the Major
  finding. Exit 1 (with --strict) when any stale count exists.

Stdlib-only (re / json / argparse). Exit codes: 0 clean (or report-only),
1 caption count not in the flow SSOT (with --strict), 2 input/usage error.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

# "n = 1,284", "n=998", "N = 1284" — the standard flow-box / caption notation.
N_RE = re.compile(r"\bn\s*=\s*([0-9][0-9,]*)", re.I)

CAPTION_HDR_RE = re.compile(
    r"^#{0,4}\s*\**\s*(Figure\s*1|Fig\.?\s*1|Figure\s+1\.)\b", re.I | re.M
)


def _ints(text: str) -> list[int]:
    out = []
    for m in N_RE.finditer(text):
        try:
            out.append(int(m.group(1).replace(",", "")))
        except ValueError:
            pass
    return out


def extract_caption(manuscript_text: str) -> str:
    """Return the Figure 1 caption block (header line to the next blank line / header)."""
    m = CAPTION_HDR_RE.search(manuscript_text)
    if not m:
        return ""
    start = m.start()
    rest = manuscript_text[m.end():]
    # caption ends at the next blank line followed by a header, or a new "Figure N"
    end_rel = len(rest)
    nxt = re.search(r"\n\s*\n|^#{1,4}\s|\bFigure\s*[2-9]\b", rest, re.M)
    if nxt:
        end_rel = nxt.start()
    return manuscript_text[start:m.end() + end_rel]


def main() -> int:
    ap = argparse.ArgumentParser(description="Reconcile Figure 1 caption counts against the flow SSOT.")
    ap.add_argument("--flow-config", required=True, help="flow-diagram config (YAML/R/text)")
    ap.add_argument("--manuscript", help="manuscript markdown (Figure 1 caption auto-located)")
    ap.add_argument("--caption", help="caption text directly (alternative to --manuscript)")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if a caption count is not in the SSOT")
    args = ap.parse_args()

    fc = Path(args.flow_config)
    if not fc.is_file():
        sys.stderr.write(f"ERROR: flow config not found: {args.flow_config}\n")
        return 2
    flow_counts = sorted(set(_ints(fc.read_text(encoding="utf-8"))))

    if args.caption:
        caption = args.caption
    elif args.manuscript:
        mp = Path(args.manuscript)
        if not mp.is_file():
            sys.stderr.write(f"ERROR: manuscript not found: {args.manuscript}\n")
            return 2
        caption = extract_caption(mp.read_text(encoding="utf-8"))
        if not caption:
            sys.stderr.write("WARN: no 'Figure 1' caption located; pass --caption to override.\n")
    else:
        sys.stderr.write("ERROR: provide --manuscript or --caption\n")
        return 2

    caption_counts = sorted(set(_ints(caption)))
    flow_set = set(flow_counts)
    stale = [n for n in caption_counts if n not in flow_set]          # caption cites a number the diagram lacks
    missing = [n for n in flow_counts if n not in set(caption_counts)]  # diagram box not mentioned in caption

    result = {
        "flow_config": str(fc),
        "flow_counts": flow_counts,
        "caption_counts": caption_counts,
        "stale_in_caption": stale,
        "missing_in_caption": missing,
        "verdict": "MISMATCH" if stale else "OK",
        "suggested_fix": (
            "Re-derive the caption counts from the flow-diagram config and update the caption; "
            "the flow diagram is the single source of truth."
        ) if stale else None,
    }

    print("=" * 41)
    print(" Figure 1 caption ↔ flow SSOT reconciliation")
    print("=" * 41)
    print(f"flow counts (SSOT): {flow_counts}")
    print(f"caption counts:     {caption_counts}")
    if stale:
        print(f"\nMISMATCH: caption cites {stale} not present in the flow diagram.")
        print(result["suggested_fix"])
    else:
        print("\nOK: every caption count is present in the flow diagram.")
    if missing:
        print(f"(note: flow boxes not mentioned in the caption: {missing})")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "derive_figure_legend_counts", **result}, indent=2), encoding="utf-8")
        print(f"wrote {args.out}")

    return 1 if (args.strict and stale) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Export a figure to a portal-ready TIFF — LZW-compressed, RGBA→RGB white-flattened.

Why this exists. Two submission-portal facts collide on figure upload:

  1. Some portals accept only a fixed raster set and NOT PNG. Springer Nature's SNAPP,
     for one, takes `.jpeg` / `.tiff` / `.eps` — a PNG has to be converted on the spot.
  2. A portal caps figure size (JACC: Asia rejects a figure over 25 MB). A raw,
     uncompressed 600-dpi RGBA TIFF blows straight past that; the *same* image saved
     LZW-compressed with the alpha channel flattened away is a fraction of the size and
     pixel-identical.

The naive conversion also introduces a print defect: a TIFF that keeps an alpha channel
renders the transparent regions BLACK on many print/production pipelines. Flattening the
alpha onto a white background (the paper) is what a human does by hand in Photoshop; this
does it deterministically and then PROVES the result is pixel-identical to that flatten
before it hands you the file.

What it does:
  * opens the input raster (any PIL-readable format — PNG, TIFF, BMP, …);
  * if it carries alpha/transparency (RGBA / LA / palette-with-transparency), composites
    it onto a solid background (white by default) to get RGB; a plain RGB/L image is kept;
  * saves TIFF with LZW compression (lossless), preserving dpi;
  * VERIFIES the output by independently re-flattening the source and comparing bytes —
    refuses (exit 1) if the produced TIFF is not pixel-identical to the expected flatten;
  * reports the before/after byte size and, with --max-mb, refuses an output that still
    exceeds the portal cap (so the failure surfaces here, not at the upload button).

This is a figure PRODUCER (like render_core_figures.py), not a manuscript detector. It
requires Pillow — the same runtime dependency every raster figure helper in this skill
already has — and does nothing over the network.

Usage:
  export_portal_tiff.py --in figure.png                    # -> figure.tiff (white bg, LZW)
  export_portal_tiff.py --in fig.png --out fig.tiff --max-mb 25
  export_portal_tiff.py --in fig.png --background 255,255,255 --dpi 600

Exit codes: 0 success (verified), 1 verification mismatch / over the --max-mb cap,
2 input/usage error (missing file, unreadable image, Pillow absent).
"""

from __future__ import annotations

import argparse
import sys
from pathlib import Path

# A palette image can carry per-pixel transparency via a `transparency` info key.
ALPHA_MODES = ("RGBA", "LA", "PA", "La")


def _load_pillow():
    try:
        from PIL import Image  # noqa: F401
    except ImportError:
        sys.stderr.write(
            "ERROR: Pillow is required (pip install Pillow) — the same dependency the "
            "other raster figure helpers in /make-figures use.\n")
        sys.exit(2)
    from PIL import Image
    return Image


def _has_alpha(img) -> bool:
    """True if the image carries per-pixel transparency that a flatten must resolve."""
    if img.mode in ALPHA_MODES:
        return True
    # A palette (P) or grayscale image can still declare a transparent colour.
    return "transparency" in img.info


def flatten_to_rgb(img, background):
    """Return an RGB copy with any alpha composited onto `background` (an (R,G,B) tuple).
    A plain RGB/grayscale image (no transparency) is converted straight to RGB. This is the
    single definition of the flatten, used both to produce the output and to verify it."""
    if not _has_alpha(img):
        return img.convert("RGB")
    rgba = img.convert("RGBA")
    Image = _load_pillow()
    bg = Image.new("RGB", rgba.size, background)
    bg.paste(rgba, mask=rgba.split()[-1])  # last band is alpha
    return bg


def _parse_bg(s: str):
    parts = s.split(",")
    if len(parts) != 3:
        raise argparse.ArgumentTypeError("background must be R,G,B (e.g. 255,255,255)")
    try:
        vals = tuple(int(p) for p in parts)
    except ValueError:
        raise argparse.ArgumentTypeError("background components must be integers 0-255")
    if not all(0 <= v <= 255 for v in vals):
        raise argparse.ArgumentTypeError("background components must be 0-255")
    return vals


def export(in_path: Path, out_path: Path, background, dpi, max_mb):
    Image = _load_pillow()
    try:
        src = Image.open(in_path)
        src.load()
    except Exception as e:  # noqa: BLE001 — PIL raises a variety of decode errors
        sys.stderr.write(f"ERROR: could not open image {in_path}: {e}\n")
        sys.exit(2)

    expected = flatten_to_rgb(src, background)

    save_kwargs = {"format": "TIFF", "compression": "tiff_lzw"}
    src_dpi = dpi or src.info.get("dpi")
    if src_dpi:
        save_kwargs["dpi"] = tuple(src_dpi) if not isinstance(src_dpi, (int, float)) else (src_dpi, src_dpi)
    out_path.parent.mkdir(parents=True, exist_ok=True)
    expected.save(out_path, **save_kwargs)

    # Verify: reopen the produced TIFF and require it to be pixel-identical to the flatten,
    # LZW-compressed, and alpha-free. A silent decode surprise fails here, not at upload.
    with Image.open(out_path) as produced:
        produced.load()
        compression = produced.tag_v2.get(259) if hasattr(produced, "tag_v2") else None
        prod_rgb = produced.convert("RGB")
        identical = prod_rgb.tobytes() == expected.tobytes()

    problems = []
    if compression != 5:  # TIFF Compression tag: 5 == LZW
        problems.append(f"output is not LZW-compressed (Compression tag={compression}, expected 5)")
    if not identical:
        problems.append("output TIFF is NOT pixel-identical to the white-flattened source")

    in_mb = in_path.stat().st_size / (1024 * 1024)
    out_mb = out_path.stat().st_size / (1024 * 1024)
    if max_mb is not None and out_mb > max_mb:
        problems.append(f"output is {out_mb:.1f} MB, over the --max-mb {max_mb} portal cap")

    print("=" * 52)
    print(" Portal TIFF export")
    print("=" * 52)
    print(f"  in:          {in_path}  ({in_mb:.2f} MB, mode {src.mode})")
    print(f"  out:         {out_path}  ({out_mb:.2f} MB, mode RGB, LZW)")
    print(f"  flattened:   {'alpha composited onto ' + str(background) if _has_alpha(src) else 'no alpha (RGB kept)'}")
    print(f"  pixel-check: {'identical to source flatten' if identical else 'MISMATCH'}")
    if problems:
        print("\nFAIL: " + "; ".join(problems))
        return 1
    print("\nOK: portal-ready TIFF (LZW, RGB, pixel-identical to source).")
    return 0


def main() -> int:
    ap = argparse.ArgumentParser(
        description="Export a figure to a portal-ready TIFF (LZW, RGBA→RGB white-flatten).")
    ap.add_argument("--in", dest="inp", required=True, help="input raster image (PNG/TIFF/…)")
    ap.add_argument("--out", default=None, help="output .tiff (default: input stem + .tiff)")
    ap.add_argument("--background", type=_parse_bg, default=(255, 255, 255),
                    help="RGB fill for transparent regions (default 255,255,255 = white)")
    ap.add_argument("--dpi", type=int, default=None, help="override dpi (default: keep source dpi)")
    ap.add_argument("--max-mb", type=float, default=None,
                    help="refuse (exit 1) if the output still exceeds this many MB (e.g. 25 for a portal cap)")
    args = ap.parse_args()

    in_path = Path(args.inp)
    if not in_path.is_file():
        sys.stderr.write(f"ERROR: input not found: {in_path}\n")
        return 2
    out_path = Path(args.out) if args.out else in_path.with_suffix(".tiff")
    return export(in_path, out_path, args.background, args.dpi, args.max_mb)


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
r"""extract_exemplar_from_pdf.py — Extract a figure region from a PDF page to
build the exemplar reference set used by the make-figures Critic Loop.

Renders a single PDF page at 300 DPI (configurable), optionally crops a
sub-region, and writes the PNG + a YAML metadata sidecar + a _why.md stub
into references/exemplar_diagrams/{type}/.

Example:
    python extract_exemplar_from_pdf.py \
        --pdf ~/Zotero/storage/ABCD/Yan2017.pdf \
        --page 3 \
        --type stard \
        --label Yan2017_STARD \
        --doi 10.1148/radiol.2017170371 \
        --crop 0.05,0.1,0.95,0.6 \
        --dpi 300
"""
from __future__ import annotations

import argparse
import sys
from pathlib import Path
from typing import Optional

import fitz  # PyMuPDF

DEFAULT_EXEMPLAR_DIR = Path(__file__).resolve().parent.parent / "references" / "exemplar_diagrams"
VALID_TYPES = {"stard", "consort", "prisma", "pipeline", "roc", "forest", "km", "other"}


def render_page(pdf_path: Path, page_num: int, dpi: int, crop: Optional[tuple] = None) -> bytes:
    doc = fitz.open(pdf_path)
    try:
        if page_num < 1 or page_num > doc.page_count:
            raise ValueError(f"Page {page_num} out of range (1-{doc.page_count})")
        page = doc[page_num - 1]
        zoom = dpi / 72.0
        matrix = fitz.Matrix(zoom, zoom)
        if crop:
            rect = page.rect
            x0, y0, x1, y1 = crop
            clip = fitz.Rect(
                rect.x0 + rect.width * x0,
                rect.y0 + rect.height * y0,
                rect.x0 + rect.width * x1,
                rect.y0 + rect.height * y1,
            )
            pix = page.get_pixmap(matrix=matrix, clip=clip, alpha=False)
        else:
            pix = page.get_pixmap(matrix=matrix, alpha=False)
        return pix.tobytes("png")
    finally:
        doc.close()


def parse_crop(s: str) -> tuple:
    parts = [float(p.strip()) for p in s.split(",")]
    if len(parts) != 4:
        raise argparse.ArgumentTypeError("crop must be 'x0,y0,x1,y1' as fractions 0.0–1.0")
    for v in parts:
        if not 0.0 <= v <= 1.0:
            raise argparse.ArgumentTypeError(f"crop fraction {v} out of range 0.0–1.0")
    if parts[0] >= parts[2] or parts[1] >= parts[3]:
        raise argparse.ArgumentTypeError("crop x0<x1 and y0<y1 required")
    return tuple(parts)


def write_metadata(meta_path: Path, **fields) -> None:
    lines = ["# Exemplar metadata (YAML)"]
    for k, v in fields.items():
        if v is None:
            continue
        if isinstance(v, str):
            lines.append(f'{k}: "{v}"')
        elif isinstance(v, (list, tuple)):
            lines.append(f"{k}: {list(v)}")
        else:
            lines.append(f"{k}: {v}")
    meta_path.write_text("\n".join(lines) + "\n", encoding="utf-8")


def write_why_stub(why_path: Path, label: str, figure_type: str) -> None:
    if why_path.exists():
        return  # don't clobber existing notes
    why_path.write_text(
        f"""# Why this exemplar is good — {label} ({figure_type})

<!-- 50–100 words on why this figure is a quality anchor. Fill in during curation. -->

Hierarchy / structure:

Whitespace & balance:

Typography (font size, weight, alignment):

Emphasis (which elements are visually strongest, why):

Color usage:

Weaknesses (if any — nothing is perfect):
""",
        encoding="utf-8",
    )


def extract_one(
    pdf: Path,
    page: int,
    figure_type: str,
    label: str,
    doi: str,
    license_: str,
    crop: Optional[tuple],
    dpi: int,
    exemplar_dir: Path,
) -> Path:
    if figure_type not in VALID_TYPES:
        raise ValueError(f"type must be one of {sorted(VALID_TYPES)}, got {figure_type}")
    target_dir = exemplar_dir / figure_type
    target_dir.mkdir(parents=True, exist_ok=True)

    png_bytes = render_page(pdf, page, dpi, crop)
    safe_label = label.replace("/", "_").replace(" ", "_")
    png_path = target_dir / f"{safe_label}.png"
    meta_path = target_dir / f"{safe_label}.meta.yaml"
    why_path = target_dir / f"{safe_label}_why.md"

    png_path.write_bytes(png_bytes)
    write_metadata(
        meta_path,
        label=label,
        figure_type=figure_type,
        source_pdf=str(pdf),
        page=page,
        crop=list(crop) if crop else None,
        dpi=dpi,
        doi=doi,
        license=license_,
    )
    write_why_stub(why_path, label, figure_type)

    return png_path


def main() -> int:
    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    p.add_argument("--pdf", required=True, type=Path, help="Path to source PDF")
    p.add_argument("--page", required=True, type=int, help="1-based page number")
    p.add_argument("--type", dest="figure_type", required=True, choices=sorted(VALID_TYPES),
                   help="Exemplar category (subdirectory under exemplar_diagrams/)")
    p.add_argument("--label", required=True, help="Short label, used as filename stem (e.g., Yan2017_STARD)")
    # --doi used to be optional, and that is exactly how ten figures ended up in a public,
    # MIT-licensed package with no record of whose they were. A tool that CAN produce an
    # unattributable exemplar eventually will.
    p.add_argument("--doi", required=True, help="DOI of the source paper. Required — no exception.")
    p.add_argument(
        "--license", required=True, dest="license_",
        help="The licence of the FIGURE (not the paper): CC-BY-4.0, CC0, public-domain, own-work. "
             "If you do not know it, you do not have permission to ship it — keep the exemplar "
             "local and uncommitted instead.",
    )
    p.add_argument("--crop", default=None, type=parse_crop,
                   help="Optional crop as 'x0,y0,x1,y1' fractions 0.0–1.0")
    p.add_argument("--dpi", type=int, default=300, help="Render DPI (default: 300)")
    p.add_argument("--exemplar-dir", type=Path, default=DEFAULT_EXEMPLAR_DIR,
                   help="Base exemplar directory (default: references/exemplar_diagrams/)")
    args = p.parse_args()

    if not args.pdf.exists():
        print(f"ERROR: PDF not found at {args.pdf}", file=sys.stderr)
        return 2

    try:
        out = extract_one(
            pdf=args.pdf,
            page=args.page,
            figure_type=args.figure_type,
            label=args.label,
            doi=args.doi,
            license_=args.license_,
            crop=args.crop,
            dpi=args.dpi,
            exemplar_dir=args.exemplar_dir,
        )
    except Exception as exc:
        print(f"ERROR: {exc}", file=sys.stderr)
        return 1

    print(f"Extracted: {out}")
    print(f"Metadata:  {out.with_suffix('')}.meta.yaml")
    print(f"Why stub:  {out.with_name(out.stem + '_why.md')}")
    print("\nNext: open the _why.md and add a 50–100 word note on why this figure is a quality anchor.")
    return 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env bash
# Fetch official reporting guideline flow diagram / figure templates from
# the canonical statement sites (PRISMA, CONSORT, STARD, SPIRIT).
#
# Idempotent: skips downloads when target already exists with non-zero size.
# Network failures are non-fatal; the script reports per-target status at the end.
#
# Usage:
#   bash scripts/fetch_official_templates.sh                  # fetch all
#   bash scripts/fetch_official_templates.sh prisma2020       # one target
#   FORCE=1 bash scripts/fetch_official_templates.sh          # re-download
set -uo pipefail

SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
DEST_ROOT="${SKILL_DIR}/templates/official"
mkdir -p "${DEST_ROOT}"

UA='Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Claude-Code-medsci-skills/1.0'

# target_id|filename|url
# URLs verified 2026-04-27. PRISMA 2020 from prismastatement.org/s/.
# CONSORT/SPIRIT migrated to consort-spirit.org (formerly consort-statement.org +
# spirit-statement.org). STARD provides PDF only — checklist .docx fetched as
# the closest official Word artifact; flow diagram remains PDF.
TARGETS=(
  # PRISMA 2020 — both new-SR and updated-SR, both v1 (databases/registers only)
  # and v2 (incl. other sources). Official .docx, CC-BY 4.0.
  "prisma2020|PRISMA_2020_flow_new_SR_v1.docx|https://prismastatement.org/s/PRISMA_2020_flow_diagram_new_SRs_v1-lml8.docx"
  "prisma2020|PRISMA_2020_flow_new_SR_v2.docx|https://prismastatement.org/s/PRISMA_2020_flow_diagram_new_SRs_v2-t3jp.docx"
  "prisma2020|PRISMA_2020_flow_updated_SR_v1.docx|https://prismastatement.org/s/PRISMA_2020_flow_diagram_updated_SRs_v1-f8ly.docx"
  "prisma2020|PRISMA_2020_flow_updated_SR_v2.docx|https://prismastatement.org/s/PRISMA_2020_flow_diagram_updated_SRs_v2-dbrh.docx"

  # CONSORT 2025 (supersedes 2010) — main flow diagram + editable checklist
  "consort2010|CONSORT_2025_flow_diagram.docx|https://www.consort-spirit.org/_files/ugd/b5740e_019fabb52c9a4894abb681afcbff41f8.docx?dn=CONSORT_2025_flow_diagram.docx"
  "consort2010|CONSORT_2025_editable_checklist.docx|https://www.consort-spirit.org/_files/ugd/b628c8_6fa59b2c6db04efb9a9d0bc967a9fcf7.docx?dn=CONSORT%20%202025%20editable%20checklist.docx"

  # STARD 2015 — flow diagram is published as PDF only (no official Word source).
  # Ship the checklist .docx + the flow PDF as the canonical bundle.
  "stard2015|STARD_2015_flow_diagram.pdf|https://www.equator-network.org/wp-content/uploads/2015/03/STARD-2015-flow-diagram.pdf"
  "stard2015|STARD_2015_checklist.docx|https://www.equator-network.org/wp-content/uploads/2015/10/STARD-2015-Checklist.docx"

  # SPIRIT 2025 (supersedes 2013) — participant timeline + editable checklist
  "spirit2013|SPIRIT_2025_participant_timeline.docx|https://www.consort-spirit.org/_files/ugd/b5740e_5fad4e7a16bf44f6a2a0a809ad2a2e9d.docx?dn=SPIRIT%202025%20participant%20timeline.docx"
  "spirit2013|SPIRIT_2025_editable_checklist.docx|https://www.consort-spirit.org/_files/ugd/b5740e_667c45b02102408ab983c9704525597b.docx?dn=SPIRIT%202025%20editable%20checklist.docx"
)

WANT="${1:-all}"
FORCE="${FORCE:-0}"

declare -a ok_list fail_list skip_list

for entry in "${TARGETS[@]}"; do
  IFS='|' read -r tid fname url <<<"${entry}"
  if [[ "${WANT}" != "all" && "${WANT}" != "${tid}" ]]; then
    continue
  fi
  out="${DEST_ROOT}/${tid}/${fname}"
  if [[ "${FORCE}" != "1" && -s "${out}" ]]; then
    skip_list+=("${tid}/${fname}")
    continue
  fi
  echo "→ ${tid}/${fname}"
  if curl -fsSL --retry 2 --max-time 30 -A "${UA}" -o "${out}.tmp" "${url}"; then
    if [[ -s "${out}.tmp" ]]; then
      mv "${out}.tmp" "${out}"
      ok_list+=("${tid}/${fname}")
    else
      rm -f "${out}.tmp"
      fail_list+=("${tid}/${fname} (empty)")
    fi
  else
    rm -f "${out}.tmp"
    fail_list+=("${tid}/${fname} (HTTP)")
  fi
done

echo
echo "── fetch summary ─────────────────────────────"
printf 'OK   : %s\n' "${ok_list[@]:-(none)}"
printf 'SKIP : %s\n' "${skip_list[@]:-(none)}"
printf 'FAIL : %s\n' "${fail_list[@]:-(none)}"

if [[ ${#fail_list[@]} -gt 0 ]]; then
  echo
  echo "Some downloads failed. Statement sites occasionally rotate URLs;"
  echo "verify at: https://www.equator-network.org/reporting-guidelines/"
  exit 2
fi

#!/usr/bin/env python3
"""Populate count placeholders in a PRISMA 2020 .pptx template.

Reads a template built by ``build_prisma2020_template.py`` (or any .pptx whose
text frames contain ``{key}``-style tokens) and substitutes integer counts.

Two input modes
---------------
1. **Positional CSV** — ``--counts "315,122,186,7,111,204,102,84,3,15"``
   maps to a fixed sequence of keys appropriate for the most common DTA / IR
   meta-analysis workflow:

       n_db, n_dup, n_screened, n_screen_excluded,
       n_sought, n_assessed, n_excl_r1, n_excl_r2, n_excl_r3,
       n_studies

   This is a convenience for quick CLI use; remaining placeholders fall back
   to ``-`` so the figure remains visually balanced.

2. **JSON / YAML** — ``--counts-file counts.json`` provides a full mapping of
   every placeholder used in the template. Any keys not supplied render as
   ``-``.

Usage
-----
    python3 fill_prisma_template.py \
        --template templates/official/prisma2020/PRISMA_2020_flow_new_v1.pptx \
        --counts "315,122,186,7,111,204,102,84,3,15" \
        --out fig1_prisma_filled.pptx

    python3 fill_prisma_template.py \
        --template templates/official/prisma2020/PRISMA_2020_flow_new_v2.pptx \
        --counts-file my_counts.json \
        --out fig1_prisma_filled.pptx
"""
from __future__ import annotations

import argparse
import json
import re
from pathlib import Path

from pptx import Presentation

POSITIONAL_KEYS = [
    "n_db",
    "n_dup",
    "n_screened",
    "n_screen_excluded",
    "n_sought",
    "n_assessed",
    "n_excl_r1",
    "n_excl_r2",
    "n_excl_r3",
    "n_studies",
]

ALL_KNOWN_KEYS = {
    "n_db", "n_reg", "n_dup", "n_auto", "n_other_removed",
    "n_web", "n_org", "n_cite",
    "n_screened", "n_screen_excluded",
    "n_sought", "n_not_retrieved",
    "n_assessed", "n_excl_r1", "n_excl_r2", "n_excl_r3",
    "n_studies", "n_reports",
}

TOKEN_RE = re.compile(r"\{([a-zA-Z_][a-zA-Z0-9_]*)\}")


def parse_counts(args) -> dict[str, str]:
    counts: dict[str, str] = {}
    if args.counts_file:
        data = json.loads(Path(args.counts_file).read_text())
        if not isinstance(data, dict):
            raise SystemExit("--counts-file must contain a JSON object mapping key→count")
        counts.update({k: str(v) for k, v in data.items()})
    if args.counts:
        values = [v.strip() for v in args.counts.split(",")]
        if len(values) != len(POSITIONAL_KEYS):
            raise SystemExit(
                f"--counts expects {len(POSITIONAL_KEYS)} comma-separated values "
                f"(got {len(values)}). Order: {', '.join(POSITIONAL_KEYS)}"
            )
        for k, v in zip(POSITIONAL_KEYS, values):
            counts.setdefault(k, v)
    return counts


def substitute(prs, counts: dict[str, str]) -> tuple[set[str], set[str]]:
    """Replace ``{key}`` tokens in every text run. Returns (filled, unfilled)."""
    filled: set[str] = set()
    unfilled: set[str] = set()
    for slide in prs.slides:
        for shape in slide.shapes:
            if not shape.has_text_frame:
                continue
            for para in shape.text_frame.paragraphs:
                for run in para.runs:
                    tokens = TOKEN_RE.findall(run.text)
                    if not tokens:
                        continue
                    new_text = run.text
                    for tok in tokens:
                        if tok in counts:
                            new_text = new_text.replace("{" + tok + "}", counts[tok])
                            filled.add(tok)
                        else:
                            new_text = new_text.replace("{" + tok + "}", "-")
                            unfilled.add(tok)
                    run.text = new_text
    return filled, unfilled


def main():
    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    ap.add_argument("--template", type=Path, required=True)
    ap.add_argument("--counts", help="Comma-separated positional counts (10 values).")
    ap.add_argument("--counts-file", type=Path, help="JSON file mapping key→count.")
    ap.add_argument("--out", type=Path, required=True)
    args = ap.parse_args()

    if not args.counts and not args.counts_file:
        ap.error("supply --counts or --counts-file (or both)")

    counts = parse_counts(args)
    unknown = set(counts) - ALL_KNOWN_KEYS
    if unknown:
        print(f"⚠ unknown keys (will still substitute if matched): {sorted(unknown)}")

    prs = Presentation(args.template)
    filled, unfilled = substitute(prs, counts)
    args.out.parent.mkdir(parents=True, exist_ok=True)
    prs.save(args.out)

    print(f"✓ wrote {args.out}")
    print(f"  filled  : {sorted(filled)}")
    if unfilled:
        print(f"  blanks  : {sorted(unfilled)}  (rendered as '-')")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
AI Image Generation via Gemini API (optional supplementary tool).
Visual abstracts and figures can be created without this tool.

Usage:
    python generate_image.py "prompt text" --output path/to/output.png
    python generate_image.py "prompt text" --output path/to/output.png --aspect 16:9
    python generate_image.py "CT-guided lung biopsy procedure" -o biopsy.png --style medical

Environment variable required:
    GEMINI_API_KEY
"""

import argparse
import base64
import os
import sys
from pathlib import Path

MEDICAL_STYLE_PREFIX = (
    "Create a clean medical illustration in the style of Servier Medical Art. "
    "Use flat vector-style graphics with clear outlines. No text in the image. "
    "White or transparent background. Anatomically accurate but simplified. "
    "Suitable for use in a peer-reviewed journal graphical abstract. "
)


def generate_image(prompt: str, output_path: str, aspect_ratio: str = "1:1",
                   style: str | None = None) -> str:
    import google.generativeai as genai

    genai.configure(api_key=os.environ["GEMINI_API_KEY"])

    model = genai.GenerativeModel("gemini-2.0-flash-preview-image-generation")

    # Prepend medical style prefix if requested
    full_prompt = prompt
    if style == "medical":
        full_prompt = MEDICAL_STYLE_PREFIX + prompt

    # Include aspect ratio instruction in the prompt
    if aspect_ratio != "1:1":
        full_prompt += f" Output aspect ratio: {aspect_ratio}."

    response = model.generate_content(
        full_prompt,
        generation_config=genai.types.GenerationConfig(
            response_mime_type="image/png",
        ),
    )

    # Extract image data from response
    if response.candidates and response.candidates[0].content.parts:
        for part in response.candidates[0].content.parts:
            if hasattr(part, "inline_data") and part.inline_data:
                image_data = part.inline_data.data
                Path(output_path).write_bytes(image_data)
                print(f"Image saved: {output_path}", file=sys.stderr)
                print(output_path)
                return output_path

    # Fallback: check if response has image in different format
    print("Error: No image data in response.", file=sys.stderr)
    if response.text:
        print(f"Response text: {response.text[:200]}", file=sys.stderr)
    sys.exit(1)


def main():
    parser = argparse.ArgumentParser(description="Generate images via Gemini API")
    parser.add_argument("prompt", help="Image generation prompt")
    parser.add_argument("--output", "-o", required=True, help="Output file path (.png)")
    parser.add_argument(
        "--aspect",
        default="1:1",
        choices=["1:1", "16:9", "9:16", "4:3", "3:4"],
        help="Aspect ratio (default: 1:1)",
    )
    parser.add_argument(
        "--style",
        choices=["medical"],
        help="Prepend a style prefix to the prompt (medical: flat vector medical illustration)",
    )
    args = parser.parse_args()

    if not os.environ.get("GEMINI_API_KEY"):
        print("Error: GEMINI_API_KEY not set", file=sys.stderr)
        print("This tool is optional — visual abstracts can be created without it.", file=sys.stderr)
        sys.exit(1)

    output_path = Path(args.output).resolve()
    output_path.parent.mkdir(parents=True, exist_ok=True)

    generate_image(args.prompt, str(output_path), args.aspect, args.style)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Visual Abstract Generator for Medical Research Papers.
Fills journal-specific PPTX templates with study content using python-pptx.

Usage:
    python generate_visual_abstract.py \
      --template european_radiology.pptx \
      --title "Effect of smoking on biopsy outcomes" \
      --hypothesis "What is the association of smoking with PTNB outcomes?" \
      --methods "Retrospective cohort|N=1200 patients|Logistic regression" \
      --finding "Smoking was associated with higher complication rates" \
      --citation "Journal Name (2026) FirstAuthor Last et al; DOI: 10.xxxx/..." \
      --visual figures/fig1_roc_curve.png \
      --badges "N=1200|CT chest|Single-center" \
      --output visual_abstract.pptx

    # With PNG conversion (requires LibreOffice):
    python generate_visual_abstract.py ... --output visual_abstract.pptx --png

Templates are stored in:
    ${CLAUDE_SKILL_DIR}/references/visual_abstract_templates/

If --template is a bare name (no path), the script looks for it in the templates directory.
If not found, falls back to medsci_default.pptx.
"""

import argparse
import os
import re
import subprocess
import sys
from pathlib import Path


# --- Shape matching patterns ---
# Each field maps to a list of substrings to search in shape.text (case-insensitive).
FIELD_PATTERNS = {
    "title": ["articletitle"],
    "hypothesis": ["hypothesis", "question"],
    "methods": ["methodology", "flowchart", "bullet point"],
    "visual": ["visual element", "image/illustration", "illustration/graph", "visualelement"],
    "finding": ["main finding", "relevance statement", "main result"],
    "citation": ["authors names", "doi", "eur radiol (year)", "journal (year)", "articlecitation"],
    "badge_patient": ["patient cohort", "patient"],
    "badge_modality": ["modality", "organ"],
    "badge_center": ["single", "multi-center", "center"],
    "footer": ["footernote"],
}


# --- Central Illustration validation rules (Fuster-Mann 2019, JACC 74:2816) ---
# See references/jacc_central_illustration_principles.md for full rationale.
CI_FORBIDDEN_METHODS_TERMS = (
    "cohort flow",
    "inclusion criteria",
    "exclusion criteria",
    "study design",
    "enrollment",
    "randomized",
    "sample size",
    "consort",
    "prisma",
    "stard",
)


def validate_central_illustration(zones: int, label_words: int,
                                  numerical_points: int, raw_text: str,
                                  allow_overrides: list[str] | None = None) -> tuple[bool, list[str]]:
    """Apply CI mode validation rules. Returns (passes, reasons)."""
    allow = set(allow_overrides or [])
    failures: list[str] = []

    if "zones" not in allow and zones > 3:
        failures.append(
            f"more than 3 visual zones (got {zones}); Fuster-Mann: 'simplicity is superior'"
        )
    if "words" not in allow and label_words > 30:
        failures.append(
            f"label word count {label_words} > 30; Fuster-Mann: 'avoid using too much text'"
        )
    if "numerical" not in allow and numerical_points > 4:
        failures.append(
            f"{numerical_points} numerical highlights > 4; Fuster-Mann: 'avoid secondary messages'"
        )
    if "methods" not in allow:
        lower = (raw_text or "").lower()
        offenders = [t for t in CI_FORBIDDEN_METHODS_TERMS if t in lower]
        if offenders:
            failures.append(
                f"methodology terms detected ({', '.join(offenders)}); CI is not a Visual Abstract"
            )
    return (len(failures) == 0, failures)


def match_field(shape_text: str) -> str | None:
    """Return the field name that matches the shape's text, or None."""
    text_lower = shape_text.lower().strip()
    if not text_lower:
        return None
    for field, patterns in FIELD_PATTERNS.items():
        for pattern in patterns:
            if pattern in text_lower:
                return field
    return None


def replace_shape_text(shape, new_text: str, preserve_formatting: bool = True):
    """Replace all text in a shape while preserving font formatting."""
    tf = shape.text_frame
    if not tf.paragraphs:
        return

    if preserve_formatting and tf.paragraphs[0].runs:
        # Preserve the first run's formatting
        first_run = tf.paragraphs[0].runs[0]
        font_name = first_run.font.name
        font_size = first_run.font.size
        font_bold = first_run.font.bold
        try:
            font_color = first_run.font.color.rgb
        except (AttributeError, TypeError):
            font_color = None

        # Handle multi-line text (split by \n)
        lines = new_text.split("\n")
        # Clear all existing paragraphs except first
        for i in range(len(tf.paragraphs) - 1, 0, -1):
            p = tf.paragraphs[i]._p
            p.getparent().remove(p)

        # Set first paragraph
        para = tf.paragraphs[0]
        para.clear()
        run = para.add_run()
        run.text = lines[0]
        if font_name:
            run.font.name = font_name
        if font_size:
            run.font.size = font_size
        if font_bold is not None:
            run.font.bold = font_bold
        if font_color:
            run.font.color.rgb = font_color

        # Add remaining lines as new paragraphs
        for line in lines[1:]:
            from pptx.oxml.ns import qn
            from copy import deepcopy
            new_p = deepcopy(para._p)
            new_p.clear()
            # Re-add run with text
            from lxml import etree
            r_elem = deepcopy(para._p.findall(qn("a:r"))[0]) if para._p.findall(qn("a:r")) else None
            if r_elem is not None:
                for t in r_elem.findall(qn("a:t")):
                    t.text = line
                new_p.append(r_elem)
            tf._txBody.append(new_p)
    else:
        # Simple replacement without formatting preservation
        tf.paragraphs[0].text = new_text


def insert_image_into_shape(slide, shape, image_path: str):
    """Replace a shape with an image, maintaining the shape's position and size."""
    from pptx.util import Emu
    from PIL import Image

    # Get shape bounds
    left = shape.left
    top = shape.top
    box_w = shape.width
    box_h = shape.height

    # Calculate image dimensions maintaining aspect ratio
    with Image.open(image_path) as img:
        img_w, img_h = img.size
        aspect = img_w / img_h
        box_aspect = box_w / box_h

        if aspect > box_aspect:
            # Image is wider than box — fit to width
            new_w = box_w
            new_h = int(box_w / aspect)
            new_left = left
            new_top = top + (box_h - new_h) // 2  # center vertically
        else:
            # Image is taller — fit to height
            new_h = box_h
            new_w = int(box_h * aspect)
            new_left = left + (box_w - new_w) // 2  # center horizontally
            new_top = top

    # Clear shape text
    if hasattr(shape, "text_frame"):
        for para in shape.text_frame.paragraphs:
            para.clear()

    # Add image on top of shape
    slide.shapes.add_picture(image_path, new_left, new_top, new_w, new_h)


def fill_template(template_path: str, content: dict, output_path: str,
                  visual_path: str | None = None, slide_index: int = 0):
    """Fill a PPTX template with content and save."""
    from pptx import Presentation

    prs = Presentation(template_path)

    if slide_index >= len(prs.slides):
        print(f"Error: Slide index {slide_index} not found in template "
              f"(template has {len(prs.slides)} slides)", file=sys.stderr)
        sys.exit(1)

    slide = prs.slides[slide_index]
    matched_fields = set()

    for shape in slide.shapes:
        if not hasattr(shape, "text"):
            continue

        field = match_field(shape.text)
        if field is None:
            continue

        if field == "visual" and visual_path and Path(visual_path).exists():
            insert_image_into_shape(slide, shape, visual_path)
            matched_fields.add(field)
        elif field in content and content[field]:
            replace_shape_text(shape, content[field])
            matched_fields.add(field)

    # Report matching results
    all_fields = set(content.keys())
    if visual_path:
        all_fields.add("visual")
    unmatched = all_fields - matched_fields
    if unmatched:
        print(f"Warning: No matching shape found for: {', '.join(unmatched)}",
              file=sys.stderr)

    # Remove unused slides (keep only the target slide)
    # python-pptx slide deletion requires direct XML manipulation
    sldIdLst = prs.slides._sldIdLst
    indices_to_remove = sorted(
        [i for i in range(len(sldIdLst)) if i != slide_index],
        reverse=True  # remove from end to preserve indices
    )
    for i in indices_to_remove:
        sldId = sldIdLst[i]
        rId = sldId.rId
        sldIdLst.remove(sldId)
        try:
            prs.part.drop_rel(rId)
        except KeyError:
            pass  # relationship already cleaned up

    prs.save(output_path)
    print(f"Visual abstract saved: {output_path}", file=sys.stderr)
    print(output_path)


def convert_to_png(pptx_path: str, dpi: int = 300) -> str | None:
    """Convert PPTX to PNG using LibreOffice CLI. Returns PNG path or None."""
    output_dir = str(Path(pptx_path).parent)
    try:
        subprocess.run(
            ["soffice", "--headless", "--convert-to", "png", pptx_path,
             "--outdir", output_dir],
            check=True, capture_output=True, timeout=30
        )
        png_path = str(Path(pptx_path).with_suffix(".png"))
        if Path(png_path).exists():
            print(f"PNG exported: {png_path}", file=sys.stderr)
            return png_path
    except FileNotFoundError:
        print("Warning: LibreOffice not found. PPTX saved but PNG conversion skipped.",
              file=sys.stderr)
        print("Install with: brew install --cask libreoffice", file=sys.stderr)
    except subprocess.TimeoutExpired:
        print("Warning: LibreOffice conversion timed out.", file=sys.stderr)
    except subprocess.CalledProcessError as e:
        print(f"Warning: LibreOffice conversion failed: {e.stderr.decode()[:200]}",
              file=sys.stderr)
    return None


def resolve_template(template_arg: str) -> str:
    """Resolve template name to full path."""
    # If it's already a full path, use it
    if os.path.isabs(template_arg) and Path(template_arg).exists():
        return template_arg

    # Look in the skill's template directory
    skill_dir = os.environ.get("CLAUDE_SKILL_DIR", "")
    if skill_dir:
        templates_dir = Path(skill_dir) / "references" / "visual_abstract_templates"
    else:
        templates_dir = Path(__file__).parent.parent / "references" / "visual_abstract_templates"

    # Try exact match
    candidate = templates_dir / template_arg
    if candidate.exists():
        return str(candidate)

    # Try with .pptx extension
    candidate = templates_dir / f"{template_arg}.pptx"
    if candidate.exists():
        return str(candidate)

    # Fallback to medsci_default
    default = templates_dir / "medsci_default.pptx"
    if default.exists():
        print(f"Template '{template_arg}' not found, using medsci_default.pptx",
              file=sys.stderr)
        return str(default)

    print(f"Error: No template found. Searched in: {templates_dir}", file=sys.stderr)
    sys.exit(1)


def parse_methods(methods_str: str) -> str:
    """Convert pipe-separated methods to bullet-point format."""
    items = [m.strip() for m in methods_str.split("|") if m.strip()]
    if len(items) <= 1:
        return methods_str
    return "\n".join(f"• {item}" for item in items)


def main():
    parser = argparse.ArgumentParser(
        description="Generate visual abstract from PPTX template"
    )
    parser.add_argument("--type", choices=["visual-abstract", "central-illustration"],
                        default="visual-abstract",
                        help="Artifact type: 'visual-abstract' (methods+results) or "
                             "'central-illustration' (single key finding, JACC house style)")
    parser.add_argument("--template", "-t", default=None,
                        help="Template name or path. Default depends on --type: "
                             "visual-abstract→medsci_default, central-illustration→jacc_central_illustration")
    parser.add_argument("--title", help="Article title (required for VA mode)")
    parser.add_argument("--hypothesis", help="Research question or hypothesis (VA mode)")
    parser.add_argument("--methods", help="Methodology (pipe-separated for bullets, VA mode)")
    parser.add_argument("--finding", help="Main finding (<20 words, VA mode)")
    parser.add_argument("--citation", help="Citation line (journal, year, authors, DOI)")
    parser.add_argument("--visual", help="Path to visual element image (PNG/JPG)")
    parser.add_argument("--badges", help="Three pipe-separated badge texts: cohort|modality|center (VA mode)")
    parser.add_argument("--output", "-o", required=True, help="Output PPTX path")
    parser.add_argument("--png", action="store_true",
                        help="Also convert to PNG (requires LibreOffice)")
    parser.add_argument("--slide-index", type=int, default=0,
                        help="Template slide index to use (default: 0)")
    parser.add_argument("--ci-zones", type=int, default=None,
                        help="CI mode: declared visual zone count (for validation)")
    parser.add_argument("--ci-label-words", type=int, default=None,
                        help="CI mode: total label word count (for validation)")
    parser.add_argument("--ci-numerical-points", type=int, default=None,
                        help="CI mode: count of numerical highlights (for validation)")
    parser.add_argument("--ci-raw-text", default="",
                        help="CI mode: raw text content for forbidden-methods-term scan")
    parser.add_argument("--ci-allow", action="append", default=[],
                        choices=["zones", "words", "numerical", "methods"],
                        help="CI mode: override a single rule (repeatable)")
    args = parser.parse_args()

    # Default template per type
    if args.template is None:
        args.template = ("jacc_central_illustration"
                         if args.type == "central-illustration" else "medsci_default")

    # CI mode: run validation BEFORE generating the PPTX
    if args.type == "central-illustration":
        zones = args.ci_zones if args.ci_zones is not None else 1
        words = args.ci_label_words if args.ci_label_words is not None else 0
        nums = args.ci_numerical_points if args.ci_numerical_points is not None else 0
        passes, reasons = validate_central_illustration(
            zones=zones, label_words=words, numerical_points=nums,
            raw_text=args.ci_raw_text, allow_overrides=args.ci_allow,
        )
        if not passes:
            print("Central Illustration validation FAILED:", file=sys.stderr)
            for r in reasons:
                print(f"  - {r}", file=sys.stderr)
            print("\nSee references/jacc_central_illustration_principles.md for guidance.",
                  file=sys.stderr)
            print("Override with --ci-allow {zones|words|numerical|methods} (use sparingly).",
                  file=sys.stderr)
            sys.exit(2)
        # CI mode does not require --title (only --visual + --citation)
        if not args.visual:
            print("CI mode requires --visual (the author content figure).", file=sys.stderr)
            sys.exit(2)
        # Synthesize a placeholder title so downstream code does not fail
        if not args.title:
            args.title = "(central illustration — title carried by manuscript)"

    # Resolve template
    template_path = resolve_template(args.template)

    # Build content dict
    content = {
        "title": args.title,
        "hypothesis": args.hypothesis or "",
        "methods": parse_methods(args.methods) if args.methods else "",
        "finding": args.finding or "",
        "citation": args.citation or "",
    }

    # Parse badges
    if args.badges:
        badges = [b.strip() for b in args.badges.split("|")]
        content["badge_patient"] = badges[0] if len(badges) > 0 else ""
        content["badge_modality"] = badges[1] if len(badges) > 1 else ""
        content["badge_center"] = badges[2] if len(badges) > 2 else ""

    # Validate visual path
    visual_path = None
    if args.visual:
        if not Path(args.visual).exists():
            print(f"Warning: Visual file not found: {args.visual}", file=sys.stderr)
        else:
            visual_path = str(Path(args.visual).resolve())

    # Ensure output directory exists
    Path(args.output).parent.mkdir(parents=True, exist_ok=True)

    # Fill template
    fill_template(template_path, content, args.output, visual_path, args.slide_index)

    # Optional PNG conversion
    if args.png:
        convert_to_png(args.output)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Render the four highest-yield clinical figures as tested, deterministic generators.

This is the *render* layer for the canonical figure anatomies described in prose under
``references/exemplar_plots/`` (km_curve / roc_pr / calibration_plot / decision_curve).
It turns those anatomy models into RUNNABLE code so a regression in a publication figure
is caught by a test, not by a reviewer — the gap that left make-figures with no
deterministic render check for any data plot.

Separation of concerns (do not duplicate the analysis SoT):
  - ``/analyze-stats`` *computes* the estimates (KM via lifelines, AUC, calibration
    slope/intercept, net benefit). Those numbers are the single source of truth.
  - this module *renders* already-computed inputs into the canonical anatomy, and
    asserts the load-bearing elements are present. It never recomputes a statistic and
    never invents a number.

Each renderer returns a matplotlib ``Figure`` so a verifier can introspect the actual
artists (lines, texts, collections) rather than pixel-diffing a PNG. ``assert_structure``
encodes the load-bearing-element invariants for each figure type.

Matplotlib (Agg, headless) + numpy only — no seaborn, no network, no RNG at import.
CLI:  render_core_figures.py --inputs fixture/synthetic_inputs.json --out-dir OUT
      (renders all four PNGs, runs every structural assertion; exit 1 on any failure).
"""
from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path

import matplotlib
matplotlib.use("Agg")  # headless, deterministic
import matplotlib.pyplot as plt  # noqa: E402
import numpy as np  # noqa: E402
from matplotlib.patches import Polygon  # noqa: E402


# --------------------------------------------------------------------------- KM
def km_curve(groups: list[dict], max_follow_up: float, *, title: str = "") -> plt.Figure:
    """Kaplan–Meier step curve(s) with a number-at-risk table and censor marks.

    groups: [{name, time:[...], surv:[0..1], censor_times:[...],
              at_risk:{time:[...], n:[...]}}]  — already-computed step coordinates.
    The x-axis is clipped to ``max_follow_up`` so the curve is never extrapolated past
    observed follow-up (a recurrent KM error the exemplar anatomy warns against).
    """
    fig, (ax, ax_risk) = plt.subplots(
        2, 1, figsize=(6.4, 5.2), gridspec_kw={"height_ratios": [4, 1]}
    )
    for g in groups:
        t = np.asarray(g["time"], float)
        s = np.asarray(g["surv"], float)
        line, = ax.step(t, s, where="post", label=g["name"])
        # censor tick marks on the step curve
        for ct in g.get("censor_times", []):
            idx = np.searchsorted(t, ct, side="right") - 1
            idx = max(0, min(idx, len(s) - 1))
            ax.plot([ct], [s[idx]], marker="|", markersize=8, color=line.get_color())
    ax.set_xlim(0, max_follow_up)          # no extrapolation past follow-up
    ax.set_ylim(0, 1.02)
    ax.set_ylabel("Survival probability")
    ax.set_title(title or "Kaplan–Meier survival")
    ax.legend(loc="lower left", frameon=False)

    # number-at-risk table on the lower axes
    ax_risk.axis("off")
    ax_risk.set_xlim(0, max_follow_up)
    ax_risk.text(0, len(groups) + 0.5, "No. at risk", fontsize=9, fontweight="bold",
                 transform=ax_risk.get_yaxis_transform())
    for row, g in enumerate(groups):
        risk = g["at_risk"]
        y = len(groups) - row - 0.5
        for tt, nn in zip(risk["time"], risk["n"]):
            ax_risk.text(tt, y, str(int(nn)), ha="center", va="center", fontsize=8)
        ax_risk.text(0, y, g["name"], ha="right", va="center", fontsize=8,
                     transform=ax_risk.get_yaxis_transform())
    ax_risk.set_xlabel("Time (months)")
    fig.tight_layout()
    fig._mf_kind = "km"  # tag for assert_structure
    fig._mf_max_follow_up = max_follow_up
    return fig


# -------------------------------------------------------------------------- ROC
def roc_curve(fpr, tpr, auc: float, *, operating_point: dict | None = None,
              title: str = "") -> plt.Figure:
    """ROC curve with the chance diagonal, an AUC annotation, and an operating point."""
    fpr = np.asarray(fpr, float)
    tpr = np.asarray(tpr, float)
    fig, ax = plt.subplots(figsize=(5.2, 5.0))
    ax.plot(fpr, tpr, label=f"Model (AUC = {auc:.3f})")
    ax.plot([0, 1], [0, 1], linestyle="--", color="0.5", label="Chance")  # diagonal
    if operating_point:
        ax.scatter([operating_point["fpr"]], [operating_point["tpr"]],
                   color="crimson", zorder=5, s=40,
                   label=operating_point.get("label", "Operating point"))
    ax.set_xlim(0, 1)
    ax.set_ylim(0, 1.02)
    ax.set_xlabel("1 − specificity (false-positive rate)")
    ax.set_ylabel("Sensitivity (true-positive rate)")
    ax.set_title(title or "Receiver operating characteristic")
    ax.text(0.55, 0.10, f"AUC = {auc:.3f}", fontsize=11,
            bbox=dict(boxstyle="round", fc="white", ec="0.7"))
    ax.legend(loc="lower right", frameon=False)
    fig.tight_layout()
    fig._mf_kind = "roc"
    return fig


# ------------------------------------------------------------------ calibration
def calibration_plot(pred_mean, obs_freq, *, slope: float, intercept: float,
                     ci_low=None, ci_high=None, title: str = "") -> plt.Figure:
    """Calibration plot: binned observed-vs-predicted, the y=x identity line, and the
    fitted calibration slope/intercept annotation (the load-bearing calibration metrics)."""
    pred_mean = np.asarray(pred_mean, float)
    obs_freq = np.asarray(obs_freq, float)
    fig, ax = plt.subplots(figsize=(5.2, 5.2))
    ax.plot([0, 1], [0, 1], linestyle="--", color="0.5", label="Ideal (y = x)")  # identity
    if ci_low is not None and ci_high is not None:
        yerr = np.vstack([obs_freq - np.asarray(ci_low, float),
                          np.asarray(ci_high, float) - obs_freq])
        ax.errorbar(pred_mean, obs_freq, yerr=yerr, fmt="o", capsize=3, label="Observed")
    else:
        ax.plot(pred_mean, obs_freq, marker="o", label="Observed")
    # fitted calibration line
    xs = np.linspace(0, 1, 50)
    ax.plot(xs, intercept + slope * xs, color="crimson", label="Calibration fit")
    ax.set_xlim(0, 1)
    ax.set_ylim(0, 1)
    ax.set_xlabel("Predicted probability")
    ax.set_ylabel("Observed frequency")
    ax.set_title(title or "Calibration")
    ax.text(0.05, 0.88, f"slope = {slope:.2f}\nintercept = {intercept:.2f}", fontsize=10,
            bbox=dict(boxstyle="round", fc="white", ec="0.7"))
    ax.legend(loc="lower right", frameon=False)
    fig.tight_layout()
    fig._mf_kind = "calibration"
    return fig


# --------------------------------------------------------------- decision curve
def decision_curve(thresholds, net_benefit_model, prevalence: float, *,
                   model_label: str = "Model", title: str = "") -> plt.Figure:
    """Decision-curve (net-benefit) plot with the treat-all and treat-none reference
    strategies — the two references without which a DCA is uninterpretable."""
    pt = np.asarray(thresholds, float)
    nb_model = np.asarray(net_benefit_model, float)
    # treat-all net benefit = prev - (1-prev) * pt/(1-pt); treat-none = 0
    with np.errstate(divide="ignore", invalid="ignore"):
        nb_all = prevalence - (1 - prevalence) * pt / (1 - pt)
    fig, ax = plt.subplots(figsize=(6.0, 4.8))
    ax.plot(pt, nb_model, label=model_label, color="crimson")
    ax.plot(pt, nb_all, label="Treat all", color="0.4", linestyle="-.")
    ax.plot(pt, np.zeros_like(pt), label="Treat none", color="0.0", linestyle=":")
    ax.set_xlim(pt.min(), pt.max())
    lo = float(min(0.0, np.nanmin(nb_model)))
    ax.set_ylim(lo - 0.02, float(np.nanmax(nb_model)) + 0.05)
    ax.set_xlabel("Threshold probability")
    ax.set_ylabel("Net benefit")
    ax.set_title(title or "Decision-curve analysis")
    ax.legend(loc="upper right", frameon=False)
    fig.tight_layout()
    fig._mf_kind = "dca"
    return fig


# ------------------------------------------------------------------- forest
def forest_plot(studies: list[dict], pooled: dict, *, null_value: float = 1.0,
                effect_label: str = "Effect (95% CI)", title: str = "",
                log_x: bool = True) -> plt.Figure:
    """Meta-analysis forest plot from already-computed per-study estimates.

    studies: [{name, est, lo, hi, weight?}] — each study's point estimate + CI.
    pooled:  {est, lo, hi, label}          — the pooled estimate + CI + model name.
    Draws a weight-scaled marker + CI whisker per study, the null reference line, and a
    pooled diamond; the pooled row is always last. For a ratio measure keep log_x=True and
    null_value=1.0; for a mean difference pass log_x=False, null_value=0.0."""
    n = len(studies)
    fig, ax = plt.subplots(figsize=(6.6, 0.5 * n + 2.0))
    ys = list(range(n, 0, -1))  # top study at the highest y
    weights = np.asarray([s.get("weight", 1.0) for s in studies], float)
    wnorm = weights / weights.max() if weights.max() > 0 else np.ones(n)
    for y, s, w in zip(ys, studies, wnorm):
        ax.plot([s["lo"], s["hi"]], [y, y], color="0.3")             # CI whisker
        ax.scatter([s["est"]], [y], s=30 + 120 * w, marker="s",
                   color="steelblue", zorder=4)                       # weight-scaled box
    ax.axvline(null_value, linestyle="--", color="0.5")               # null reference
    # pooled diamond on a row below the studies
    yd = 0
    d = pooled
    ax.add_patch(Polygon([[d["lo"], yd], [d["est"], yd + 0.35],
                          [d["hi"], yd], [d["est"], yd - 0.35]],
                         closed=True, facecolor="crimson", edgecolor="black", zorder=5))
    labels = [s["name"] for s in studies] + [pooled.get("label", "Pooled")]
    ax.set_yticks(ys + [yd])
    ax.set_yticklabels(labels)
    ax.set_ylim(-1, n + 1)
    if log_x:
        ax.set_xscale("log")
    ax.set_xlabel(effect_label)
    ax.set_title(title or "Meta-analysis forest plot")
    fig.tight_layout()
    fig._mf_kind = "forest"
    fig._mf_n_studies = n
    fig._mf_null = null_value
    return fig


# -------------------------------------------------------------- Bland–Altman
def bland_altman(mean_vals, diff_vals, *, bias: float, sd_diff: float,
                 title: str = "") -> plt.Figure:
    """Bland–Altman agreement plot: difference vs mean, with the bias line and the
    95% limits of agreement (bias ± 1.96·SD) — the load-bearing agreement elements."""
    mean_vals = np.asarray(mean_vals, float)
    diff_vals = np.asarray(diff_vals, float)
    loa_hi, loa_lo = bias + 1.96 * sd_diff, bias - 1.96 * sd_diff
    fig, ax = plt.subplots(figsize=(6.0, 5.0))
    ax.scatter(mean_vals, diff_vals, s=25, color="steelblue", alpha=0.8)
    ax.axhline(bias, color="crimson", label=f"Bias {bias:.2f}")
    ax.axhline(loa_hi, linestyle="--", color="0.4", label=f"+1.96 SD {loa_hi:.2f}")
    ax.axhline(loa_lo, linestyle="--", color="0.4", label=f"−1.96 SD {loa_lo:.2f}")
    ax.set_xlabel("Mean of the two measurements")
    ax.set_ylabel("Difference between measurements")
    ax.set_title(title or "Bland–Altman agreement")
    ax.legend(loc="upper right", frameon=False)
    fig.tight_layout()
    fig._mf_kind = "bland_altman"
    fig._mf_loa = (loa_lo, loa_hi)
    return fig


# ---------------------------------------------------------- confusion matrix
def confusion_matrix(matrix, labels, *, title: str = "") -> plt.Figure:
    """Confusion matrix from an already-computed count grid. Rows = actual, cols =
    predicted; every cell is annotated with its count (for a 2×2, TN/FP/FN/TP)."""
    m = np.asarray(matrix, float)
    k = m.shape[0]
    if m.shape[0] != m.shape[1] or k != len(labels):
        raise AssertionError("confusion matrix must be square and match the label count")
    fig, ax = plt.subplots(figsize=(1.4 * k + 2, 1.4 * k + 2))
    ax.imshow(m, cmap="Blues")
    thresh = m.max() / 2.0 if m.max() else 0.5
    for i in range(k):
        for j in range(k):
            ax.text(j, i, str(int(m[i, j])), ha="center", va="center",
                    color="white" if m[i, j] > thresh else "black")
    ax.set_xticks(range(k)); ax.set_xticklabels(labels)
    ax.set_yticks(range(k)); ax.set_yticklabels(labels)
    ax.set_xlabel("Predicted")
    ax.set_ylabel("Actual")
    ax.set_title(title or "Confusion matrix")
    fig.tight_layout()
    fig._mf_kind = "confusion"
    fig._mf_k = k
    return fig


# ------------------------------------------------------------------ MRMC ROC
def mrmc_roc(readers: list[dict], averaged: dict, *, delta_auc: dict | None = None,
             title: str = "") -> plt.Figure:
    """Multi-reader multi-case ROC: each reader's ROC curve plus the reader-averaged
    curve and the chance diagonal (the load-bearing MRMC-reader-study elements).

    readers:  [{name, fpr, tpr, auc}]  — per-reader ROC coordinates.
    averaged: {fpr, tpr, auc, label}   — the reader-averaged curve.
    delta_auc (optional): {value, margin} — a ΔAUC-vs-margin annotation."""
    fig, ax = plt.subplots(figsize=(5.4, 5.2))
    for r in readers:
        ax.plot(np.asarray(r["fpr"], float), np.asarray(r["tpr"], float),
                color="0.7", linewidth=1)                              # thin per-reader
    a = averaged
    ax.plot(np.asarray(a["fpr"], float), np.asarray(a["tpr"], float),
            color="crimson", linewidth=2.4,
            label=f"{a.get('label', 'Reader-averaged')} (AUC = {a['auc']:.3f})")
    ax.plot([0, 1], [0, 1], linestyle="--", color="0.5", label="Chance")
    ax.set_xlim(0, 1); ax.set_ylim(0, 1.02)
    ax.set_xlabel("1 − specificity (false-positive rate)")
    ax.set_ylabel("Sensitivity (true-positive rate)")
    ax.set_title(title or "Multi-reader multi-case ROC")
    txt = f"averaged AUC = {a['auc']:.3f}"
    if delta_auc:
        txt += f"\nΔAUC = {delta_auc['value']:.3f} (margin {delta_auc['margin']:.3f})"
    ax.text(0.55, 0.08, txt, fontsize=10,
            bbox=dict(boxstyle="round", fc="white", ec="0.7"))
    ax.legend(loc="lower right", frameon=False)
    fig.tight_layout()
    fig._mf_kind = "mrmc_roc"
    fig._mf_n_readers = len(readers)
    return fig


# ------------------------------------------------------------------ Manhattan
def manhattan(x, neglogp, threshold: float, *, labels=None,
              ylabel: str = "−log10(p)", xlabel: str = "Exposure / position",
              title: str = "") -> plt.Figure:
    """Manhattan / *-wide-scan plot: −log10(p) vs position with the significance
    threshold line (the two load-bearing elements of an agnostic many-test scan)."""
    x = np.asarray(x, float)
    y = np.asarray(neglogp, float)
    fig, ax = plt.subplots(figsize=(7.0, 4.4))
    ax.scatter(x, y, s=14, color="steelblue", alpha=0.8)
    ax.axhline(threshold, color="crimson", linestyle="--",
               label=f"significance threshold (−log10 = {threshold:.2f})")
    if labels:  # sparse labelling of hits above the threshold
        for xi, yi, lab in zip(x, y, labels):
            if lab and yi >= threshold:
                ax.annotate(lab, (xi, yi), fontsize=8,
                            xytext=(0, 4), textcoords="offset points", ha="center")
    ax.set_xlabel(xlabel)
    ax.set_ylabel(ylabel)
    ax.set_title(title or "Manhattan plot")
    ax.legend(loc="upper right", frameon=False)
    fig.tight_layout()
    fig._mf_kind = "manhattan"
    fig._mf_threshold = threshold
    return fig


# --------------------------------------------------------- clinical timeline
def clinical_timeline(events: list[dict], *, time_unit: str = "days from admission",
                      title: str = "") -> plt.Figure:
    """Case-report clinical timeline: an event marker + label at each time on a single
    time axis (the load-bearing elements of a longitudinal case figure)."""
    times = [float(e["time"]) for e in events]
    fig, ax = plt.subplots(figsize=(max(6.0, 0.9 * len(events)), 3.4))
    lo, hi = (min(times), max(times)) if times else (0, 1)
    pad = max(1.0, (hi - lo) * 0.08)
    ax.axhline(0, color="0.4")                                        # the timeline
    for i, e in enumerate(events):
        t = float(e["time"])
        up = 1 if i % 2 == 0 else -1
        ax.plot([t, t], [0, up * 0.6], color="0.6")                  # stem
        ax.scatter([t], [0], s=40, color="crimson", zorder=5)         # event marker
        ax.annotate(str(e["label"]), (t, up * 0.65), ha="center",
                    va="bottom" if up > 0 else "top", fontsize=8)
    ax.set_xlim(lo - pad, hi + pad)
    ax.set_ylim(-1.3, 1.3)
    ax.get_yaxis().set_visible(False)
    for spine in ("left", "right", "top"):
        ax.spines[spine].set_visible(False)
    ax.set_xlabel(f"Time ({time_unit})")
    ax.set_title(title or "Clinical timeline")
    fig.tight_layout()
    fig._mf_kind = "timeline"
    fig._mf_n_events = len(events)
    return fig


# ----------------------------------------------------- structural invariants
def assert_structure(fig: plt.Figure) -> list[str]:
    """Assert the load-bearing elements for the figure's kind. Returns the list of
    checks that PASSED; raises AssertionError on the first violated invariant."""
    kind = getattr(fig, "_mf_kind", None)
    passed: list[str] = []

    def has_text(ax, needle: str) -> bool:
        n = needle.lower()
        return any(n in t.get_text().lower() for t in ax.texts) \
            or (ax.get_legend() and any(n in t.get_text().lower()
                                        for t in ax.get_legend().get_texts()))

    if kind == "km":
        ax, ax_risk = fig.axes[0], fig.axes[1]
        steps = [ln for ln in ax.lines if len(ln.get_xdata()) > 2]
        assert steps, "KM: no step curve drawn"
        passed.append("KM step curve present")
        # no extrapolation past follow-up
        muf = getattr(fig, "_mf_max_follow_up")
        assert abs(ax.get_xlim()[1] - muf) < 1e-9, "KM: x-axis extends past follow-up"
        passed.append("KM x-axis clipped to follow-up (no extrapolation)")
        # monotonic non-increasing survival on each step curve
        for ln in steps:
            y = np.asarray(ln.get_ydata(), float)
            assert np.all(np.diff(y) <= 1e-9), "KM: survival curve is not non-increasing"
        passed.append("KM survival monotonic non-increasing")
        assert any(t.get_text().lower().startswith("no. at risk") or "at risk"
                   in t.get_text().lower() for t in ax_risk.texts), \
            "KM: number-at-risk table missing"
        passed.append("KM number-at-risk table present")
        assert "survival" in ax.get_ylabel().lower(), "KM: y-label not survival"
        passed.append("KM survival y-label")

    elif kind == "roc":
        ax = fig.axes[0]
        diag = [ln for ln in ax.lines
                if len(ln.get_xdata()) == 2
                and np.allclose(ln.get_xdata(), [0, 1])
                and np.allclose(ln.get_ydata(), [0, 1])]
        assert diag, "ROC: chance diagonal (0,0)-(1,1) missing"
        passed.append("ROC chance diagonal present")
        assert has_text(ax, "auc"), "ROC: AUC annotation missing"
        passed.append("ROC AUC annotation present")
        assert ax.collections, "ROC: operating-point marker missing"
        passed.append("ROC operating point present")
        assert "sensitiv" in ax.get_ylabel().lower(), "ROC: y-label not sensitivity"
        passed.append("ROC sensitivity y-label")

    elif kind == "calibration":
        ax = fig.axes[0]
        identity = [ln for ln in ax.lines
                    if len(ln.get_xdata()) == 2
                    and np.allclose(ln.get_xdata(), [0, 1])
                    and np.allclose(ln.get_ydata(), [0, 1])]
        assert identity, "Calibration: identity y=x line missing"
        passed.append("Calibration identity line present")
        assert has_text(ax, "slope") and has_text(ax, "intercept"), \
            "Calibration: slope/intercept annotation missing"
        passed.append("Calibration slope+intercept annotation present")
        assert "predicted" in ax.get_xlabel().lower(), "Calibration: x not predicted"
        assert "observed" in ax.get_ylabel().lower(), "Calibration: y not observed"
        passed.append("Calibration predicted-vs-observed axes")

    elif kind == "dca":
        ax = fig.axes[0]
        assert len(ax.lines) >= 3, "DCA: fewer than 3 strategies (model/all/none) drawn"
        passed.append("DCA has model + treat-all + treat-none")
        treat_none = [ln for ln in ax.lines if np.allclose(ln.get_ydata(), 0.0)]
        assert treat_none, "DCA: treat-none (net benefit = 0) reference missing"
        passed.append("DCA treat-none reference present")
        assert "net benefit" in ax.get_ylabel().lower(), "DCA: y-label not net benefit"
        passed.append("DCA net-benefit y-label")
        assert has_text(ax, "treat all") and has_text(ax, "treat none"), \
            "DCA: treat-all / treat-none not labelled"
        passed.append("DCA reference strategies labelled")

    elif kind == "forest":
        ax = fig.axes[0]
        n = getattr(fig, "_mf_n_studies")
        # one horizontal CI whisker (2-point line, equal y) per study
        whiskers = [ln for ln in ax.lines
                    if len(ln.get_xdata()) == 2 and np.allclose(np.diff(ln.get_ydata()), 0.0)]
        assert len(whiskers) >= n, "forest: missing per-study CI whiskers"
        passed.append(f"forest per-study CI rows present ({n})")
        null = getattr(fig, "_mf_null")
        assert any(len(ln.get_xdata()) == 2 and np.allclose(ln.get_xdata(), [null, null])
                   for ln in ax.lines), "forest: null reference line missing"
        passed.append("forest null reference line present")
        assert any(isinstance(p, Polygon) and len(p.get_xy()) >= 4 for p in ax.patches), \
            "forest: pooled diamond missing"
        passed.append("forest pooled diamond present")
        assert len(ax.get_yticklabels()) >= n + 1, "forest: study/pooled row labels missing"
        passed.append("forest study + pooled row labels present")

    elif kind == "bland_altman":
        ax = fig.axes[0]
        assert ax.collections, "Bland–Altman: scatter of differences missing"
        passed.append("Bland–Altman difference scatter present")
        hlines = [ln for ln in ax.lines if np.allclose(np.diff(ln.get_ydata()), 0.0)]
        assert len(hlines) >= 3, "Bland–Altman: need bias + two limits-of-agreement lines"
        passed.append("Bland–Altman bias + 2 LoA lines present")
        loa_lo, loa_hi = getattr(fig, "_mf_loa")
        yvals = [float(ln.get_ydata()[0]) for ln in hlines]
        assert any(abs(y - loa_hi) < 1e-6 for y in yvals) and any(abs(y - loa_lo) < 1e-6 for y in yvals), \
            "Bland–Altman: LoA lines not at bias ± 1.96·SD"
        passed.append("Bland–Altman LoA at bias ± 1.96·SD")
        assert "difference" in ax.get_ylabel().lower() and "mean" in ax.get_xlabel().lower(), \
            "Bland–Altman: axes not difference-vs-mean"
        passed.append("Bland–Altman difference-vs-mean axes")

    elif kind == "confusion":
        ax = fig.axes[0]
        k = getattr(fig, "_mf_k")
        assert ax.images, "confusion: matrix image missing"
        passed.append("confusion matrix image present")
        cells = [t for t in ax.texts if t.get_text().strip().lstrip("-").isdigit()]
        assert len(cells) >= k * k, f"confusion: expected {k * k} annotated cells"
        passed.append(f"confusion all {k}×{k} cells annotated")
        assert "predicted" in ax.get_xlabel().lower() and "actual" in ax.get_ylabel().lower(), \
            "confusion: axes not Predicted/Actual"
        passed.append("confusion Predicted/Actual axes")

    elif kind == "mrmc_roc":
        ax = fig.axes[0]
        n = getattr(fig, "_mf_n_readers")
        curves = [ln for ln in ax.lines
                  if len(ln.get_xdata()) > 2]                          # multi-point ROC curves
        assert len(curves) >= n + 1, "MRMC-ROC: fewer curves than readers + averaged"
        passed.append(f"MRMC-ROC per-reader + averaged curves present ({n}+1)")
        diag = [ln for ln in ax.lines
                if len(ln.get_xdata()) == 2 and np.allclose(ln.get_xdata(), [0, 1])
                and np.allclose(ln.get_ydata(), [0, 1])]
        assert diag, "MRMC-ROC: chance diagonal missing"
        passed.append("MRMC-ROC chance diagonal present")
        assert has_text(ax, "auc"), "MRMC-ROC: averaged-AUC annotation missing"
        passed.append("MRMC-ROC averaged-AUC annotation present")
        assert "sensitiv" in ax.get_ylabel().lower(), "MRMC-ROC: y-label not sensitivity"
        passed.append("MRMC-ROC sensitivity y-label")

    elif kind == "manhattan":
        ax = fig.axes[0]
        assert ax.collections, "Manhattan: point scatter missing"
        passed.append("Manhattan scatter present")
        thr = getattr(fig, "_mf_threshold")
        assert any(np.allclose(ln.get_ydata(), thr) for ln in ax.lines
                   if np.allclose(np.diff(ln.get_ydata()), 0.0)), \
            "Manhattan: significance threshold line missing"
        passed.append("Manhattan significance threshold line present")
        yl = ax.get_ylabel().lower()
        assert "log" in yl and ("10" in yl or "log10" in yl or "−log" in yl or "-log" in yl), \
            "Manhattan: y-label not −log10(p)"
        passed.append("Manhattan −log10(p) y-label")

    elif kind == "timeline":
        ax = fig.axes[0]
        ne = getattr(fig, "_mf_n_events")
        assert any(np.allclose(ln.get_ydata(), 0.0) for ln in ax.lines), \
            "timeline: baseline axis missing"
        passed.append("timeline baseline present")
        assert ax.collections, "timeline: event markers missing"
        passed.append("timeline event markers present")
        assert len([t for t in ax.texts if t.get_text().strip()]) >= ne, \
            "timeline: an event label is missing"
        passed.append(f"timeline all {ne} event labels present")
        assert "time" in ax.get_xlabel().lower(), "timeline: x-axis not a time axis"
        passed.append("timeline time x-axis")

    else:
        raise AssertionError(f"unknown figure kind: {kind!r}")
    return passed


# ----------------------------------------------------------------- driver
def render_all(inputs: dict, out_dir: Path) -> dict:
    """Render each figure kind present in ``inputs``, save PNGs, and assert structure.
    Returns {kind: [passed checks]}. Raises on any structural violation."""
    out_dir.mkdir(parents=True, exist_ok=True)
    results: dict[str, list[str]] = {}
    builders = {
        "km": lambda d: km_curve(d["groups"], d["max_follow_up"], title=d.get("title", "")),
        "roc": lambda d: roc_curve(d["fpr"], d["tpr"], d["auc"],
                                   operating_point=d.get("operating_point")),
        "calibration": lambda d: calibration_plot(
            d["pred_mean"], d["obs_freq"], slope=d["slope"], intercept=d["intercept"],
            ci_low=d.get("ci_low"), ci_high=d.get("ci_high")),
        "dca": lambda d: decision_curve(d["thresholds"], d["net_benefit_model"],
                                        d["prevalence"]),
        "forest": lambda d: forest_plot(d["studies"], d["pooled"],
                                        null_value=d.get("null_value", 1.0),
                                        effect_label=d.get("effect_label", "Effect (95% CI)"),
                                        log_x=d.get("log_x", True)),
        "bland_altman": lambda d: bland_altman(d["mean_vals"], d["diff_vals"],
                                               bias=d["bias"], sd_diff=d["sd_diff"]),
        "confusion": lambda d: confusion_matrix(d["matrix"], d["labels"]),
        "mrmc_roc": lambda d: mrmc_roc(d["readers"], d["averaged"],
                                       delta_auc=d.get("delta_auc")),
        "manhattan": lambda d: manhattan(d["x"], d["neglogp"], d["threshold"],
                                         labels=d.get("labels"),
                                         xlabel=d.get("xlabel", "Exposure / position")),
        "timeline": lambda d: clinical_timeline(d["events"],
                                                time_unit=d.get("time_unit", "days from admission")),
    }
    for kind, build in builders.items():
        if kind not in inputs:
            continue
        fig = build(inputs[kind])
        results[kind] = assert_structure(fig)
        fig.savefig(out_dir / f"{kind}.png", dpi=120)
        png = out_dir / f"{kind}.png"
        assert png.exists() and png.stat().st_size > 2000, f"{kind}: PNG not written"
        plt.close(fig)
    return results


def main(argv=None) -> int:
    ap = argparse.ArgumentParser(description="Render + structurally verify core clinical figures.")
    ap.add_argument("--inputs", required=True, help="JSON with km/roc/calibration/dca inputs")
    ap.add_argument("--out-dir", required=True, help="directory for rendered PNGs")
    args = ap.parse_args(argv)
    inputs = json.loads(Path(args.inputs).read_text(encoding="utf-8"))
    try:
        results = render_all(inputs, Path(args.out_dir))
    except AssertionError as e:
        print(f"RENDER-FAIL: {e}", file=sys.stderr)
        return 1
    for kind, checks in results.items():
        print(f"OK [{kind}] {len(checks)} structural invariants: {'; '.join(checks)}")
    print(f"PASS: {len(results)} figure(s) rendered + structurally verified.")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""Validate a .pptx for Mac PowerPoint compatibility.

Detects four classes of defect that PowerPoint Mac renders differently
from PowerPoint Windows / Keynote / LibreOffice and that PDF export
alone does not catch:

1. TIFF images embedded in ppt/media/ — Mac PowerPoint silently drops them.
2. <a:sp3d> 3-D bevel inside text rPr — Mac renders as red outline that
   does not appear in PDF or on Windows.
3. docProps/app.xml count mismatch with actual slide count — triggers a
   "PowerPoint found a problem" recovery dialog on first open.
4. <a:srcRect> values exceeding 100000 (1/1000-percent) — image is
   over-cropped (sometimes 99 % cut off) only on Mac.

Reference rule: ~/.claude/rules/pptx-mac-compatibility.md.

Usage:
    python validate_pptx_mac_compat.py path/to/deck.pptx
    python validate_pptx_mac_compat.py deck.pptx --json out.json
    python validate_pptx_mac_compat.py deck.pptx --strict   # exit 1 on any FAIL

Exit codes:
    0 — all checks PASS
    1 — at least one FAIL (only with --strict; otherwise still 0 with WARN)
    2 — input invalid (file missing, not a zip, etc.)
"""

from __future__ import annotations

import argparse
import json
import re
import sys
import zipfile
from pathlib import Path


SP3D_RE = re.compile(r"<a:sp3d\b", re.IGNORECASE)
SRC_RECT_RE = re.compile(
    r'<a:srcRect\b[^/>]*?(?:l|t|r|b)="(\d+)"', re.IGNORECASE
)
APP_XML_SLIDES_RE = re.compile(r"<Slides>(\d+)</Slides>", re.IGNORECASE)
APP_XML_VECTOR_SIZE_RE = re.compile(
    r'<vt:vector\b[^>]*?size="(\d+)"', re.IGNORECASE
)


def _check_tiff(zf: zipfile.ZipFile) -> list[str]:
    found = [
        name
        for name in zf.namelist()
        if name.lower().startswith("ppt/media/")
        and name.lower().endswith((".tif", ".tiff"))
    ]
    return found


def _check_sp3d(zf: zipfile.ZipFile) -> list[tuple[str, int]]:
    hits: list[tuple[str, int]] = []
    for name in zf.namelist():
        if not (name.startswith("ppt/slides/") and name.endswith(".xml")):
            continue
        try:
            text = zf.read(name).decode("utf-8", errors="replace")
        except Exception:
            continue
        count = len(SP3D_RE.findall(text))
        if count > 0:
            hits.append((name, count))
    return hits


def _check_app_xml(zf: zipfile.ZipFile) -> dict:
    result = {"present": False, "declared_slides": None, "actual_slides": None,
              "vector_size_max": None, "mismatch": False}
    actual = sum(
        1
        for n in zf.namelist()
        if n.startswith("ppt/slides/slide") and n.endswith(".xml")
    )
    result["actual_slides"] = actual
    try:
        app = zf.read("docProps/app.xml").decode("utf-8", errors="replace")
    except KeyError:
        return result
    result["present"] = True
    m = APP_XML_SLIDES_RE.search(app)
    if m:
        declared = int(m.group(1))
        result["declared_slides"] = declared
        if declared != actual:
            result["mismatch"] = True
    sizes = [int(s) for s in APP_XML_VECTOR_SIZE_RE.findall(app)]
    if sizes:
        result["vector_size_max"] = max(sizes)
    return result


def _check_src_rect(zf: zipfile.ZipFile) -> list[tuple[str, int]]:
    """Return [(slide_path, max_value)] for any srcRect value > 100000.

    srcRect uses 1/1000-percent units; legitimate values are 0–100000.
    Anything above 100000 indicates a unit-conversion bug (e.g., a
    percent-to-1/1000-percent miscalculation) and produces severe over-crop
    on Mac PowerPoint.
    """
    hits: list[tuple[str, int]] = []
    for name in zf.namelist():
        if not (name.startswith("ppt/slides/") and name.endswith(".xml")):
            continue
        try:
            text = zf.read(name).decode("utf-8", errors="replace")
        except Exception:
            continue
        values = [int(v) for v in SRC_RECT_RE.findall(text)]
        bad = [v for v in values if v > 100000]
        if bad:
            hits.append((name, max(bad)))
    return hits


def validate(pptx_path: Path) -> dict:
    if not pptx_path.exists():
        return {"ok": False, "error": f"file not found: {pptx_path}"}
    if not zipfile.is_zipfile(pptx_path):
        return {"ok": False, "error": f"not a zip / pptx: {pptx_path}"}

    with zipfile.ZipFile(pptx_path) as zf:
        tiffs = _check_tiff(zf)
        sp3d = _check_sp3d(zf)
        app = _check_app_xml(zf)
        srcrect = _check_src_rect(zf)

    findings: list[dict] = []

    if tiffs:
        findings.append({
            "id": "TIFF",
            "severity": "FAIL",
            "message": f"{len(tiffs)} TIFF image(s) embedded; Mac PowerPoint will silently drop these.",
            "files": tiffs,
            "fix": "Convert each to PNG (`sips -s format png in.tif --out out.png` on macOS) and update _rels/*.rels to reference the new .png filenames.",
        })

    if sp3d:
        total = sum(c for _, c in sp3d)
        findings.append({
            "id": "SP3D",
            "severity": "FAIL",
            "message": f"<a:sp3d> 3-D bevel found in {len(sp3d)} slide(s) ({total} occurrence(s)); renders as red outline on Mac PowerPoint and is invisible in PDF export.",
            "files": [{"slide": n, "count": c} for n, c in sp3d],
            "fix": "Strip <a:sp3d>...</a:sp3d> blocks via regex in each slide XML. Verify on Mac PowerPoint after fix.",
        })

    if app["present"] and app["mismatch"]:
        findings.append({
            "id": "APP_XML_COUNT",
            "severity": "FAIL",
            "message": f"docProps/app.xml declares <Slides>{app['declared_slides']}</Slides> but the package contains {app['actual_slides']} slide XML files; PowerPoint Mac will show a 'recover file' dialog on first open.",
            "fix": "Update <Slides>, <HeadingPairs>, and <TitlesOfParts> in docProps/app.xml to match the actual slide count.",
        })
    elif not app["present"]:
        findings.append({
            "id": "APP_XML_MISSING",
            "severity": "WARN",
            "message": "docProps/app.xml not found in package; PowerPoint Mac may show a recovery dialog or open with broken metadata.",
            "fix": "Re-export the deck from PowerPoint (which writes app.xml) or generate one programmatically.",
        })

    if srcrect:
        findings.append({
            "id": "SRC_RECT_OVERFLOW",
            "severity": "FAIL",
            "message": f"<a:srcRect> values >100000 (1/1000-percent maximum) found in {len(srcrect)} slide(s); image will be over-cropped on Mac PowerPoint (often >99 % cut off).",
            "files": [{"slide": n, "max_value": v} for n, v in srcrect],
            "fix": "Recompute srcRect: percentages stay 0–100; 1/1000-percent units stay 0–100000. Compare to original .pptx srcRect values if a build script regressed.",
        })

    fail_count = sum(1 for f in findings if f["severity"] == "FAIL")
    warn_count = sum(1 for f in findings if f["severity"] == "WARN")

    return {
        "ok": fail_count == 0,
        "file": str(pptx_path),
        "summary": {
            "fail": fail_count,
            "warn": warn_count,
            "slides": app["actual_slides"],
        },
        "findings": findings,
    }


def _format_human(report: dict) -> str:
    if not report.get("ok") and "error" in report:
        return f"ERROR: {report['error']}"
    lines = [f"PPTX Mac compatibility check — {report['file']}"]
    s = report["summary"]
    lines.append(f"  slides={s['slides']}  fail={s['fail']}  warn={s['warn']}")
    if not report["findings"]:
        lines.append("  ✓ All four checks PASS (TIFF, sp3d, app.xml count, srcRect).")
        return "\n".join(lines)
    for f in report["findings"]:
        lines.append(f"  [{f['severity']}] {f['id']}: {f['message']}")
        lines.append(f"        fix: {f['fix']}")
    return "\n".join(lines)


def main(argv: list[str] | None = None) -> int:
    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    ap.add_argument("pptx", help="path to .pptx")
    ap.add_argument("--json", help="write JSON report to this path")
    ap.add_argument("--strict", action="store_true",
                    help="exit 1 if any FAIL (default exits 0 with WARN)")
    args = ap.parse_args(argv)

    report = validate(Path(args.pptx))
    if not report.get("ok") and "error" in report:
        print(_format_human(report), file=sys.stderr)
        return 2

    if args.json:
        Path(args.json).write_text(json.dumps(report, indent=2))
    print(_format_human(report))

    if args.strict and not report["ok"]:
        return 1
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""STROBE participant-flow cascade closure check for a build_strobe_template.py config.

A STROBE flow diagram's exclusion cascade must balance: the count in a spine box, minus the
exclusions declared after it, must equal the count in the next spine box. A real cohort
figure once read "500 excluded -> N = 9,470" while the enrolled box said 10,000, so
10,000 - 500 = 9,500, not 9,470 — a second exclusion, present in the legend, had been
dropped from the figure. It survived a full round of peer review and was found only by
rendering the submission PDF to an image and reading it by eye, because figure-image numbers
are text-grep blind.

`check_cohort_arithmetic.py` already asserts this closure in manuscript prose, GFM tables and
committed CSVs. The number that a reviewer actually sees, though, lives as text in the flow
diagram, generated here from a structured YAML — so the diagram can drift from the prose.
This makes the figure carry its own assertion.

Low false-positive by construction: a spine link is checked ONLY when at least one exclusion
is declared after that box (the author is asserting "A minus these gives B"), and only when
every count involved is extractable. A branching Analysis leaf (two boxes sharing a parent,
no exclusion between them) is never treated as a cascade step. A box with no "n = …" count is
skipped, not guessed.

Reused by build_strobe_template.py (a loud warning during the build; fatal under
--strict-cascade) and runnable standalone (`_strobe_cascade.py --config figure1.yaml
--strict`) so the check travels without python-pptx.
"""
from __future__ import annotations

import argparse
import re
import sys
from pathlib import Path

# The box TOTAL is the first "n = X" / "N = X" in the box text — the parenthetical after the
# label ("Enrolled (n = 10,000)", "Excluded (n = 500):"). Sub-bullet counts come after it.
_COUNT_RE = re.compile(r"[nN]\s*=\s*([\d,]+)")


def extract_count(text: str | None) -> int | None:
    """First `n = X` in the box text as an int, or None when the box carries no count."""
    if not text:
        return None
    m = _COUNT_RE.search(str(text))
    return int(m.group(1).replace(",", "")) if m else None


def check_cascade(cfg: dict) -> list[dict]:
    """Return an imbalance finding for every declared exclusion link A -> B where
    ``A.count - sum(exclusions after A) != B.count``."""
    spine = cfg.get("spine") or []
    exclusions = cfg.get("exclusions") or []
    if len(spine) < 2:
        return []

    counts = {b.get("id"): extract_count(b.get("text")) for b in spine if isinstance(b, dict)}
    excl_after: dict[str, list[int | None]] = {}
    for e in exclusions:
        if isinstance(e, dict) and e.get("after"):
            excl_after.setdefault(e["after"], []).append(extract_count(e.get("text")))

    findings: list[dict] = []
    for i in range(len(spine) - 1):
        a, b = spine[i], spine[i + 1]
        if not (isinstance(a, dict) and isinstance(b, dict)):
            continue
        aid = a.get("id")
        excls = excl_after.get(aid)
        if not excls:                       # only a DECLARED exclusion link is a cascade step
            continue
        a_n, b_n = counts.get(aid), counts.get(b.get("id"))
        if a_n is None or b_n is None or any(x is None for x in excls):
            continue                        # never guess a missing count
        got = a_n - sum(excls)
        if got != b_n:
            findings.append({
                "after": aid,
                "next": b.get("id"),
                "detail": (f"STROBE cascade does not close after '{aid}': {a_n:,} - "
                           f"{'+'.join(f'{x:,}' for x in excls)} = {got:,}, but the next box "
                           f"'{b.get('id')}' says {b_n:,} (off by {b_n - got:+,})"),
            })
    return findings


def _load(path: Path) -> dict:
    text = path.read_text(encoding="utf-8")
    if path.suffix.lower() in {".yaml", ".yml"}:
        try:
            import yaml  # noqa: PLC0415
        except ModuleNotFoundError:
            sys.exit("PyYAML not installed; install it or pass a JSON config.")
        return yaml.safe_load(text) or {}
    import json  # noqa: PLC0415
    return json.loads(text)


def main() -> int:
    ap = argparse.ArgumentParser(description="STROBE flow cascade-closure check.")
    ap.add_argument("--config", required=True, help="build_strobe_template.py YAML/JSON config")
    ap.add_argument("--strict", action="store_true", help="exit 1 if the cascade does not close")
    a = ap.parse_args()
    findings = check_cascade(_load(Path(a.config)))
    if findings:
        for f in findings:
            print(f"CASCADE_IMBALANCE: {f['detail']}")
    else:
        print("OK: STROBE exclusion cascade closes at every declared link.")
    return 1 if (findings and a.strict) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env bash
# Regression test for the Figure 1 caption ↔ flow-SSOT reconciler.
# Synthetic fixtures: a flow config with counts {1284, 286, 998}; an OK caption
# that matches, and a stale caption citing 1,150 (absent from the diagram).
# Stdlib-only (python3).
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/derive_figure_legend_counts.py"
FLOW="$HERE/fixtures/figure1_flow.yaml"
OK="$HERE/fixtures/manuscript_ok.md"
STALE="$HERE/fixtures/manuscript_stale.md"
OUT="$(mktemp -t fl_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

python3 "$SCRIPT" --flow-config "$FLOW" --manuscript "$OK" --strict >/dev/null 2>&1
check "exit 0 when caption matches the flow SSOT" test "$?" -eq 0

python3 "$SCRIPT" --flow-config "$FLOW" --manuscript "$STALE" --out "$OUT" --strict >/dev/null 2>&1
check "exit 1 when caption cites a count absent from the flow SSOT" test "$?" -eq 1
check "stale count 1150 flagged" python3 -c "
import json; d=json.load(open('$OUT'))
assert 1150 in d['stale_in_caption'], d['stale_in_caption']"
check "verdict MISMATCH" python3 -c "
import json; assert json.load(open('$OUT'))['verdict']=='MISMATCH'"

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env python3
"""Regression test for scripts/validate_pptx_mac_compat.py.

Builds a clean .pptx (python-pptx, with a corrected docProps/app.xml slide
count) that must PASS, then injects each of the four Mac-incompatibility defect
classes into a copy and asserts the validator FAILs under --strict:

    TIFF media, <a:sp3d> 3-D bevel, app.xml slide-count mismatch, srcRect
    over-crop (> 100000).

Also asserts a missing input exits 2. Requires python-pptx (a CI dependency).
"""

from __future__ import annotations

import re
import subprocess
import sys
import tempfile
import zipfile
from pathlib import Path

HERE = Path(__file__).resolve().parent
VALIDATOR = HERE.parent / "scripts" / "validate_pptx_mac_compat.py"

_pass = 0
_fail = 0


def ck(label: str, expected: int, actual: int) -> None:
    global _pass, _fail
    if expected == actual:
        print(f"  PASS  {label:<48} exit={actual}")
        _pass += 1
    else:
        print(f"  FAIL  {label:<48} expected={expected} actual={actual}")
        _fail += 1


def run(pptx: Path, strict: bool = True) -> int:
    cmd = [sys.executable, str(VALIDATOR), str(pptx)]
    if strict:
        cmd.append("--strict")
    return subprocess.run(cmd, capture_output=True, text=True).returncode


def build_clean(path: Path, n_slides: int = 2) -> None:
    """A python-pptx deck with app.xml <Slides> corrected to match — should PASS."""
    from pptx import Presentation

    prs = Presentation()
    for _ in range(n_slides):
        prs.slides.add_slide(prs.slide_layouts[6])  # blank
    prs.save(str(path))
    # python-pptx writes <Slides>0</Slides>; fix it so the clean baseline passes.
    _rewrite_member(path, "docProps/app.xml",
                     lambda b: re.sub(rb"<Slides>\d+</Slides>",
                                      f"<Slides>{n_slides}</Slides>".encode(), b))


def _read_member(path: Path, member: str) -> bytes:
    with zipfile.ZipFile(path) as z:
        return z.read(member)


def _rewrite_member(path: Path, member: str, transform, extra: dict | None = None) -> None:
    """Rewrite the zip, replacing `member` (via transform) and adding `extra` files."""
    with zipfile.ZipFile(path) as z:
        items = {n: z.read(n) for n in z.namelist()}
    if member in items:
        items[member] = transform(items[member])
    if extra:
        items.update(extra)
    tmp = path.with_suffix(".tmp.pptx")
    with zipfile.ZipFile(tmp, "w", zipfile.ZIP_DEFLATED) as z:
        for n, data in items.items():
            z.writestr(n, data)
    tmp.replace(path)


def first_slide(path: Path) -> str:
    with zipfile.ZipFile(path) as z:
        for n in sorted(z.namelist()):
            if n.startswith("ppt/slides/slide") and n.endswith(".xml"):
                return n
    raise AssertionError("no slide XML in fixture")


def main() -> int:
    if VALIDATOR.exists() is False:
        print(f"validator missing: {VALIDATOR}")
        return 1
    tmp = Path(tempfile.mkdtemp())

    clean = tmp / "clean.pptx"
    build_clean(clean)
    ck("clean deck (app.xml fixed) passes", 0, run(clean))

    # 1) TIFF embedded in ppt/media/
    tiff = tmp / "tiff.pptx"
    build_clean(tiff)
    _rewrite_member(tiff, "docProps/app.xml", lambda b: b,
                    extra={"ppt/media/image1.tiff": b"II*\x00 fake tiff"})
    ck("TIFF media -> FAIL", 1, run(tiff))

    # 2) <a:sp3d> 3-D bevel inside a slide
    sp3d = tmp / "sp3d.pptx"
    build_clean(sp3d)
    sl = first_slide(sp3d)
    _rewrite_member(sp3d, sl, lambda b: b.replace(b"</p:sld>", b"<a:sp3d/></p:sld>"))
    ck("sp3d bevel -> FAIL", 1, run(sp3d))

    # 3) app.xml slide-count mismatch (declare a wrong count)
    appx = tmp / "appx.pptx"
    build_clean(appx)
    _rewrite_member(appx, "docProps/app.xml",
                    lambda b: re.sub(rb"<Slides>\d+</Slides>", b"<Slides>99</Slides>", b))
    ck("app.xml slide-count mismatch -> FAIL", 1, run(appx))

    # 4) srcRect over-crop (> 100000)
    src = tmp / "srcrect.pptx"
    build_clean(src)
    sl2 = first_slide(src)
    _rewrite_member(src, sl2, lambda b: b.replace(b"</p:sld>", b'<a:srcRect l="997171"/></p:sld>'))
    ck("srcRect over-crop (>100000) -> FAIL", 1, run(src))

    # 5) missing input -> exit 2
    ck("missing input -> exit 2", 2, run(tmp / "does_not_exist.pptx"))

    # 6) non-strict tolerates a WARN-only deck (no app.xml -> WARN, exit 0)
    nowarn = tmp / "noappxml.pptx"
    build_clean(nowarn)
    _rewrite_member(nowarn, "docProps/app.xml", lambda b: b, extra=None)
    # remove app.xml entirely
    with zipfile.ZipFile(nowarn) as z:
        items = {n: z.read(n) for n in z.namelist() if n != "docProps/app.xml"}
    with zipfile.ZipFile(nowarn, "w", zipfile.ZIP_DEFLATED) as z:
        for n, data in items.items():
            z.writestr(n, data)
    ck("missing app.xml is WARN, tolerated without --strict", 0, run(nowarn, strict=False))

    print("----")
    print(f"test_pptx_mac_compat: {_pass} passed, {_fail} failed")
    return 0 if _fail == 0 else 1


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env bash
# Regression test for the STROBE flow cascade-closure check (make-figures).
# Synthetic, PII-free YAML fixtures modelled on a real cohort-figure defect:
#   imbalanced -> 10,000 - 500 = 9,500, but the analysis box says 9,470 (off by 30)
#   balanced   -> the same cascade closing exactly (9,500)
#   branching  -> a landmark-subset leaf with no exclusion between it and its parent, which
#                 must NOT be read as an unbalanced cascade step (low-false-positive guard)
# The helper (_strobe_cascade.py) is checked directly (no python-pptx needed); the
# build_strobe_template.py --strict-cascade integration is checked only when pptx is present.
set -u
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
CHK="$HERE/../scripts/_strobe_cascade.py"
BUILD="$HERE/../scripts/build_strobe_template.py"
FX="$HERE/fixtures"
fail=0
ck() { if [ "$2" = "$3" ]; then printf '  PASS  %s\n' "$1"; else printf '  FAIL  %s (want %s got %s)\n' "$1" "$2" "$3"; fail=$((fail+1)); fi; }

[ -f "$CHK" ] || { echo "ENV-ERR: helper missing" >&2; exit 2; }

# (1) imbalanced cascade -> exit 1 under --strict, and the message names the offending link.
out="$(python3 "$CHK" --config "$FX/strobe_cascade_imbalanced.yaml" --strict 2>&1)"; rc=$?
ck "imbalanced exits 1 under --strict" 1 "$rc"
printf '%s\n' "$out" | grep -q 'CASCADE_IMBALANCE' && ck "imbalanced reports CASCADE_IMBALANCE" yes yes || ck "imbalanced reports CASCADE_IMBALANCE" yes no
printf '%s\n' "$out" | grep -q "off by -30" && ck "imbalanced names the -30 offset" yes yes || ck "imbalanced names the -30 offset" yes no

# (2) balanced cascade -> exit 0, no imbalance.
python3 "$CHK" --config "$FX/strobe_cascade_balanced.yaml" --strict >/dev/null 2>&1; ck "balanced exits 0" 0 "$?"

# (3) branching leaf -> exit 0 (the 4,200 subset is not a cascade step off the 5,000 parent).
out3="$(python3 "$CHK" --config "$FX/strobe_cascade_branching.yaml" --strict 2>&1)"; ck "branching leaf exits 0 (no false positive)" 0 "$?"
printf '%s\n' "$out3" | grep -q 'CASCADE_IMBALANCE' && { echo "  FAIL  branching leaf falsely flagged" >&2; fail=$((fail+1)); } || printf '  PASS  branching leaf not flagged\n'

# (4) build integration (only if python-pptx is installed): --strict-cascade refuses the
#     imbalanced config and builds the balanced one.
if python3 -c "import pptx" 2>/dev/null; then
  tmp="$(mktemp -d)"; trap 'rm -rf "$tmp"' EXIT
  python3 "$BUILD" --config "$FX/strobe_cascade_imbalanced.yaml" --out "$tmp/x.pptx" --strict-cascade >/dev/null 2>&1
  ck "build --strict-cascade refuses the imbalanced config" 1 "$?"
  python3 "$BUILD" --config "$FX/strobe_cascade_balanced.yaml" --out "$tmp/ok.pptx" --strict-cascade >/dev/null 2>&1
  ck "build --strict-cascade builds the balanced config" 0 "$?"
  [ -f "$tmp/ok.pptx" ] && ck "balanced build wrote the pptx" yes yes || ck "balanced build wrote the pptx" yes no
else
  echo "  SKIP  build integration (python-pptx not installed)"
fi

echo "fail=$fail"; [ "$fail" -eq 0 ] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"