d3-chessboard-count v0.2.1

d3-chessboard-count

Plot per-square frequencies on a chessboard. The frequencies are represented by circles — the higher the frequency, the larger the circle, scaled such that the circle representing the highest overall frequency takes up the full space of its square minus padding.

For an example of the plug-in in action, see this notebook.

Changes to the data are animated, and the board can be customized, including:

• the size of the squares,
• the number of files and ranks, as well as their names and styles,
• the colors of the squares and circles,
• the orientation of the board (including mirroring across one or both axes).

TypeScript types are included.

Installation

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

You can also load directly from directly unpkg.com as a standalone library, or from jsdelivr.com here.

AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3 global is exported:

<script src="https://unpkg.com/d3-chessboard-count/dist/d3-chessboard-count.min.js"></script>
<script>
    const plot = d3.chessboardSquarePlot();
</script>

Basic Usage

First you need to have your data as a list of elements, each describing the count for some square (described by its file and its rank, both ranging from 0 to the number of files/ranks minus one). By default, it is assumed that each element is an object with properties file, rank, and count, but custom accessors can be specified.

Then, create a div to contain the plot and a new chessboardSquarePlot object.
After configuring the plot object, select the div, set your data, and apply the plot object to it:

<div id="plot"></div>
<script>
    const plot = d3.chessboardSquarePlot()
                   .margin({top: 16, right: 16, bottom: 16, left: 16})
                   .lightSquareFill('red')
                   .darkSquareFill('black');
    
    d3.select('#plot')
      .datum(data)
      .call(plot);
</script>

API Reference

• Creating Plots
• Accessors
• Geometry
• Files and Ranks
• Fill Colors

Unless specified otherwise, units are SVG user units.

Creating Plots

# d3.chessboardSquarePlot() <>

Constructs a new plot with top/right/bottom/left margins of 24, square size of 32, padding of 4, no mirroring, 8 files and ranks ('a'–'h', '1'–'8'), white light squares, gainsboro dark squares, nero fill for the circles, which takes files, ranks, and counts from file, rank, count properties of the data, respectively.

Accessors

# plot.file(file)

If file is specified, sets the file accessor to the specified function and returns this plot generator. If file is not specified, returns the current file accessor which defaults to a function returning the file property if available, or 0 otherwise.

# plot.rank(rank)

If rank is specified, sets the file accessor to the specified function and returns this plot generator. If rank is not specified, returns the current rank accessor which defaults to a function returning the file property if available, or 0 otherwise.

# plot.count(count)

If count is specified, sets the count accessor to the specified function and returns this plot generator. If count is not specified, returns the current count accessor which defaults to a function returning the count property if available, or 0 otherwise.

Geometry

# plot.margins(margins)

If margins is specified, sets the margins to the specified object. If margins is not specified, returns the current margins which defaults to {top: 24, left: 24, bottom: 24, right: 24}.

The margins define the empty space around the chessboard.

# plot.squareSize(squareSize)

If squareSize is specified, sets the square size to the specified number. If squareSize is not specified, returns the current square size which defaults to 32.

# plot.padding(padding)

If padding is specified, sets the padding to the specified number. If padding is not specified, returns the current padding which defaults to 4.

The padding defines the smallest amount of empty space between the edges of a square and the circle with the maximum radius in the plot.

Files and Ranks

# plot.files(files)

If files is specified, sets the files to the specified list of strings. If files is not specified, returns the current files which defaults to ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'].

# plot.ranks(ranks)

If ranks is specified, sets the ranks to the specified list of strings. If ranks is not specified, returns the current ranks which defaults to ['1', '2', '3', '4', '5', '6', '7', '8'].

# plot.fileStyle(fileStyle)

If fileStyle is specified, sets the file label style to the specified CSS style. If fileStyle is not specified, returns the current file label style which is empty by default.

# plot.rankStyle(rankStyle)

If rankStyle is specified, sets the rank label style to the specified CSS style. If rankStyle is not specified, returns the current rank label style which is empty by default.

# plot.fileNotationPadding(fileNotationPadding)

If fileNotationPadding is specified, sets the inner distance between file labels and the board to the specified number. If fileNotationPadding is not specified, returns the current distance which defaults to 6.

# plot.rankNotationPadding(rankNotationPadding)

If rankNotationPadding is specified, sets the inner distance between rank labels and the board to the specified number. If rankNotationPadding is not specified, returns the current distance which defaults to 6.

# plot.mirrorFiles(mirrorFiles)

If mirrorFiles is specified, mirror the board along the files if true. If mirrorFiles is not specified, returns the current state of the mirroring.

# plot.mirrorRanks(mirrorRanks)

If mirrorRanks is specified, mirror the board along the ranks if true. If mirrorRanks is not specified, returns the current state of the mirroring. To rotate the board, mirror along both files and ranks.

Fill Colors

# plot.lightSquareFill(lightSquareFill)

If lightSquareFill is specified, sets the light square fill color to the specified CSS color string. If lightSquareFill is not specified, returns the current light square fill color which defaults to white.

# plot.darkSquareFill(darkSquareFill)

If darkSquareFill is specified, sets the dark square fill color to the specified CSS color string. If darkSquareFill is not specified, returns the current dark square fill color which defaults to gainsboro.

# plot.circleFill(circleFill)

If circleFill is specified, sets the circle fill color to the specified CSS color string. If circleFill is not specified, returns the current circle fill color which defaults to nero.

Contributing

Comments, suggestions, and pull requests are welcome.

Acknowledgments

The structure of the plugin is based on Mike Bostock's article Towards Reusable Charts, and the packaging on Let's Make a (D3) Plugin with some updates taken from other D3 plugins, and additional support for TypeScript.

License (MIT)

Copyright (c) 2020 Christoffer Karlsson

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.