eda.plots.plot_ip_histograms

eda.plots.plot_ip_histograms(
    df,
    bins=10,
    num_cols=2,
    figwidth=10,
    thrs_unique=5,
    add_points=None,
    add_points_col=['red'],
)

Generate infill-point histograms for each numerical column in a DataFrame.

A separate histogram is created for each numerical column of df and arranged in a grid. The title of each subplot shows the total point count, the number of unique values, the number of outliers detected via the IQR method, and the standard deviation. Columns with fewer unique values than thrs_unique are coloured differently to draw attention to low-variability features.

If add_points is provided and its numerical columns differ from those of df in name but agree in count, the column names of add_points are silently replaced by those of df before plotting. This ensures that infill points drawn from a differently named search space are always overlaid correctly.

Parameters

Name	Type	Description	Default
df	pd.DataFrame	DataFrame containing the data to plot.	required
bins	int	Number of bins for the histograms. Defaults to 10.	10
num_cols	int	Number of columns in the subplot grid. Defaults to 2.	2
figwidth	int	Width of the entire figure in inches. Defaults to 10.	10
thrs_unique	int	Threshold for unique values below which the histogram bar colour switches from lightblue to lightcoral. Defaults to 5.	5
add_points	pd.DataFrame	DataFrame containing additional points to highlight with diamond markers at y = 0. Defaults to None.	None
add_points_col	list	List of colours, one per row of add_points. Defaults to [“red”].	['red']

Returns

Name	Type	Description
	None	None

Raises

Name	Type	Description
	ValueError	If the number of rows in add_points does not equal the length of add_points_col.

Examples

import pandas as pd
from spotoptim.eda.plots import plot_ip_histograms
data = {'A': [1, 2, 2, 3, 4, 5, 100], 'B': [10, 10, 10, 10, 10, 10, 10]}
df = pd.DataFrame(data)
plot_ip_histograms(df, bins=5, num_cols=1, thrs_unique=3)
# Example with multiple added points and colors
add_points = pd.DataFrame({'A': [1.5, 3.5], 'B': [10, 10]})
plot_ip_histograms(df, add_points=add_points, add_points_col=["red", "blue"])
# Example: add_points with different column names are aligned automatically
add_points_renamed = pd.DataFrame({'x': [1.5, 3.5], 'y': [10, 10]})
plot_ip_histograms(df, add_points=add_points_renamed, add_points_col=["green", "orange"])

References

Bartz-Beielstein, T. (2025). Multi-Objective Optimization and Hyperparameter Tuning With Desirability Functions. arXiv preprint arXiv:2503.23595. https://arxiv.org/abs/2503.23595