The classical time series heatmap plot extended with a mean profile and daily average and peaks. This type of visualization is very informative when showing large amounts of time series data. While I mostly use it for energy data, it can easily be adapted for any other time series. The figure works best for data with a range of a few months to a few years and a resolution of a few minutes to a few hours.

Installation

The package is available on PyPI:

pip install heatmapts

Alternatively, you can install it from GitHub:

pip install git+https://github.com/markus-kreft/heatmapts.git

or simply clone this repository and work in the local directory.

Usage

The module provides the heatmapfigure function that takes a pandas Series with a timezone-aware DatetimeIndex with frequency.

This example shows how to load and prepare data from a csv file in the necessary way. This needs to be adapted depending on the format of the data at hand.

import pandas as pd
from heatmapts import heatmapfigure

# Read data
df = pd.read_csv('data.csv', index_col='Timestamp')
# Convert index to datetime and set timezone
df.index = pd.to_datetime(df.index, format='%Y-%m-%d %H:%M:%S').tz_convert('Europe/Zurich')
# Resample to 15min frequency
df = df.asfreq("15min", fill_value=pd.NA)
# Take data column and convert energy to power
series = df['Value'] * 4

fig = heatmapfigure(series, rasterized=True)
fig.savefig("plot.pdf")

Customization

The figure is designed for easy customization.

• Any additional keyword arguments are passed to pcolormesh, which is especially convenient for using a different colormap or norm or to use rasterization.

• Passing a tuple of latitude and longitude coordinates will add sunrise and sunset times to the plot.

fig = heatmapfigure(series, annotate_suntimes=(52.37, 4.90))

• Passing None as daily_label or hourly_label omits the respective daily overview or mean profile subplot.

fig = heatmapfigure(series, daily_label=None)

• The returned figure is subclassed from matplotlib.figure.Figure and features additional attributes for the heatmap, colorbar, daily and hourly axes. These can be modified as any other matplotlib axis.

fig.ax_heatmap.xaxis.set_major_locator(mdates.YearLocator())
fig.ax_heatmap.xaxis.set_major_formatter(mdates.DateFormatter("%Y"))

• The figure uses its own rcParams for styling. Pass a rc_params dictionary to override individual parameters for a single figure; it is merged on top of the defaults in HeatmapFigure.rc_params. The colors of the daily peak scatter, its zero line, and the sunrise/sunset lines are not rcParams and can be set directly via color_scatter, color_axes, and color_suntimes.

fig = heatmapfigure(
    series,
    rc_params={"font.family": "serif", "font.size": 5},
    color_scatter="white",
)

• To change the defaults for every figure, modify HeatmapFigure.rc_params on the class. Passing an empty rc_params={} together with empty class defaults uses the current matplotlib parameters (e.g., as determined by matplotlibrc).

from heatmapts import HeatmapFigure
HeatmapFigure.rc_params["font.family"] = "serif"