PaperBanana Documentation

PaperBanana uses uv for Python package management. Follow these steps to set up your environment:

1. Clone the repository:

   git clone https://github.com/dwzhu-pku/PaperBanana.git
   cd PaperBanana

2. Create and activate a virtual environment:

   uv venv
   source .venv/bin/activate  # On Windows use: .venv\Scripts\activate

3. Install Python 3.12:

   uv python install 3.12

4. Install required dependencies:

   uv pip install -r requirements.txt

The Streamlit demo offers two main workflows:

1. Generate Candidates Tab: Paste method content (Markdown) and a figure caption, configure settings (pipeline mode, retrieval, etc.), and click "Generate Candidates".
2. Refine Image Tab: Upload a generated candidate or diagram, describe changes or request upscaling, and select resolution (2K/4K).

To run locally:

streamlit run demo.py

Execute the skill/run.py script to transform methodology text and a figure caption into a diagram. You must provide either the --content string or a --content-file path, along with a --caption.

Basic Usage:

python skill/run.py \
  --content "METHOD_TEXT" \
  --caption "FIGURE_CAPTION" \
  --task diagram \
  --output output.png

Use the following Streamlit commands to view internal process results:

To view pipeline evolution and intermediate results:

streamlit run visualize/show_pipeline_evolution.py

To view evaluation results:

streamlit run visualize/show_referenced_eval.py

Specific guidelines for complex plot types:

• Scatter Plots: Use different marker shapes (e.g., circles vs. triangles) to encode categorical dimensions alongside color. Markers should be solid and fully opaque.
• Heatmaps: Ensure cells are square. Highly preferred: write the exact value (in white or black text) inside the cell. Use either borderless cells or very thin white lines for separation.
• Radar Charts: Use translucent fills (alpha ~0.2) for the polygon area to allow grid lines to show through. Use a solid, darker line for the outer perimeter.

To use PaperBanana, install the required dependencies using uv and configure your API keys via environment variables.

Installation:

cd <repo-root>
uv pip install -r requirements.txt

API Configuration: PaperBanana supports two options for API keys. If both are provided, OpenRouter is used by default.

• Option 1 (Recommended): OpenRouter API key (provides both text reasoning and image generation):

  export OPENROUTER_API_KEY="sk-or-v1-..."

• Option 2: Google API key (direct access to Gemini API):

  export GOOGLE_API_KEY="your-key-here"

The Gradio app provides a user-friendly interface for generating diagrams. You can use the hosted version on Hugging Face Spaces or run it locally.

To run locally:

python app.py

Note on Figure Size: In the Gradio UI, the Figure Size setting maps as follows:

• 1-3cm and 4-6cm $\rightarrow$ 1k resolution
• 7-9cm and 10-13cm $\rightarrow$ 2k resolution
• 14-17cm and 17cm $\rightarrow$ 4k resolution (Applies to Gemini and OpenRouter calls; OpenAI gpt-image uses fixed-size API paths).

When creating statistical plots for NeurIPS 2025, follow these color usage patterns to ensure professional aesthetics and accessibility:

• Categorical Data: Use soft pastels (salmon, sky blue, mint, lavender), muted earth tones (olive, beige, slate grey, navy), or high-contrast primaries for distinct categories.
• Accessibility: Combine colors with geometric patterns (hatches, dots, stripes) to support colorblind readers and black-and-white printing.
• Sequential/Heatmaps: Use perceptually uniform scales like Viridis (blue-to-yellow) or Magma/Plasma (purple-to-orange). For diverging data (positive/negative), use Coolwarm (blue-to-red).
• Avoid: Do not use the traditional Jet or Rainbow colormaps.

Follow these conventions for line charts to ensure clarity:

• Markers: Always include geometric markers (circles, squares, diamonds) at data points.
• Line Styles: Use solid lines for primary experimental data and dashed lines (--) for theoretical limits, baselines, or secondary data.
• Uncertainty: Represent uncertainty using semi-transparent shaded bands (confidence intervals) rather than vertical error bars.

When rendering bar charts or histograms, use the following styles:

• Borders: Either use high-definition black outlines around colored bars or use a borderless style with solid color fills.
• Grouping: Group bars tightly and provide significant whitespace between different categorical groups.
• Error Bars: Style error bars with black, flat caps.

To enable the Retriever Agent's few-shot learning capabilities, download the PaperBananaBench dataset and place it in the data directory (e.g., data/PaperBananaBench/).

If you require the original PDFs, download them from PaperBananaDiagramPDFs. The framework will still function without the dataset by bypassing the Retriever Agent.