ribs.visualize.cvt_archive_heatmap¶

ribs.visualize.cvt_archive_heatmap(archive: CVTArchive, ax: Axes | None = None, *, df: DataFrame | ArchiveDataFrame | None = None, transpose_measures: bool = False, cmap: str | Sequence[matplotlib.typing.ColorType] | Colormap = 'magma', aspect: 'auto' | 'equal' | float | None = None, lw: float = 0.5, ec: matplotlib.typing.ColorType = 'black', vmin: float | None = None, vmax: float | None = None, cbar: 'auto' | None | Axes = 'auto', cbar_kwargs: dict | None = None, rasterized: bool = False, clip: bool | Polygon = False, plot_centroids: bool = False, ms: float = 1, pcm_kwargs: dict | None = None, plot_samples: None = None) → None[source]¶

Plots heatmap of a CVTArchive with 1D or 2D measure space.

In the 2D case, we create a Voronoi diagram and shade in each cell with a color corresponding to the objective value of that cell’s elite. In the 1D case, we plot a horizontal series of cells.

Depending on how many cells are in the archive, ms and lw may need to be tuned. If there are too many cells, the Voronoi diagram and centroid markers will make the entire image appear black. In that case, try turning off the centroids with plot_centroids=False or even removing the lines completely with lw=0.

Examples

Heatmap of a 2D CVTArchive

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from ribs.archives import CVTArchive
>>> from ribs.visualize import cvt_archive_heatmap
>>> # Populate the archive with the negative sphere function.
>>> archive = CVTArchive(solution_dim=2,
...                      centroids=100, ranges=[(-1, 1), (-1, 1)])
>>> x = np.random.uniform(-1, 1, 10000)
>>> y = np.random.uniform(-1, 1, 10000)
>>> archive.add(solution=np.stack((x, y), axis=1),
...             objective=-(x**2 + y**2),
...             measures=np.stack((x, y), axis=1))
>>> # Plot a heatmap of the archive.
>>> plt.figure(figsize=(8, 6))
>>> cvt_archive_heatmap(archive)
>>> plt.title("Negative sphere function with 2D measures")
>>> plt.xlabel("x coords")
>>> plt.ylabel("y coords")
>>> plt.show()

../_images/ribs-visualize-cvt_archive_heatmap-1.png

Heatmap of a 1D CVTArchive

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from ribs.archives import CVTArchive
>>> from ribs.visualize import cvt_archive_heatmap
>>> # Populate the archive with the negative sphere function.
>>> archive = CVTArchive(solution_dim=2,
...                      centroids=20, ranges=[(-1, 1)])
>>> x = np.random.uniform(-1, 1, 1000)
>>> archive.add(solution=np.stack((x, x), axis=1),
...             objective=-x**2,
...             measures=x[:, None])
>>> # Plot a heatmap of the archive.
>>> plt.figure(figsize=(8, 6))
>>> cvt_archive_heatmap(archive)
>>> plt.title("Negative sphere function with 1D measures")
>>> plt.xlabel("x coords")
>>> plt.show()

../_images/ribs-visualize-cvt_archive_heatmap-2.png

Parameters:¶

archive: CVTArchive¶: A 1D or 2D CVTArchive.
ax: Axes | None = None¶: Axes on which to plot the heatmap. If None, the current axis will be used.
df: DataFrame | ArchiveDataFrame | None = None¶: If provided, we will plot data from this argument instead of the data currently in the archive. This data can be obtained by, for instance, calling ribs.archives.ArchiveBase.data() with return_type="pandas" and modifying the resulting ArchiveDataFrame. Note that, at a minimum, the data must contain columns for index, objective, and measures. To display a custom metric, replace the “objective” column.
transpose_measures: bool = False¶: By default, the first measure in the archive will appear along the x-axis, and the second will be along the y-axis. To switch this behavior (i.e. to transpose the axes), set this to True. Does not apply for 1D archives.
cmap: str | Sequence[matplotlib.typing.ColorType] | Colormap = 'magma'¶: The colormap to use when plotting intensity. Either the name of a Colormap, a list of Matplotlib color specifications (e.g., an \(N \times 3\) or \(N \times 4\) array – see ListedColormap), or a Colormap object.
aspect: 'auto' | 'equal' | float | None = None¶: The aspect ratio of the heatmap (i.e. height/width). Defaults to 'auto' for 2D and 0.5 for 1D. 'equal' is the same as aspect=1. See matplotlib.axes.Axes.set_aspect() for more info.
lw: float = 0.5¶: Line width when plotting the Voronoi diagram.
ec: matplotlib.typing.ColorType = 'black'¶: Edge color of the cells in the Voronoi diagram. See here for more info on specifying colors in Matplotlib.
vmin: float | None = None¶: Minimum objective value to use in the plot. If None, the minimum objective value in the archive is used.
vmax: float | None = None¶: Maximum objective value to use in the plot. If None, the maximum objective value in the archive is used.
cbar: 'auto' | None | Axes = 'auto'¶: By default, this is set to 'auto' which displays the colorbar on the archive’s current Axes. If None, then colorbar is not displayed. If this is an Axes, displays the colorbar on the specified Axes.
cbar_kwargs: dict | None = None¶: Additional kwargs to pass to colorbar().
rasterized: bool = False¶: Whether to rasterize the heatmap. This can be useful for saving to a vector format like PDF. Essentially, only the heatmap will be converted to a raster graphic so that the archive cells will not have to be individually rendered. Meanwhile, the surrounding axes, particularly text labels, will remain in vector format.
clip: bool | Polygon = False¶: Clip the heatmap cells to a given polygon. By default, we draw the cells along the outer edges of the heatmap as polygons that extend beyond the archive bounds, but these polygons are hidden because we set the axis limits to be the archive bounds. Passing clip=True will clip the heatmap such that these “outer edge” polygons are within the archive bounds. An arbitrary polygon can also be passed in to clip the heatmap to a custom shape. See #356 for more info. Only applies to 2D archives.
plot_centroids: bool = False¶: Whether to plot the cluster centroids.
ms: float = 1¶: Marker size for centroids.
pcm_kwargs: dict | None = None¶: Additional kwargs to pass to pcolormesh(). Only applicable to 1D heatmaps. linewidth and edgecolor are set with the lw and ec args.
plot_samples: None = None¶: DEPRECATED.

Raises:¶

ValueError – The archive’s measure dimension must be 1D or 2D.