Food-Figure — Data-Driven Figure System for Food & Nutrition Science

Turn a dataset (or a described result) into the right submission-grade figure. The chart serves the scientific logic; polish is subordinate to making the core conclusion clear, defensible, and reviewable. Original work; architecture informed by open community figure skills (see the repo README Acknowledgements).

Load reference files as needed (progressive disclosure) — don't read them all up front. The map is in the frontmatter references list.

Workflow

flowchart TD
    A[Data or described result] --> B[1. Analyze the data<br/>scripts/analyze_data.py -> profile]
    B --> C[2. Recommend figures<br/>references/data-to-figure.md]
    C --> D[3. Figure contract<br/>references/figure-contract.md]
    D --> E{Backend?}
    E -- unknown --> Eq[Ask 'Python or R?' once<br/>scripts/backend_pref.py]
    E -- known --> F
    Eq --> F[4. Render<br/>python-guide.md OR r-guide.md + food-recipes.md]
    F --> G[5. Export at journal spec<br/>references/journal-specs.md]
    G --> H[6. QA<br/>references/qa-checklist.md]
    H --> OUT[Journal-ready SVG/PDF/TIFF + editable source]

1 — Analyze the data

If the user supplies a data file (CSV/TSV/Excel) or table, profile it first: run scripts/analyze_data.py <file> to get, per column, the type (numeric/categorical/datetime), cardinality, missingness, distribution summary, and the detected structure (grouping factors, repeated measures, time/dose axis, wide sensory/composition matrix). If the user only describes a result, elicit the same: what varies, what's measured, n, and the error type. See references/data-to-figure.md.

2 — Recommend the figure(s)

From the profile, propose the best figure type(s) with a one-line rationale each, and say what each would show. Prefer the figure that makes the paper's claim most directly; note honest alternatives. The decision rules and a full catalog are in references/data-to-figure.md and references/chart-types.md. Never force a chart the data can't support (e.g. bar-of-means where a distribution matters → box/violin + points).

3 — Figure contract + provenance (before code)

Fix the conclusion, evidence logic, export needs (target journal), and review risks (references/figure-contract.md). Open a figure trace card (references/figure-provenance.md): the real data source, the script that makes the figure, what it shows, and the claim it supports — so the plotted values match the reported statistics. Choose the palette by data type (references/color-palettes.md).

For a dense Figure 1/2-style request, first design the complete evidence story with references/figure-story-design.md: experimental sequence, evidence hierarchy, non-redundant panel questions, source-data map, opening schematic, and an integrated synthesis panel. Do not start by filling a grid with chart types.

4 — Backend gate (blocking)

• Data figures → Python or R (always). Resolve the backend by priority: explicit request → language of the user's input files/data → saved preference (python scripts/backend_pref.py get) → ask once ("Python or R? I'll remember this") and save it (backend_pref.py set python|r). The chosen backend does all data graphics, preview, and export; the other may only help with data prep/conversion.
• AI image route (opt-in, schematics only). Only if the user explicitly asks to generate the image with Gemini, ChatGPT, or Claude (or another named image model) — and only for conceptual visuals (mechanism diagrams, graphical abstracts, process schematics) — use that model instead. Never use an AI image model for a data-bearing figure, and never let it invent data. See references/ai-image-generation.md.

5 — Render & export

Use the selected backend's guide (python-guide.md = matplotlib/seaborn/ subplot_mosaic/statsmodels; r-guide.md = ggplot2/patchwork/ComplexHeatmap/ ggrepel + svglite/cairo_pdf/ragg) plus food-recipes.md for the food/nutrition figure types. Start from the template library — examples/python_food_figures.py or examples/r_food_figures.R — which has a ready function for every figure type; adapt it to the user's data. Export vector (PDF/SVG) for line/bar/scatter and TIFF (LZW) at the journal DPI for raster/microscopy; keep an editable source. Pull DPI, column width, font, and format from the target journal via references/journal-specs.md; if no journal is set, default to 300 dpi, ~90/190 mm widths, TIFF+PDF, Arial 7–9 pt.

6 — QA

Run references/qa-checklist.md before delivering (error bars defined + n; statistics shown consistently; axes honest; colorblind-safe; labels legible at final size; matches journal spec; every panel cited). Privacy: any code or legend you hand back must use relative paths, never local machine paths — scan with python3 scripts/privacy_scan.py (see food-paper/references/privacy-and-confidentiality.md).

Deliver

Hand back, per figure: the file(s) (vector + raster), the figure trace card, a self-contained caption (APA 7.0 or the journal's style — see references/figure-provenance.md), and the plotting code. For a .tex build, include the \includegraphics environment.

Modes

• recommend — analyze data and suggest figures, no rendering yet.
• make (default) — full pipeline to a rendered, exported figure + caption + trace card.
• revise / audit — critique or fix an existing figure against the QA checklist and journal spec.
• multi-panel — compose labelled panels (a, b, c) that share a logical thread.
• figure-story — design and render an 8–12 panel journal-style evidence narrative from experimental design through primary results, diagnostics, robustness, and an integrated conclusion.
• schematic — a graphical abstract / mechanism diagram: Python/R by default, or the opt-in AI-image route (references/ai-image-generation.md) if the user asks.

Scope

Reproducible, code-generated, submission-grade scientific figures for food & nutrition. Not for dashboards or Illustrator/Figma-first artwork. A schematic/graphical-abstract (mechanism diagram) is a drawing task: keep it in Python/R by default, or — only if the user explicitly asks — generate it with an AI image model (Gemini/ChatGPT/Claude) per references/ai-image-generation.md. Data figures are always Python/R.

Handoff

Called by food-paper's viz_designer at the journal spec; figures feed the manuscript's Results.