sg-heatmap
Open-source all-in-one Swiss Army knife tool for creating Choropleth maps
Motivation
How do you generate a Choropleth map?
Step 1:
First get a bunch of polygons
Step 2:
Then get a ton of location data points
Step 3:
Assign each data point to an area (i.e. binning)
Step 4:
Aggregate the data points in each bin (area) with an aggregating function (eg. count, mean, median)
Step 5:
Map each bin's aggregated value to a color using a color scale
Step 6:
Render the colored polygons onto Google map
Step 7:
Received a new set of data points? Repeat Step 3 to Step 6
Clearly generating a Choropleth is not an easy task. Our goal is to provide a simple yet highly customizable JavaScript tool for data enthusiast to spend less time engineering and more time building beautiful visualizations.
Content
- A basic example
- Binning by key / Working with pre-aggregated data
- NEW Plugin to support LeafletJS
- NEW Plugin to support MapboxGL
- NEW Plugin to support OpenLayers
- API Documentation
- Installing
- Importing to project
- Using predefined maps with polygon data loaded
- Defining map with your own polygon data
- Polygon data must takes the format of an array of GeoJSON feature objects
- Defining the aggregating function
- List of predefined aggregating functions
- .update( ) method
- .getStat( ) method
- .render( ) method
- colorScale function
- Using predefined colorScale
- List of predefined colorScale
- Using colorScale helper function to generate customized colorScale
- Normalization and remapping of values
- Advance Topics
A basic example
// initialize heatmapvar heatmap = // set up heatmap to use MEAN for aggregating // pass in the data points// binning and aggregating is done in one stepdataPoints // initialize color scalevar colorScale = // initialize renderervar renderer = heatmaprenderer // renderheatmap
Binning by key / Working with pre-aggregated data
Sometimes we might be working with pre-aggregated data. Instead of binning and updating with the location (lnglat), you want to bin directly to each polygon using keys. In this case we provides a helper function to modify your SgHeatmap object
aggregatedData
One potential use case is doing the (relatively time-consuming) binning and aggregating server-side and send only the aggregated values to the client for rendering
// Server-side var heatmap = dataPoints var stat = heatmap// Send 'stat' object to client
// Client-side var heatmap = // Receive 'stat' object from serverObject // initialize colorScale// initialize renderer... // call render on stat 'latest'heatmap
NEW Plugin to support LeafletJS
var heatmap = dataPoints var colorScale = // .initializeRenderer( ) has been overridden to// return a Leaflet GeoJSON layer// refer to http://leafletjs.com/reference-1.0.0.html#geojsonvar renderer = heatmaprenderer heatmap
NEW Plugin to support MapboxGL
var heatmap = dataPoints mapboxglMap
NEW Plugin to support OpenLayers
var heatmap = dataPoints var colorScale = // defaultStyle and addonStyle need to be OpenLayers ol.style.Style objectvar defaultStyle = stroke: color: 'black' width: 1 fill: color: 'white' // .initializeRenderer( ) has been overridden to// return an OpenLayers ol.layer.Vector object// refer to http://openlayers.org/en/latest/apidoc/ol.layer.Vector.htmlvar renderer = heatmaprendereropenLayersMap heatmap
API Documentation
Installing
npm install --save sg-heatmap
Importing to project
// OR in ES5var SgHeatmap =
Using predefined maps with polygon data loaded
// OR// OR// OR // initializevar heatmap =
Impt: If using predefined maps browser-side, include json-loader in your webpack config
Data source:
- https://data.gov.sg/dataset/master-plan-2014-region-boundary-web
- https://data.gov.sg/dataset/master-plan-2014-planning-area-boundary-web
- https://data.gov.sg/dataset/master-plan-2014-subzone-boundary-web
- https://data.gov.sg/dataset/singapore-police-force-npc-boundary
Defining map with your own polygon data
var heatmap = polygonDatafeatures
Polygon data must takes the format of an array of GeoJSON feature objects
Position: Number Number// first element longitude// second element latitude LinearRing: Array<Position>// first position to match last position Polygon: type: 'Polygon' coordinates: Array<LinearRing> // required // first element is outer boundary // second element onward are inner "holes" bbox: Number Number Number Number // optional // first element West bound, second element South bound // third element East bound, fourth element North bound MultiPolygon: type: 'MultiPolygon' coordinates: Array<Array<LinearRing>> bbox: Number Number Number Number Feature: type: 'Feature' id: String // required, must be unique properties: Object // optional, meta data in key/value form geometry: Polygon | MultiPolygon // required polygonData: Array<Feature>
Refer to relevant sections in IETF's 2015 GeoJSON Specification (RFC7946)
- https://tools.ietf.org/html/rfc7946#section-3.2
- https://tools.ietf.org/html/rfc7946#section-3.1.6
- https://tools.ietf.org/html/rfc7946#section-3.1.7
- https://tools.ietf.org/html/rfc7946#section-3.1.1
- https://tools.ietf.org/html/rfc7946#section-5
Defining the aggregating function
// this step is required before passing in any data
List of predefined aggregating functions
- register_HISTORY
- register_LATEST
- register_COUNT
- register_SUM
- register_MEAN
- register_VARIANCE
- register_STDEV
- register_MIN
- register_MAX
- register_MEDIAN
register_HISTORY and register_LATEST does not do any actual aggregating
register_HISTORY simply push data point to an array in the update order while
register_LATEST replaces old value with each update and keeps only the latest data point
.update( ) method
// push one data pointvar pt = dataPoints0heatmap // push another data pointpt = dataPoints1heatmap // push the remaining data pointsdataPoints
This design supports streaming data. Each time .update( ) is called, binning and aggregating is performed on the single data point. Therefore .getStat( ) and .render( ) can be called even without all data points loaded
// eg.heatmap dataPointsheatmap// returns aggregated values for first 100 data points dataPointsheatmap// returns aggregated values for first 200 data points dataPointsheatmap// returns aggregated values for first 300 data points // say you only want to check which bin data point falls into// i.e. bin but don't updatept = dataPoints0heatmap// this returns filtered list of heatmap.children// where inside function evaluates true // to get their respective keyvar matchingKeys = heatmap
.getStat( ) method
// returnsvar stat = = stat: String // name of statistic queried (in this case 'mean') values: Object // key/value map of aggregated stat for each child that has been matched to at least one data point unchanged: String // keys of children where no update (i.e. not matched to any data point) min: Number // minimum among the set of values in stat.values max: Number // maximum among the set of values in stat.values
Each data point only needs to be passed in once and any number of statistics can be called on the SgHeatmap Object
// eg. dataPoints heatmap // return MEANheatmap // return MAXheatmap // return MIN
.render( ) method
// initialize rendererheatmap // initialize colorScale by providing domain min/max endpointsheatmap // key is the name of the statistic to render
- .initializeRenderer( ) method requires a colorScale function to be passed in as its first parameter (see below)
- defaultStyle and addonStyle are optional style options to be applied onto map polygons
- refer to https://developers.google.com/maps/documentation/javascript/3.exp/reference#Data.StyleOptions
- defaultStyle applies to every polygon (including those in the unchanged group)
- addonStyle applies to those polygons that has been assigned at least one data point
- do not set 'fillColor' in addonStyle as it will be overridden by the fillColor colorScale specify
colorScale function
Any function that maps numeric values between 0 and 1 to CSS colors
// example // returns 'orange' // returns '#ff0000'
Using predefined colorScale
var colorScale =
List of predefined colorScale
- eg. Spectral, YlOrRd, Purples
- Refer to COLORBREWER 2.0 for the full set of color schemes available
Using colorScale helper function to generate customized colorScale
var colorArray = 'white' 'yellow' 'orange' 'red' 'black' var colorScaleOptions = transform: 1 bezierInterpolate: false correctLightness: true interpolationMode: 'lab' var customColorScale =
Refer to chroma.js docs for detail explanation of the different colorScaleOptions
Normalization and remapping of values
Since colorScale accepts input value only between 0 and 1 while stat.values can be any numeric value. Values in stat.values are first normalized before passing into colorScale. By default, we perform a linear interpolation with domain end points set to the min and max values
{ return value - statmin / statmax - statmin}
You may set your own domain by providing it through an option argument in render( ). Eg.
heatmap
Sometimes linear mapping of value to color may not visibly separate the different values sufficiently (eg. majority of values are clustered in the lower range) In this case, we may want to apply a power transformation to accentuate difference within certain part of the domain.
The power transformation to apply can be specified in the same option argument. Eg.
// to accentuate difference in the lower range, set transformation < 1heatmap // to accentuate difference in the upper range, set transformation > 1heatmap
Advance Topics
Adding Event Handlers
// eg.var defaultStyle = strokeOpacity: 0 fillOpacity: 0var addonStyle = strokeOpacity: 1 fillOpacity: 07// by setting opacity 0, empty areas will be hidden var renderer = heatmaprenderer
Refer to https://developers.google.com/maps/documentation/javascript/3.exp/reference#Data.Feature for details on the methods available on the feature object
// you can even do this// creates a highlight effect on hoverrendererrenderer
Refer to https://developers.google.com/maps/documentation/javascript/3.exp/reference#Data for a detailed list of methods on the renderer object
// Leaflet plugin examplevar renderer = heatmaprenderer
// OpenLayers plugin examplevar renderer = heatmapvar clickHandler = openLayersMap
Custom aggregate functions
When .update( ) is called binning and aggregation is performed simultaneously. How does this work? How does the SgHeatmap object aggregate before being exposed to the full dataset.
SgHeatmap does this by using a reducer approach in aggregation. Those who has worked with Redux.js will be familiar with this approach.
Each child of the SgHeatmap object (corresponding to one feature) has a state object
var heatmap = console// prints empty object {}
To enable aggregation, first you need to define a default state on all the children by calling .setDefaultState( ).
heatmapconsole// prints {_count: 0, _sum: 0}
Then you register some updater functions by calling .registerUpdater( ). These updaters are reducer functions that requires two parameters newValue and oldState and returns a newState by performing some some update operations.
// eg. { return _count: oldState_count + 1} { return _sum: oldState_sum + newValue}heatmapheatmapheatmap// prints a stringified version countUpdater and sumUpdater
The final step is to register a compute statistic function by calling .registerStat( ). stat functions takes in a child's state and output a numeric statistic value. Only stat that has been registered are available to be called by the .getStat( ) method.
// eg. { return state_sum / state_count}heatmapheatmap// prints a stringified version of computeMean
To reset a heatmap and empty all it's data you can call .resetState( ) and all the children's state will be reverted to the defaultState.
heatmapconsole// prints {_count: 0, _sum: 0}
If all these looks too complicated to you, just use one of the predefined aggregate functions. It should do everything for you. The predefined aggregate functions provided are more than enough for most use cases.
Another alternative (for those who have problems wrapping their head around to writing reducer functions) is to just use a history updater and rely solely on the stat function for aggregating.
// eg. { var sum = state_history var count = state_historylength return sum / count}
The reducer design has a few advantages:
- SgHeatmap object holds only the data needed for rendering the choropleth map instead of the entire dataset. If state needs to be passed around, you'll have a much smaller footprint.
- Supports streaming data. You can do interesting things like say 'moving average'
// eg. implementing moving averageheatmap { // clone history into new array var _history = ...state_history // ES6 syntax if _historylength === 10 _history _history return _history: _history} heatmap { var sum = state_history var count = state_historylength return sum / count} heatmap
Dynamic stat
There are times when it may not be feasible to pre-register all the stat we need upfront. For example:
heatmap // returns 50th percentile // what if we need the 25th & 75th percentile also?// maybe we can register multiple similar 'stat'heatmapheatmap heatmapheatmap
What if we are using a slider? (10th, 20th, 30th, ... , 90th percentile). Are we going to write one new stat for each percentile? In this case we need a more flexible way of defining your 'stat'. How about a stat function that accepts a payload?
To provide for such situation, we allow our .getstat( ) and .render( ) method to accept a function instead of a key string. What this mean is you can supplied a stat function directly rather than calling a pre-registered stat function.
// you can write a higher order function (i.e. a function generator) that returns a computePercentile function for any percentile value { return { // return Nth percentile of values in state._history }} heatmap // compute 25th percentileheatmap // render choropleth map of 75th percentile
Cloning SgHeatmap object
var oldHeatmap = // Method 1 (cloning locally)var newHeatmap = oldHeatmap// setting option false will clone only polygon data// but not state object // Method 2 (for sending data between server and client)var serializedData = oldHeatmapvar newHeatmap = JSON// as before, setting option false will clone only polygon data
Cloned SgHeatmap can retain original state of all its children but updaters and stats will still have to be re-registered
var newHeatmap = oldHeatmapnewHeatmap // prints []newHeatmap // prints {}newHeatmap // throws Error // complete clone by