Tutorial 8: AreaMapper and grid visualization

In this tutorial, we'll learn how to use grid visualization with different indicator scales. Currently, there are two ways of using grid in CleverMaps:

  • connecting your geometryPoint dataset using h3Grid datasets with grid geometries generated on the fly
  • mapping your geometryPoint dataset using AreaMapper and importing a grid data dimension with vector tiles

This tutorial covers both cases. It's up to you if you want to learn only of them, or both.

What you'll create

We will add a grid visualization and some more indicator scales.

grid visualization, heatmap scalegrid visualization, magma scale

grid visualization, positive scalegrid visualization, negative scale

Using H3 grid

CleverMaps natively supports visualization using the H3 grid spatial index developed by Uber. This hierarchical spatial index consists of several resolutions of grid cells which cover the whole Earth, and are related to each other (similar to lower and higher administrative units). The differences between this approach and using AreaMapper and data dimension are:

  • The geometries are not in vector tile format, but are generated on the fly by the application frontend
  • There is no need for pre-computed DWH datasets in the project - H3 grids have generated cell names
  • The grid can be used for any location on Earth (in any resolution)

The usage is also much simpler - to use the H3 grid visualization we need to:

  1. add some h3Grid datasets (each for one resolution)
  2. add these datasets to the ref.h3Geometries array of the geometryPoint dataset we want to visualize

So, let's add these 4 h3Grid datasets:

Resolution 6Resolution 7Resolution 8Resolution 9

Use addMetadata to add these datasets. Now add the h3Geometries reference to the customers dataset:

And use pushProject to push the changes. You can review the references to the h3Grid datasets in the data model.

Now you can skip right to Tutorial 8: AreaMapper and grid visualization#Grid visualization, or explore the second way - AreaMapper and data dimension.

Using AreaMapper and data dimension

Running AreaMapper

CleverMaps AreaMapper is one of our data preparation tools. AreaMapper computes geometric intersection between points and polygons (areas, grids) and then adds ID's of polygons to the points table if an intersection exists.

It can be run in Docker or at Keboola. We will use Docker, because not everyone has a Keboola account and it can be run locally.

Then use following command to get the AreaMapper image:

We will create an empty directory on our local drive (e.g. /home/user/CleverMaps/AreaMapper) and copy the customers.csv file from the first tutorial into the folder.

Now, we will create a configuration file for AreaMapper. There are two possible ways of running AreaMapper:

  • using polygons CSV on your local drive
  • using polygons CSV prepared and hosted by us

The difference is - when using local CSV, you can use any CSV you want. When using the hosted CSV, the file has to be hosted by us first. For more info, contact us at info@clevermaps.io. Current list of hosted dimensions can be found here.

The CSV we will use in this tutorial is already hosted. In case you want to try the "local" way, or just have a look at the CSV, you can download it here.

Hosted CSVLocal CSV

We will run AreaMapper using following command. Please note that you have to modify the paths according to your system.

(warning) Copy the output file you specified in the JSON config (customers_mapped.csv) to your project dump /data folder and rename it to customers.csv to overwrite the older customers CSV.

Importing the grid dimension

Let's import the grid data dimension using the importProject command.

Here, we omit a significant amount of the import command output for the sake of readability.

Add the imported files using addMetadata and pushProject.

Now we have to edit the customers dataset. AreaMapper added one column to the end of the CSV file - hex_id. We have to add this property to the end of our dataset. It's foreign key will point to the lowest grid dataset - cz_grid_res9_dwh.

Take a look at the data model to see that the customers and cz_grid_res9_dwh are joined. 

Grid visualization

Enter the Business overview view, and select the new granularity from the granularity drop down menu.

Now, we have a new visualization available - grid.

Alternatively, select one of the lower levels to get to a bigger detail.

Indicator scales

Let's take a look at more indicator scales. So far we've used only the standard (blue) scale. 

To try some of them, set following scales for these indicators:

  • for online_turnover_indicator, set content.scale to "heatmap"
  • for offline_turnover_indicator, set content.scale to "magma"
  • for online_ratio_indicator, set content.scale to "positive"
  • for offline_ratio_indicator, set content.scale to "negative"

Use pushProject to push the indicators and enter the view. Select the grid visualization, select one of the lower levels (e.g. "Cell edge 460 m") and click "Visualize" on the "Online channel turnover" indicator.

But indicators offer way more scales. Feel free to explore them and use them in your projects!