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.

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

TODO: block

# 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

# 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

TODO: block

# 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.

TODO: Block

Scale

You can use any kind of scale to draw you 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()

# scale(x)

# scale.domain([numbers])

# scale.range([numbers])

# scale.gapInterval(x)

# scale.gapSize(x)

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