PlotSingleVariableHistogram — Analysis Tool Box

Introduction

Is this variable roughly normal, skewed, bimodal, or full of outliers — and where do the mean and median sit relative to each other? Those shape questions determine which statistical tests and transformations are appropriate downstream, and a histogram answers them faster than any summary statistic. PlotSingleVariableHistogram renders the frequency distribution of a numeric column with optional mean and median reference lines, giving an immediate read on central tendency and skew.

Teaching Note

Single-variable histograms are essential for:

Epidemiology: Visualizing the distribution of patient ages in a disease outbreak.
Healthcare: Analyzing the distribution of systolic blood pressure readings across a population.
Intelligence Analysis: Monitoring the distribution of travel distances for suspected illicit transport.
Data Science: Inspecting numeric features for skewness, outliers, and normalization requirements.
Public Health: tracking the distribution of daily water consumption per capita.
Finance: Examining the distribution of trade transaction sizes in a specific portfolio.
Project Management: Analyzing the distribution of task completion times across a project lifecycle.
Social Science: Visualizing the distribution of household income levels in a surveyed region.

Parameters

Parameter	Type	Default	Description
`dataframe`required	`pd.DataFrame`	—	The pandas DataFrame containing the numeric variable to analyze.
`value_column_name`required	`str`	—	The name of the continuous numeric column to be plotted on the x-axis.
`fill_color`	`str`	`'#999999'`	The hex color code for the histogram bars. Defaults to '#999999'.
`fill_transparency`	`float`	`0.6`	The transparency level (alpha) of the histogram bars (0 to 1). Defaults to 0.6.
`show_mean`	`bool`	`True`	Whether to overlay a dashed vertical line and text label indicating the arithmetic mean of the data. Defaults to True.
`show_median`	`bool`	`True`	Whether to overlay a dotted vertical line and text label indicating the median of the data. 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 source of the data, appended to the caption. Defaults to None.
`show_y_axis`	`bool`	`False`	Whether to display the vertical frequency (count) axis. 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.
`figure_size`	`tuple`	`(8, 6)`	Dimensions of the output 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 histogram using matplotlib and optionally saves it to disk.

Example

python

from analysistoolbox.visualizations import PlotSingleVariableHistogram
import pandas as pd
import numpy as np

# Epidemiology: age distribution of study participants
epi_df = pd.DataFrame({'Age': np.random.normal(45, 12, 500)})
PlotSingleVariableHistogram(
    epi_df, 'Age',
    fill_color="#27ae60",
    title_for_plot="Participant Age Distribution",
    subtitle_for_plot="Samples collected from regional demographic survey (N=500)"
)