Build a calendar heatmap

A calendar heatmap is a data visualization that shows activity or values over time, typically across days in a year, where each day is colored based on the intensity or frequency of an event. It’s widely used to represent user activity, stock prices, or any time-series data on a calendar grid.

How to Build a Calendar Heatmap

1. Understand the Structure

• The heatmap is laid out as a grid with weeks as columns and days of the week as rows.

• Each cell represents one day.

• Color intensity reflects the data value for that day.

2. Data Preparation

• You need a dataset with dates and corresponding values (e.g., number of events per day).

• Fill missing dates with zero or null values to maintain continuity.

Example data structure:

python
CopyEdit
[
  {"date": "2025-01-01", "value": 5},
  {"date": "2025-01-02", "value": 2},
  ...
]

3. Tools and Libraries

• Python: Matplotlib, Seaborn, or Plotly

• JavaScript: D3.js, Chart.js, or libraries like react-calendar-heatmap

• Excel or Google Sheets can be used for basic heatmaps but less flexible

Example: Building a Calendar Heatmap in Python with Matplotlib & Pandas

python
CopyEdit
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import calendar
from matplotlib.colors import LinearSegmentedColormap

# Generate example data: one year of daily values
date_range = pd.date_range(start='2025-01-01', end='2025-12-31')
values = np.random.poisson(lam=2, size=len(date_range))  # example values
data = pd.DataFrame({'date': date_range, 'value': values})

# Prepare data: add columns for week and day of week
data['week'] = data['date'].dt.isocalendar().week
data['weekday'] = data['date'].dt.weekday  # Monday=0

# Handle the case where week number resets after Dec 31 to 1 of next year
# This can cause alignment issues
data.loc[(data['date'].dt.month == 12) & (data['week'] == 1), 'week'] = 53

# Create pivot table: rows=weekday, columns=week, values=value
pivot = data.pivot(index='weekday', columns='week', values='value')

# Create custom color map (light to dark green)
cmap = LinearSegmentedColormap.from_list("mycmap", ["#e0f3db", "#43a2ca"])

# Plot
fig, ax = plt.subplots(figsize=(15, 5))
c = ax.imshow(pivot, aspect='auto', cmap=cmap)

# Formatting
ax.set_yticks(range(7))
ax.set_yticklabels(['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'])
ax.set_xlabel('Week Number')
ax.set_title('Calendar Heatmap for 2025')

# Add colorbar
fig.colorbar(c, ax=ax, orientation='vertical', label='Value')

plt.show()

Explanation

• The heatmap shows each week horizontally.

• Each row corresponds to a day of the week.

• Color intensity shows the value for that date.

Alternative: Using JavaScript with D3.js

• D3 has great examples of calendar heatmaps with interactivity.

• You need to:

  • Parse date data

  • Map dates into week/day grid

  • Use color scales to shade rectangles

• Plenty of open-source examples exist like this one.

Key Tips

• Always align weeks properly, especially at year boundaries.

• Handle missing dates gracefully.

• Use a color gradient that is intuitive (e.g., light for low activity, dark for high).

• Add tooltips or interactivity if used in web apps for better usability.

Would you like a fully coded example in JavaScript or more advanced features like interactivity?