d3-heatmap2

A D3.js plugin that produces heatmaps.

Example

Click here to check the demo, and source.

Installing

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

Getting Started

<head>
  <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/spiermar/d3-heatmap2@0.1/dist/d3-heatmap2.css">
</head>
<body>
  <div id="chart"></div>
  <div id="details"></div>
  <script src="https://d3js.org/d3.v4.min.js" charset="utf-8"></script>
  <script src="https://cdn.jsdelivr.net/gh/spiermar/d3-heatmap2@0.1/dist/d3-heatmap2.js"></script>
  <script>
    d3.json("data.json", function(error, data) {
        if (error) return console.warn(error)    
        var h = d3.heatmap()
            .width(960)
            .xAxisScale([0,120])
            .yAxisScale([0,2000])
            .colorScale(d3.scaleLinear()
                .domain([0, 65 / 2, 65])
                .range(['#F5F5DC', '#FF5032', '#E50914'])
            )
            
        d3.select("#chart")
            .datum(data)
            .call(h)
    })
  </script>
</body>

Heatmap Data Structure

[
    [1,0,0],
    [0,1,0],
    [0,0,1]
]

API Reference

# heatmap.title([title])

Heatmap title. Defaults to empty if not set. If called with no arguments, title will return the heatmap title.

# heatmap.subtitle([subtitle])

Heatmap subtitle. Defaults to empty if not set. If called with no arguments, subtitle will return the heatmap subtitle.

# heatmap.legendLabel([label])

Heatmap label legend. Defaults to empty if not set. If called with no arguments, legendLabel will return the heatmap label legend.

# heatmap.width([width])

Heatmap width in px. Defaults to 960px if not set. If called with no arguments, width will return the heatmap width.

# heatmap.margin([object])

Heatmap title. Defaults to the values below if not set.

{
    top: 20,
    right: 0,
    bottom: 0,
    left: 0
}

If called with no arguments, margin will return the heatmap margin object.

# heatmap.colorScale([function])

Replaces the built-in color scale function. The scale function takes no arguments, and returns a d3.scale function. Example:

heatmap.colorScale(d3.scaleLinear()
    .domain([0, 65 / 2, 65])
    .range(['#FFFFFF', '#ff5032', '#e50914'])
);

If called with no arguments, colorScale will return the heatmap colorScale function.

# heatmap.xAxisScale([array])

Heatmap xAxis scale domain, in a value scale array format. Defaults to null if not set, which displays the xAxis labels instead of the scale.

heatmap.xAxisScale([0, 1000]);

If called with no arguments, xAxisScale will return the heatmap xAxis scale domain array.

# heatmap.yAxisScale([array])

Heatmap yAxis scale domain, in a value scale array format. Defaults to null if not set, which displays the yAxis labels instead of the scale.

heatmap.yAxisScale([0, 100]);

If called with no arguments, yAxisScale will return the heatmap yAxis scale domain array.

# heatmap.xAxisScaleTicks([integer])

If using xAxisScale, defines the number of scale ticks. Defaults to 20 if not set.

If called with no arguments, xAxisScaleTicks will return the number of ticks in the xAxis scale.

# heatmap.yAxisScaleTicks([integer])

If using yAxisScale, defines the number of scale ticks. Defaults to 20 if not set.

If called with no arguments, yAxisScaleTicks will return the number of ticks in the yAxis scale.

# heatmap.xAxisLabelFormat([function])

Heatmap xAxis label formatter function. The label formatter function takes a single argument, the label array value, and returns a label string. Defaults to function (d) { return d } if not set, which displays the value in the xAxis labels array.

heatmap.xAxisLabelFormat(function (d) { return d + ' sec' });

If called with no arguments, xAxisLabelFormat will return the heatmap xAxis label formatter function.

# heatmap.yAxisLabelFormat([function])

Heatmap yAxis label formatter function. The label formatter function takes a single argument, the label array value, and returns a label string. Defaults to function (d) { return d } if not set, which displays the value in the yAxis labels array.

heatmap.yAxisLabelFormat(function (d) { return d + ' bucket' });

If called with no arguments, yAxisLabelFormat will return the heatmap yAxis label formatter function.

# heatmap.xAxisTickFormat([function])

Heatmap xAxis tick format function. The tick format function takes a single argument, the tick value, and returns a formatted tick. Defaults to d3.format('.0f') if not set.

heatmap.xAxisTickFormat(d3.format('.0f'));

If called with no arguments, xAxisTickFormat will return the heatmap xAxis tick format function.

# heatmap.yAxisTickFormat([function])

Heatmap yAxis tick format function. The tick format function takes a single argument, the tick value, and returns a formatted tick. Defaults to d3.format('.2s') if not set.

heatmap.yAxisTickFormat(d3.format('.2s'));

If called with no arguments, yAxisTickFormat will return the heatmap yAxis tick format function.

# heatmap.hideLegend([bool])

Hide heatmap legend. Defaults to false if not set. If called with no arguments, hideLegend will return the status of the heatmap legend.

# heatmap.legendScaleTicks([integer])

Defines the number of scale ticks in the legend. Defaults to 5 if not set.

If called with no arguments, legendScaleTicks will return the number of ticks in the legend scale.

# heatmap.legendTickFormat([function])

Replaces the built-in legend tick format. The tick format function takes a single argument, the tick value, and returns a formatted tick. Defaults to d3.format('.0f') if not set.

heatmap.legendTickFormat(d3.format('.2f'));

If called with no arguments, legendTickFormat will return the heatmap legendTickFormat function.

# heatmap.gridStrokeOpacity([float])

Set the heatmap grid stroke opacity. Grid stroke is white by default, and gridStrokeOpacity controls the stroke opacity, ranging from 0.0 to 1.0, or completely transparent to completely white respectively. Defaults to 0.6 if not set.

If called with no arguments, gridStrokeOpacity will return the current grid stroke opacity.

# heatmap.onClick([function])

Defines a function that will be executed when the user clicks on a frame. Function takes 3 arguments, the value, the column index and row index respectively.

heatmap.onClick(function (d, i, j) {
    console.info("Clicked on row " + j + ", column " + i + ", value " + d);
});

If called with no arguments, onClick will return the click handler.

# heatmap.onMouseOver([function])

Defines a function that will be executed when the user hovers the mouse over a frame. Function takes 3 arguments, the value, the column index and row index respectively.

heatmap.onMouseOver(function (d, i, j) {
    document.getElementById("details").innerHTML = "column: " + i + ", row: " +  j + ", value: " + d
});

If called with no arguments, onMouseOver will return the mouse over handler.

# heatmap.onMouseOut([function])

Defines a function that will be executed when the user moves the mouse out of a frame. Function takes 3 arguments, the value, the column index and row index respectively.

If called with no arguments, onMouseOut will return the mouse out handler.

# heatmap.xAxisLabels([array])

Heatmap xAxis labels array. Defaults to null if not set, which hides de xAxis label.

heatmap.xAxisLabels([0, 1, 2, ...]);

If called with no arguments, xAxisLabels will return the heatmap xAxis labels array.

# heatmap.yAxisLabels([array])

Heatmap yAxis labels array. Defaults to null if not set, which hides de yAxis label.

heatmap.yAxisLabels([0, 1, 2, ...]);

If called with no arguments, yAxisLabels will return the heatmap yAxis labels array.

# heatmap.highlightColor([string])

Heatmap highlight base color. Defaults to #936EB5 if not set. If called with no arguments, highlightColor will return the heatmap highlight base color.

# heatmap.highlightOpacity([string])

Heatmap highlight opacity. Defaults to 0.4 if not set. If called with no arguments, highlightOpacity will return the heatmap highlight opacity.

# heatmap.setHighlight([string])

Set heatmap highlight ranges. Defaults to [] if not set, which doesn't highlight any frame.

heatmap.setHighlight(
    [
        {"start": [0,0], "end": [0,3]},
        {"start": [1,0], "end": [1,3]}
    ]
);

The highlight range object must contain a start property and an end property. Start and end properties are tuples, [column, row] coordinates, in a two integer array format.

If called with no arguments, setHighlight will return the selected heatmap highlight ranges.

# heatmap.invertHighlightRow([bool])

Inverts the highlight row selection. Defaults to false if not set. If called with no arguments, invertHighlightRow will return the status of the highlight inverse row selection option.

# heatmap.updateHighlight()

Updates the heatmap highlights based on the ranges set by the setHighlight function. updateHighlight is executed automatically at first draw, if highlight ranges are set.

heatmap.updateHighlight();

updateHighlight takes no arguments and returns void.

# heatmap.nullValueColor([string])

Heatmap color for null data values. Defaults to #CCCCCC if not set. If called with no arguments, nullValueColor will return the heatmap color for null data values.

Acknowledgements

Thank you Nadieh Bremer for the visual inspiration and D3.js examples.