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)
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.
Copyright¶
This library is licensed under the MIT License, meaning you can do whatever you want with it as long as all copies include these license terms. The full license text can be found in the LICENSE.rst file. See the AUTHORS.rst for for a complete list of copyright holders.