Plot100PercentStackedBarChart — Analysis Tool Box

Introduction

"How close is each region to its vaccination target, how far along is each collection requirement" is a progress-toward-goal question, and a plain bar chart of raw counts doesn't answer it as directly as a completion percentage does. Plot100PercentStackedBarChart renders each group as a horizontal bar filled to its percentage of completion — either against an explicit target column or as a share of the total across all groups — with the unfilled remainder shown in a muted background color, so the gap to 100% is as visible as the progress itself.

Teaching Note

100% stacked bar charts are essential for:

Epidemiology: Comparing vaccination coverage rates across multiple geographic regions.
Intelligence Analysis: Visualizing the completion status of intelligence collection requirements.
Healthcare: Monitoring medication adherence levels or patient satisfaction benchmarks.
Project Management: Tracking progress toward milestones across different project tracks.
Public Health: Monitoring hospital bed occupancy or ICU capacity by facility.
Sales: Visualizing revenue achieved vs. target quotas for regional sales teams.
Data Science: Monitoring data labeling progress or model training iterations.
Quality Control: Comparing the proportion of units passing inspection across production lines.

Parameters

Parameter	Type	Default	Description
`dataframe`required	`pd.DataFrame`	—	The pandas DataFrame containing the data to be visualized. Must contain one row per group.
`group_column_name`required	`str`	—	The name of the column containing the category or group labels for the bars.
`value_column_name`required	`str`	—	The name of the column containing the current or numerator values.
`target_value_column_name`	`str`	`None`	The name of the column containing the target or denominator values. If None, the percentage is calculated as the value's share of the total sum across all groups. Defaults to None.
`background_color`	`str`	`'#e8e8ed'`	The hex color code used for the empty/remaining portion of the bars. Defaults to '#e8e8ed'.
`color_palette`	`str`	`'Set1'`	The seaborn color palette used for the filled portion of the bars if fill_color is not specified. Defaults to 'Set1'.
`fill_color`	`str`	`None`	A specific hex color code to use for all bars. If provided, overrides color_palette. Defaults to None.
`fill_transparency`	`float`	`0.8`	The transparency level (alpha) of the bar fill, ranging from 0 to 1. Defaults to 0.8.
`figure_size`	`tuple`	`(8, 6)`	A tuple of (width, height) in inches for the plot. Defaults to (8, 6).
`data_label_fontsize`	`int`	`10`	The font size for axis and group labels. Defaults to 10.
`title_for_plot`	`str`	`None`	The primary title text displayed at the top of the figure. Defaults to None.
`subtitle_for_plot`	`str`	`None`	The descriptive subtitle text displayed below the title. Defaults to None.
`caption_for_plot`	`str`	`None`	Descriptive text or notes displayed at the bottom of the plot. Defaults to None.
`data_source_for_plot`	`str`	`None`	Data attribution text appended to the caption. Defaults to None.
`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 Plot100PercentStackedBarChart
import pandas as pd

# Epidemiology: vaccination coverage across different provinces
prov_data = pd.DataFrame({
    'Province': ['North', 'South', 'East', 'West'],
    'Vaccinated': [8500, 7200, 9100, 6800],
    'Population': [10000, 10000, 10000, 10000]
})
Plot100PercentStackedBarChart(
    prov_data, 'Province', 'Vaccinated', 'Population',
    title_for_plot="COVID-19 Vaccination Coverage",
    subtitle_for_plot="Percentage of population fully vaccinated by province",
    color_palette="viridis"
)