d3-hexgrid

A wrapper of _d3-hexbin_, _d3-hexgrid_ does three things:

1. It allows you to regularly tessellate polygons with hexagons. _d3-hexbin_ produces hexagons where there is data. _d3-hexgrid_ produces hexagons where there is a base geography you define.

2. Hexagons at the edge of your geography are often truncated by the geography's border. _d3.hexgrid_ calculates the inside-area or _cover_ of these edge hexagons allowing you to encode edge data based on the correct point density. See below for more.

3. Lastly, _d3.hexgrid_ provides an extended layout generator for your point location data to simplify the visual encoding of your data. The layout rolls up the number of point locations per hexagon, adds cover and point density and provides point count and point density extents for colour scale domains. See below for more.

Please see this notebook for a description of the algorithm.

Go straight to the API reference.

Install

``
npm install d3-hexgrid
`

You can also download the build files from here.

Or you can use unpkg to script-link to _d3-hexgrid_:

`

`

Examples

#### Militarised interstate disputes in Europe 1816-2001

!disputes

_{Data source: Midloc via data.world. Additional clip-path applied. • code}

#### Cities across the world

!cities

_{Data source: maxmind. Not equal area projected. • code}

#### Farmers Markets in the US

!farmer markets

_{Data source: USDA • code}

#### Post boxes in the UK

!postboxes

_{Data source: dracos.co.uk from here via Free GIS Data • code}

$3

The tessellation aspect might become clear in these examples. The edge cover calculation might not. In short, _d3.hexgrid_ identifies all edge hexagons that partly lie beyond the borders of the geography, or more general: the base image presented. In a next step it calculates the edge hexagon's cover: the area the edge hexagon lies within the bounds of the base image in percent. Lastly, the point density will be calculated by:

_Point density = Points in hexagon / Hexagon area in px2 × Cover_

A comparison:

!edge comparison

Both maps encode the number of Farmer's Markets per hexagon. Yellow represents a low, purple a high number. The edge hexagons of the upper map are not cover corrected, the edge hexagons of the lower map are.

The edge hexagon at the south-eastern tip of Florida we're comparing has a cover of 55%, meaning 55% of the hexagon's area is inland, 45% is in the Atlantic. There are a total of 22 Farmer's Markets in this hexagon. Not cover corrected, the hexagon would have a point density of 0.09 and would be filled in a dark blue with the colour scale of choice. When cover corrected, its real point density increases to 0.17 and it is coloured in a dark purple—indicating higher point density as it should.

Differences might be subtle but noticeable.

Please see the d3-hexgrid's notebook section on edge cover for a detailed description of the cover calculation.

Example usage

A lean example usage of _d3-hexgrid_.

`
// Container.
const svg = d3.select('body')
.append('svg')
.attr(width, 'width')
.attr('height, 'height');

// Projection and path.
const projection = d3.geoAlbers().fitSize([width, height], geo);
const geoPath = d3.geoPath().projection(projection);

// Produce and configure the hexgrid instance.
const hexgrid = d3.hexgrid()
.extent([width, height])
.geography(geo)
.projection(projection)
.pathGenerator(geoPath);

// Get the hexbin generator and the layout.
const hex = hexgrid(myPointLocationData);

// Create a colour scale.
const colourScale = d3.scaleSequential(d3.interpolateViridis)
.domain([...hex.grid.maxPoints].reverse());

// Draw the hexes.
svg.append('g')
.selectAll('.hex')
.data(hex.grid.layout)
.enter()
.append('path')
.attr('class', 'hex')
.attr('d', hex.hexagon())
.attr('transform', d => translate(${d.x}, ${d.y}))
.style('fill', d => !d.datapoints ? '#fff' : colourScale(d.datapoints));
`

$3

First, we create an SVG element. Let's assume our geography represents mainland US and comes in as a geoJSON called geo. We use an Albers projection to fit our SVG and finally get the appropriate path generator.

`
const svg = d3.select('body')
.append('svg')
.attr(width, 'width')
.attr('height, 'height');

const projection = d3.geoAlbers().fitSize([width, height], geo);
const geoPath = d3.geoPath().projection(projection);
`

Next, we use d3.hexgrid() to produce a _hexgrid_ instance we creatively call hexgrid. We immediately configure it by passing in the extent, the GeoJSON, the projection and the path-generator.

`
const hexgrid = d3.hexgrid()
.extent([width, height])
.geography(geo)
.projection(projection)
.pathGenerator(geoPath);
`

Now we can call our _hexgrid_ instance passing in the data.

`
const hex = hexgrid(myPointLocationData);
`

This will return a hexbin generator as d3.hexbin() does, augmented with an additional object called grid, which exposes the following properties:

!grid object

- imageCenters is an array of objects exposing at least the _x_, _y_ hexagon centre coordinates of the hexgrid in screen space.

- layout is an array of arrays, each sub-array representing a hexagon in the grid. Each sub-array holds all point locations per hexagon in an object exposing at least _x_ and _y_ pixel coordinates as well as aggregate values. Here's an example hexagon layout sub-array with three point locations (or _datapoints_):

!layout object

The aggregate values per hexagon are:

- cover is the percentage of this hexagon's area within the geography expressed as a number between 0 and 1.
- datapoints is the number of points binned in the hexagon.
- datapointsWt is the number of points weighted by the inverse cover.
- pointDensity is the hexagon's point density.
- gridpoint marks the hexagon as part of the initial hexgrid. This allows you to identify hexagons added by the data. Imprecise latitude and longitude data values can lead to the generation of hexagons just outside the hexgrid. _d3.hexgrid_ will still capture and produce them. But you can spot and treat them by filtering for gridpoint === 0.
- x and y are the hexagon centre positions in pixel coordinates.

- extentPoints is the extent of point location counts over all hexagons in the form _[min number of points, max number of points]_.
- extentPointsWeighted is the extent of point location counts weighted by their cover over all hexagons in the form _[min number of weighted points, max number of weighted points]_.
- extentPointDensity is the extent of cover adjusted point density over all hexagons in the form _[min point density, max point density]_.

These extents can be used to set a colour scale domain when encoding number of points or point density.

Working with points, for example, we might want to create the following colour scale:

`
const colourScale = d3.scaleSequential(d3.interpolateViridis)
.domain([...hex.grid.maxPoints].reverse());
`

Here, we decide to encode the number of points per hexagon as colours along the spectrum of the Viridis colour map and create an appropriate colour scale. We reverse the extent (without modifying the original array) as we want to map the maximum value to the darkest colour, which the Viridis colour space starts with.

Finally, we build the visual:

`
svg.append('g')
.selectAll('.hex')
.data(hex.grid.layout)
.enter()
.append('path')
.attr('class', 'hex')
.attr('d', hexgrid.hexagon())
.attr('transform', d => translate(${d.x}, ${d.y}))
.style('fill', d => !d.datapoints ? '#fff' : colourScale(d.datapoints));
`

We use the hex.grid.layout to produce as many path's as there are hexagons—as we would with d3.hexbin()—now, however, making sure we have as many hexagons to cover our entire GeoJSON polygon. We draw each hexagon with with hexgrid.hexagon() and translate them into place. Lastly, we give our empty hexagons (!d.datapoints) a white fill and colour encode all other hexagons depending on their number of datapoints.

API Reference

# d3.hexgrid()

Constructs a hexgrid generator called _hexgrid_ in the following. To be configured before calling it with the data you plan to visualise.

# _hexgrid_(_data_[, _names_])

Generates a hexbin generator augmented with a grid property, exposing the hexagon layout data as well as extents for point and point density measures. See above for the grid object's properties. Optionally _names_ can be an array of strings, listing properties you would like to pass through from your original data to the grid layout.

Assuming you want to visualise restaurants on a map and have a restaurant dataset containing the variables website and opening_times you can say:

`
hexgrid(restaurantData, ['website', 'opening_times'])
`

As a result, objects in the _hexgrid_.grid.layout array will contain the two variables in addition to the default _x_ and _y_ coordinates:

!layout-object-vars

# _hexgrid._extent([_extent_])

_Required_. Sets the extent of the hexbin generator produced internally. _extent_ can come as either a 2D array specifying top left start and bottom right end point [[x₀, y₀], [x₁, y₁]]. Alternatively _extent_ can be specified as an array of just width and height [x₁, y₁] with the top-left corner assumed to be [0, 0]. The following two statements are equivalent:

`
hexgrid.extent([[0, 0], [width, height]]);
hexgrid.extent([width, height]);
`

# _hexgrid._geography([_object_])

_Required_. _object_ represents the base polygon for the hexgrid in GeoJSON format. If you were to project a hexgrid onto Bhutan, _object_ would be a GeoJSON object of Bhutan.

# _hexgrid._projection([_projection_])

_Required_. _projection_ is the projection function for the previously defined _geography_ commonly specified within the bounds of _extent_. See here or here for a large pond of projection functions.

# _hexgrid._pathGenerator([_path_])

_Required_. _path_ is the path generator to produce the drawing instructions of the previously defined _geography_ based on the also previously defined _projection_.

# _hexgrid._hexRadius([_radius_[, _unit_]])

_Optional_. The desired hexagon radius in pixel. Defaults to 4. _unit_ can optionally be specified if the radius should be expressed not in pixel but in either _"miles"_ or _"kilometres"_. The following is valid configuration:

`js
.hexRadius(50, 'm') // or 'miles'
.hexRadius(50, 'km') // or 'kilometres' or 'kilometers'
`

The conversion is based on a geoCircle projected in the center of the drawing area. As such the conversion can only be a proxy, however, a good one if an equal area projection is used to minimise area distortions across the geography.

# _hexgrid._edgePrecision([_precision_])

_Optional_. The edge precision sets the size of the internally produced canvas to identify which area of the edge hexagon is covered by the _geography_. The higher the precision, the better the pixel detection at the hexagon edges. Values can be larger than 1 for small visuals. Values smaller than 0.3 will be coerced to 0.3. The default value of 1 will be fine for most purposes.

# _hexgrid._gridExtend([_extension_])

_Optional_. _gridExtend_ controls the size of the base geography. _gridExtend_ allows you to "inflate" your hexgrid and can be used to draw more hexagons around the edges that otherwise would not be drawn.

!gridExtend

_gridExtend_ is measured in units of _hexRadius_. For example, a _gridExtend_ value of 2 would extend the grid by _2 × hexRadius_ pixel.

# _hexgrid._geoKeys([_keys_])

_Optional_. _d3.hexgrid_ will try to guess the key names for longitude and latitude variables in your data. The following case-insensitive key names will be sniffed out:

- _longitude_, _long_, _lon_, _lng_, _lambda_ as well as
- _latitude_, _lat_ and _phi_.

If you choose other names like for example _upDown_ and _leftRight_, you
have to specify them as hexgrid.geokeys(['upDown', 'leftRight']) with the first element representing longitude and the second latitude.

Don't call your geo keys x or y or otherwise include x and/or y keys in your passed in user variables as they are reserved keys for the pixel coordinates of the layout.

$3

The following functions can be helpful to filter out point location data that lie beyond the base geography.

# d3.geoPolygon([_geo_, _projection_])

Transforms a GeoJSON geography into a Polygon or MultiPolygon. _geo_ is a GeoJSON of the base geography. _projection_ is the applied projection function.

# d3.polygonPoints([_data_, _polygon_])

_data_ is an array of point location objects with _x_ and _y_ properties in screen space. _polygon_ is a Polygon or MultiPolygon as produced by d3.geoPolygon(). Returns a new array of point location objects exclusively within the bounds of the specified _polygon_.

If you had a point location dataset of all post boxes in the world, but you only want to visualise UK post boxes you can use these helper functions to produce a dataset with only UK post boxes like so:

`
const polygonUk = d3.geoPolygon(ukGeo, projectionUk);
const postboxesUk = d3.polygonPoints(postboxesWorld, polygonUk);
``

If you plan to use the d3-hexgrid produced extents in a color scale, it is suggested to focus your dataset on your base geography. If produced with data beyond your base geography, the extents might not be meaningful.

General notes on hexagonal binning

Hexagons are often ideal for binning point location data as they are the shape closest to circles that can be regularly tessellated. As a result, point distributions binned by a hexagon are relatively spike-less and neighbouring hexagons are equidistant.

While being the right choice in many cases, two notes should be considered when using hexagonal binning—or any point location binning for that matter:

#### Use equal area projections for the base geography.

The world is something like a sphere and there are numerous ways to project a sphere onto a 2D plane. The projection used has an important effect on the analysis. Any tessellation normalises space to equally sized units—hexagons in this case—which invites the reader to assume that each unit covers the same area. However, some projections, like the ubiquitous Mercator projection, will distort area increasingly towards the poles:

!mercator

_{Source: D3 in depth by Peter Cook}

All red circles on above map are of the same area. As a result, tessellating a Mercator world map with hexagons will produce many more hexagons per square mile in Norway compared to Brazil, for example.

Equal area projections will help to avoid this problem to a large extent.

#### Consciously choose the hexagon radius size.

Location binning is susceptible to the Modifiable Areal Unit Problem. The MAUP—or more specifically the _zonal_ MAUP—states that a change in size of the analysis units can lead to different results. In other words, changing the hexagons’ size can produce significantly different patterns—although the views across different sizes share the same data. Awareness is the only corrective to the MAUP. As such, it is recommended to test a few unit sizes before consciously settling for one, stating the reasons why and/or allowing the readers to see or chose different hexagon sizes.

Thanks!

A big thanks to Philippe Rivière for bringing the grid layout algorithm on track and sparking the idea for the edge cover calculation. This plug-in would look different and be significantly less performant without his elegant ideas.

For a deeper dive read Amit Patel's (aka reblobgames) seminal hexagon tutorial. The best to find out there. Also see the great things Uber's been doing with H3, which in many ways goes far beyond this plugin.