feat: comparison plots

docs/api/analysis.md

@@ -0,0 +1,84 @@
+# 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:
+
+```bash
+# 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
+
+```bash
+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.