parasolpy.plotting

Plotting helpers for ensemble trace analysis using pandas DataFrames.

These helpers assume a wide-format DataFrame where: - rows are timesteps (DatetimeIndex or datetime-like values) - columns are simulation traces (numeric)

All plotting functions save a static figure to disk and return the matplotlib figure/axes plus the saved output path.

Functions

plot_archive_lifespans(snapshots, output_dir)

Plot the birth and death of Borg archive solutions as a survival chart.

plot_trace_exceedance(trace_df, output_dir)

Plot ensemble exceedance (flow-duration) curves for all simulation traces.

plot_trace_fan_chart(trace_df, output_dir[, ...])

Plot percentile ribbons and median over time for ensemble traces.

plot_trace_heatmap(trace_df, output_dir[, ...])

Plot an ensemble heatmap with time on x-axis and simulation runs on y-axis.

plot_trace_monthly_seasonality(trace_df, ...)

Plot monthly distribution of ensemble values across all years and runs.

plot_trace_spaghetti(trace_df, output_dir[, ...])

Plot a traditional spaghetti chart with all traces in one transparent color.
parasolpy.plotting.plot_trace_heatmap(trace_df, output_dir, filename='trace_heatmap.png', run_columns=None, cmap='viridis', figsize=(14, 8), dpi=200, value_label='Value')[source]

Plot an ensemble heatmap with time on x-axis and simulation runs on y-axis.

Parameters:

  • trace_df (pd.DataFrame) – Wide trace DataFrame (rows=time, cols=runs).

  • output_dir (str | PathLike) – Directory where figure will be saved.

  • filename (str, optional) – Output image file name.

  • run_columns (list of str, optional) – Subset of run columns to include.

  • cmap (str, optional) – Matplotlib/seaborn colormap.

  • figsize (tuple, optional) – Figure size in inches.

  • dpi (int, optional) – Output image DPI.

  • value_label (str, optional) – Colorbar label.

Returns:

(fig, ax, output_path)

Return type:

tuple

parasolpy.plotting.plot_trace_spaghetti(trace_df, output_dir, filename='trace_spaghetti.png', run_columns=None, color='#1f77b4', alpha=0.15, linewidth=0.9, figsize=(14, 6), dpi=200, y_label='Value')[source]

Plot a traditional spaghetti chart with all traces in one transparent color.

Parameters:

  • trace_df (pd.DataFrame) – Wide trace DataFrame (rows=time, cols=runs).

  • output_dir (str | PathLike) – Directory where figure will be saved.

  • filename (str, optional) – Output image file name.

  • run_columns (list of str, optional) – Subset of run columns to include.

  • color (str, optional) – Single line color used for all traces.

  • alpha (float, optional) – Line transparency for each trace.

  • linewidth (float, optional) – Line width.

  • figsize (tuple, optional) – Figure size in inches.

  • dpi (int, optional) – Output image DPI.

  • y_label (str, optional) – Y-axis label.

Returns:

(fig, ax, output_path)

Return type:

tuple

parasolpy.plotting.plot_trace_fan_chart(trace_df, output_dir, filename='trace_fan_chart.png', run_columns=None, low_percentile=0.05, inner_low_percentile=0.25, median_percentile=0.5, inner_high_percentile=0.75, high_percentile=0.95, figsize=(14, 6), dpi=200, y_label='Value')[source]

Plot percentile ribbons and median over time for ensemble traces.

Parameters:

  • trace_df (pd.DataFrame) – Wide trace DataFrame (rows=time, cols=runs).

  • output_dir (str | PathLike) – Directory where figure will be saved.

  • filename (str, optional) – Output image file name.

  • run_columns (list of str, optional) – Subset of run columns to include.

  • low_percentile (float, optional) – Lower outer percentile.

  • inner_low_percentile (float, optional) – Lower inner percentile.

  • median_percentile (float, optional) – Median percentile, usually 0.50.

  • inner_high_percentile (float, optional) – Upper inner percentile.

  • high_percentile (float, optional) – Upper outer percentile.

  • figsize (tuple, optional) – Figure size in inches.

  • dpi (int, optional) – Output image DPI.

  • y_label (str, optional) – Y-axis label.

Returns:

(fig, ax, output_path)

Return type:

tuple

parasolpy.plotting.plot_trace_monthly_seasonality(trace_df, output_dir, filename='trace_monthly_seasonality.png', run_columns=None, kind='box', figsize=(12, 6), dpi=200, y_label='Value')[source]

Plot monthly distribution of ensemble values across all years and runs.

Parameters:

  • trace_df (pd.DataFrame) – Wide trace DataFrame (rows=time, cols=runs).

  • output_dir (str | PathLike) – Directory where figure will be saved.

  • filename (str, optional) – Output image file name.

  • run_columns (list of str, optional) – Subset of run columns to include.

  • kind (str, optional) – Distribution plot type: ‘box’ or ‘violin’.

  • figsize (tuple, optional) – Figure size in inches.

  • dpi (int, optional) – Output image DPI.

  • y_label (str, optional) – Y-axis label.

Returns:

(fig, ax, output_path)

Return type:

tuple

parasolpy.plotting.plot_trace_exceedance(trace_df, output_dir, filename='trace_exceedance.png', run_columns=None, alpha=0.12, linewidth=0.8, color='#1f77b4', show_median=True, figsize=(10, 6), dpi=200, y_label='Value')[source]

Plot ensemble exceedance (flow-duration) curves for all simulation traces.

Parameters:

  • trace_df (pd.DataFrame) – Wide trace DataFrame (rows=time, cols=runs).

  • output_dir (str | PathLike) – Directory where figure will be saved.

  • filename (str, optional) – Output image file name.

  • run_columns (list of str, optional) – Subset of run columns to include.

  • alpha (float, optional) – Transparency for individual trace curves.

  • linewidth (float, optional) – Line width for individual trace curves.

  • color (str, optional) – Color used for trace curves.

  • show_median (bool, optional) – If True, overlay median exceedance curve.

  • figsize (tuple, optional) – Figure size in inches.

  • dpi (int, optional) – Output image DPI.

  • y_label (str, optional) – Y-axis label.

Returns:

(fig, ax, output_path)

Return type:

tuple

parasolpy.plotting.plot_archive_lifespans(snapshots, output_dir, filename='archive_lifespan.png', leaked_ids=None, restart_gap_threshold=50, figsize=(9, 10), dpi=300)[source]

Plot the birth and death of Borg archive solutions as a survival chart.

Draws one horizontal bar per solution: rows are solutions ordered by birth NFE, each bar runs from the solution’s birth to its death (see parasolpy.borg_runtime.solution_lifespans for the death convention). An archive-size panel above shares the x-axis. Snapshot gaps wider than restart_gap_threshold NFE — which coincide with Borg restarts, during which no runtime output is written — are shaded.

Parameters:

  • snapshots (list of tuple) – (nfe, ids) pairs from parasolpy.borg_runtime.parse_borg_runtime.

  • output_dir (str | PathLike) – Directory where figure will be saved.

  • filename (str, optional) – Output image file name.

  • leaked_ids (list of int, optional) – Solution IDs with a saved model file but no snapshot record (from parasolpy.borg_runtime.leaked_model_ids); drawn as a third category of minimum-width ticks, since only their birth is known.

  • restart_gap_threshold (int, optional) – Shade snapshot gaps wider than this many NFE.

  • figsize (tuple, optional) – Figure size in inches.

  • dpi (int, optional) – Output image DPI.

Returns:

(fig, (ax_size, ax), output_path)

Return type:

tuple