Awesome Open Source
Awesome Open Source

July

July

A small library for creating pretty heatmaps of daily data.

Features

  • Get rid of the eternal matplotlib tweaking every time you want to plot data in proper calendar format.
  • Generate GitHub activity overview-like heatmaps of your daily data.
  • Automatic handling of missing dates in input date range.
  • July does not rely only pandas (though it accepts it). Only numpy arrays and native Python data structures are used internally.
  • Accepted date formats: datetime.datetime, datetime.date, str, pd.DatetimeIndex

Install

$ pip install july

Usage

import numpy as np
import matplotlib.pyplot as plt
import july
from july.utils import date_range

dates = date_range("2020-01-01", "2020-12-31")
data = np.random.randint(0, 14, len(dates))
# GitHub Activity like plot (for someone with consistently random work patterns).
july.heatmap(dates, data, title='Github Activity', cmap="github")

GitHub heatmap

# Here, 'osl_df' is a pandas df. 
july.heatmap(osl_df.date, osl_df.temp, cmap="golden", colorbar=True, title="Average temperatures: Oslo , Norway")

Golden heatmap

# More exhaustive example using useless, but pretty colours.
july.heatmap(dates=dates, 
             data=data, 
             cmap='Pastel1',
             month_grid=True, 
             horizontal=True,
             value_label=False,
             date_label=False,
             weekday_label=True,
             month_label=True, 
             year_label=True,
             colorbar=False,
             fontfamily="monospace",
             fontsize=12,
             title=None,
             titlesize='large',
             dpi=100)

Pastel heatmap

# Month plot with dates.
july.month_plot(dates, data, month=5, date_label=True, ax=axes[0])
# Month plot with values.
july.month_plot(dates, data, month=5, value_label=True, ax=axes[1])

Month plot

# Calendar plot. 
july.calendar_plot(dates, data)

Calendar plot

Why "July"?

Main reason: All the obvious names like calplot, calmap, and calendarplot were all already taken by similar packages. This had me looking for a new name that wouldn't get easily mixed up with the other packages.

The reasoning was roughly as follows:

  • Heatmap + monthHot monthJuly

Also, as a summer loving person stuck in the Northern hemisphere, July is my favourite month by a light year.

Release notes

  • v0.1.0: Working build but with minimal documentation.
  • v0.1.1: Fix relative image link in readme.
  • v0.1.2: Remove unnecessary argument from rcmod to be compatible with matplotlib versions earlier than v3.4.x.
  • v0.1.3: Fix week number labelling bug in month_plot() and calendar_plot()

TODO:

  • Fix slight misalignment of plot and cbar when date_grid and colorbar are used in conjunction.
  • Document everything...
  • Add type hints.
  • Add automatic date handling for strings of more types than just YYYY-MM-DD.
Related Awesome Lists
Top Programming Languages

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Python (865,958
Calendar (9,917
Matplotlib (4,228
Visualisation (2,728
Heatmap (1,587
Calendar Heatmap (13
Heatmap Visualization (12
Daily Data (6