PlotOverlappingAreaChart — Analysis Tool Box

Introduction

Several time series plotted as thin lines on the same axes tend to blur together, especially once you're past two or three of them — filled areas make magnitude and overlap far easier to read than lines alone. PlotOverlappingAreaChart renders multiple categorical variables over time as semi-transparent overlapping areas, automatically ordering them by mean value and optionally labeling each area directly, so both the trend and the relative scale of each series stay visible at once.

Teaching Note

Overlapping area charts are essential for:

Epidemiology: Comparing time-series trends of infection rates across multiple regions.
Healthcare: Visualizing patient census levels by hospital department over a fiscal year.
Intelligence Analysis: Monitoring threat activity levels across monitored geopolitical sectors.
Data Science: Tracking cumulative performance metrics across different model training versions.
Public Health: Monitoring atmospheric pollutant concentrations across several urban stations.
Finance: Visualizing the growth of multiple asset classes within an investment portfolio.
Operations: Tracking resource utilization (CPU/Memory) across different server clusters.
Economics: Visualizing historical unemployment rates across various demographic segments.

Parameters

Parameter	Type	Default	Description
`dataframe`required	`pd.DataFrame`	—	The pandas DataFrame containing the time series data in long format.
`value_column_name`required	`str`	—	The name of the column containing the numeric values (y-axis).
`variable_column_name`required	`str`	—	The name of the categorical column used to group the data into different areas.
`time_column_name`required	`str`	—	The name of the column containing the temporal data (x-axis).
`figure_size`	`tuple`	`(8, 5)`	Dimensions of the output figure as a (width, height) tuple in inches. Defaults to (8, 5).
`line_alpha`	`float`	`0.9`	The transparency level (alpha) for the boundary lines. Defaults to 0.9.
`color_palette`	`str`	`'Paired'`	The name of the seaborn color palette to use for the areas. Defaults to 'Paired'.
`fill_alpha`	`float`	`0.8`	The transparency level (alpha) for the filled areas beneath the lines. Defaults to 0.8.
`label_variable_on_area`	`bool`	`True`	Whether to place text labels for each variable directly inside their respective areas. Defaults to True.
`label_font_size`	`int`	`12`	The font size for the internal area labels. Defaults to 12.
`label_font_color`	`str`	`'#FFFFFF'`	The hex color code for the internal area labels. Defaults to '#FFFFFF'.
`number_of_x_axis_ticks`	`int`	`None`	The maximum number of ticks to display on the horizontal time axis. Defaults to None.
`x_axis_tick_rotation`	`int`	`None`	The rotation angle (in degrees) for the x-axis tick labels. Defaults to None.
`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 data origin, appended to the caption. Defaults to None.
`x_indent`	`float`	`-0.127`	Horizontal offset for the titles and captions relative to the axes. Defaults to -0.127.
`title_y_indent`	`float`	`1.125`	Vertical offset for the title position relative to the grid. Defaults to 1.125.
`subtitle_y_indent`	`float`	`1.05`	Vertical offset for the subtitle position relative to the grid. Defaults to 1.05.
`caption_y_indent`	`float`	`-0.3`	Vertical offset for the caption position relative to the grid. Defaults to -0.3.
`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 overlapping area chart using matplotlib and optionally saves it to disk.

Example

python

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

# Epidemiology: regional infection trends over 6 months
dates = pd.date_range(start="2024-01-01", periods=6, freq='M')
epi_df = pd.DataFrame({
    'Date': np.tile(dates, 3),
    'Region': np.repeat(['East', 'West', 'Central'], 6),
    'Cases': [10, 15, 45, 60, 30, 20, 5, 8, 22, 35, 18, 12, 15, 25, 35, 45, 50, 40]
})
PlotOverlappingAreaChart(
    epi_df, 'Cases', 'Region', 'Date',
    title_for_plot="Viral Transmission Velocity",
    subtitle_for_plot="New confirmed cases per 100,000 residents"
)