Skip to content

Visualisation API

Visualisation APIs cover reward/safety plots, episodic plots, shield telemetry, legends, and styling helpers used by notebooks.

Reward and Safety Figures

src.visualisation.reward_safety.plot_cum_reward_and_safety_side_by_side(*, figure_title=None, smooth=False, smooth_kind='moving', smooth_window=21, ema_alpha=0.15, smooth_points=800, show_seed_traces=False, show_level_changes=True, level_line_aggregate='median', annotate_level_changes=True, wm_hist=None, wm_prepend_to='IPPO_Shielded', show_world_model_line=True, wm_line_aggregate='median', annotate_world_model_line=True, truncate_to_smallest=False, band='ci95', include_legend=True, paper_panel=False, save_path=None, **alg_histories)

Example

plot_cum_reward_and_safety_side_by_side( IPPO=ippo_histories, IPPO_Lag=ippo_lag_histories, smooth=True, smooth_kind="moving", smooth_window=21, smooth_points=800 )

src.visualisation.reward_safety_episodic.plot_reward_and_safety_episodic(*, figure_title=None, smooth=False, smooth_kind='moving', smooth_window=21, ema_alpha=0.15, smooth_points=800, show_seed_traces=False, reward_per_step=False, safety_per_step=False, show_level_changes=True, level_line_aggregate='median', annotate_level_changes=True, wm_hist=None, wm_prepend_to='IPPO_Shielded', show_world_model_line=True, wm_line_aggregate='median', annotate_world_model_line=True, truncate_to_smallest=False, band='ci95', include_legend=True, paper_panel=False, save_path=None, **alg_histories)

Episodic view:

Left panel: per-episode violations Right panel: per-episode reward

For each episode

x = t_end (global timestep where the episode terminated) y = cum_violations or cum_reward for that episode.

If *_per_step=True, y is divided by ep_len (episode length) so you get average per-step violation / reward within the episode.

src.visualisation.shield_telemetry.plot_shield_telemetry(*, figure_title=None, smooth=False, smooth_kind='moving', smooth_window=21, smooth_points=800, ema_alpha=0.15, band='ci95', include_legend=True, paper_panel=False, save_path=None, **alg_histories)

Legends

src.visualisation.legend.ExperimentLegendVariant dataclass

src.visualisation.legend.build_experiment_legend_handles(algorithm_labels, *, include_world_model_line=True, include_shield_level_change=True)

src.visualisation.legend.export_experiment_legend(save_path, *, algorithm_labels, include_world_model_line=True, include_shield_level_change=True, single_row=False)

src.visualisation.legend.export_experiment_legend_variants(export_dir='exports/legends')

Shared Plot Helpers

src.visualisation.common.build_seed_series(history_one_seed, metric_key)

src.visualisation.common.summarize_band(histories_list, metric_key, *, band='minmax')

Align seeds on the union timestep grid; forward-fill within each seed range. Returns grid, mean, lower, upper.

band
  • "minmax": lower=min across seeds, upper=max across seeds
  • "std": lower=mean-std, upper=mean+std
  • "ci95": 95% CI for the mean: mean ± tcrit * (std / sqrt(n))

src.visualisation.common.smooth_curve(x, y, kind='moving', window=21, ema_alpha=0.15, points=600)

Resample to a uniform grid then smooth. kind: "moving" (centered moving average) or "ema" (exponential). window: odd window size for 'moving'. points: number of x samples.

src.visualisation.common.draw_event_line(ax, t, *, label, kind='dotted', annotate=None, color='0.15', lw=None, alpha=None, zorder=1, dashes=None, text_kwargs=None)

src.visualisation.common.maybe_save_show(fig, *, save_path=None, show=False)

Styling

src.visualisation.styling.use_paper_style()

src.visualisation.styling.use_paper_panel_style()

src.visualisation.styling.use_nice_mpl_style()

Compatibility alias for older notebook callers.

src.visualisation.styling.format_step_axis(ax, *, paper_panel=False)

src.visualisation.styling.style_axis_like_reference(ax, *, paper_panel=False)