How to create cluster tooltips in symbol maps?

Once you've enabled the clustering feature while customizing your symbol map, you can create tooltips for your clusters (just like you would for individual symbol markers). This article will explain how to do so.

This is an article for advanced users. You can simply copy and paste our examples, but if you want to adjust things, you might need some Javascript knowledge.
Note: You can set the symbol tooltip separately than the cluster tooltip. Learn how to do so here.

To create a nifty cluster annotation in symbol maps, here’s what you have to do:

  • In Step 3: Visualize under the Refine tab, go to the section titled ''Clustering/Binning'' and select ‘’cluster overlapping symbols’’ option in the clustering drop-down menu.
  • The last section in the Refine tab is ‘’Tooltips’’. Click on‘’Set cluster tooltips’’ and you'll see a pop-up with an empty Title and Body together with a group of column category names on the right.

    You can click on a column name on the right to bring it into the Title and/or Body text field. Let’s have a look in detail as to what these column names do:

  • {{ symbols }} denotes a name, usually in a specific scope (i-e grouping of variables or functions) to avoid naming conflicts) that will look up the ''function'' in a particular environment.

  • {{ symbols.length }} returns the number of symbols or names within a cluster.

  • {{ symbols[0] }} returns the “content” of a symbol. This won’t work until you tell the tooltip editor which column content you want. For example, if you have a column in your data set called “Time”, writing {{ symbols[0].Time }} will display the content of the column “Time” for the first symbol within the cluster. (The symbols are numbered starting from 0. To return the content of the second symbol, write {{ symbol[1].Time }} etc.) The column names are case-sensitive, so write them exactly as they appear in your imported data or else the tooltip will not display correctly.

  • Note: Datawrapper tooltips accept HTML, which means you can experiment with different HTML tags, small tables, links, and even images.
Note:  Clustering tooltips adjust to what’s in the clusters. So if your map shows different clusters on mobile than on desktop, the cluster tooltips will be different, too. The same happens if you change clustering settings like toleration and iteration: The tooltips will adjust accordingly.

Let’s see in the following example how we can use these column names, {{ symbols }}, {{ symbols.length }} and {{ symbols[0] }} to create a cluster tooltip:

Example 1: Polling stations in NYC

This map shows the location of polling stations in different boroughs of New York City for the year 2018. There are 1000+ polling stations in our data so we cluster them to make the map more readable.

In this symbol map's dataset, we have 5 columns:

  • Latitude and Longitude that specify the geocoordinates of these voting sites
  • Borough which specifies in which neighbourhood the voting site is located.
  • Site_Name which indicates the name of the polling station and
  • Voter_Entrance which includes information about the exact street and building number from where the voting site could be accessed

In the cluster tooltip, we want to display the number of polling stations per cluster and the name of each polling station in that cluster. To do so, we’ll go through all our symbols within the cluster with a  for-loop and then use a conditional statement (if/else statement) in Javascript where we tell the tooltip that if our first condition is true then it should show the cluster annotation in a certain way (the if statement) and if condition 1 is not met, than it should show our cluster annotation as per condition 2 (the else statement).

Here's the code snippet that we add to the Body of the cluster tooltip:

{% if (Array.isArray(symbols)) 
{%} {% symbols.forEach(function(symbol, i)   
{ %} {{ i == symbols.length - 1 ? 'and' : '' }}   
{{ symbol.categoryXYZ }}  
{{ i < symbols.length - 2 ? ',' : '' }} {% }); %}  in {{ symbols[0].categoryABC }} insert text here.   
{% } else { %} 
{{ categoryXYZ }}, your text here {{ categoryABC }}, insert   some more text here {% } %}

In the cluster tooltip, we want to display the number of polling stations per cluster and the name of each polling station in that cluster. To do so, we’ll go through all our symbols within the cluster with a for-loop (this will iterate our function(s) over an array) and then use a conditional statement (if/else statement) in Javascript. We construct an if/else statement in situations when several data points are located so close to each other that they tend to overlap in zoomed-out view. So the if statement is a means to bring order from chaos when there are too many markers in a small area.

Since our data has both numbers (integers) and words (strings), we want to group both of these using an array. Array is a data structure that allows us to organize the data in a certain way and do things with it. When the algorithm searches the polling stations (or any other value/element for that matter) within a region, it looks up the numeric position of the elements (i-e polling stations) within the array. This numeric position is called index. Now since Arrays in JavaScript are zero-based, this means that every time JavaScript indexes an array, it will count from zero. Below is an example of this indexing:

Index 0 1 2 3 4 5
Value The Sun sets in  the West

The index at 0 starting from left-to-right in the table is a string ‘’The’’. The index at 1 is ‘’Sun’’, that at 2 is ‘’sets’’, that at 3 is ‘’in’’ and so on.

When we put brackets around array () we are asking JavaScript to pass all the elements within the array as parameters. And since our array indexes start at 0 and go up to the number of elements minus 1 that is why in the if statement we specify that it should count one less out of a group of elements within a region and put ‘and’ or empty space ‘’ and if it counts two or less than two then it should put a comma ‘,’ or empty space.

The function {{ i == symbols.length - 1 ? 'and' : '' }} in the if statement basically says that when the clustering algorithm queries an area, it should put ‘and’ between two symbols when the index of the symbol is at 1. If the index does not equals 1, then it should add empty space (specified by quotation marks). The function {{ i < symbols.length - 2 ? ',' : '' }} dictates that if the algorithm locates a symbol at the index of 2 or before 2, it should add a comma between the two symbols or else just add empty space.

The else statement specifies that if none of the the elements (i-e polling stations) are equal or less than the index we specified in the if statement then it should return the names of the categories as specified in this part of the statement. So for example, if you wrote

‘’The polling station {{ Site_Name }} was located in {{ Borough }}’’

for the else statement, the algorithm will just display the name of the polling state with the borough and will not do any clustering.

This is what the cluster tooltip would look like after adding the code snippet:

Once you hit the ''save'' button on your cluster tooltip, the map looks like this:

Here's how the symbol tooltip looks like when you zoom in on an individual marker.

Here's the cluster tooltip of the same map:

Example 2: Squirrel Census Data (Central Park)

Here's another example of a symbol map with 1000+ markers with clustering enabled (and believe it or not, there is squirrel census data available not only for 2018 but also for 2019). In this example, we have six columns:

  • Latitude and Longitude that specify the geo-coordinates of where the squirrel sighters spotted the squirrels
  • Hectare denotes the specific part of the park where squirrel sighters saw the squirrels (the researchers mapped out and assigned different codes to different parts of the park)
  • Time specifies whether squirrel sighters saw the squirrels in morning shift or afternoon shift
  • Combination of Primary and Highlight Color specifies the color coat of the squirrel
  • Activity columns explains what the squirrels were doing during the brief time window (~20 min) when the squirrel sighters were observing them

Not all the columns in our dataset need to be displayed in the tooltips. For instance, you can leave the coordinates out. We choose to show the color coat of the squirrels, the time and the location where they were seen in Central Park as well as what they were up to. So this is what we add to the if part of our conditional statement. Here's how we structure our tooltip:

{% if (Array.isArray(symbols)) 
{%}  In this part of the Central Park, more specifically, hectare #{{ symbols[0].Hectare }}, squirrel sighters spotted 
<b>{{ symbols.length }}</b> squirrels in the 
{{ symbols[0].Time }} time.  
<br><br>They were engaged in various activties like chasing, climbing, eating and foraging.  
{% } else { %}  
Squirrel sighters spotted {{ Combination_of_Primary_and_Highlight_Color}} squirrel in this part of Central Park doing {{ Activity }} 
{% } %}

Here's how the cluster tooltip looks like after we add the code to the Body of the tooltip:

Once you click on the ''save'' button on your cluster tooltip, the map will look this if you hover over a specific cluster:

Here's how the symbol tooltip looks like when you zoom in on an individual marker:

and here's how the cluster tooltip looks like when you hover over one of the clusters:

You can read more on how to customize your symbol map by following the link here.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us