# Python Plotter for Constraint Optimization Results

This directory contains tools for plotting results from constraint optimization experiments.

## Files

- `plotter.py` - Main plotting script
- `config_example.json` - Example configuration file  
- `config_feasible_fraction.json` - Example config for feasible fraction plots
- `config_constraint_violation.json` - Example config for constraint violation plots
- `objectives.json` - Global configuration with optimal objective values

## Configuration

The JSON configuration specifies:

- `plot_type`: Type of data to plot (`best_candidates`, `constraint_violation`, `feasible_fraction`)
- `algorithms`: List of algorithms with visualization settings
  - `name`: Algorithm directory name
  - `label`: Display name in legend
  - `color`: Algorithm color (hex code)
  - `linestyle`: Line style (`-`, `--`, `-.`, `:`)
- `instances`: List of problem instances with colors
  - `name`: Instance directory name  
  - `label`: Display name in legend
  - `color`: Instance color (hex code)
- `data_path`: Path to solutions directory
- `output_dir`: Directory for saving plots
- `plot_settings`: Figure settings (size, labels, grid, log scales, etc.)
  - `log_x`: Enable logarithmic x-axis
  - `log_y`: Enable logarithmic y-axis
  - `show_std`: Show standard deviation bands (default: true)
  - `color_combination`: How to combine algorithm and instance colors
    - `"blend"`: Blend algorithm and instance colors (default)
    - `"algorithm"`: Use only algorithm colors
    - `"instance"`: Use only instance colors

## Usage

Basic usage:
```bash
python3 plotter.py config_example.json
```

With Guix (recommended):
```bash
guix shell python python-matplotlib python-pandas python-numpy -- python3 plotter.py config_example.json
```

## Data Structure

The plotter expects data in this structure:
```
data_path/
├── algorithm1/
│   ├── instance1/
│   │   ├── best_candidates_*.csv
│   │   ├── constraint_violation/
│   │   │   └── constraint_violations_*.csv
│   │   └── feasible_fraction/
│   │       └── feasible_fractions_*.csv
│   └── instance2/...
└── algorithm2/...
```

## Features

- Averages multiple runs automatically
- Shows standard deviation as transparent bands around mean
- Single plot with multiple instances (colored by instance)
- Different line styles for algorithms  
- Logarithmic axes support for both x and y
- **Percentage deviation from optimal** for `best_candidates` plots
- Absolute values for other plot types (`constraint_violation`, `feasible_fraction`)
- Automatic legend with run counts
- High-quality SVG output

## Percentage Deviation Calculation

For `best_candidates` plots, the plotter automatically:
1. Loads optimal objective values from `objectives.json`
2. Validates that all values are >= optimal (raises error if better values found)
3. Calculates percentage deviation: `(current - optimal) / |optimal| * 100`
4. Plots deviation percentages so you can see convergence to 0%

Other plot types use absolute values as normal.