PlotBoxWhiskerByGroup — Analysis Tool Box

Introduction

A table of summary statistics per group hides exactly the thing you usually want to see — how spread out each group is, and whether outliers are dragging the comparison. PlotBoxWhiskerByGroup renders a box-and-whisker plot across one or two categorical grouping levels, showing median, interquartile range, and outliers side by side, so differences in central tendency and variability are visible at a glance rather than buried in a table.

Teaching Note

Box-and-whisker plots are essential for:

Epidemiology: Comparing the distribution of body mass index (BMI) across multiple demographic groups.
Healthcare: Analyzing the spread of patient recovery times between different treatment protocols.
Intelligence Analysis: Evaluating the distribution of response times for various threat detection systems.
Data Science: Detecting outliers and comparing feature distributions across target classes.
Public Health: Monitoring variability in air quality index levels across urban and rural zones.
Finance: Comparing the distribution of daily stock returns across different industry sectors.
Quality Control: Assessing the variance in product dimensions across different manufacturing shifts.
Social Science: Analyzing the distribution of standardized test scores across different school districts.

Parameters

Parameter	Type	Default	Description
`dataframe`required	`pd.DataFrame`	—	The input dataset containing the numeric values and categorical grouping variables.
`value_column_name`required	`str`	—	The name of the continuous numeric variable to plot on the y-axis.
`grouping_column_name_1`required	`str`	—	The name of the primary categorical variable to plot on the x-axis.
`grouping_column_name_2`	`str`	`None`	The name of a secondary categorical variable used for nested grouping and color encoding (hue). Defaults to None.
`fill_color`	`str`	`'#8eb3de'`	A hex color code used for the box interiors if color_palette is not specified. Defaults to '#8eb3de'.
`color_palette`	`str`	`None`	The name of the seaborn color palette to use for grouping levels (e.g., 'Set2', 'viridis'). Defaults to None.
`display_order_list`	`list`	`None`	A specific list of categories to define the horizontal order of the first grouping variable. If None, categories are sorted by the median of the value column. Defaults to None.
`show_legend`	`bool`	`True`	Whether to display the plot legend, particularly useful when grouping_column_name_2 is specified. Defaults to True.
`title_for_plot`	`str`	`None`	The primary title text displayed at the top of the chart. Defaults to None.
`subtitle_for_plot`	`str`	`None`	Descriptive subtitle text displayed below the main title. Defaults to None.
`caption_for_plot`	`str`	`None`	Explanatory text or notes displayed at the bottom of the plot. Defaults to None.
`data_source_for_plot`	`str`	`None`	Text identifying the origin of the data, appended to the caption. Defaults to None.
`show_y_axis`	`bool`	`False`	Pass-through argument for consistency; the y-axis is managed by seaborn's boxplot defaults. Defaults to False.
`title_y_indent`	`float`	`1.1`	Vertical offset for the title position relative to the axes. Defaults to 1.1.
`subtitle_y_indent`	`float`	`1.05`	Vertical offset for the subtitle position relative to the axes. Defaults to 1.05.
`caption_y_indent`	`float`	`-0.15`	Vertical offset for the caption position relative to the axes. Defaults to -0.15.
`x_indent`	`float`	`-0.1`	Horizontal offset for the titles and captions relative to the axes. Defaults to -0.10.
`figure_size`	`tuple`	`(8, 6)`	Dimensions of the figure as a (width, height) tuple in inches. Defaults to (8, 6).
`filepath_to_save_plot`	`str`	`None`	The local path (ending in .png or .jpg) where the plot should be exported. If None, the file is not saved. Defaults to None.

Returns

None — the function displays the plot using matplotlib and optionally saves it to disk.

Example

python

from analysistoolbox.visualizations import PlotBoxWhiskerByGroup
import pandas as pd

# Epidemiology: recovery days by treatment type and age group
epi_df = pd.DataFrame({
    'Recovery Days': [10, 12, 11, 14, 15, 13, 22, 25, 24, 30],
    'Treatment': ['A', 'A', 'A', 'A', 'A', 'B', 'B', 'B', 'B', 'B'],
    'Age Group': ['Adult', 'Child', 'Adult', 'Child', 'Adult', 'Child', 'Adult', 'Child', 'Adult', 'Child']
})
PlotBoxWhiskerByGroup(
    epi_df, 'Recovery Days', 'Treatment', 'Age Group',
    title_for_plot="Clinical Trial Recovery Analysis",
    subtitle_for_plot="Days to complete recovery stratified by treatment and patient age"
)