In my last blog entry, I introduced HumanGeo’s Leaflet Data Visualization Framework (DVF) and provided insight into the motivations driving the development of the framework. Now let’s take a closer look at some of the new features that the framework provides for simplifying thematic mapping using Leaflet.
New Marker Types
In terms of visualizing point data, Leaflet offers image-based (L.Marker), HTML-based (L.Marker with L.DivIcon), and circle markers (L.CircleMarker). While these can be useful tools for symbolizing data values (particularly the CircleMarker), it’s always nice to have some variety. The framework adds several new marker types that are geared towards illustrating dynamic data values.
| L.RegularPolygonMarker |  |
| L.PieChartMarker, L.BarChartMarker, L.CoxcombChartMarker, and L.RadialBarChartMarker |  |
| L.RadialMeterMarker |  |
| L.StackedRegularPolygonMarker |  |
Mapping Data Properties to Leaflet Styles
The framework includes classes for dynamically mapping data values to Leaflet style values (e.g. radius, fillColor, etc.). These classes are similar to D3’s scale concept. Mapping values from one scale/format to another is a common aspect of creating thematic maps, so this is a critical feature despite its relative simplicity. The main classes to consider are:
- L.LinearFunction: This class maps a data value from one scale to another. One example use might be to map a numeric data property (e.g. temperature, counts, earthquake magnitude, etc.) to a radius in pixels. You create a new LinearFunction by passing in two data points composed of x and y values (L.Point instances or any object with x and y properties), where these points represent the bounds of possible values – x values represent the range of input values and y values represent the range of output values. If you remember back to your algebra days, you’ll recall the concept of linear equations, where given two points in cartesian space, you can calculate the slope (m) and y-intercept (b) values from those points in order to determine the equation for the line that passes through those two points (y = mx + b). This is really all that the LinearFunction class is doing behind the scenes. Call the evaluate method of a LinearFunction to get an output value from a provided input value; this method interpolates a y value based on the provided x value using the pre-determined linear equation. The LinearFunction class also includes options for pre-processing the provided x value (preProcess) and post-processing the returned y value (postProcess) whenever evaluate is called. This can be useful for translating a non-numeric value into a numeric value or translating a numeric output into some non-numeric value (e.g. a boolean value, category string ,etc.). It can also be used to chain linear functions together.
- L.PiecewiseFunction: It’s not always possible to produce the desired mapping from data property to style property using just a single LinearFunction. The PiecewiseFunction class allows you to produce more complicated mappings and is literally based on the Piecewise Function concept. For instance, if you wanted to keep the radius of a marker constant at 5 pixels until your data property reaches a value of 100 and then increase the radius after that from 5 pixels to 20 pixels between the values of 100 and 200, you could by using a PiecewiseFunction composed of two LinearFunctions as illustrated in the example below.
var radiusFunction = new L.PiecewiseFunction([new L.LinearFunction(new L.Point(0, 5), new L.Point(100, 5)), new L.LinearFunction(new L.Point(100, 5), new L.Point(200, 20))]); - Color Functions: Color is an important aspect of data visualization, so the framework provides classes derived from LinearFunction that make it easy to translate data properties into colors. The framework relies heavily on Hue, Saturation, Luminosity/Lightness (HSL) color space over the more familiar, ubiquitous Red, Green, Blue (RGB) color space. HSL color space offers some advantages over RGB for data visualizations, particularly with respect to numeric data. Hue, the main component used to determine a color in HSL space, is an angle on the color wheel that varies from 0 degrees to 360 degrees according to the visible spectrum/colors of the rainbow (red, orange, yellow, green, blue, indigo, violet, back to red). This makes it easy to map a numeric input value to an output hue using the same LinearFunction concept described previously and gives us nice color scales – green to red, yellow to red, blue to red, etc – that work well for illustrating differences between low and high values. Achieving the same effect with RGB color requires varying up to three variables at once, leading to more code and complexity.
- L.HSLHueFunction: This class produces a color value along a rainbow color scale that varies from one hue to another, while keeping saturation and luminosity constant.
- L.HSLLuminosityFunction: This class varies the lightness/darkness of a color value dynamically according to the value of some data property, while keeping hue and saturation constant.
- L.HSLSaturationFunction: This class varies the saturation of a color value dynamically according to the value of some data property, while keeping hue and luminosity constant.
Data Layers
As I mentioned in my previous post, one point of the framework is to standardize and simplify the way in which thematic mapping data are loaded and displayed; keeping this in mind, the framework provides classes for loading and displaying data in any JSON format. The framework introduces the concept of a DataLayer, which serves as a standard foundation for loading/visualizing data from any JavaScript object that has a geospatial component.
- L.DataLayer: Visualizes data as dynamically styled points/proportional symbols using regular polygon or circle markers
- L.ChoroplethDataLayer: This class allows you to build a choropleth map from US state or country codes in the data. The framework provides built-in support for creating US state and country choropleth maps without needing server-side components. Simply import the JavaScript file for state boundaries or the JavaScript file for country boundaries if you’re interested in building a state or country level choropleth. In addition, states and countries can be referenced using a variety of codes.
- ChartDataLayers – L.PieChartDataLayer, L.BarChartDataLayer, L.CoxcombChartDataLayer, L.RadialBarChartDataLayer, L.StackedRegularPolygonDataLayer: These classes visualize multiple data properties at each location using pie charts, bar charts, etc.
Support for custom/non-standard location formats (e.g. addresses)
Data doesn’t always come with nicely formatted latitude and longitude locations. Often there is work involved in translating those location values into a format that’s useable by Leaflet. DataLayer classes allow you to pass a function called getLocation as an option. This function takes a location identified in a record and allows you to provide custom code that turns that location into a format that’s suitable for mapping. Part of this conversion could involve using an external web service (e.g. geocoding an address).
Support for automatically generating a legend that describes your visualization
Legends are common thematic mapping tools that help users better understand and interpret what a given map is showing. Simply call getLegend on any DataLayer instance to get chunk of HTML that can be added to your application or add the L.Control.Legend control to your Leaflet map. This control will automatically display the legend for any DataLayer instance that has been added to the map.
A Quick Example
Here’s a quick example choropleth map of electoral votes by state with states colored from green to red based on the number of electoral votes:
//Setup mapping between number of electoral votes and color/fillColor. In this case, we're going to vary color from green (hue of 120) to red (hue of 0) with a darker border (lightness of 25%) and lighter fill (lightness of 50%)
var colorFunction = new L.HSLHueFunction(new L.Point(1, 120), new L.Point(55, 0), {outputSaturation: '100%', outputLuminosity: '25%'});
var fillColorFunction = new L.HSLHueFunction(new L.Point(1, 120), new L.Point(55, 0), {outputSaturation: '100%', outputLuminosity: '50%'});
var electionData = {…};
var options = {
recordsField: 'locals',
locationMode: L.LocationModes.STATE,
codeField: 'abbr',
displayOptions: {
electoral: {
displayName: 'Electoral Votes',
color: colorFunction,
fillColor: fillColorFunction
}
},
layerOptions: {
fillOpacity: 0.5,
opacity: 1,
weight: 1
},
tooltipOptions: {
iconSize: new L.Point(80,55),
iconAnchor: new L.Point(-5,55)
}
};
// Create a new choropleth layer from the available data using the specified options
var electoralVotesLayer = new L.ChoroplethDataLayer(electionData, options);
// Create and add a legend
$('#legend').append(electoralVotesLayer.getLegend({
numSegments: 20,
width: 80,
className: 'well'
}));
map.addLayer(electoralVotesLayer);I want to highlight a few details in the code above. One is that there’s not a lot of code. Most of the code is related to setting up options for the DataLayer. Compare this to the Leaflet Choropleth tutorial example, and you’ll see that there’s less code in the example above (34 lines vs. about 89 lines in the Leaflet tutorial). It’s not a huge reduction in lines of code given that the framework handles some of the functions that the Leaflet tutorial provides (e.g. mouseover interactivity), but the Leaflet tutorial is using GeoJSON, which as I mentioned earlier is well handled by Leaflet, and the example above is not. I’ve omitted the data for this example, but it comes from Google’s election 2008 data and looks like this:
{
...,
"locals":{
...,
"Mississippi": {
"name": "Mississippi",
"electoral": 6,
...,
"abbr": "MS"
},
"Oklahoma": {
"name": "Oklahoma",
"electoral": 7,
...,
"abbr": "OK"
},
...
},
...
}
When configuring the L.ChoroplethDataLayer, I tell the DataLayer where to look for records in the data (the locals field), what property of each record identifies each boundary polygon (the abbr field), and what property/properties to use for styling (the electoral field). In this case, the L.ChoroplethDataLayer expects codeField to point to a field in the data that identifies a political/admin boundary by a state code. In general, DataLayer classes can support any JSON-based data structure, you simply have to point them (using JavaScript style dot notation) to where the records to be mapped reside (recordsField), the property of each record that identifies the location (codeField, latitudeField/longitudeField, etc. – depending on the specific locationMode value), and the set of one or more properties to use for dynamic styling (displayOptions). Another feature illustrated in the example above is that there’s no picking of a set of colors to use for representing the various possible ranges of numeric data values. In the example above, color varies continuously with respect to a given data value, based on the range that I’ve specified using an L.HSLHueFunction, which as I mentioned earlier varies the hue of a color along a rainbow color scale. The last feature I want to highlight is that the framework makes it as easy as one function call to generate a legend that describes your DataLayer to users. There’s no need to write custom HTML in order to generate a legend.
That’s it for now. Hopefully this overview has given you a better sense of the key features that the framework provides. Detailed documentation is still in the works, but check out the examples on GitHub. In my next post, I’ll walk through the Earthquakes example, which is basically just a recreation of the USGS Real-Time Earthquakes map that I alluded to in my previous post.
HumanGeo 