Item page
CodePen
Sandbox Download

Global power plants clustered and categorized by fuel type to surface spatial density at a glance.

What is clustering?

Clustering is a method of reducing features in a layer by grouping them into clusters based on their spatial proximity to one another. Typically, clusters are proportionally sized based on the number of features within each cluster.

This is an effective way to show areas where many points stack on top of one another.

CodePen
Sandbox Download

Use the swipe control to compare unclustered power plants with clustered versions of the same data.

Why is clustering useful?

Large layers can be deceptive. What appears to be just a few features can in reality be several thousand. Clustering allows you to visually represent large numbers of features in relatively small areas.

For example, the following map shows the locations of thousands of power plants. In the image below, regions A and B both have a high density of points, making them impossible to compare.

clustering disabled

Figure :

Region A and region B both have a high density of points. It is impossible to tell how many points overlap in each area.

However, when clustering is enabled, the user can now clearly see that region B has nearly twice as many points as region A.

classed with no label

Figure : Clustering allows the user to easily compare the density of overlapping features at a glance.

How clustering works

Clustering is configured by setting a layer’s featureReduction property to cluster.

layer.featureReduction = {
type: "cluster",
};

The featureReduction property gives you control over many other cluster properties. The clusterRadius defines each cluster’s area of influence for including features. You may also define popupTemplates and labels for clusters to summarize the features included in the cluster.

To improve the readability of clustered layers, consider the following:

  • Turn off label deconfliction when labeling clusters with a count in the center of the cluster. If label placement is outside the cluster, keep label deconfliction enabled.
  • Increase the clusterMinSize to fit labels inside smaller clusters (16pt is a good starting point).
  • For larger layers, format the cluster count in the label with either a rounded value or an abbreviated value (e.g. 10k instead of 10000).

Clustering polylines and polygons

Clustering is typically used to visualize large point layers, but may be used with any geometry type (since version 4.31). In the case of clustering polyline or polygon features, the centroid of the line or polygon is used to determine the cluster in which it is placed. This may lead to some features being placed in unexpected clusters. Small features like parcels, buildings, swimming pools, bridges, culverts, or connectors are well-suited for binning at small scales. Large, irregularly shaped features like counties, states, or countries do not need to be clustered.

Use the following guidelines when clustering lines or polygons:

  • When clustering polygon or polyline layers, you must define a cluster renderer for clusters to be visible in the view. Use a renderer that complements the layer’s renderer so that clusters are closely associated with the features they represent.
  • Clustering lines and polygons works best for small features that are uniform in size and smaller than the cluster radius. This prevents misrepresenting the spatial distribution of features. For example, a very large polygon may intersect multiple clusters, but it is only represented in one cluster (the one nearest its centroid). So, some areas may show no clusters at all even though they are covered by large features.
  • Clustering works best at smaller scales (when zoomed out). You should set a maxScale in the feature reduction configuration to disable clustering at larger scales (when zoomed in). This allows you to view features in full fidelity.

Examples

Basic clustering

The aggregate fields used by clusters are generated once clustering is enabled on the layer. By default, all clustered layers have a cluster_count aggregate field. This can be used in the labels and the popup for each cluster. Other fields used in the layer’s renderer may be accessible for display in the popup. You can learn more about how to use these in the FeatureReductionCluster.popupTemplate documentation.

Item page
CodePen
Sandbox Download
Global power plants are clustered by count, with summaries displayed in labels and popups.
Clustering - basic
20 collapsed lines
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
<title>Clustering - basic</title>
<!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
<script type="module" src="https://js.arcgis.com/5.2/"></script>
<style>
html,
body {
height: 100%;
margin: 0;
}
</style>
</head>
<body>
<arcgis-map item-id="47d23dd1a3784be0bc768154a1c2b243">
<arcgis-zoom slot="top-left"></arcgis-zoom>
<arcgis-expand slot="top-left">
<arcgis-legend></arcgis-legend>
</arcgis-expand>
</arcgis-map>
2 collapsed lines
</body>
</html>

Suggested cluster defaults

By default, the cluster symbol always summarizes the features in the cluster. When a layer has a UniqueValueRenderer, the symbol of each cluster represents the predominant value of features in the cluster. When a layer has any visual variables applied to it, the average of each variable in the cluster is applied to the cluster symbol. The fields describing the predominant type and average of numeric fields can be referenced in the cluster popup and label.

Smart Mapping can generate a suggested cluster configuration specific to a layer’s renderer.

Item page
CodePen
Sandbox Download
Smart Mapping clusters global power plants and summarizes each cluster by its fuel type.
Clustering - suggested defaults
20 collapsed lines
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
<title>Clustering - suggested defaults</title>
<!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
<script type="module" src="https://js.arcgis.com/5.2/"></script>
<style>
html,
body {
height: 100%;
margin: 0;
}
</style>
</head>
<body>
<arcgis-map item-id="e85caeb5727d4d2b9de9b21453a4ec41">
<arcgis-zoom slot="top-left"></arcgis-zoom>
<arcgis-expand slot="top-left">
<arcgis-legend></arcgis-legend>
</arcgis-expand>
</arcgis-map>
2 collapsed lines
</body>
</html>

Clusters as pie charts

By default, when a layer has a UniqueValueRenderer or ClassBreaksRenderer, the symbol of each cluster represents the predominant category within the cluster.

You may prefer to visualize clusters of type-based renderers as pie charts rather than the predominant category. To do this, you can call the pieChart.createRendererForClustering method, which will create a pie chart renderer based on the categories defined in a UniqueValueRenderer or a ClassBreaksRenderer. The fields and renderer returned from this method should be set directly on the FeatureReductionCluster instance on the layer.

Item page
CodePen
Sandbox Download
311 incident reports summarized as pie charts for categories in a unique value or class breaks renderer.
Clustering - pie charts
20 collapsed lines
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
<title>Clustering - pie charts</title>
<!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
<script type="module" src="https://js.arcgis.com/5.2/"></script>
<style>
html,
body {
height: 100%;
margin: 0;
}
</style>
</head>
<body>
<arcgis-map item-id="f0b417992ac64d4197070cb613f0ad66">
<arcgis-zoom slot="top-left"></arcgis-zoom>
<arcgis-home slot="top-left"></arcgis-home>
<arcgis-expand slot="top-left">
<arcgis-legend></arcgis-legend>
</arcgis-expand>
</arcgis-map>
2 collapsed lines
</body>
</html>

API support

The following table describes the geometry and view types that are suited well for each visualization technique.

  • Full support
  • Partial support
  • No support
2D3DPointsLinesPolygonsMeshClient-sideServer-side
  1. Feature reduction selection not supported
  2. Only by feature reduction selection
  3. Only by scale-driven filter