How to create a custom color legend for a calendar-based heatmap plot (calmap)?

Question

I have a dataframe that contains numerical data collected over the whole year, which I want to plot as a heatmap over time (similar to Github contributions), where

• months are plotted along the x-axis
• days are plotted along the y-axis
• color of each box/datapoint denotes high/low numerical value: for my example below, blue represents a high number and red represents a low number.

I'm using a Python library calmap which generates a calendar heatmaps from Pandas time series data. This is the code I used to create the above heatmap.

days = df_activities.loc[:,'Date'].to_numpy()  
events = pd.Series(df_activities.loc[:, 'ActivityLevel'].to_numpy(), index=days)
calmap.yearplot(events, cmap='RdYlBu', linewidth=0.3)
calmap.plt.title("Activity Data across 2022")

where a snippet of df_activites looks like this:

df_activites[['Date', 'ActivityLevel']].head(10)

    Date            ActivityLevel
0   2022-01-01      5.733
1   2022-01-02      1.317
2   2022-01-03      5.150
3   2022-01-04      7.283
4   2022-01-05      6.450
5   2022-01-06      8.933
6   2022-01-07      7.333
7   2022-01-08      8.483
8   2022-01-09      6.417
9   2022-01-10      5.517

Question: I want to create a customized legend to label my heatmap and show that blue corresponds to high activity level and red corresponds to low activity level. As I'm using calmap and not using seaborn, what would be the best way to achieve this? Any help is greatly appreciated!

It could be something as simple as below legend, where the colors/labels are replaced with my dataset.

Answer 1

First, you can create a custom discrete colormap similar to this example.

Second, you can create a series of empty plots to hold labels for the legend (supposed that you already have a list of labels corresponding to every color).

Finally, bbox_to_anchor could be used to put legend outside of the plot. More details about this parameter can be found in this excellent answer.

Hope it helps.

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import calmap
from matplotlib import colors

# Generating sample data
all_days = pd.date_range('01.01.2022', periods=700, freq='D')
days = np.random.choice(all_days, 500)
events = pd.Series(np.random.randn(len(days)), index=days)

# The colors and labels could be used from elsewhere as long as they are of the same size
cm_colors = ['blue', 'green', 'red']
cm_labels = ['Low', 'Medium', 'High']

cmap = colors.ListedColormap(cm_colors)

fig, ax = plt.subplots(figsize=(10, 3))
calmap.yearplot(events, cmap=cmap, vmin=events.min(), vmax=events.max(), linewidth=0.3, ax=ax)

for i in range(len(cm_colors)):
    ax.plot([],[],c=cmap.colors[i],label=cm_labels[i])

ax.legend(bbox_to_anchor=(1.04,0.5), loc='center left')
plt.title('Activity data across 2022')
fig.tight_layout()

plt.show()

The result is:

In addition, calmap.yearplot source could be found here.