PlotTimeSeries — Analysis Tool Box

Introduction

Is a metric trending up, flattening out, or swinging seasonally — and does that pattern differ across segments? Time is usually the axis that matters most for operational and epidemiological monitoring, and a well-formatted line chart makes trend, inflection points, and group divergence visible at a glance. PlotTimeSeries plots one or more series against a time axis, with automatic color grouping, optional marker sizing by a third variable, and smart tick density control for long date ranges.

Teaching Note

Time series plots are essential for:

Epidemiology: Tracking the daily count of new infection cases during an epidemic.
Healthcare: Monitoring patient vitals (e.g., heart rate) over the course of a hospital stay.
Intelligence Analysis: Visualizing changes in identified troop movements over a tactical cycle.
Data Science: Monitoring model performance metrics across sequential training epochs.
Public Health: Tracking seasonal fluctuations in urban air quality indices.
Finance: Analyzing historical price movements of various assets to identify trends.
Operations: Monitoring server response times or throughput during peak traffic periods.
Marketing: Tracking weekly conversion rates following a multi-channel campaign launch.

Parameters

Parameter	Type	Default	Description
`dataframe`required	`pd.DataFrame`	—	The pandas DataFrame containing the temporal data, numeric values, and optional grouping variables.
`value_column_name`required	`str`	—	The name of the column containing the numeric values to be plotted on the vertical y-axis.
`time_column_name`required	`str`	—	The name of the column containing the temporal data (e.g., dates or sessions) for the x-axis.
`grouping_column_name`	`str`	`None`	The name of a categorical column used to group the data into multiple colored lines. Defaults to None.
`line_color`	`str`	`'#3269a8'`	The hex color code for the time-series line when no grouping is applied. Defaults to '#3269a8'.
`line_alpha`	`float`	`0.8`	The transparency level (alpha) of the line and associated markers (0 to 1). Defaults to 0.8.
`color_palette`	`str`	`'Set2'`	The name of the seaborn color palette to use when grouping by a categorical variable. Defaults to 'Set2'.
`show_legend`	`bool`	`True`	Whether to display the legend for grouping categories. Defaults to True.
`marker_size_column_name`	`str`	`None`	The name of an additional numeric column to control the size of optional scatter markers. Defaults to None.
`marker_size_normalization`	`tuple`	`None`	A (min, max) tuple representing the scaling range for the markers. Defaults to None.
`number_of_x_axis_ticks`	`int`	`None`	The maximum number of ticks to display on the horizontal time axis to avoid overcrowding. 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 figure. 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.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.
`figure_size`	`tuple`	`(8, 5)`	Dimensions of the output figure as a (width, height) tuple in inches. Defaults to (8, 5).
`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 time series plot using matplotlib and optionally saves it to disk.

Example

python

from analysistoolbox.visualizations import PlotTimeSeries
import pandas as pd

monthly_sales = pd.DataFrame({
    'month': pd.date_range('2023-01', periods=12, freq='MS'),
    'revenue': [420, 380, 510, 490, 600, 720, 680, 750, 810, 870, 920, 1050],
})

PlotTimeSeries(
    dataframe=monthly_sales,
    value_column_name='revenue',
    time_column_name='month',
    title_for_plot='Monthly Revenue — North Region',
    subtitle_for_plot='Jan–Dec 2023',
    data_source_for_plot='Internal Sales Database',
)