---
description: 'format: cluster'
---

# Cluster Layer

Cluster layer are point layers. [A combination of PostGIS cluster algorithm](https://medium.com/@goldrydigital/cluster-f-x-nesting-postgresql-kmeans-in-dbscan-for-responsive-maps-9ed99590a439) are applied by the XYZ backend in order to display aggregate cluster for large point location datasets in the map control.

It is possible to select individual locations from an aggregate cluster and theme the cluster based on their aggregate scores.

The size of a cluster represents the count of locations which are aggregated into a cluster.

![](https://1429262937-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LMms4_qYZAl-8nd6vhU%2F-LRpw-wRFifpG_Qbcb0n%2F-LRpwti1s4-U2FOsR47j%2Fimage.png?alt=media\&token=dfa853e7-6dc3-4ea9-be97-60f90724bc4d)

### **Cluster geometry**

`"geom": "geom"`

Cluster layer require a PostGIS geometry column of the type GEOMETRY(POINT,4326). By default the geom value will be set to 'geom'.

## **Cluster parameter**

The cluster algorithm which is used to aggregate locations can be specified with additional cluster parameter.

`"cluster_kmeans": 0.05`

**cluster\_kmeans** defines the minimum number of cluster. The number is determined by 1 over the kmeans value (eg. KMeans 0.05 will generate a minimum number of 20 cluster). The XYZ backend will adjusted KMeans by the absolute number of locations in a map view. The KMeans value can be altered through the cluster panel. _The default value is 0.5._ **A lower KMeans value will produce more cluster.**

`"cluster_dbscan": 0.01`

**cluster\_dbscan** defines the maximum distance between locations in a cluster. The applied value is a ratio of the cross distance across the map view (eg. DBScan 0.01 with 10km cross distance of the map view will set the maximum distance between locations to 100 meter). _The default value is 0.01._ **A higher DBScan value will produce more cluster.**

## **Cluster locations**

`"qID": "optional"`

Setting the **qID** as a valid id column for the database table will make cluster locations selectable. There is no default for the qID value. The qID value together with the table and dbs parameter will be tested during the workspace load.

`"cluster_label": "optional"`

**cluster\_label** defines the label which is shown in the select dialog for multiple locations in a cluster. If not defined, the qID value will be shown in the select dialog.

![Select dialog showing location ID. Default cluster styling.](https://1429262937-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LMms4_qYZAl-8nd6vhU%2F-LPQGY3zl1ODGu8Cokqd%2F-LPRRVms0a3AyjMlUnSv%2Fimage.png?alt=media\&token=43f71a49-3e65-4814-b184-82efda60343a)

Additional parameter will be discussed in the [locations](../infoj) section of this document.

## Cluster styling

Cluster are represented by marker on the map. Two different markers can be defined for single location cluster or multi location cluster. Markers can be svg resources or generated from a set of instructions. The default marker is a 'target' which is displayed as multiple discs of varying size and colour.

```javascript
"style": {
  "markerMin": 20,
  "markerMax": 40,
  "anchor": [20, 40], // optional anchor can align location icon with selection marker
  "marker": {
    "type": "target",
    "fillColor": "#999999"
  },
  "markerMulti": {
    "type": "target",
    "fillColor": "#333333"
  },
  "themes": {}
}
```

### **Marker**

The default target marker is defined by their fillColour only.

```javascript
"fillColor": "#ee8a00",
"layers": {
  "0.5": "#ffffff",
  "0.35": "#ee8a00"
}
```

Complex target marker can be created by adding additional layers to the marker definition. The size of the fillColour disc is 1. Additional layers will be drawn in the order of their defintion in the layers entry. The key is the size of the disc as a fraction of 1. Larger target discs must be defined first or will otherwise be hidden underneath subsequently drawn layers.

## Themes

Cluster layers support categorized, graduated and competition themes. A theme must have a unique name as key in the themes object. The type of the theme must be defined in the theme entry.

**Theme styles are adaptive.** The marker and markerMulti definition will be augmented by the style elements in theme's categories (cat).

### **Categorized cluster theme**

```javascript
"Retailer": {
  "type": "categorized",
  "field": "retailer",
  "other": true,
  "cat": {
      "Tesco": {
          "label": "Tesco",
          "fillColor": "#0055a8",
          "layers": {
              "0.75": "#ffffff",
              "0.35": "#f02f26"
          }
      },
      "Sainsburys": {
          "label": "Sainsbury's",
          "fillColor": "#ee8a00",
          "layers": {
              "0.5": "#ffffff",
              "0.35": "#ee8a00"
          }
      },
      "Marks and Spencer": {
          "label": "Marks & Spencer",
          "fillColor": "#0a0d10",
          "layers": {
              "0.5": "#def036",
              "0.25": "#0a0d10"
          }
      }
  }
}  
```

A categorized theme requires as a minimum the type, field, and cat properties. The type is **categorized**. The **field** value must be a column in the PostGIS table which can be used to categorize a location. **cat** is an array like object which lists the different categories as key/value pairs. The key is used to identify the category of a location while the value defines the styling of the marker as well as the label which should be shown in the legend.

`"other": true`

The other entry will show a marker for values which do not match a category key in the theme's legend.

![](https://1429262937-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LMms4_qYZAl-8nd6vhU%2F-LRpw-wRFifpG_Qbcb0n%2F-LRq11K8OlHY7G-fSuVZ%2Fimage.png?alt=media\&token=defaec13-0788-49d4-83c7-fe6c75d40f90)

Entries (label) in the categorized theme legend can be used to filter the respective category.

![](https://1429262937-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LMms4_qYZAl-8nd6vhU%2F-LRpw-wRFifpG_Qbcb0n%2F-LRq2X-nijKrmre3_va-%2Fimage.png?alt=media\&token=3aca04df-5eb6-4197-9df5-4ff810b1358f)

### **Graduated cluster theme**

Cluster fall into a graduated theme category when their aggregated value is larger then the categories key (parsed) but smaller than the subsequent category's key (parsed).

```javascript
"Households": {
  "type": "graduated",
  "field": "hhdooc_11",
  "cat": {
      "0": {
          "label": "0 to 100",
          "fillColor": "#15773f"
      },
      "100": {
          "label": "100 to 250",
          "fillColor": "#66bd63"
      },
      "250": {
          "label": "250 to 500",
          "fillColor": "#a6d96a"
      },
      "500": {
          "label": "500 to 1000",
          "fillColor": "#d9ef8b"
      },
      "1000": {
          "label": "1000 to 2500",
          "fillColor": "#fdae61"
      },
      "2500": {
          "label": "2500 to 5000",
          "fillColor": "#f46d43"
      },
      "5000": {
          "label": "5000 or more",
          "fillColor": "#d73027"
      }
  }
```

Graduated categories can not be filtered from the legend.

![](https://1429262937-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LMms4_qYZAl-8nd6vhU%2F-LRpw-wRFifpG_Qbcb0n%2F-LRq3w_6gd7ZWp7ih7Jj%2Fimage.png?alt=media\&token=0833ac85-6458-447c-9d93-024325cf687e)

### Competition Theme

Competition themes allow to show the makeup of locations aggregated in individual cluster.

```javascript
"Tesco/Sainsbury's": {
  "type": "competition",
  "field": "retailer",
  "other": true,
  "cat": {
      "Tesco": {
          "label": "Tesco",
          "fillColor": "#0055a8"
      },
      "Sainsburys": {
          "label": "Sainsbury's",
          "fillColor": "#ee8a00"
      }
  }
}
```

The size of the competition layers in marker are defined by their respective size. A single colour cluster marker indicates that the whole cluster is made up of the same category. A cluster split 50/50 between two categories will have a base colour of one category and a target disc with a radius of 0.5 the size of the cluster to represent the second category.

![](https://1429262937-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LMms4_qYZAl-8nd6vhU%2F-LRpw-wRFifpG_Qbcb0n%2F-LRqK6PvHRM2B6s78M3B%2Fimage.png?alt=media\&token=28995e05-6b9c-4c19-88d5-7603bf20f28c)

The legend can be used to filter individual competition categories.

![](https://1429262937-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LMms4_qYZAl-8nd6vhU%2F-LRpw-wRFifpG_Qbcb0n%2F-LRqKFC5G2sWJ96iCj8q%2Fimage.png?alt=media\&token=5e94d374-0558-4b88-81ee-16ae2b3a24c0)

## Cluster size

By default cluster will be sized according to their count. The marker for a cluster with three locations will be bigger than a marker for a cluster with 2 locations. The size is linear to the size of the cluster with the highest count of locations.

It is possible to set the minimum and maximum size for cluster locations in the cluster panel.

![](https://1429262937-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LMms4_qYZAl-8nd6vhU%2F-LRpw-wRFifpG_Qbcb0n%2F-LRqLQiuQHyy0mMw7npN%2Fimage.png?alt=media\&token=a7cd7164-3ba1-4680-b3e0-26ae87b05130)

It is also possible to use a log scale instead of a linear scale to size cluster in relation to the largest cluster in the view.

![](https://1429262937-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LMms4_qYZAl-8nd6vhU%2F-LRpw-wRFifpG_Qbcb0n%2F-LRqM5TsM5tCzMC8N3MT%2Fimage.png?alt=media\&token=deac682d-01b1-4abc-91b3-ed742d33ee4c)

### Cluster size in themes

![](https://1429262937-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LMms4_qYZAl-8nd6vhU%2F-LRpw-wRFifpG_Qbcb0n%2F-LRqOX2AHpWU2M9pc6DO%2Fimage.png?alt=media\&token=7226dea6-b11e-4864-a2d9-c14b9f84ae10)

It is possible to define a size entry themes.

```
"Households": {
  "type": "graduated",
  "field": "hhdooc_11",
  "size": "hhdooc_11",
  "cat": {...}
}
```

The aggregated cluster value from the size field will then be used to determine the relative size of cluster.

![](https://1429262937-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LMms4_qYZAl-8nd6vhU%2F-LRpw-wRFifpG_Qbcb0n%2F-LRqPALoN0FgmWN2cN-q%2Fimage.png?alt=media\&token=f460ee5e-54a3-48f4-b89d-e7122e00dfd5)

