d3-iconarray

A D3 plugin targeting V4 helping you to draw an array of icons.

Why?

There are two parts to this plugin. First a layout which will assign x,y coordinates to elements of an array given some parameters. Second a scale which will put regular breaks in the array of icons to aid legibility.

Installing

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

Examples

• A minimal example using both layout and scale features
• Using the plugin to make a hemicycle for election results
• Recreating a GBS risk graphic from Scientific American
• Setting the scale's gapSize and gapInterval properties
• US Senate battlegrounds
• when to use the widthFirst switch (UK election results)
• Modal transport share with emojis

API Reference

Layout

# d3_iconarray.layout()

Construct a new icon array layout function.

# layout([data array])

The function created by the above. When given an array of data will return an array containing grid positions as well as the original data. Unless a height or width restriction has been specified the layout will try to make the grid as square as possible. eg. a 100 element data array will result in a 10x10 grid.

example

var layout = d3_iconarray.layout();

var grid = layout([1,2,3,4]); 

/*
'grid' is

[
	{"data":1,"position":{"x":0,"y":0}},
	{"data":2,"position":{"x":1,"y":0}},
	{"data":3,"position":{"x":0,"y":1}},
	{"data":4,"position":{"x":1,"y":1}}
]

/*

You can use the resulting grid to plot icons, the data points will be arranged like this

# layout.widthFirst([boolean])

This function sets the order in which points are arranged in the grid. if widthFirst is set to true rows will be filled before starting the next, if it's false columns in the layout will be filled first. if no argument is provided it returns the current value.

example

var layout = d3_iconarray.layout()
					.widthFirst(true);

var grid = layout([1,2,3,4]); 

the resulting in the resulting grid the icons will be arranged like this

with .widthFirst(false) they'll be arranged like this

when to use the widthFirst switch (UK election results)

# layout.width([integer])

the width function defines the maximum number of elements the grid will have in a given row. if no argument is provided it returns the current value.

example

var layout = d3_iconarray.layout().width(3);
var grid = layout([1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]);

results in a grid like

# layout.height([integer])

the height function sets the maximum number of elements the grid will have in a given row. if no argument is provided it returns the current value.

example

var layout = d3_iconarray.layout().height(3);
var grid = layout([1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]);

results in a grid like

# layout.position([integer])

given the a number representing an array element this function will tell you it's {x, y} location in the grid. This function needs some dimension of the grid (height or width) to have been set explicitly (by height or width) or implicitly by passing a data array to the layout function

example

var layout = d3_iconarray.layout();
var grid = layout([1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]);

var p = layout.position(7);
// p is {x: 3, y: 1}

# layout.maxDimension([integer])

A bit like position but given a number will return the maximum extent of the lyout if it were to have that many elements. THis is useful for setting the domain of scales.

Scale

You can use any kind of scale to draw your grid to the screen. The scale provided by the plugin can let you add breaks to your icon array to improve legibility e.g. here's a 2500 element array grouped in to blocks of 100.

# d3_iconarray.scale()

Creates a scale function just like good ol' d3.scaleLinear() etc.

# scale(x)

Given a value x in the input domain, returns the corresponding value in the output range.

# scale.domain([numbers])

Set the input domain, an array of 2 numbers.

If no arguments are provided this returns the current value.

# scale.range([numbers])

Set the output range, an array of 2 numbers.

If no arguments are provided this returns the current value.

# scale.gapInterval(x)

This function accepts a number which sets at what interval a gaps appear in the output range. i.e. if x is 10 there will be an extra gap after every ten items in the output range.

If no arguments are provided this returns the current value.

see this example

# scale.gapSize(x)

This sets how big the gaps in the output range will be relative to the normal spacing. So if the normal spacing between two whole numbers is 10px and the gap size is set to 1.5 the extra wide space will be 15px.

If no arguments are provided this returns the current value.

see this example

Why?

#

Twenty years ago, a psychological study compared for the first time rudimentary icon displays for communicating risk. Today, we have dozens of randomized experiments to support the use of icon arrays (sometimes referred to as “pictographs”) as an evidence-based standard in medical risk communication.

Why use Icon Arrays

Icon arrays are particularly effective, and are apparently less likely to increase patient anxiety than other graphical techniques.

Scientific American: Inadequate Data Visualization Leaves Patients Undereducated