This chart is developed for Zoomdata 2.6.x and requires the Zoomdata Custom Chart CLI 3.0.0. It has not been migrated to Zoomdata 3.x/CLI 4 yet.
This proof of concept visualization uses the MapboxGL library and the Mapbox Enterprise Boundaries dataset to build a choropleth map. The map is similar to the Zoomdata Map: World Countries in that it colors polygons based on aggregate data from Zoomdata. Instead of using GeoJSON for the boundaries this chart uses the enterprise boundaries for the polygons. This offers the following advantages:
- Enterprise Boundaries are global at multiple levels, providing great fidelity for geopolitical boundaries not avaialble from freely downloadable resources (or other paid sources, for that matter)
- The boundaries are provided as a stream from the Mapbox service. There is no need to load the GeoJSON as a library at design time, boundaries are loaded dynamically as needed.
Go to https://www.mapbox.com/studio. Create an account or log in to an existing account. Go to your account profile and click "Create a Token" in the Access Tokens section.
The Mapbox Enterprise Boundaries layer is a special dataset available from Mapbox. Contact Mapbox to have that dataset enabled for your account.
On Linux/Mac OS machines with the zip utility use the included package_2.6.sh script to build the import file for Zoomdata. Otherwise, add the files version, visualization.js, and the components folder (all contents). These 3 entities should reside at the root of the zip file, so if you unpack them they don't create a new folder (except for components).
Use the Zoomdata chart CLI to add the chart to the Zoomdata instance:
zd-chart add "Mapbox Boundaries" mapbox_boundaries.zip
This only needs to be done once, after the chart has been added to the server it can be updated with zd-chart push or zd-chart watch.
The sample_data folder contains test_data_boundaries_global.csv. Add this file as a flat file source to your Zoomdata instance. Alternatively the CSV could be imported into any data store supported by Zoomdata. This sample data file has a set of attributes and values generated by a random algorithm. The data set also includes region information for administrative levels 0, 1, and 2 world wide. These values were randomly pulled from the enterprise boundaries metadata provided by Mapbox. The values for boundaries respect the parent relationship - admin level 2 items actually belong to the admin 1 and admin 0. So, "Fairfax County" will also be "Virginia" and "US".
The visualization currently uses the internal Mapbox region identifiers, as opposed to region name or abbreviation. These values are in the adm#_id fields of the data.
Add the data as a flat file source in Zoomdata and navigate through the options to the "Chart Configuration" tab. Enable the new "Mapbox Boundaries" visualization in the "Custom" tab. Set the desired metrics for color and height, these will be used to render the polygons in the chart. Paste in your access token for Mapbox. Finally, paste the contents of sample_data/global_boundaries-config.json into the "Layer Configuration" block on the map configuration page.
Optionally, you can tweak the opacity and extrusion factor properties.
- Opacity controls how transparent the polygons. Partial transparency is nice, then the underlying map tiles show through
- Extrusion factor will be multiplied against the height metric to make the height of the polygons. If the values are close, or very small, this helps to exaggerate the height. For the sample data an extrusion factor of 100 looks good
The chart expects aggregations to be done on the Mapbox ID for the region. This is not acceptable as most customer data will not use this value. Instead they will use some well known identifier for the region such as country 2 letter code, or geopolitical full name. Names could be in a single language for the data or in the native language of the specific region.
Mapbox provides some mapping files between their identifiers and different possible values. We would have to perform some mapping, either at the data/fusion level or in the chart, to match the IDs and know what polygon to color.
Set the initial center point and zoom level of the map using variables or a block in the property (see the custom regions visualization).
The "mapdatagen" folder contains a script used to generate the data. See the readme in that folder for more info.