scientific-schematics

name	scientific-schematics
description	Create publication-quality scientific diagrams using Nano Banana Pro AI with iterative refinement. AI generation is the default method for all diagram types. Generates high-fidelity images with automatic quality review. Specialized in neural network architectures, system diagrams, flowcharts, biological pathways, and complex scientific visualizations.
allowed-tools	["Read","Write","Edit","Bash"]

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:

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

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:

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:

{
  "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,
       
    
  
   

Advanced AI Generation Usage

Python API

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(
    user_prompt="Transformer architecture diagram",
    output_path="figures/transformer.png",
    iterations=3
)

# Access results
print(f"Final score: {results['final_score']}/10")
print(f"Final image: {results['final_image']}")

# Review individual iterations
for iteration in results['iterations']:
    print(f"Iteration {iteration['iteration']}: {iteration['score']}/10")
    print(f"Critique: {iteration['critique']}")

Command-Line Options

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

# Custom iterations (1-10)
python scripts/generate_schematic.py "complex diagram" -o diagram.png --iterations 5

# Verbose output (see all API calls and reviews)
python scripts/generate_schematic.py "flowchart" -o flow.png -v

# Provide API key via flag
python scripts/generate_schematic.py "diagram" -o out.png --api-key "sk-or-v1-..."

Prompt Engineering Tips

1. Be Specific About Layout:

✓ "Flowchart with vertical flow, top to bottom"
✓ "Architecture diagram with encoder on left, decoder on right"
✓ "Circular pathway diagram with clockwise flow"

2. Include Quantitative Details:

✓ "Neural network with input layer (784 nodes), hidden layer (128 nodes), output (10 nodes)"
✓ "Flowchart showing n=500 screened, n=150 excluded, n=350 randomized"
✓ "Circuit with 1kΩ resistor, 10µF capacitor, 5V source"

3. Specify Visual Style:

✓ "Minimalist block diagram with clean lines"
✓ "Detailed biological pathway with protein structures"
✓ "Technical schematic with engineering notation"

4. Request Specific Labels:

✓ "Label all arrows with activation/inhibition"
✓ "Include layer dimensions in each box"
✓ "Show time progression with timestamps"

5. Mention Color Requirements:

✓ "Use colorblind-friendly colors"
✓ "Grayscale-compatible design"
✓ "Color-code by function: blue for input, green for processing, red for output"

AI Generation Examples

Example 1: CONSORT Flowchart

python scripts/generate_schematic.py \
  "CONSORT participant flow diagram for randomized controlled trial. \
   Start with 'Assessed for eligibility (n=500)' at top. \
   Show 'Excluded (n=150)' with reasons: age<18 (n=80), declined (n=50), other (n=20). \
   Then 'Randomized (n=350)' splits into two arms: \
   'Treatment group (n=175)' and 'Control group (n=175)'. \
   Each arm shows 'Lost to follow-up' (n=15 and n=10). \
   End with 'Analyzed' (n=160 and n=165). \
   Use blue boxes for process steps, orange for exclusion, green for final analysis." \
  -o figures/consort.png

Example 2: Neural Network Architecture

python scripts/generate_schematic.py \
  "Transformer encoder-decoder architecture diagram. \
   Left side: Encoder stack with input embedding, positional encoding, \
   multi-head self-attention, add & norm, feed-forward, add & norm. \
   Right side: Decoder stack with output embedding, positional encoding, \
   masked self-attention, add & norm, cross-attention (receiving from encoder), \
   add & norm, feed-forward, add & norm, linear & softmax. \
   Show cross-attention connection from encoder to decoder with dashed line. \
   Use light blue for encoder, light red for decoder. \
   Label all components clearly." \
  -o figures/transformer.png --iterations 3

Example 3: Biological Pathway

python scripts/generate_schematic.py \
  "MAPK signaling pathway diagram. \
   Start with EGFR receptor at cell membrane (top). \
   Arrow down to RAS (with GTP label). \
   Arrow to RAF kinase. \
   Arrow to MEK kinase. \
   Arrow to ERK kinase. \
   Final arrow to nucleus showing gene transcription. \
   Label each arrow with 'phosphorylation' or 'activation'. \
   Use rounded rectangles for proteins, different colors for each. \
   Include membrane boundary line at top." \
  -o figures/mapk_pathway.png

Example 4: System Architecture

python scripts/generate_schematic.py \
  "IoT system architecture block diagram. \
   Bottom layer: Sensors (temperature, humidity, motion) in green boxes. \
   Middle layer: Microcontroller (ESP32) in blue box. \
   Connections to WiFi module (orange box) and Display (purple box). \
   Top layer: Cloud server (gray box) connected to mobile app (light blue box). \
   Show data flow arrows between all components. \
   Label connections with protocols: I2C, UART, WiFi, HTTPS." \
  -o figures/iot_architecture.png

---

Additional Tools

TikZ Compilation (compile_tikz.py)

If you have existing TikZ .tex files that need compilation:

# Compile TikZ diagram to PDF
python scripts/compile_tikz.py diagram.tex -o diagram.pdf

# Compile and generate PNG
python scripts/compile_tikz.py diagram.tex --png --dpi 300

# Compile and preview
python scripts/compile_tikz.py diagram.tex --preview

For details on using compile_tikz.py, run:

python scripts/compile_tikz.py --help

---

Unified Entry Point: generate_schematic.py

The main entry point supports both AI and code-based generation:

# AI generation (default)
python scripts/generate_schematic.py "diagram description" -o output.png

# Explicit AI method
python scripts/generate_schematic.py "diagram description" -o output.png --method ai

# Code-based generation
python scripts/generate_schematic.py "1. Step one\n2. Step two" -o flow.tex --method code --type flowchart

# Custom iterations for AI
python scripts/generate_schematic.py "complex diagram" -o diagram.png --iterations 5

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

Method Selection:

• --method ai: Use Nano Banana Pro with iterative refinement (default)
• --method code: Use traditional code-based generation

Code-Based Types:

• --type flowchart: Generate TikZ flowchart
• --type circuit: Generate circuit diagram
• --type pathway: Generate biological pathway

Helper Scripts

compile_tikz.py

Standalone TikZ compilation utility with quality checks:

# Compile TikZ to PDF with verification
python scripts/compile_tikz.py flowchart.tex -o flowchart.pdf --verify

# Generate PNG with quality report
python scripts/compile_tikz.py flowchart.tex -o flowchart.pdf --png --dpi 300 --verify

# Preview with quality overlay
python scripts/compile_tikz.py flowchart.tex --preview --show-quality

Note: The Nano Banana Pro 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 Principles

1. Clarity over complexity - Simplify, remove unnecessary elements
2. Consistent styling - Use templates and style files
3. Colorblind accessibility - Use Okabe-Ito palette, redundant encoding
4. Appropriate typography - Sans-serif fonts, minimum 7-8 pt
5. Vector format - Always use PDF/SVG for publication

Technical Requirements

1. Resolution - Vector preferred, or 300+ DPI for raster
2. File format - PDF for LaTeX, SVG for web, PNG as fallback
3. Color space - RGB for digital, CMYK for print (convert if needed)
4. Line weights - Minimum 0.5 pt, typical 1-2 pt
5. Text size - 7-8 pt minimum at final size

Integration Guidelines

1. Include in LaTeX - Use \input{} for TikZ, \includegraphics{} for external
2. Caption thoroughly - Describe all elements and abbreviations
3. Reference in text - Explain diagram in narrative flow
4. Maintain consistency - Same style across all figures in paper
5. Version control - Keep source files (.tex, .py) in repository

Troubleshooting Common Issues

TikZ Compilation Errors

Problem: ! Package tikz Error: I do not know the key '/tikz/...

• Solution: Missing library - add \usetikzlibrary{...} to preamble

Problem: Overlapping text or elements

• Solution: Use AI generation which automatically handles spacing
• Solution: Increase iterations: --iterations 5 for better refinement
• Solution: Use auto_spacing=True in pathway generator for automatic adjustment

Problem: Arrows not connecting properly

• Solution: Use anchor points: (node.east), (node.north), etc.
• Solution: Check overlap report for arrow/node intersections

Python Generation Issues

Problem: Schemdraw elements not aligning

• Solution: Use .at() method for precise positioning
• Solution: Enable auto_spacing to prevent overlaps

Problem: Matplotlib text rendering issues

• Solution: Set plt.rcParams['text.usetex'] = True for LaTeX rendering
• Solution: Ensure LaTeX installation is available

Problem: Export quality poor

• Solution: AI generation produces high-quality images automatically
• Solution: For TikZ, use: python scripts/compile_tikz.py diagram.tex --png --dpi 300

Problem: Elements overlap after generation

• Solution: Run detect_overlaps() function to identify problem regions
• Solution: Use iterative refinement: iterative_diagram_refinement(create_function)
• Solution: Increase spacing between elements by 20-30%

Quality Check Issues

Problem: False positive overlap detection

• Solution: Adjust threshold: detect_overlaps(image_path, threshold=0.98)
• Solution: Manually review flagged regions in visual report

Problem: Generated image quality is low

• Solution: AI generation produces high-quality images by default
• Solution: Increase iterations for better results: --iterations 5

Problem: Colorblind simulation shows poor contrast

• Solution: Switch to Okabe-Ito palette explicitly in code
• Solution: Add redundant encoding (shapes, patterns, line styles)
• Solution: Increase color saturation and lightness differences

Problem: High-severity overlaps detected

• Solution: Review overlap_report.json for exact positions
• Solution: Increase spacing in those specific regions
• Solution: Re-run with adjusted parameters and verify again

Problem: Visual report generation fails

• Solution: Check Pillow and matplotlib installations
• Solution: Ensure image file is readable: Image.open(path).verify()
• Solution: Check sufficient disk space for report generation

Accessibility Problems

Problem: Colors indistinguishable in grayscale

• Solution: Run accessibility checker: verify_accessibility(image_path)
• Solution: Add patterns, shapes, or line styles for redundancy
• Solution: Increase contrast between adjacent elements

Problem: Text too small when printed

• Solution: Run resolution validator: validate_resolution(image_path)
• Solution: Design at final size, use minimum 7-8 pt fonts
• Solution: Check physical dimensions in resolution report

Problem: Accessibility checks consistently fail

• Solution: Review accessibility_report.json for specific failures
• Solution: Increase color contrast by at least 20%
• Solution: Test with actual grayscale conversion before finalizing

Resources and References

Detailed References

Load these files for comprehensive information on specific topics:

• references/tikz_guide.md - Complete TikZ syntax, positioning, styles, and techniques
• references/diagram_types.md - Catalog of scientific diagram types with examples
• references/best_practices.md - Publication standards and accessibility guidelines
• references/python_libraries.md - Guide to Schemdraw, NetworkX, and Matplotlib for diagrams

External Resources

TikZ and LaTeX

• TikZ & PGF Manual: https://pgf-tikz.github.io/pgf/pgfmanual.pdf
• TeXample.net: http://www.texample.net/tikz/ (examples gallery)
• CircuitikZ Manual: https://ctan.org/pkg/circuitikz

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: http://www.consort-statement.org/consort-statement/flow-diagram

Integration with Other Skills

This skill works synergistically with:

• Scientific Writing - Diagrams follow figure best practices
• Scientific Visualization - Shares color palettes and styling
• LaTeX Posters - Reuse TikZ styles for poster diagrams
• Research Grants - Methodology diagrams for proposals
• Peer Review - Evaluate diagram clarity and accessibility

Quick Reference Checklist

Before submitting diagrams, verify:

Visual Quality

• High-quality image format (PNG from AI generation)
• No overlapping elements (AI handles automatically)
• Adequate spacing between all components (AI optimizes)
• Clean, professional alignment
• All arrows connect properly to intended targets

Accessibility

• Colorblind-safe palette (Okabe-Ito) used
• Works in grayscale (tested with accessibility checker)
• Sufficient contrast between elements (verified)
• Redundant encoding where appropriate (shapes + colors)
• Colorblind simulation passes all checks

Typography and Readability

• Text minimum 7-8 pt at final size
• All elements labeled clearly and completely
• Consistent font family and sizing
• No text overlaps or cutoffs
• Units included where applicable

Publication Standards

• Consistent styling with other figures in manuscript
• Comprehensive caption written with all abbreviations defined
• Referenced appropriately in manuscript text
• Meets journal-specific dimension requirements
• Exported in required format for journal (PDF/EPS/TIFF)

Quality Verification (Required)

• Ran run_quality_checks() and achieved PASS status
• Reviewed overlap detection report (zero high-severity overlaps)
• Passed accessibility verification (grayscale and colorblind)
• Resolution validated at target DPI (300+ for print)
• Visual quality report generated and reviewed
• All quality reports saved with figure files

Documentation and Version Control

• Source files (.tex, .py) saved for future revision
• Quality reports archived in quality_reports/ directory
• Configuration parameters documented (colors, spacing, sizes)
• Git commit includes source, output, and quality reports
• README or comments explain how to regenerate figure

Final Integration Check

• Figure displays correctly in compiled manuscript
• Cross-references work (\ref{} points to correct figure)
• Figure number matches text citations
• Caption appears on correct page relative to figure
• No compilation warnings or errors related to figure

Summary: AI vs Code-Based Generation

Quick Decision Guide

Choose AI Generation (Nano Banana Pro) if:

• ✓ Speed is important (get results in minutes)
• ✓ You want automatic quality review and refinement
• ✓ The diagram is complex with many visual elements
• ✓ You prefer natural language over coding
• ✓ You need publication-ready images immediately
• ✓ You're exploring different design options

Choose Code-Based Generation if:

• ✓ You need exact reproducibility from source code
• ✓ You want version control for the diagram source
• ✓ You're generating many similar diagrams programmatically
• ✓ You need LaTeX-native TikZ integration
• ✓ You want pixel-perfect control over every element
• ✓ The diagram is generated from data/algorithms

Workflow Comparison

Aspect	AI Generation	Code-Based
Time to first result	2-3 minutes	15-30 minutes
Iterations	Automatic (3 rounds)	Manual
Quality review	Automatic by AI	Manual or scripted
Customization	Natural language	Full programmatic control
Reproducibility	Prompt-based	Code-based (exact)
Learning curve	Low (just describe)	Medium-High (learn libraries)
Output format	PNG/JPG	PDF/SVG/EPS/PNG
Version control	Prompt + images	Source code + outputs
Best for	Quick iteration, complex visuals	Reproducible research, data-driven

Hybrid Approach (Recommended)

Many users find success with a hybrid workflow:

1. Prototype with AI: Generate initial designs quickly using natural language
2. Review and refine: Use the AI's iterative refinement to get close to final
3. Recreate in code (optional): If exact reproducibility is needed, recreate the approved design in code
4. Version control: Keep both the AI prompts and code versions

Environment Setup

For AI Generation:

# Required
export OPENROUTER_API_KEY='your_api_key_here'

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

For Code-Based Generation:

# Install Graphviz
brew install graphviz  # macOS
sudo apt-get install graphviz  # Linux

# Install Python packages
pip install graphviz schemdraw networkx matplotlib

Getting Started

Simplest possible usage (AI):

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

Simplest possible usage (Code):

python scripts/generate_schematic.py "1. Step one\n2. Step two" -o flow.tex --method code

---

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, while the code-based approach provides exact reproducibility for research publications.