d3-calendar

A d3-module (version 4) implementation of the heatmap calendar.

The module is based on the original Calendar View as a starting point and on many of the other implementations for code improvements and refactoring ( see DKirwan's, g1eb's and KathyZ's ).

The module has been created on the basis of Mike Bostock's guidelines and skeleton project

Installing

If you use NPM, npm install d3-calendar. Otherwise, download the latest release.

Usage

Make sure to include both d3 (version 4, not included) and the module, in this order.

<script src="d3.min.js"></script>
<script src="/dist/d3-calendar.min.js"></script>

The HTML code only needs 2 placeholders: one for the calendar itself (e.g. <div id="chart">), one for the legend (<div id="chart">).

<div id="chart"></div>
<div id="legend"></div>

Create your data, nesting it by date:

let byDay = d3.nest()
    .key(function (d) { return formatYear(d.date); })
    .rollup(function () { return d.value || NaN;
    })
    .object(myData);

Finally, create the graph and associate it with both the placeholder and the nested dataset

let chart = d3.calendar()
    .mondayWeek(true);
d3.select('#chart')
    .datum(byDay)
    .call(chart);

Check the examples for mode detailed instructions.

API Reference

# d3.calendar()

Constructs a new calendar graph

# calendar.width([number])

If number is specified, sets the width of the chart and returns the chart instance (for chaining). If number is not specified, returns the current width. Default is 960.

# calendar.height([number])

If number is specified, sets the height of the chart and returns the chart instance (for chaining). If number is not specified, returns the current height. Default is 136.

# calendar.cellSize([number])

If number is specified, sets the dimension of the day cards (the rectangle showing the heat value) and returns the chart instance (for chaining). If number is not specified, returns the current dimension. Default is 17.

# calendar.weeklySummary([boolean])

If boolean is specified, sets whether the weekly summary should be displayed and returns the chart instance (for chaining). If boolean is not specified, returns the current status. Default is false.

# calendar.mondayWeek([boolean])

If boolean is specified, sets whether the week starts on a Monday (true)or a Sunday (false)and returns the chart instance (for chaining). If boolean is not specified, returns the current status. Default is true.

# calendar.color([scale])

If scale is specified, sets the color scale used for the heatmap and returns the chart instance (for chaining). If scale is not specified, returns the current scale.

The scale needs to define both the quantitative input domain (i.e. the extent of the values to be graphed) and the discrete range of the colors to be used. Default is defined as follow, using the d3.scaleQuantize scale:

d3.scaleQuantize()
    .domain([0, 5])
    .range(["#a50026", "#d73027", "#f46d43", "#fdae61", "#fee08b", "#ffffbf", "#d9ef8b", "#a6d96a", "#66bd63", "#1a9850", "#006837"]);

# calendar.labels([array])

If array is specified, sets the labels for the different elements of the graph and returns the chart instance (for chaining). If array is not specified, returns the current labels. Default is defined as follow:

defaultLabels = {
    day: ["M","T","W","T","F","S","S"],
    month: ["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep","Oct","Nov","Dec"],
    legend: ["Low","High"]
};

New values are merged with the default using JavaScript's Object.assign() so subsets of the labels can be redefined, leaving others untouched, e.g.:

calendar.labels({
    day: ["L","M","M","J","V","S","D"]
});

Note that the day labels are always given starting from Monday, regardless of the status of the mondayWeek().

Thanks