​

Reports and Presentations

​

Report Generation Flow

1. When the report is created — The Markdown report is generated after the analysis pipeline finishes. The backend (Synthesizer) has access to: results directory, plan steps (names, descriptions, code, outputs), conversation, and the list of output files (figures, tables, etc.).
2. Scan and order — The report generator scans the results directory and groups files by step folder. It builds an ordered figure list: figures are sorted by (step folder order, then file name). Each figure gets a global index 1, 2, …, N. This order is used in both the report and the PPT so “Figure 3” always refers to the same image.
3. Caption source — If an LLM is configured, the generator may call a dedicated caption API (e.g. one LLM call with the list of figure filenames and step context) to get a title and explanation for each figure. If the call fails or no LLM is available, a template caption is used (e.g. auto-description from filename + “This figure shows the results for this step”).
4. Report path — LLM path: the generator sends the full context (including “Figure 1: name → url”, etc.) to the LLM and asks it to write the full report with Figure N, subtitle, and explanation for every figure. Template path: the generator fills sections (Summary, Dataset, Methods, Results, Discussion, Output Files, References) and, for each figure in order, writes “Figure N. title”, “explanation”, and “”. Optionally, a post-processing step ensures every image in the final Markdown is preceded by a Figure N block (so even LLM output is normalized).
5. Save — The Markdown is saved under the project’s results directory (e.g. report_<title>.md). The UI can then show it in the Result Viewer and offer download/export.

1. The frontend calls POST /projects/{project_id}/generate-pptx.
2. The backend uses the same results directory and the same ordered figure list as the report. It optionally calls the same or a similar LLM to get a presentation title, background text, and figure captions (keyed by filename).
3. It builds the deck: title slide, background, methods/results slides (with step descriptions and figure slides), discussion, conclusion. On figure slides, each image is labeled Figure N. Caption using the global index and the caption map.
4. The .pptx is saved and the UI either returns a download link or streams the file. Preview: when you open the PPT preview, the backend reads the generated .pptx, extracts embedded images per slide, and serves them so the in-page preview matches the downloaded file.

​

Logic: Figure Ordering, Caption Source, and Paths

• Figure order — Determined only by (1) the order of step folders in the results directory (e.g. 01_load_and_qc, 02_normalize, …), and (2) within each folder, the alphabetical order of figure file names. No manual reordering is applied; the same logic runs for both report and PPT so numbering is identical.
• When LLM is used for captions — For the report, if an LLM is available, the template path can still call _generate_figure_captions_llm once with the ordered list of (figure_entry, index) and get back a list of { title, explanation }. For the PPT, the same LLM is called (e.g. _get_pptx_title_and_captions) with figure filenames and step descriptions to get a map filename → caption. So report and PPT can share the same caption semantics; the report uses “title + explanation”, the PPT uses a single line per figure from the same source when possible.
• When template is used — If no LLM is configured or the caption call fails, each figure gets: title = auto-description from filename (e.g. “QC spatial plot”); explanation = “This figure shows the results for this step.” The report and PPT still use the same ordering so Figure N is consistent.
• Post-processing — Some pipelines optionally run a pass over the final Markdown: for each known figure URL, find the corresponding ![...](url) and, if the preceding text does not already contain “Figure N.”, insert “Figure N. title\n\nexplanation\n\n” before the image. This guarantees that even if the LLM omits a caption, the output still meets the Nature-style requirement.

​

Report Structure

​

Figure Numbering and Captions (Nature-Style)

• Order — Figures are numbered globally in the order they appear in the report (by analysis step order, then by file name within each step). The same order is used in the PowerPoint so “Figure 3” in the report corresponds to “Figure 3” on a slide.
• Format — For each figure the report includes:
  1. Figure N. — Bold label.
  2. Subtitle — One short line (sentence case), e.g. “QC metrics across spatial spots.”
  3. Explanation — One or two sentences describing what the figure shows and how to interpret it.
  4. Image — The figure file embedded via Markdown ![Figure N](url).

**Figure 1.** Quality control metrics across spatial spots.

Violin plots show the distribution of genes per spot, total counts, and mitochondrial percentage. No spots were excluded, indicating high-quality preparation and sequencing.

![Figure 1](.../qc_spatial.png)

• Caption source — When an LLM is available (e.g. for report or PPT generation), the framework can generate subtitles and explanations from the figure filenames and analysis context. Otherwise, a template caption (e.g. “This figure shows the results for this step”) and the file’s auto-description are used.

​

Report Generation Paths

• LLM path — If an LLM is configured, the report can be authored by the model using the full context (plan steps, code, outputs, file list). The system prompt instructs the model to use Figure 1, Figure 2, … with subtitle and explanation for every figure.
• Template path — If no LLM is available or LLM report generation fails, a structured template is used. The template fills in the same sections and injects Figure N, subtitle, and explanation for each figure using the ordered figure list and (optionally) LLM-generated captions from a dedicated caption call.
• Post-processing — The pipeline can ensure that every embedded figure in the final Markdown has a corresponding “Figure N. subtitle + explanation” block so that even LLM-generated reports meet the same standard when the model omits captions.

​

PowerPoint Generation

• Trigger — From the Web UI, you can generate a PowerPoint from the current project’s results (e.g. “Download” or “Generate PPT” in the result viewer or project actions). The backend calls the report generator’s PPTX module with the same results directory and optional LLM.
• Structure — The deck follows a Nature-style outline: Background, Methods, Results (with figure slides), Discussion, Conclusion. Body text uses 18 pt; footer (author, institution, date) uses 14 pt.
• Figure slides — Figures are placed on slides (e.g. two per slide when space allows). Each figure’s caption on the slide uses the same global numbering: Figure N. Caption. Captions come from the same LLM call used for the report (when available) or from auto-description.
• Preview — The in-page “PPT preview” uses the same .pptx file: the backend extracts embedded images from the generated file and serves them so the preview matches the downloaded deck.

​

Export Formats

• Report — Markdown (.md) is the primary format. You can export to:
  • HTML — Styled page with embedded images.
  • PDF — Rendered from HTML (e.g. for printing or submission).
  • Word — .docx with embedded images and basic formatting.
• Presentation — Single .pptx file; download from the UI or via API.

​

API Endpoints

​

Next Steps

• Web UI — How to view reports and download PPT in the UI.
• Self-Correction — Report quality and self-refinement.
• Provenance and Reproducibility — How results and reports are tracked.