scientific-schematics

What this skill does

# Scientific Schematics and Diagrams

## Overview

Scientific schematics and diagrams transform complex concepts into clear visual representations for publication. **This skill uses Nano Banana Pro AI for all diagram generation.**

**How it works:**
- Describe your diagram in natural language
- Nano Banana Pro generates publication-quality images automatically
- Automatic iterative refinement (3 iterations by default)
- Built-in quality review and improvement
- Publication-ready output in minutes
- No coding, templates, or manual drawing required

**Simply describe what you want, and Nano Banana Pro 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 Pro handles everything automatically:

```bash
# Generate any scientific diagram from a description
python scripts/generate_schematic.py "CONSORT participant flow diagram with 500 screened, 150 excluded, 350 randomized" -o figures/consort.png

# Neural network architecture
python scripts/generate_schematic.py "Transformer encoder-decoder architecture showing multi-head attention, feed-forward layers, and residual connections" -o figures/transformer.png

# Biological pathway
python scripts/generate_schematic.py "MAPK signaling pathway from EGFR to gene transcription" -o figures/mapk_pathway.png

# Custom iterations for complex diagrams
python scripts/generate_schematic.py "Complex circuit diagram with op-amp, resistors, and capacitors" -o figures/circuit.png --iterations 5
```

**What happens behind the scenes:**
1. **Generation 1**: Nano Banana Pro creates initial image following scientific diagram best practices
2. **Review 1**: AI evaluates clarity, labels, accuracy, and accessibility
3. **Generation 2**: Improved prompt based on critique, regenerate
4. **Review 2**: Second evaluation with specific feedback
5. **Generation 3**: Final polished version addressing all critiques

**Output**: Three versions (v1, v2, v3) plus a detailed review log with quality scores and critiques.

### Configuration

Set your OpenRouter API key:
```bash
export OPENROUTER_API_KEY='your_api_key_here'
```

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

### AI Generation Best Practices

**Effective Prompts for Scientific Diagrams:**

✓ **Good prompts** (specific, detailed):
- "CONSORT flowchart showing participant flow from screening (n=500) through randomization to final analysis"
- "Transformer neural network architecture with encoder stack on left, decoder stack on right, showing multi-head attention and cross-attention connections"
- "Biological signaling cascade: EGFR receptor → RAS → RAF → MEK → ERK → nucleus, with phosphorylation steps labeled"
- "Block diagram of IoT system: sensors → microcontroller → WiFi module → cloud server → mobile app"

✗ **Avoid vague prompts**:
- "Make a flowchart" (too generic)
- "Neural network" (which type? what components?)
- "Pathway diagram" (which pathway? what molecules?)

**Key elements to include:**
- **Type**: Flowchart, architecture diagram, pathway, circuit, etc.
- **Components**: Specific elements to include
- **Flow/Direction**: How elements connect (left-to-right, top-to-bottom)
- **Labels**: Key annotations or text to include
- **Style**: Any specific visual requirements

**Scientific Quality Guidelines** (automatically applied):
- Clean white/light background
- High contrast for readability
- Clear, readable labels (minimum 10pt)
- Professional typography (sans-serif fonts)
- Colorblind-friendly colors (Okabe-Ito palette)
- Proper spacing to prevent crowding
- Scale bars, legends, axes where appropriate

## Classic Code-Based Generation

For reproducible, version-controlled diagrams with full programmatic control, use the traditional code-based approach.

## 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

## How to Use This Skill

**Simply describe your diagram in natural language.** Nano Banana Pro 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 Pro)

## Iterative Refinement Workflow

The AI generation system uses a sophisticated three-iteration refinement process:

### Iteration 1: Initial Generation
**Prompt Construction:**
```
Scientific diagram guidelines + User request
```

**Example internal prompt:**
```
Create a high-quality scientific diagram with:
- Clean white background
- High contrast for readability
- Clear labels (minimum 10pt font)
- Professional typography
- Colorblind-friendly colors
- Proper spacing

USER REQUEST: CONSORT participant flow diagram showing screening, 
exclusion, randomization, and analysis phases with participant counts
```

**Output:** `diagram_v1.png`

### Iteration 2: Review and Improve
**AI Quality Review:**
- Evaluates scientific accuracy
- Checks label clarity and readability
- Assesses layout and composition
- Verifies accessibility (grayscale, colorblind)
- Assigns quality score (0-10)
- Provides specific improvement suggestions

**Example critique:**
```
Score: 7/10

Strengths:
- Clear flow from top to bottom
- Good use of colors
- All phases labeled

Issues:
- Participant counts (n=X) are too small to read
- "Excluded" box overlaps with arrow
- Would benefit from reasons for exclusion

Suggestions:
- Increase font size for all numbers to at least 12pt
- Add more vertical spacing between boxes
- Include exclusion criteria in a separate annotation box
```

**Improved Prompt:**
```
[Original guidelines + user request]

ITERATION 2: Address these improvements:
- Increase font size for participant counts to 12pt minimum
- Add vertical spacing to prevent overlaps
- Include exclusion criteria in annotation box
```

**Output:** `diagram_v2.png`

### Iteration 3: Final Polish
**Second Review:**
- Verifies improvements were implemented
- Checks for any remaining issues
- Final quality assessment

**Final Generation:**
- Incorporates all feedback
- Produces publication-ready diagram

**Output:** `diagram_v3.png` (final version)

### Review Log
All iterations are saved with a JSON review log:
```json
{
  "user_prompt": "CONSORT participant flow diagram...",
  "iterations": [
    {
      "iteration": 1,
      "image_path": "figures/consort_v1.png",
      "score": 7.0,
      "critique": "..."
    },
    {
      "iteration": 2,
      "image_path": "figures/consort_v2.png",
      "score": 8.5,
      "critique": "..."
    },
    {
      "iteration": 3,
      "image_path": "figures/consort_v3.png",
      "score": 9.5,
      "critique": "..."
    }
  ],
  "final_score": 9.5
}
```

## Advanced AI Generation Usage

### Python API

```python
from scripts.generate_schematic_ai import ScientificSchematicGenerator

# Initialize generator
generator = ScientificSchematicGenerator(
    api_key="your_openrouter_key",
    verbose=True
)

# Generate with iterative refinement
results = generator.generate_iterative(
    us