Calendar heatmaps from Pandas time series data

Plot Pandas time series data sampled by day in a heatmap per calendar year, similar to GitHub’s contributions plot, using matplotlib.

Package calplot was started as a fork of calmap with the addition of new arguments for easier customization of plots. Code refactoring was carried out to increase the maintainability of this package.

Installation

To install the latest release via PyPI using pip:

pip install calplot

The latest development version can be found on GitHub.

Usage

Assume we have some weighted events as a Pandas Series with a DatetimeIndex.

For illustration purposes we just create 500 events as random float values assigned to random days over a 730-day period:

import numpy as np; np.random.seed(sum(map(ord, 'calplot')))
import pandas as pd
import calplot

all_days = pd.date_range('1/1/2019', periods=730, freq='D')
days = np.random.choice(all_days, 500)
events = pd.Series(np.random.randn(len(days)), index=days)

We can use calplot() to plot all years as subplots into one figure:

calplot.calplot(events, cmap='YlGn', colorbar=False)
_images/index-2.svg

In particular, note that calplot.calplot() wraps calplot.yearplot(). Keyword arguments passed to calplot.calplot() will be passed to calplot.yearplot() when it is called.

API documentation

calplot.yearplot(data, year=None, how='sum', vmin=None, vmax=None, cmap='viridis', fillcolor='whitesmoke', linewidth=1, linecolor=None, edgecolor='gray', daylabels=['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'], dayticks=True, dropzero=None, textformat=None, textfiller='', textcolor='black', monthlabels=['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'], monthlabeloffset=15, monthticks=True, ax=None, **kwargs)[source]

Plot one year from a timeseries as a calendar heatmap.

Parameters
dataSeries

Data for the plot. Must be indexed by a DatetimeIndex.

yearinteger

Only data indexed by this year will be plotted. If None, the first year for which there is data will be plotted.

howstring

Method for resampling data by day. If None, assume data is already sampled by day and don’t resample. Otherwise, this is passed to Pandas Series.resample.

vmin, vmaxfloats

Values to anchor the colormap. If None, min and max are used after resampling data by day.

cmapmatplotlib colormap name or object

The mapping from data values to color space.

fillcolormatplotlib color

Color to use for days without data.

linewidthfloat

Width of the lines that will divide each day.

linecolorcolor

Color of the lines that will divide each day. If None, the axes background color is used, or ‘white’ if it is transparent.

daylabelslist

Strings to use as labels for days, must be of length 7.

daytickslist or int or bool

If True, label all days. If False, don’t label days. If a list, only label days with these indices. If an integer, label every n day.

dropzerobool

If True, don’t fill a color for days with a zero value.

monthlabelslist

Strings to use as labels for months, must be of length 12.

monthlabeloffsetinteger

Day offset for labels for months to adjust horizontal alignment.

monthtickslist or int or bool

If True, label all months. If False, don’t label months. If a list, only label months with these indices. If an integer, label every n month.

edgecolorcolor

Color of the lines that will divide months.

textformatstring

Text format string for grid cell text

textfillerstring

Fallback text for grid cell text for cells with no data

textcolorcolor

Color of the grid cell text

axmatplotlib Axes

Axes in which to draw the plot, otherwise use the currently-active Axes.

kwargsother keyword arguments

All other keyword arguments are passed to matplotlib ax.pcolormesh.

Returns
axmatplotlib Axes

Axes object with the calendar heatmap.

calplot.calplot(data, how='sum', yearlabels=True, yearascending=True, yearlabel_kws=None, subplot_kws=None, gridspec_kws=None, figsize=None, fig_kws=None, colorbar=None, suptitle=None, suptitle_kws=None, tight_layout=True, **kwargs)[source]

Plot a timeseries as a calendar heatmap.

Parameters
dataSeries

Data for the plot. Must be indexed by a DatetimeIndex.

howstring

Method for resampling data by day. If None, assume data is already sampled by day and don’t resample. Otherwise, this is passed to Pandas Series.resample.

figsize(float, float)

Size of figure for the plot.

suptitlestring

Title for the plot.

yearlabelsbool

Whether or not to draw the year label for each subplot.

yearascendingbool

Sort the calendar in ascending or descending order.

yearlabel_kwsdict

Keyword arguments passed to the matplotlib set_ylabel call which is used to draw the year for each subplot.

subplot_kwsdict

Keyword arguments passed to the matplotlib subplots call.

gridspec_kwsdict

Keyword arguments passed to the matplotlib GridSpec constructor used to create the grid the subplots are placed on.

fig_kwsdict

Keyword arguments passed to the matplotlib subplots call.

suptitle_kwsdict

Keyword arguments passed to the matplotlib suptitle call.

kwargsother keyword arguments

All other keyword arguments are passed to yearplot.

Returns
fig, axesmatplotlib Figure and Axes

Tuple where fig is the matplotlib Figure object axes is an array of matplotlib Axes objects with the calendar heatmaps, one per year.