medsci-skills 4.1.0

package/skills/make-figures/scripts/derive_figure_legend_counts.py

@@ -0,0 +1,138 @@
+#!/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(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())

package/skills/make-figures/scripts/extract_exemplar_from_pdf.py

@@ -0,0 +1,186 @@
+#!/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: Optional[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,
+    )
+    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)")
+    p.add_argument("--doi", default=None, help="DOI of source paper (for attribution)")
+    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,
+            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())

package/skills/make-figures/scripts/fetch_official_templates.sh

@@ -0,0 +1,88 @@
+#!/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

package/skills/make-figures/scripts/fill_prisma_template.py

@@ -0,0 +1,142 @@
+#!/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()

package/skills/make-figures/scripts/generate_flow_diagram.R

@@ -0,0 +1,133 @@
+#!/usr/bin/env Rscript
+# generate_flow_diagram.R
+# Monochrome outline flow diagrams (STROBE / CONSORT / PRISMA / STARD).
+#
+# Usage:
+#   Rscript generate_flow_diagram.R \
+#       --type {strobe|consort|prisma|stard} \
+#       --config <path/to/counts.yaml> \
+#       --out   <path/to/output_prefix>
+#
+# Output:
+#   <prefix>.pdf            true vector PDF (journal submission)
+#   <prefix>.png            ~300 dpi review copy (width 2400)
+#   <prefix>_600.png        600 dpi RSNA/Eur Radiol line-art
+#
+# YAML schema (see references/exemplar_diagrams/<type>/example_input.yaml):
+#   title: "Optional title"
+#   rankdir: TB            # or LR
+#   nodes:
+#     - id: db
+#       label: "Database (n = 1,000)"
+#       highlight: true    # optional, draws thicker border
+#       shape: note        # optional; overrides default "box"
+#     - id: excl
+#       label: "Excluded (n = 50)"
+#       rank_same_with: db # optional; renders on same rank as <id>
+#   edges:
+#     - from: db
+#       to:   cohort
+#       style: solid       # or dashed
+#       arrow: true        # false -> no arrowhead
+#       constraint: true   # false -> layout ignores this edge
+#
+# Dependencies: DiagrammeR, DiagrammeRsvg, rsvg, yaml, librsvg (system).
+
+suppressPackageStartupMessages({
+  library(DiagrammeR); library(DiagrammeRsvg); library(rsvg); library(yaml)
+})
+
+# ---- CLI parsing ------------------------------------------------------------
+parse_args <- function() {
+  args <- commandArgs(trailingOnly = TRUE)
+  out  <- list(type = NULL, config = NULL, out = NULL)
+  i <- 1L
+  while (i <= length(args)) {
+    key <- args[[i]]; val <- args[[i + 1L]]
+    if (key == "--type")   out$type   <- val
+    if (key == "--config") out$config <- val
+    if (key == "--out")    out$out    <- val
+    i <- i + 2L
+  }
+  valid <- c("strobe", "consort", "prisma", "stard")
+  if (is.null(out$type) || !(out$type %in% valid))
+    stop("--type must be one of: ", paste(valid, collapse = ", "))
+  if (is.null(out$config) || !file.exists(out$config))
+    stop("--config file missing or not found: ", out$config)
+  if (is.null(out$out)) stop("--out prefix required")
+  out
+}
+
+# ---- DOT assembly -----------------------------------------------------------
+STYLE_HEADER <- '  graph [layout=dot, rankdir=%s, fontname="Arial",
+         splines=ortho, nodesep=0.45, ranksep=0.55]
+  node  [shape=box, style="rounded,filled", fillcolor=white,
+         color=black, fontname="Arial", fontsize=11, penwidth=1.2,
+         margin="0.20,0.12"]
+  edge  [color=black, arrowhead=normal, arrowsize=0.75, penwidth=1.0]'
+
+escape_label <- function(txt) {
+  # Convert \n in YAML-supplied string to DOT literal "\n" for line break.
+  txt <- gsub('"', '\\\\"', txt, fixed = TRUE)
+  gsub("\n", "\\n", txt, fixed = TRUE)
+}
+
+node_line <- function(node) {
+  attrs <- c(sprintf('label="%s"', escape_label(node$label)))
+  if (!is.null(node$shape))    attrs <- c(attrs, sprintf('shape=%s', node$shape))
+  if (isTRUE(node$highlight))  attrs <- c(attrs, 'penwidth=1.8')
+  if (!is.null(node$fontsize)) attrs <- c(attrs, sprintf('fontsize=%d', node$fontsize))
+  sprintf("  %s [%s]", node$id, paste(attrs, collapse = ", "))
+}
+
+edge_line <- function(e) {
+  attrs <- character()
+  if (!is.null(e$style) && e$style != "solid")
+    attrs <- c(attrs, sprintf("style=%s", e$style))
+  if (isFALSE(e$arrow))       attrs <- c(attrs, "arrowhead=none")
+  if (isFALSE(e$constraint))  attrs <- c(attrs, "constraint=false")
+  suffix <- if (length(attrs)) sprintf(" [%s]", paste(attrs, collapse = ", ")) else ""
+  sprintf("  %s -> %s%s", e$from, e$to, suffix)
+}
+
+rank_same_lines <- function(nodes) {
+  pairs <- Filter(function(n) !is.null(n$rank_same_with), nodes)
+  if (!length(pairs)) return(character())
+  vapply(pairs, function(n)
+         sprintf("  { rank=same; %s; %s }", n$rank_same_with, n$id),
+         character(1))
+}
+
+build_dot <- function(cfg) {
+  rankdir <- if (!is.null(cfg$rankdir)) cfg$rankdir else "TB"
+  header  <- sprintf(STYLE_HEADER, rankdir)
+  nodes   <- vapply(cfg$nodes, node_line, character(1))
+  edges   <- vapply(cfg$edges, edge_line, character(1))
+  ranks   <- rank_same_lines(cfg$nodes)
+  paste(c("digraph flow {", header, nodes, edges, ranks, "}"), collapse = "\n")
+}
+
+# ---- Render -----------------------------------------------------------------
+render <- function(dot, prefix) {
+  svg <- export_svg(grViz(dot))
+  raw <- charToRaw(svg)
+  rsvg_pdf(raw, paste0(prefix, ".pdf"))
+  rsvg_png(raw, paste0(prefix, ".png"),     width = 2400)
+  rsvg_png(raw, paste0(prefix, "_600.png"), width = 4800)
+  invisible(list(pdf = paste0(prefix, ".pdf"),
+                 png = paste0(prefix, ".png"),
+                 png600 = paste0(prefix, "_600.png")))
+}
+
+main <- function() {
+  a <- parse_args()
+  cfg <- yaml::read_yaml(a$config)
+  # Type is informational for now (same style applies).
+  # Future: load type-specific defaults from references/exemplar_diagrams/<type>/template.dot
+  dot <- build_dot(cfg)
+  out <- render(dot, a$out)
+  cat(sprintf("[%s] rendered: %s + %s + %s\n",
+              a$type, out$pdf, out$png, out$png600))
+}
+
+if (!interactive()) main()