Alterlab Scientific Schematics

---
name: alterlab-scientific-schematics
description: Creates publication-quality scientific diagrams with Nano Banana 2 AI and smart iterative refinement, using Gemini 3.1 Pro Preview for quality review and regenerating only when quality falls below the document-type threshold. Use when the request is for a rendered technical or scientific diagram — CONSORT/PRISMA flowcharts, neural-network architectures, system/block diagrams, biological pathways, circuits, or other complex scientific visuals. For general photos, illustrations, or artwork use alterlab-generate-image; for infographics use alterlab-infographics; for editable text-based Mermaid diagrams use alterlab-mermaid. Part of the AlterLab Academic Skills suite.
allowed-tools: Read Write Edit Bash
license: MIT
compatibility: Requires an OpenRouter API key (OPENROUTER_API_KEY) and the requests library for Nano Banana 2 generation (google/gemini-3.1-flash-image) and Gemini 3.1 Pro Preview quality review (google/gemini-3.1-pro-preview); override with ALTERLAB_IMAGE_MODEL / ALTERLAB_REVIEW_MODEL
metadata:
    skill-author: AlterLab
    version: "1.1.0"
    last_updated: "2026-09-23"
---

# Scientific Schematics and Diagrams

## Overview

Scientific schematics and diagrams transform complex concepts into clear visual representations for publication. **This skill uses Nano Banana 2 AI for diagram generation with Gemini 3.1 Pro Preview quality review.**

**How it works:**
- Describe your diagram in natural language
- Nano Banana 2 generates publication-quality images automatically
- **Gemini 3.1 Pro Preview reviews quality** against document-type thresholds
- **Smart iteration**: Only regenerates if quality is below threshold
- Publication-ready output in minutes
- No coding, templates, or manual drawing required

**Quality Thresholds by Document Type:**
| Document Type | Threshold | Description |
|---------------|-----------|-------------|
| journal | 8.5/10 | Nature, Science, peer-reviewed journals |
| conference | 8.0/10 | Conference papers |
| thesis | 8.0/10 | Dissertations, theses |
| grant | 8.0/10 | Grant proposals |
| preprint | 7.5/10 | arXiv, bioRxiv, etc. |
| report | 7.5/10 | Technical reports |
| poster | 7.0/10 | Academic posters |
| presentation | 6.5/10 | Slides, talks |
| default | 7.5/10 | General purpose |

**Simply describe what you want, and Nano Banana 2 creates it.** All diagrams are stored in the figures/ subfolder and referenced in papers/posters.

## Quick Start: Generate Any Diagram

Create any scientific diagram by simply describing it. Nano Banana 2 handles everything automatically with **smart iteration**:

```bash
# Generate for journal paper (highest quality threshold: 8.5/10)
python scripts/generate_schematic.py "CONSORT participant flow diagram with 500 screened, 150 excluded, 350 randomized" -o figures/consort.png --doc-type journal

# Generate for presentation (lower threshold: 6.5/10 - faster)
python scripts/generate_schematic.py "Transformer encoder-decoder architecture showing multi-head attention" -o figures/transformer.png --doc-type presentation

# Generate for poster (moderate threshold: 7.0/10)
python scripts/generate_schematic.py "MAPK signaling pathway from EGFR to gene transcription" -o figures/mapk_pathway.png --doc-type poster

# Custom max iterations (max 2)
python scripts/generate_schematic.py "Complex circuit diagram with op-amp, resistors, and capacitors" -o figures/circuit.png --iterations 2 --doc-type journal
```

**What happens behind the scenes:**
1. **Generation 1**: Nano Banana 2 creates initial image following scientific diagram best practices
2. **Review 1**: **Gemini 3.1 Pro Preview** evaluates quality against document-type threshold
3. **Decision**: If quality >= threshold → **DONE** (no more iterations needed!)
4. **If below threshold**: Improved prompt based on critique, regenerate
5. **Repeat**: Until quality meets threshold OR max iterations reached

**Smart Iteration Benefits:**
- ✅ Saves API calls if first generation is good enough
- ✅ Higher quality standards for journal papers
- ✅ Faster turnaround for presentations/posters
- ✅ Appropriate quality for each use case

**Output**: Versioned images plus a detailed review log with quality scores, critiques, and early-stop information. If the review call fails, the image is kept and the log records `"review_skipped": true` with a null score instead of inventing one.

**Check the content yourself before submission.** The image model draws every label and number, so it can misspell a term or change a count (e.g. a CONSORT `n=`) even when the prompt was right, and the review model judges clarity and layout rather than checking values against your records. Compare every count, label, and arrow direction with your data and protocol before the figure goes into a manuscript.

### Configuration

Set your OpenRouter API key (or put `OPENROUTER_API_KEY=...` in a `.env` file if `python-dotenv` is installed):
```bash
export OPENROUTER_API_KEY='your_api_key_here'
```

Get an API key at: https://openrouter.ai/keys

Default models (verified on OpenRouter 2026-09-23): `google/gemini-3.1-flash-image` (Nano Banana 2) for generation and `google/gemini-3.1-pro-preview` for review. Override them with `ALTERLAB_IMAGE_MODEL` / `ALTERLAB_REVIEW_MODEL`.

### Data & privacy

This skill's generation scripts (`scripts/generate_schematic_ai.py`) send your diagram description / prompt to a **third-party API (OpenRouter)** over the network for image generation and quality review. Your text prompts — and any details you include in them — leave your machine and are processed by an external provider. **Do not include confidential, clinical, patient-identifying, or unpublished proprietary content** in figure descriptions. Describe figures generically and add sensitive labels locally afterward if needed.

### AI Generation Best Practices

Good prompts are specific: name the diagram **type**, **components**, **flow/direction**,
**labels**, and **style**. Vague prompts ("make a flowchart", "neural network") underperform.
Scientific quality guidelines (clean background, ≥10pt labels, sans-serif, Okabe-Ito palette,
proper spacing) are applied automatically. Good/bad prompt examples and the full guideline
list are in `references/ai_generation_guide.md`.

## When to Use This Skill

This skill should be used when:
- Creating neural network architecture diagrams (Transformers, CNNs, RNNs, etc.)
- Illustrating system architectures and data flow diagrams
- Drawing methodology flowcharts for study design (CONSORT, PRISMA)
- Visualizing algorithm workflows and processing pipelines
- Creating circuit diagrams and electrical schematics
- Depicting biological pathways and molecular interactions
- Generating network topologies and hierarchical structures
- Illustrating conceptual frameworks and theoretical models
- Designing block diagrams for technical papers

### Does NOT Trigger

| Scenario | Use Instead |
|----------|-------------|
| Diagram that should stay editable text in a README or Markdown doc (renders on GitHub, diffs in git) | `alterlab-mermaid` |
| Photo, illustration, artwork, or slide/poster hero image | `alterlab-generate-image` |
| Infographic that presents statistics, a timeline, or a comparison for a general audience | `alterlab-infographics` |
| Plot of measured data (scatter, bar, line, heatmap) | `alterlab-matplotlib` / `alterlab-scientific-viz` |
| Network graph whose layout is computed from real node/edge data | `alterlab-networkx` |

## How to Use This Skill

**Simply describe your diagram in natural language.** Nano Banana 2 generates it automatically:

```bash
python scripts/generate_schematic.py "your diagram description" -o output.png
```

**That's it!** The AI handles:
- ✓ Layout and composition
- ✓ Labels and annotations
- ✓ Colors and styling
- ✓ Quality review and refinement
- ✓ Publication-ready output

**Works for all diagram types:**
- Flowcharts (CONSORT, PRISMA, etc.)
- Neural network architectures
- Biological pathways
- Circuit diagrams
- System architectures
- Block diagrams
- Any scientific visualization

**No coding, no templates, no manual drawing required.**

---

# AI Generation Mode (Nano Banana 2 + Gemini 3.1 Pro Preview Review)

The AI generation system uses **smart iteration**: Nano Banana 2 generates an image, Gemini 3.1
Pro Preview scores it (0-10 across scientific accuracy, clarity, label quality, layout, and
professional appearance), and the system **stops early** once the score meets the document-type
threshold — otherwise it improves the prompt from the critique and regenerates (max 2 iterations).
Every run writes a JSON review log with per-iteration scores, critiques, and early-stop info.

The deep dive — iteration flowchart, review rubric, example review output, decision table, JSON
log schema, the `ScientificSchematicGenerator` Python API, all command-line options, and prompt
engineering tips — is in `references/ai_generation_guide.md`.

Copy-and-adapt worked invocations for CONSORT flowcharts, transformer architectures, biological
pathways, and system block diagrams are in `references/generation_examples.md`.

---

## Command-Line Usage

The main entry point for generating scientific schematics:

```bash
# Basic usage
python scripts/generate_schematic.py "diagram description" -o output.png

# Custom iterations (max 2)
python scripts/generate_schematic.py "complex diagram" -o diagram.png --iterations 2

# Verbose mode
python scripts/generate_schematic.py "diagram" -o out.png -v
```

**Note:** The Nano Banana 2 AI generation system includes automatic quality review in its iterative refinement process. Each iteration is evaluated for scientific accuracy, clarity, and accessibility.

## Best Practices Summary

Design for **clarity over complexity**, consistent styling, colorblind accessibility (Okabe-Ito,
redundant encoding), ≥7-8 pt sans-serif type, and vector output (PDF/SVG; 300+ DPI for raster).
Integrate with LaTeX via `\includegraphics{}`, caption thoroughly, reference in text, and keep
prompts + outputs under version control. The full design/technical/integration checklist and the
pre-submission verification checklist are in `references/submission_checklist.md`.

## Troubleshooting Common Issues

For fixes to AI generation problems (overlaps, poor connections), image-quality issues,
quality-check failures, and accessibility problems (grayscale contrast, small text), see
`references/troubleshooting.md`. Most issues resolve by making the prompt more specific or
raising `--iterations 2`.

## Resources and References

### Detailed References

Load these files for comprehensive information on specific topics:

- **`references/ai_generation_guide.md`** - Smart-iteration workflow, review rubric, Python API, CLI options, prompt engineering
- **`references/generation_examples.md`** - Worked CLI invocations (CONSORT, transformer, pathway, system diagrams)
- **`references/troubleshooting.md`** - Fixes for generation, quality-check, and accessibility issues
- **`references/submission_checklist.md`** - Best-practices summary and pre-submission verification checklist
- **`references/diagram_types.md`** - Catalog of scientific diagram types with examples
- **`references/best_practices.md`** - Publication standards and accessibility guidelines

### External Resources

**Python Libraries**
- Schemdraw Documentation: https://schemdraw.readthedocs.io/
- NetworkX Documentation: https://networkx.org/documentation/
- Matplotlib Documentation: https://matplotlib.org/

**Publication Standards**
- Nature Figure Guidelines: https://www.nature.com/nature/for-authors/final-submission
- Science Figure Guidelines: https://www.science.org/content/page/instructions-preparing-initial-manuscript
- CONSORT Diagram: https://www.consort-spirit.org/

## Integration with Other Skills

This skill works synergistically with:

- **`alterlab-scientific-writing`** - Diagrams follow figure best practices
- **`alterlab-scientific-viz`** - Shares color palettes and styling
- **`alterlab-latex-posters`** - Generate diagrams for poster presentations
- **`alterlab-research-grants`** - Methodology diagrams for proposals
- **`alterlab-peer-review`** - Evaluate diagram clarity and accessibility

## Quick Reference Checklist

Before submitting diagrams, run through the full checklist (visual quality, accessibility,
typography, publication standards, required quality verification, documentation/version control,
and final integration) in `references/submission_checklist.md`.

## Environment Setup

```bash
# Required
export OPENROUTER_API_KEY='your_api_key_here'

# Get key at: https://openrouter.ai/keys
```

## Getting Started

**Simplest possible usage:**
```bash
python scripts/generate_schematic.py "your diagram description" -o output.png
```

---

Use this skill to create clear, accessible, publication-quality diagrams that effectively communicate complex scientific concepts. The AI-powered workflow with iterative refinement ensures diagrams meet professional standards.