ArcGIS Online

Summarize and explore point clusters with Arcade in popups

Starting with the December 2021 update of ArcGIS Online and version 4.22 of the ArcGIS API for JavaScript (ArcGIS JS API), you can summarize point clusters in more detail using Arcade expressions in popups. This allows you to display informative reports, summaries and charts of clustered data.

If you already know what clustering is, feel free to skip the clustering overview and navigate to the Access and summarize clustered features using Arcade section below.

Clustering overview

Clustering is a method of merging nearby and overlapping features into a single symbol to declutter the view. The size of the cluster icon indicates the number of features in each cluster relative to other clusters.

For example, check out this map of earthquakes that occurred along the Aleutian Islands in June 2020.

Earthquakes clustered.
Earthquakes that occurred along the Aleutian Islands in June 2020. The points are clustered so you can easily see where more earthquakes occur.

Clustering helps you immediately see the relative density of features. When clustering is not enabled, it’s difficult to discern areas where there are a lot of overlapping points.

Notice how the cluster of 1,000+ earthquakes in the previous image is not noticeable when the same layer is not clustered. In fact, the density appears largely uniform.

Earthquakes along the Aleutian Islands from the last 30 days. Not clustered.
Earthquakes that occurred along the Aleutian Islands in June 2020. In this visualization, each earthquake is represented with one point. When points aren't clustered, overlapping points make it difficult to see areas with a high number of earthquakes.

You can define cluster labels and popups to provide users with additional information about the cluster.

Cluster popups

By default, when you enable clustering in the Map Viewer and select a cluster, you will see a nice popup that summarizes the data in the cluster. Clusters with no data-driven style will only display the number of features in the popup.

Clusters of power plants in western Europe. When all points are symbolized with the same style, the default cluster popup will only show the number of features contained within the cluster.
Clusters of power plants in western Europe. When all points are symbolized with the same style, the default cluster popup will only show the number of features contained within the cluster.

For clusters rendered with unique values, the popup displays the number of features in the cluster along with the predominant value of the categorical field.

Clustered power plants colored based on the most common fuel type for generating power within the cluster. Cluster popups in layers styled with unique values will display the predominant unique value (i.e. category) within the cluster.
Clustered power plants colored based on the most common fuel type for generating power within the cluster. Cluster popups in layers styled with unique values will display the predominant unique value (i.e. category) within the cluster.

If the clustered layer is rendered with any numeric values (either using color, size, opacity, or rotation), the average of those values will be displayed in the cluster popup.

Clusters of power plants colored based on the average mW capacity of plants in the cluster. The default popup in this scenario will display the average value of the color variable.
Clusters of power plants colored based on the average mW capacity of plants in the cluster. The default popup in this scenario will display the average value of the color variable.

Prior to the December 2021 update, you could update the text of the cluster popup to be more descriptive, but you didn’t have the flexibility to summarize any additional information.

Updating popup content prior to December 2021 was limited to more descriptive wording and number formatting.
Updating popup content prior to December 2021 was limited to more descriptive wording and number formatting.

Access and summarize clustered features using Arcade

While the default popups for clusters are good, the information they provide can feel insufficient. In some scenarios, you may want to provide a more detailed summary of the cluster, such as a breakdown of categories present in the cluster, a list of features, or additional statistics.

Two enhancements were added to the ArcGIS Online map viewer that give you more control over the content to display in cluster popups. These include the ability to:

  1. Create popup elements directly from Arcade expressions. Rather than return a text or number value from an expression, now you can return tables, charts, and HTML. I encourage you to read this excellent post introducing this capability.
  2. Access a cluster’s features within an Arcade expression for cluster popups. Now you can iterate through a cluster’s features in an Arcade expression to create lists, tables, and charts summarizing the cluster. The remainder of this post will demonstrate various ways you can do this.

As of December 2021, you can now add an Arcade expression to a cluster popup either using the Manage Expressions entry point for returning a single text or numeric value, or you can add an Arcade element to return HTML elements, a table, or a chart directly from an Arcade expression. We’ll use the Arcade element in each of the examples below.

Now you can author Arcade expressions within cluster popups to provide more detailed information about a cluster.
Now you can author Arcade expressions within cluster popups to provide more detailed information about a cluster.

Access aggregated features with Arcade

Cluster popups already give you access to individual features included in the cluster via the Browse features action. This action allows you to scroll through a list of the aggregated (i.e. clustered) features and open an individual feature’s popup. Note that you can also see the selected feature’s location on the map.

Now that Arcade is enabled for cluster popups, you can access all features using the $aggregatedFeatures feature set within cluster popup expressions. With $aggregatedFeatures, you can calculate any statistic on the cluster’s features, filter them, or even list them in the popup content.

// Returns the total capacity of all plants in the cluster
Expects($aggregatedFeatures, "capacity_mw")
Text(Sum($aggregatedFeatures, "capacity_mw"), "#,###")

Examples

The remainder of this post will walk through various popup configurations that take advantage of these new capabilities in Arcade. They’ll all use a variation of this web map showing a clustered layer representing global power plants.

Clustered power plants colored based on the most common fuel type for generating power within the cluster. Cluster popups in layers styled with unique values will display the predominant unique value (i.e. category) within the cluster.
Clustered power plants colored based on the most common fuel type for generating power within the cluster. Cluster popups in layers styled with unique values will display the predominant unique value (i.e. category) within the cluster.

The following list describes content you can now summarize in cluster popups.

  1. Display the sum of one attribute
  2. Display the largest value
  3. Ordered list by type
  4. Table of custom attributes
  5. HTML table with 3+ columns
  6. Pie Charts
  7. List of features
  8. Column charts for features

1. Display the sum of one attribute

By default, the cluster popup only displays the average of numeric attributes included in the layer’s style. However, it may be more appropriate to display the sum of numeric attributes. The following example demonstrates how to calculate the total mW capacity of all power plants in the cluster using Arcade.

// Returns the total capacity of all plants in the cluster
Expects($aggregatedFeatures, "capacity_mw")
Text(Sum($aggregatedFeatures, "capacity_mw"), "#,### mW")
By providing $aggregatedFeatures to statistic functions in Arcade, you can now display statistics for any numeric attribute in a cluster popup.
By providing $aggregatedFeatures to statistic functions in Arcade, you can now display statistics for any numeric attribute in a cluster popup. Click the image above to open the web map with this popup configuration.

2. Display the largest value

You may want to display information about the power plant that produces the most power within the cluster. The expression can return its name, capacity, and the type of fuel it uses to generate power. These are multiple bits of information that can be returned as a text element directly from the expression.

This cluster popup displays information about the plant that produces the most power in the cluster. You can display multiple values from a single expression by returning a rich text element containing these values directly from an Arcade expression.
This cluster popup displays information about the plant that produces the most power in the cluster. You can display multiple values from a single expression by returning a rich text element containing these values directly from an Arcade expression. Click the image to open the web map with this popup configuration.

3. Ordered list by type

When a clustered layer styles points by category or type, the color (or symbol) of the cluster indicates the most common type of feature included within the cluster. While this is helpful in many cases, you may want to display a list of all the types included in the cluster, along with the number of features belonging to each category.

Because expressions can return popup content elements, you can return HTML from an expression to display in the popup within a rich text element. The following expression finds the distinct types within the cluster, iterates through each to get the count of each category, and dynamically builds an ordered list as HTML to return in the popup text element.

This cluster popup displays a list of distinct categories of features within the cluster along with their count.
This cluster popup displays a list of distinct categories of features within the cluster along with their count. Click the image to open the web map with this popup configuration.

Alternatively, you could filter and display the count of only one critical category, such as the total number of fatalities in a cluster of traffic accidents.

http://Clicking%20the%20dock%20action%20will%20allow%20the%20user%20to%20view%20more%20content%20in%20a%20popup%20in%20a%20single%20view.

4. Table of custom attributes

You can also build a table of key-value pairs that mimics the fields content element in the popup. When displaying a list of fields in a layer popup, you can use the Map Viewer UI to select the fields to include and set their formatting. The list of fields will then display as a table.

Similarly, you can return an attribute table directly from an Arcade expression. The following snippet does this to list the distinct types within the cluster. Rather than report the count for each fuel type, it reports the total capacity for each fuel type. It’s interesting to observe how different the list looks when comparing total count vs. total capacity.

Note how the attributes manage the values calculated by the expression and the fieldInfos indicate which attributes must be displayed in the output table.

A cluster popup displaying unique categories of power plants by fuel type as an attribute table. Rather than sort the categories by count, they are sorted by total capacity.
A cluster popup displaying unique categories of power plants by fuel type as an attribute table. Rather than sort the categories by count, they are sorted by total capacity. Click the image to open the web map with this popup configuration.

5. HTML table with 3+ columns

Returning a fields element works well if you only need to display one value per attribute or category. However, you may want to display more than one data attribute per category. In this scenario, you can return an HTML table within a text element. The table in the expression below has columns for four attributes per fuel type: total capacity, total count, average capacity, and maximum capacity.

The Arcade expression in this popup returns a multi-column table displaying various summary statistics for each fuel type. Click the image to open the webmap with this popup configuration.
The Arcade expression in this popup returns a multi-column table displaying various summary statistics for each fuel type. Click the image to open the webmap with this popup configuration.

I added information about the largest plant from a previous expression to put the outliers in context with the rest of the cluster.

6. Pie Charts

You can also return charts directly from Arcade expressions within a popup. I was intrigued by the differences in capacity versus count for the lists of each fuel type, so I decided to create two pie charts to make it easy to compare the number of plants by fuel type with the total capacity of each type.

The mediaInfo element in a popup allows you to return an array of charts to scroll through. I did that here to keep the logic for both charts in one expression and the popup content more compact.

Notice how clusters that show a lot of solar or wind plants report that more power is generated from other sources of power, like nuclear.

The selected cluster contains more wind power plants than any other fuel type.
The selected cluster contains more wind power plants than any other fuel type. Click the image to open the web map with this cluster popup configuration.
Despite the number of wind plants comprising 43 percent of the cluster, wind plants only account for 11 percent of the total power generated by power plants within the cluster.
Despite the number of wind plants comprising 43 percent of power plants in the cluster, wind plants only account for 11 percent of the total power generated by power plants within the cluster. Click the image to open the web map with this cluster popup configuration.

7. List of features

Sometimes you may want to list the titles of aggregated features directly in a cluster popup as an alternative to the Browse features experience. You can do this using the techniques described above, but keep in mind that simply listing names or titles of all features in the popup can lead to a very lengthy popup and a bad experience for the user.

In the example below, I opt to list the features in the popup only if there are fewer than 20 features included in the cluster. This allows me to list individual features without worrying about the length of the popup content. I added a condition to the expression that displays a list of categories if the cluster count exceeds 20 features.

When fewer than 20 features exist in a cluster, then the popup will list the power plants included in the cluster along with the type of fuel for generating power and its total capacity.
When fewer than 20 features exist in a cluster, then the popup will list the power plants included in the cluster along with the type of fuel for generating power and its total capacity. Click the image to open the web map with this cluster popup configuration.
When more than 20 features exist in a cluster, the popup will list the various fuel types for generating power within the cluster along with the number of power plants using each fuel type.
When more than 20 features exist in a cluster, the popup will list the various fuel types for generating power within the cluster along with the number of power plants using each fuel type. Click the image to open the web map with this cluster popup configuration.

8. Column charts for features

As an alternative to listing features included in a cluster, you could display the top 20 features in a chart visualizing their total capacity. The following expression returns a column chart comparing the capacity of the top 20 power plants within each cluster. The tooltip displayed as you hover on each bar includes additional information about the power plant, such as the type of fuel used to generate power, and the percentage of the total capacity of the cluster that is generated by the plant.

This cluster popup displays the top 20 features in a column chart based on their total capacity. Click the image to view the web map with this cluster popup configuration.
This cluster popup displays the top 20 features in a column chart based on their total capacity. Click the image to view the web map with this cluster popup configuration.

Conclusion

Thanks to advancements in Arcade and ArcGIS Online, you now have many alternatives for summarizing cluster content. I highly encourage you to enhance your cluster popup content and share your maps!

About the author

Kristian is a Senior Product Engineer at Esri. His work focuses on data visualization and Arcade integration in the ArcGIS API for JavaScript. His goal is to help developers be successful, efficient, and confident in building web applications with the JS API, especially when it comes to visualizing data. Prior to joining Esri he worked as a GIS Specialist for an environmental consulting company. He enjoys cartography, GIS analysis, and building GIS applications for genealogy.

Connect:
4 Comments
Oldest
Newest
Inline Feedbacks
View all comments

Next Article

How to summarize aggregate data using Arcade in popups

Read this article