Plotting

Plotting utilities for visualizing evolutionary progress.

This module provides functions for visualizing: - Fitness statistics (best, mean, median, std) - Diversity over time - Mutation probability and strength trends - Fitness comparison

evolib.utils.plotting.plot_approximation(y_pred, y_true, *, title='Approximation', show=True, show_grid=True, legend_location='upper right', save_path=None, pred_label='Prediction', true_label='Target', pred_marker=None, true_marker=None, pred_lw=2, true_lw=2, pred_ls='--', true_ls='-', x_vals=None, y_limits=None, dpi=150, size=(6, 4), fitness=None, support_points=None, support_label='Support points', support_marker='o', support_size=30.0, xlabel=None, ylabel=None, residuals_style=None, residuals_label='Residuals (target - prediction)', residuals_alpha=0.5, residuals_linewidth=1.0, residuals_ylimits=None, extra_lines=None)[source]

Plot predicted values against targets with optional support points and residual visualization.

Parameters:

  • y_pred (Union[Sequence[float], ndarray]) – Predicted values (1D).

  • y_true (Union[Sequence[float], ndarray]) – Target values (1D), same length as y_pred.

  • title (str) – Plot title. If fitness is given, it is appended.

  • show (bool) – If True, show the plot interactively.

  • show_grid (bool) – Toggle background grid.

  • legend_location (str) – Matplotlib legend location string.

  • save_path (Optional[str]) – If provided, save the figure to this path.

  • pred_label (str) – Legend label for predictions.

  • true_label (str) – Legend label for targets.

  • x_vals (Union[Sequence[float], ndarray, None]) – Optional x-axis values; defaults to range(len(y_true)).

  • y_limits (tuple[float, float] | None) – Optional (ymin, ymax) for the main plot; if None, computed with padding.

  • dpi (int) – Figure DPI.

  • size (tuple[float, float]) – Figure size (width, height) in inches.

  • fitness (float | None) – Optional fitness to append to the title (e.g. MSE).

  • support_points (tuple[Union[Sequence[float], ndarray], Union[Sequence[float], ndarray]] | None) – Optional (x_support, y_support) to visualize discrete support points.

  • support_label (str) – Legend label for support points.

  • support_marker (str) – Marker symbol for support points.

  • support_size (float) – Marker size for support points.

  • xlabel (str | None) – Axis labels for the main plot.

  • ylabel (str | None) – Axis labels for the main plot.

  • residuals_style (Optional[Literal['overlay', 'subplot']]) – “subplot” for a second axes below, or “overlay” to draw error segments in the main axes.

  • residuals_label (str) – Legend label for residuals (subplot mode).

  • residuals_alpha (float) – Transparency for residual drawing.

  • residuals_linewidth (float) – Line width for residual drawing.

  • extra_lines (Optional[Iterable[tuple[Union[Sequence[float], ndarray], Union[Sequence[float], ndarray], Optional[str], Optional[dict]]]]) – Iterable of (x, y, label, style_dict). Each will be plotted via ax.plot(x, y, **style_dict). Use it e.g. for a noisy target line: (X, Y_noisy, “Noisy target”, {“ls”: “:”, “alpha”: 0.6})

Return type:

None

evolib.utils.plotting.plot_bit_prediction(pred_values, true_bits, save_path, input_bits=None, title='Bit Prediction', show=False, dpi=150, pred_name='Prediction', show_target_raster=True)[source]

Visualize a bit-sequence task over time.

This plot combines two views:

  • A raster plot (top) showing discrete input/target/predicted bits

  • A line/scatter plot (bottom) showing target vs. predicted values

Parameters:

  • true_bits (list[int]) – Ground truth sequence of bits (0/1).

  • pred_values (list[float]) – Model output values. Shown as continuous in the line plot and rounded to 0/1 in the raster plot.

  • input_bits (list[int] | None) – Optional input sequence of bits (0/1). If given, it is shown in the raster plot above target and prediction.

  • save_path (str) – File path to save the plot image.

  • title (str) – Title of the figure. Default is “Bit Prediction”.

  • show (bool) – If True, show the plot window interactively. Default: False.

  • dpi (int) – Resolution for saving the figure.

  • pred_name (str) – Label used for the predicted/output series (e.g., “Prediction” or “Echo”).

  • show_target_raster (bool) – If True, include the target bits in the raster plot.

Return type:

None

Notes

  • For general regression/function approximation, use plot_approximation.

evolib.utils.plotting.plot_diversity(history, *, title='Population Diversity', show=True, log=False, save_path=None)[source]

Wrapper to plot diversity over generations.

Return type:

None

evolib.utils.plotting.plot_fitness(history, *, title='Fitness over Generations', show=True, log=False, save_path=None)[source]

Wrapper to plot best, mean, and median fitness with optional std band.

Return type:

None

evolib.utils.plotting.plot_fitness_comparison(histories, *, labels=None, metric='best_fitness', title='Fitness Comparison over Generations', show=True, log=False, save_path=None)[source]
Return type:

None

evolib.utils.plotting.plot_history(histories, *, metrics=['best_fitness'], labels=None, title='Evolutionary Metrics', xlabel='Generation', ylabel=None, show=True, log_y=False, save_path=None, with_std=True, figsize=(10, 6))[source]

General-purpose plotting function for evolutionary history metrics.

Supports multiple metrics (e.g. fitness, diversity, mutation )probability and comparison across runs.

Parameters:

  • histories (Union[Sequence[Union[Pop, DataFrame]], Pop]) – Single or multiple history DataFrames.

  • metrics (list[str]) – List of metric column names to plot (e.g., ‘best_fitness’).

  • labels (Optional[list[str]]) – Optional list of labels for each run.

  • title (str) – Title of the plot.

  • xlabel (str) – Label for the x-axis.

  • ylabel (Optional[str]) – Label for the y-axis (auto-generated if None).

  • show (bool) – Whether to display the plot interactively.

  • log_y (bool) – Apply logarithmic scale to the y-axis.

  • save_path (Optional[str]) – Optional file path to save the plot.

  • with_std (bool) – If True, plot standard deviation shading when available.

  • figsize (tuple) – Size of the figure (width, height).

Return type:

None

Wrapper to plot mutation and/or strength trends over time.

Return type:

None

evolib.utils.plotting.save_combined_net_plot(net, X, Y_true, Y_pred, path, *, dpi=100, title='Approximation', xlabel='x', ylabel='y', true_label='Target', pred_label='Network Output', show_grid=True)[source]

Save a side-by-side image of the network graph and an approximation plot.

Parameters:

  • net (Nnet) – EvoNet instance; must provide plot(out_path_base, …).

  • X (ndarray) – X values used for plotting (1D).

  • Y_true (ndarray) – Ground-truth targets aligned with X.

  • Y_pred (ndarray) – Model predictions aligned with X.

  • path (str) – Output PNG file.

  • dpi (int) – DPI for the approximation subplot.

  • title (str) – Plot annotations.

  • xlabel (str) – Plot annotations.

  • ylabel (str) – Plot annotations.

  • true_label (str) – Legend labels for target and prediction.

  • pred_label (str) – Legend labels for target and prediction.

  • show_grid (bool) – Toggle grid in the approximation subplot.

Return type:

None

evolib.utils.plotting.save_current_plot(filename, dpi=300)[source]

Save the current matplotlib figure to file.

Return type:

None