89 lines
3.6 KiB
Markdown
89 lines
3.6 KiB
Markdown
# 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.
|