Skip to content

Analysis & Plotting Tools

This guide outlines the tools available for analyzing experimental data and generating poster-quality visualizations for the Brittle Star project.

Shared Configuration

All plotting scripts share a central configuration in scripts/plots/plot_config.py. This file defines:

  • Color Palette: A color-blind friendly, high-contrast palette for different architectures.
  • Typography: Consistent font sizes and styles tailored for A0 posters.
  • Markers: Shared visual indicators, such as the ★ used for best performers.

Comparison Visualization

The scripts/plots/analyze_comparisons.py script generates grouped bar charts comparing the performance of different architectures across various morphologies.

Usage

Run the script from the root of the project, providing the path to your evaluation CSV:

# Basic usage (saves PNG and SVG to runs/evaluation/plots/)
uv run python scripts/plots/analyze_comparisons.py path/to/results.csv

# Advanced usage for Figma/Poster integration
uv run python scripts/plots/analyze_comparisons.py path/to/results.csv \
    --output_dir docs/assets/plots/ \
    --font_size 30 \
    --fig_width 14 \
    --fig_height 10

CLI Arguments

  • input_csv: (Required) Path to the CSV file containing evaluation results.
  • --output_dir, -o: Directory where plots will be saved (default: runs/evaluation/plots).
  • --show_titles: Include titles in the plots. Default is False, as titles are typically added natively in design tools like Figma.
  • --font_size: Base font size in points (default: 28).
  • --fig_width / --fig_height: Physical dimensions of the plot in inches. Match these to your Figma layout to maintain exact font sizes.

Outputs

The script generates four key plots, each saved as both .png and .svg:

  1. Forward Velocity: Grouped bar chart (cm/s).
  2. Accumulated Reward: Mean cumulative reward.
  3. Success Rate: Target acquisition percentage.
  4. Distance Remaining: Navigational accuracy.

Convergence Analysis

The scripts/plots/analyze_convergence.py script determines the convergence point of training runs.

Usage

uv run python scripts/plots/analyze_convergence.py --output_dir runs/convergence/

Configuration

  • File Mapping: The script uses hardcoded paths in the FILE_MAPPING dictionary. Update these paths to point to your specific run evaluation files.
  • CLI Arguments: Supports the same --show_titles, --font_size, and --fig_width/height flags as the comparison script.

Outputs

Generates three plots (PNG & SVG):

  1. convergence_comparison: Grouped horizontal bar chart.
  2. progress_reward_curves: Line plots of reward over time.
  3. progress_velocity_curves: Line plots of velocity over time.

Poster Integration (Figma)

SVG & Scaling

We recommend using the SVG outputs for poster design in Figma:

  1. No Resolution Loss: SVGs are vector-based and will remain sharp at any size.
  2. Native Text: Text in the SVG imports as native text layers in Figma.
  3. Exact Font Matching: To ensure a 28pt font in the plot matches a 28pt font in your poster, set the --fig_width and --fig_height to match the physical dimensions of the plot box in your Figma layout.
  4. Editable: You can "Ungroup" the SVG in Figma to manually move labels, adjust colors, or tweak individual bars.

Image Placeholders

The comparison charts include light-gray square placeholders below the X-axis. These are designed as guides; in Figma, you can drop your morphology renders or illustrations directly on top of these squares.