Labeling Box And Whisker Plot

The Practical Reality of Adding Text Labels to Box Plots

Box plots are useful because they compress a dataset into quartiles, but most people skip the labeling step until the chart looks bare. Labeling a box plot properly takes maybe twenty minutes if you already know the mechanics, or a few hours if you're fumbling through matplotlib documentation for the first time. The hardest part isn't generating the plot. It's figuring out where to place the text so it doesn't overlap the box edges or get clipped by the figure boundary. I usually generate box plots using Python's matplotlib or seaborn because the infrastructure is solid and the customization options are predictable. Here's the approach I rely on when I need labeled quartile values on each box without spending a day debugging placement logic. Start by computing the statistics you want to label. A standard five-number summary gives you the minimum, first quartile, median, third quartile, and maximum. Matplotlib's boxplot function returns a dictionary of artists, which means you can extract the exact coordinate values programmatically instead of guessing where the boxes sit on the axes.

The code looks like this: import matplotlib.pyplot as plt
import numpy as np

data = [np.random.normal(0, 1, 100),
np.random.normal(2, 1.5, 100),
np.random.normal(-1, 0.8, 100)]

bp = plt.boxplot(data, patch_artist=True)

for i, box in enumerate(bp['boxes']):
y vals = box.get_ydata()
x pos = box.get_xdata()[1]
median val = np.median(data[i])
plt.text(x pos + 0.15, median val, f'M: {median_val:.2f}',
va='center', ha='left', fontsize=9) This places a median label just to the right of each box. I offset it by 0.15 on the x-axis because if I place it directly on the box edge, the text sits on top of the line and becomes unreadable. The exact offset depends on your figure width and how many boxes you're drawing side by side, so you may need to adjust that value experimentally.

Common Pitfalls and the Workaround I Use

The first time I tried labeling box plots automatically, I ran into a problem with outliers. When a dataset has extreme values, the whiskers shrink inward and the box becomes very compact. If I applied the same text offset for every group, the labels for the narrow boxes ended up colliding with the outlier markers above or below. The chart looked cluttered and the labels were impossible to read. My fix was to check the interquartile range for each group and apply a dynamic offset. Narrow IQR boxes get a larger horizontal shift, while wide IQR boxes keep the standard offset. I also rotated the text to forty-five degrees when the IQR dropped below a certain threshold. This took about ten extra lines of code but eliminated almost all the overlap issues. Another issue I encountered was that matplotlib clips text that extends past the axes border. When your labels are positioned far to the right, they simply disappear. The solution is to adjust the subplot parameters with plt.subplots_adjust(right=0.85) before calling plt.tight_layout(). I learned this the hard way during a project where I spent two hours trying to make text visible before realizing it was being clipped by the figure boundary.

More Advanced Labeling Strategies

If you need to label not just the median but the full five-number summary on each box, the process scales linearly. You iterate through the quartile positions and add a text element for each. The key insight is that you should never stack all five labels vertically at the same x-position. They will overlap. Instead, stagger them slightly along the y-axis and use a monospace font so the alignment stays consistent. For publication-quality figures, I use a small text box with a white background behind each label. This prevents the text from blending into dark-colored boxes or busy background elements. In matplotlib, you accomplish this with the bbox parameter in plt.text(), passing a dictionary with facecolor set to white and an alpha value around 0.8 for slight transparency. When working with many groups, labeling every single box becomes noise rather than information. In those cases, I switch to a summary table placed beside the plot or use a single annotation that lists the key statistics for all groups. This is a judgment call that depends on your audience. Technical readers can parse dense labels. General audiences cannot.

Tool Options and My Recommendation

You have several options depending on your environment. Matplotlib gives you full control but requires more code. Seaborn simplifies the plotting but adds an extra layer you need to unwrap before labeling. Plotly generates interactive plots where you can hover to see statistics, which removes the need for static labels in many cases. If interactivity is acceptable for your use case, Plotly often saves the most time. For static reports and printed materials, I stick with matplotlib. It produces consistent output across different systems and the labeling logic I described above works reliably. The download and setup are straightforward. Install matplotlib with pip install matplotlib and seaborn if you want the higher-level API. No special libraries are required for basic labeling.

When Box Plot Labeling Fails Completely

Box plots are not suitable when your data has heavy ties or discrete ordinal values. If your dataset contains repeated values that cluster at specific points, the quartile calculation becomes misleading and labeling those values gives a false impression of precision. In those situations, a strip plot or a violin plot provides more honest representation. I stopped trying to force labels onto box plots for discrete data about five years ago and switched to complementary visualizations. The results are cleaner and the labels actually mean something. Another scenario where labeling breaks down is when groups have vastly different scales. A box plot with a median near zero alongside another box with a median near one million will make the smaller box visually irrelevant regardless of how carefully you label it. In these cases, use a logarithmic scale on the y-axis or separate the groups into individual subplots. Neither solution is elegant, but they prevent the chart from becoming misleading.