PlotBarChart — Analysis Tool Box

Introduction

When the question is "which categories stand out, and by how much?" — which departments drive admissions, which strains dominate an outbreak, which features carry a model — a horizontal bar chart answers it faster than a table of numbers. PlotBarChart produces a clean, presentation-ready comparison from a single DataFrame: it sorts categories by value, wraps long labels, and can highlight the top N so the signal you care about reads at a glance. Reach for it to turn categorical counts or scores into a figure a stakeholder can act on, with titles, captions, and a data-source annotation for defensible reporting.

Teaching Note

Horizontal bar charts are essential for:

Epidemiology: Comparing disease incidence rates across different age groups or districts.
Healthcare: Comparing the number of patient admissions across different medical departments.
Data Science: Comparing feature importance scores or model performance metrics.
Public Health: Visualizing the distribution of health resource allocations.
Marketing: Comparing customer preference scores for different product categories.
Finance: Visualizing budget allocations across various operational departments.
Social Science: Presenting survey response counts for multiple-choice questions.

Parameters

Parameter	Type	Default	Description
`dataframe`required	`pd.DataFrame`	—	The pandas DataFrame containing the categorical and numeric data to plot.
`categorical_column_name`required	`str`	—	The name of the column representing the categories (y-axis).
`value_column_name`required	`str`	—	The name of the column representing the numeric values (x-axis).
`fill_color`	`str`	`'#8eb3de'`	A hex color code used for all bars. Applied when color_palette and top_n_to_highlight are not set.
`color_palette`	`str \| list`	`None`	A seaborn palette name (e.g., 'Set2') or a list of colors to use for the bars.
`top_n_to_highlight`	`int`	`None`	Number of highest-value categories to highlight; other bars render in neutral gray.
`highlight_color`	`str`	`'#b0170c'`	The hex color code used for highlighted bars.
`fill_transparency`	`float`	`0.8`	The alpha (transparency) of the bar fill, from 0 to 1.
`display_order_list`	`list`	`None`	Explicit category order (top to bottom). If None, bars sort by value descending.
`figure_size`	`tuple`	`(8, 6)`	The (width, height) of the figure in inches.
`title_for_plot`	`str`	`None`	The primary title text displayed at the top of the chart.
`subtitle_for_plot`	`str`	`None`	Descriptive subtitle text displayed below the title.
`caption_for_plot`	`str`	`None`	Descriptive text or notes displayed at the bottom of the plot.
`data_source_for_plot`	`str`	`None`	Text identifying the source of the data, appended to the caption.
`title_y_indent`	`float`	`1.15`	Vertical offset for the title position relative to the axes.
`subtitle_y_indent`	`float`	`1.1`	Vertical offset for the subtitle position relative to the axes.
`caption_y_indent`	`float`	`-0.15`	Vertical offset for the caption position relative to the axes.
`decimal_places_for_data_label`	`int`	`1`	Number of decimal places in the value label at the end of each bar.
`data_label_fontsize`	`int`	`11`	Font size for the numeric labels next to the bars.
`data_label_padding`	`float`	`None`	Horizontal gap between the bar end and its label. If None, uses 10% of the max value.
`filepath_to_save_plot`	`str`	`None`	Local path ending in .png or .jpg to save the plot. If None, the figure is not saved.

Example

python

from analysistoolbox.visualizations import PlotBarChart
import pandas as pd

# Epidemiology: incidence of influenza strains
flu_data = pd.DataFrame({
    'Virus Strain': ['A(H1N1)', 'A(H3N2)', 'B/Victoria', 'B/Yamagata'],
    'Confirmed Cases': [1250, 840, 310, 120],
})

PlotBarChart(
    flu_data, 'Virus Strain', 'Confirmed Cases',
    top_n_to_highlight=1,
    title_for_plot="Influenza Strain Distribution",
    subtitle_for_plot="Total confirmed cases for the current flu season",
)