Introduction
A single categorical breakdown — infection rate by age group, wait time by department — often hides a second dimension worth seeing: how does that pattern change by gender, by priority level, by source type? PlotClusteredBarChart puts both dimensions on one chart, grouping bars of a secondary category within each level of a primary category on the x-axis, with automatic data labeling and text wrapping so the comparison stays readable even with several groups.
Teaching Note
Clustered bar charts are essential for:
- Epidemiology: Comparing disease prevalence across various age groups (primary) by gender (secondary).
- Healthcare: Analyzing patient recovery outcomes across different treatment protocols (primary) by facility (secondary).
- Intelligence Analysis: Visualizing intercepted signal counts across geographic regions (primary) by source type (secondary).
- Data Science: Comparing model performance metrics across various datasets (primary) by algorithm type (secondary).
- Public Health: Monitoring vaccine uptake across different administrative districts (primary) by age bracket (secondary).
- Finance: Visualizing quarterly revenue across different product lines (primary) by market segment (secondary).
- Operations: Comparing production defect rates across manufacturing lines (primary) by work shift (secondary).
- Social Science: Analyzing survey response trends across demographic groups (primary) by political affiliation (secondary).
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dataframerequired | pd.DataFrame | — | The pandas DataFrame containing the categorical and numeric data to plot. |
grouping_column_name_1required | str | — | The name of the primary categorical variable to be plotted on the x-axis. |
grouping_column_name_2required | str | — | The name of the secondary categorical variable used for color encoding (hue). |
value_column_namerequired | str | — | The name of the column containing the numeric values to be represented by bar height. |
color_palette | str | 'Set1' | The name of the seaborn color palette to use for the grouping levels. Defaults to 'Set1'. |
fill_transparency | float | 0.8 | The transparency level (alpha) of the bar fill, ranging from 0 to 1. Defaults to 0.8. |
display_order_list | list | None | A specific list of primary category names to define the horizontal order of groups. If None, categories are sorted by value in descending order. Defaults to None. |
figure_size | tuple | (6, 6) | A tuple of (width, height) in inches representing the desired plot dimensions. Defaults to (6, 6). |
show_legend | bool | True | Whether to display the legend for the secondary categorical variable. Defaults to True. |
decimal_places_for_data_label | int | 0 | The number of decimal places to include in the labels at the top of each bar. Defaults to 0. |
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 source of the data, appended to the caption. Defaults to None. |
x_indent | float | -0.04 | Horizontal offset for the titles and captions relative to the axes. Defaults to -0.04. |
title_y_indent | float | 1.15 | Vertical offset for the title position relative to the axes. Defaults to 1.15. |
subtitle_y_indent | float | 1.1 | Vertical offset for the subtitle position relative to the axes. Defaults to 1.1. |
caption_y_indent | float | -0.15 | Vertical offset for the caption position relative to the axes. Defaults to -0.15. |
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 PlotClusteredBarChart
import pandas as pd
# Epidemiology: infection rates by age group and gender
infection_df = pd.DataFrame({
'Age Group': ['0-18', '19-40', '41-65', '65+'] * 2,
'Gender': ['Male'] * 4 + ['Female'] * 4,
'Incidence Rate': [45, 120, 85, 210, 40, 115, 80, 205]
})
PlotClusteredBarChart(
infection_df, 'Age Group', 'Gender', 'Incidence Rate',
title_for_plot="Influenza Incidence Analysis",
subtitle_for_plot="Confirmed cases per 100,000 population stratified by age and gender"
)