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:
data : Series

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

year : integer

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

how : string

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, vmax : floats

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

cmap : matplotlib colormap name or object

The mapping from data values to color space.

fillcolor : matplotlib color

Color to use for days without data.

linewidth : float

Width of the lines that will divide each day.

linecolor : color

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

daylabels : list

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

dayticks : list 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.

dropzero : bool

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

monthlabels : list

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

monthlabeloffset : integer

Day offset for labels for months to adjust horizontal alignment.

monthticks : list 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.

edgecolor : color

Color of the lines that will divide months.

textformat : string

Text format string for grid cell text

textfiller : string

Fallback text for grid cell text for cells with no data

textcolor : color

Color of the grid cell text

ax : matplotlib Axes

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

kwargs : other keyword arguments

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

Returns:
ax : matplotlib 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:
data : Series

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

how : string

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.

suptitle : string

Title for the plot.

yearlabels : bool

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

yearascending : bool

Sort the calendar in ascending or descending order.

yearlabel_kws : dict

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

subplot_kws : dict

Keyword arguments passed to the matplotlib subplots call.

gridspec_kws : dict

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

fig_kws : dict

Keyword arguments passed to the matplotlib subplots call.

suptitle_kws : dict

Keyword arguments passed to the matplotlib suptitle call.

kwargs : other keyword arguments

All other keyword arguments are passed to yearplot.

Returns:
fig, axes : matplotlib 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.