Calendar Heat Map

Setup

1. Download the plugin and copy cal-heatmap.min.js and cal-heatmap.css to your app.
2. Install d3js in your app.
3. Create your first calendar:

   <div id="cal-heatmap"></div>
   <script type="text/javascript">
   	var cal = new CalHeatMap();
   	cal.init({
   		data: "datas.json"
   	});
   </script>

This will insert a new calendar into #cal-heatmap in your page, and fill it with data from datas.json.

By default, the calendar will display 12 hours, divided into 60 minutes.

There's a lot of other settings available to customize your calendar.

API

• General
• Callback
• Formatting

10

2

0

2

[10, 20, 30, 40]

true

{
  lower: "less than {min} {name}",
  inner: "between {down} and {up} {name}",
  upper: "more than {max} {name}"
}

["item", "items"]

{
  empty: "{date}",
  filled: "{count} {name} {connector} {date}"
}

{}

false

{
  nextLabel: "Next",
  previousLabel: "Previous"
}

500

1

Examples

With Default values

By default, cal-heatmap will always display 12 hours, split into 60 minutes each.

Unless you set the date property in init(), the calendar will start at the beginning of the current hour.

var calendar = new CalHeatMap();
calendar.init({});

Days > hours

Display all the hours for 10 days, starting from January 15th, 2000.

JsFiddlevar calendar = new CalHeatMap();
calendar
	data: "datas-years.json",		// Fill the graph with datas from that json file
	start: new Date(2000, 0, 15), 	// Start the calendar on 15th January, 2000
	id : "graph_b",
	domain : "day",					// Group data by days
	subDomain : "hour",				// Split each day by hours
	range : 10,						// Number of days to display
	browsing: true, 				// Enable browsing
    afterLoadNextDomain: function (start, end) {
        alert("You just loaded a new domain starting on " + start + " and ending on " + end);
    }
});

Months > days

Display all days, for 3 months, from February 2000.
Let's try changing the scale threshold, since the number of data represented in a subdomain is larger, since it's now a day instead of hour. Hover on the scale to view the new range each color is representing.

• Hover on the scale to notice that each color is now representing a different range than the previous calendar
• The date formatting when you hover on a day is also changed, according to the subdomain

JsFiddlevar calendar = new CalHeatMap();
calendar
	data: "datas-years.json",
	start: new Date(2000, 1),
	id : "graph_c",
	domain : "month",			// Group data by month
	subDomain : "day",			// Split each month by days
	range : 3,					// Just display 3 months
	scale: [40, 60, 80, 100] 	// Custom threshold for the scale
});

Months > days (horizontally)

Same as above, but with the days layered like a regular month calendar, with each column corresponding to a day, and each row to a week. Also start the week on Sunday.

var calendar = new CalHeatMap();
calendar
	data: "datas-years.json",
	start: new Date(2000, 5),
	id : "graph_k",
	domain : "month",
	subDomain : "x_day",
	range : 3,
	cellsize: 15,
	cellpadding: 3,
	cellradius: 5,
	domainGutter: 15,
	weekStartOnMonday: 0,
	scale: [40, 60, 80, 100]
});

Months > hours

Display all the hours of January 2000.
Also resize the cell to fit in the page.

JsFiddlevar calendar = new CalHeatMap();
calendar
	data: "datas-years.json",
	start: new Date(2000, 0),
	id : "graph_f",
	domain : "month",
	subDomain : "hour",
	range : 1,
	cellsize: 6,
	cellpadding: 1
});

Months > weeks

Display weeks for February, March and April 2000.

JsFiddlevar calendar = new CalHeatMap();
calendar
	data: "datas-years.json",
	start: new Date(2000, 1),
	id : "graph_c",
	domain : "month",				// Group data by month
	subDomain : "week",				// Split each month by week
	range : 3,						// Just display 3 months
	scale: [120, 400, 450, 500] 	// Custom threshold for the scale
});

Weeks > hours

Display all the hours of the first 2 weeks of Januray 2000

JsFiddlevar calendar = new CalHeatMap();
calendar
	data: "datas-years.json",
	start: new Date(2000, 0),
	id : "graph_h",
	domain : "week",
	subDomain : "hour",
	range : 2
});

Year > days

Display all days of year 2000.
Additionally, use a custom name for the data : we're representing the number of lost kittens by days, in french.

• Hover on a day or legend to view the new title

JsFiddlevar calendar = new CalHeatMap();
calendar.init({
	moment.lang("fr");
	var calendar = new CalHeatMap();
	calendar.init({
		data: "datas-years.json",
		start: new Date(2000, 0),
		id : "graph_d",
		domain : "year",
		subDomain : "day",
		range : 1,
		scale: [40, 60, 80, 100],
		itemName: ["chat perdu", "chats perdus"],
		cellLabel: {
			empty: "Aucune données pour le {date}",
			filled: "il y a eu {count} {name} le {date}"
		},
		scaleLabel: {
			lower: "Belle journée, il y a eu moins de {min} {name}",
			inner: "Pas mal, entre {down} et {up} {name}",
			upper: "Peut faire mieux, plus de {max} {name}"
		},
		format: {
			date: function(date) {
				return moment(date).format("LL");
			},
			legend: null,
		}
	});
});

Year > months

Display 1 year, split by months, with a custom legend and title formatting, as well as a custom callback when clicking on a month.

• Hover on a cell to view custom title formatting
• Click on a cell to view custom onClick callback

JsFiddlevar calendar = new CalHeatMap();
calendar.init({
	data: "datas-years.json",
	start: new Date(2000, 0),
	id : "graph_e",
	range : 1,
	domain : "year",
	subDomain : "month",
	scale: [1950, 2050, 2150, 2250],
	displayScale: false,					// Don't display the scale
	format: {
		date: "==%B==",						// Custom date format, hover on a month to view
		legend: "Thy year is %Y, yeah !"	// Custom domain legend
	},
	onClick: function(date, count) {
		alert("Oh gosh, " + count + " things occured on " + date.toISOString());
	}
});

Theme

All colors can be customized via the css

This graph represents the number of visitors per hour for one month. Datas are pulled from Google Analytics, in csv format. This example also highlight the datas format conversion, to transform your datas to something understandable by cal-heatmap.

var calendar = new CalHeatMap();
calendar.init({
	id: "graph_l",
	data: "ga.csv",
	dataType: "csv",
	domain: "day",
	subDomain: "hour",
	range: 31,
	cellpadding: 1,
	itemName : ["visitor", "visitors"],
	scale: [2, 4, 6, 8, 10],
	start: new Date(2013, 03, 14),
	afterLoadData: function(d) {
		var start = +new Date(2013, 03, 14) / 1000;
		var stats = {};
		for (var i = 0, total = d.length; i < total; i++ ) {
			o = d[i];
			stats[(parseInt(o.Hour, 10) * 3600) + start] = o.Visits;
		}
		return stats;
	}
});

Data Source

Expected Datas format

To display datas in the calendar, cal-heatmap takes a set of dates, associated with a count value. Those datas are grouped inside a json object, following the convention :

{
	"946702811" : 12,
	"946702812" : 53
	....
}

The object must contains one property by date, keyname is the unix timestamp of the date (in seconds), and the value, is the count number associated to this date.

See the example datas-hours.json file.

It's the same formatting for all domain type, data will automatically be grouped into min/days/week/hours/month, depending on the domain type. Having a count for each seconds lets you jump to the smaller domain without losing datas.

Exotic datas format

Of course, we can't expect all the API to return the results following the format above.

That's why there's a special callback (afterLoadData(d)) that you can use to convert your results to the required format. This function takes the result of your API as argument, after interpretation by the dataType engine, and must return a json object formatted as above.

// datas is an array of object
var datas = [
	{date: 946702811, value: 15},
	{date: 946702812, value: 25},
	{date: 946702813, value: 10}
]

var parser = function(data) {
	var stats = {};
	for (var d in data) {
		stats[data[d].date] = data[d].value;
	}
	return stats;
};

// Parser will output the object
//{
//	"946702811": 15,
//	"946702812": 25,
//	"946702813": 10
}

var calendar = new CalHeatMap();
calendar.init({
  data: datas,
  afterLoadData: parser
});

Support

Support and bug reports are on tracked with the project github issues

Faq : https://github.com/kamisama/cal-heatmap/wiki/FAQ

Authors

Wan Qi Chen

• Github: https://github.com/kamisama
• Email : kami@kamisama.me
• Google+

Licence

CalHeatMap is released under the MIT License

Copyright (c) 2013 Wan Qi Chen

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.