plotting

Plotting Skill

Generate standard visualizations from SWARM run data (sweep CSVs or time-series history).

Prerequisites

• matplotlib>=3.7
• pandas>=2.0
• numpy>=1.24
• Optional: seaborn>=0.12 for enhanced styling

Procedure

1. Detect data type

import pandas as pd
import os

def detect_data_type(path):
    """Determine if data is sweep results or time-series."""
    if path.endswith(".json"):
        return "timeseries"
    df = pd.read_csv(path)
    # Sweep data has a parameter column with repeated values
    param_cols = [c for c in df.columns if c not in 
                  ["seed", "welfare", "toxicity_rate", "quality_gap",
                   "mean_payoff_honest", "mean_payoff_opportunistic",
                   "mean_payoff_deceptive", "epoch"]]
    if param_cols and df[param_cols[0]].nunique() < len(df):
        return "sweep"
    return "timeseries"

2. Sweep plots

Grouped bar chart (welfare by parameter)

import matplotlib.pyplot as plt
import numpy as np

def plot_welfare_bars(df, param_col, output_dir):
    summary = df.groupby(param_col)["welfare"].agg(["mean", "std"]).reset_index()
    
    fig, ax = plt.subplots(figsize=(8, 5))
    x = np.arange(len(summary))
    ax.bar(x, summary["mean"], yerr=summary["std"], capsize=5, 
           color="steelblue", edgecolor="black", alpha=0.8)
    ax.set_xticks(x)
    ax.set_xticklabels([f"{v:.2f}" for v in summary[param_col]])
    ax.set_xlabel(param_col.replace("_", " ").title())
    ax.set_ylabel("Welfare (mean ± SD)")
    ax.set_title("Welfare by Governance Configuration")
    plt.tight_layout()
    plt.savefig(os.path.join(output_dir, "welfare_by_config.png"), dpi=150)
    plt.close()

Box plot (welfare distribution)

def plot_welfare_boxplot(df, param_col, output_dir):
    fig, ax = plt.subplots(figsize=(8, 5))
    groups = sorted(df[param_col].unique())
    data = [df[df[param_col] == g]["welfare"].values for g in groups]
    bp = ax.boxplot(data, labels=[f"{g:.2f}" for g in groups], patch_artist=True)
    for patch in bp["boxes"]:
        patch.set_facecolor("lightblue")
    ax.set_xlabel(param_col.replace("_", " ").title())
    ax.set_ylabel("Welfare")
    ax.set_title("Welfare Distribution by Configuration")
    plt.tight_layout()
    plt.savefig(os.path.join(output_dir, "welfare_boxplot.png"), dpi=150)
    plt.close()