JS Charting: Mapping

JS Charting comes integrated with geographic mapping support, including optimized data files for all country, province and state maps without the need of a separate product or add-on. What's more interesting is that the API for mapping is the same as that used for regular charts, enabling users to leverage the existing experience to create new map charts quickly and easily. In this tutorial, we will set up a multi-step thematic map bound to real-world data from a live source.

See the Pen by Arthur Puszynski (@jsblog) on CodePen.

To enable charting in the page, jQuery and the JSCharting scripts are added.

    <script src="https://code.jquery.com/jquery-1.11.3.min.js"></script>
    <script src="JSC/JSCharting.js"></script>
    

Then a div element is placed in HTML to host the chart visual.

<div id="mainChart"></div>
    

To draw a chart the jquery plugin API can be used to bind chart options to a the div and takes the following form:

$('#mainChart').JSC({/*chart options*/});
    

The Basics

In traditional mapping, the concept of map layers are used to construct maps and JSCharting is similar, however, regular series and points are used for this purpose. Chart series are equivalent to map layers and points represent the shapes within those layers. To render a map layer of the United States the chart options define the type of chart as map, and a series with a map code:

{ 
    type:'map',
    series:[{
        map:'us'
    }]
}
     

For a reference of the included map areas, see the interactive mapping browser.

Because a series is used, the points of the series become states within the US map. Alternatively, if we only wanted the outline of the US, we would add a series with a point map property set to US.

{ 
    type:'map',
    series:[{
        points:[{
            map:'us'
        }]
    }]
}
     

Returning to the first example, where we use a series of the United States, points are generated internally. In order to customize the individual map layer shapes of a series, points can be specified for each state and their properties will be used instead of the auto generated points. For example:

{ 
    type:'map',
    series:[{
        map:'us',
        points:[{
            map:'us.il',
            color:'red'
        }]
    }]
}
     

See the Pen by Arthur Puszynski (@jsblog) on CodePen.

Map Context

Another useful mapping concept in JSCharting is base layers. These layers are used to show continuation of landmasses when the surrounding areas of the Map are not part of the data series. For example, when showing a map of the US, we can optionally add Mexico and Canada as context layers. These layers do not affect the view bounds of the map and appear grayed out so visual focus remains on the landmass of primary interest.

{
    mappingBaseLayers:'mx,ca'
}
     

For more examples of map related features, see the js map features gallery

Binding to data

Now that we have the basics covered, let's bind maps to real-world data. For this, we will use the following dataset pulled from a live google sheets document so the map data will always reflect the new data and edits made on the sheet in real-time.

A utility function will convert the spreadsheet JSON data into a series of points. The data feed contains an array of rows with state abbreviations and a value for each state. These rows are mapped to points and passed on to the chart.

Note: When identifying states, the HASC code syntax such as ‘us.il’ is used to specify Illinois. However, FIPS is also supported (where applicable) and the equivalent code for Illinois would be written as ‘us.fips:US17’. For a complete reference of map codes for all world countries, see this this reference

This associates the state codes to point map properties and the value to the Z value property. We don't use Y values here, which are commonly used by most chart types, because Y values represent the Latitude coordinates in maps. Z values can be thought of as magnitude.

The data is now loaded for the chart; however, this chart does not yet visualize the Z values on this map. We will use a feature named smartPalettes to bind the point Z values to a color scale in order to visualize the Z values by color coding them.

palette:{
    pointValue:'{%zValue}',
    colors:['green','yellow','red']
}
     

First we specify the value we will bind to the palette through the pointValue property. This can be bound to any point level token in addition to expressions that evaluate mathematical formulas dynamically. Next, we specify a set of colors that will apply to the range of values available for each point, based on its value.

Now this map visualizes the data bound to the point z values:

See the Pen by Arthur Puszynski (@jsblog) on CodePen.

SmartPalettes

Let's delve a little deeper into palettes and explore some of the additional options. When we specify an array of colors, they are rendered in order on the scale with equal allocations; for more control of color placement, we can use the stops property as shown in Palette 1 below. Color stops define the exact positions for each color on a range of 0 to 1 in place of the default.

See the Pen by Arthur Puszynski (@jsblog) on CodePen.

Color stops are defined with a position on the scale between 0-1. This is similar to conventional gradient fill color stops. And conventionally, if we wanted this range to remain green between 0 and .5, then fade to yellow as it approaches 1, an additional color stop would be required. SmartPalettes have a color snapping feature that allows this to be applied more easily and without additional color stops. In the Palette 2 example, we will indicate that the green color should snap to half of the range between it and the next stop.

If we wanted the yellow color to remain solid from .5 to 1 instead, the Palette 3 configuration could be used.

Here, the setting indicates that green should start transitioning immediately at 0 (default) and end the transition at .5.

We tie all this together in Palette 4, where we will use a more complex case with two colors, while having them remain mostly solid except for a small portion in the middle where the colors transition seamlessly.

Note: A set of predefined color scales is available in this smart palette gallery sample

This approach is used very effectively on the US election map example where the colors snap to either red or blue, but in states that were close, intermediary colour variations are still rendered.

Conclusion

In this article we have started to scratch the surface of mapping with JSCharting. The map related API is very intuitive and makes it easy to get started quickly. The built-in map data set allows you to immediately create map charts without having to learn or be aware of map data format standards; however, advanced users are also able to load custom geoJSON and topoJSON files as needed. Despite the simplicity of the API, the mapping component is designed with developer convenience at its core.

About Arthur Puszynski

Initially inspired by C++ graphics demoscenes in the 90s, Arthur’s passion for graphics programming has continued to grow since that time. With 15+ years focused on chart and mapping visualizations, the death of plugins have brought a renewed passion for platform independent graphics using JavaScript and SVG.

JSCharting.comPosts