Relationship | ArcGIS Maps SDK for JavaScript

Item page

Sandbox

Download

Census tracts styled with a relationship renderer showing the geographic relationship between household size and home value.

What is a relationship style?

Also known as a bivariate choropleth map A choropleth map displays a set of pre-defined geographical areas proportionate to an aggregated summary of a specific, statistical variable within each area, such as the area's population density or per capita income. Learn more , you can use a relationship style to explore the potential relationship between two numeric attributes. It overlays two sequential color schemes, each associated with a range of values to color features based on how each variable is classified in relation to the other.

Keep in mind that even if you observe a positive relationship between the two variables of interest, it doesn’t mean they are statistically correlated. It also doesn’t imply that the presence of one variable influences the other. Therefore, this renderer should be used judiciously with some prior knowledge that two variables may likely be related.

How a relationship style works

This renderer classifies each variable in either 2, 3, or 4 classes along separate color ramps. One of those ramps is rotated 90 degrees and overlaid on the other to create a 2x2, 3x3, or 4x4 square grid. The x-axis indicates the range of values for one variable, and the y-axis indicates the range for the second variable. The squares running diagonal from the lower left corner to the upper right corner indicate features where the two variables may be related or in agreement with one another.

The legend of a relationship renderer resembles a grid of two single-hue sequential color ramps overlaid on each other, forming a third hue along a diagonal line, which indicates where the two variables could potentially be related.

relationship-legend

The lower right and upper left corners indicate features where one field has high values and the other field low values and vice versa.

Examples

3x3 grid

To create a relationship map, you need to request the renderer from the relationship Smart Mapping module.

Item page

Sandbox

Download

A 3x3 relationship color scheme compares average household size and home value across census tracts; expand the legend to interpret the result.

Relationship - 3x3 grid


20 collapsed lines
1
<!doctype html>
2
<html lang="en">
3
  <head>
4
    <meta charset="utf-8" />
5
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
6
    <title>Relationship - 3x3 grid</title>
7

8
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
9
    <script type="module" src="https://js.arcgis.com/5.2/"></script>
10

11
    <style>
12
      html,
13
      body {
14
        height: 100%;
15
        margin: 0;
16
      }
17
    </style>
18
  </head>
19

20
  <body>
21
    <arcgis-map item-id="3be6385d7200453eb377020b0df78a19">
22
      <arcgis-zoom slot="top-left"></arcgis-zoom>
23
      <arcgis-expand slot="top-right">
24
        <arcgis-legend></arcgis-legend>
25
      </arcgis-expand>
26
    </arcgis-map>
2 collapsed lines
27
  </body>
28
</html>

Sandbox

Download

A 3x3 relationship color scheme compares average household size and home value across census tracts; expand the legend to interpret the result.

Relationship - 3x3 grid


72 collapsed lines
1
<!doctype html>
2
<html>
3
  <head>
4
    <meta charset="utf-8" />
5
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
6
    <title>Relationship - 3x3 grid</title>
7

8
    <link rel="stylesheet" href="https://js.arcgis.com/5.2/esri/themes/light/main.css" />
9
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
10
    <script type="module" src="https://js.arcgis.com/5.2/"></script>
11

12
    <style>
13
      html,
14
      body {
15
        height: 100%;
16
        margin: 0;
17
      }
18
    </style>
19
  </head>
20

21
  <body>
22
    <arcgis-map center="-111.96688, 33.464339" scale="1155581">
23
      <arcgis-zoom slot="top-left"></arcgis-zoom>
24
      <arcgis-expand slot="top-right">
25
        <arcgis-legend></arcgis-legend>
26
      </arcgis-expand>
27
    </arcgis-map>
28

29
    <script type="module">
30
      const [WebMap, FeatureLayer, relationshipRendererCreator] = await $arcgis.import([
31
        "@arcgis/core/WebMap.js",
32
        "@arcgis/core/layers/FeatureLayer.js",
33
        "@arcgis/core/smartMapping/renderers/relationship.js",
34
      ]);
35

36
      const viewElement = document.querySelector("arcgis-map");
37

38
      const layer = new FeatureLayer({
39
        title: "Household size and home cost",
40
        portalItem: {
41
          id: "1cbb0faa0f1f424bbe213bfae9319309",
42
        },
43
        blendMode: "multiply",
44
        definitionExpression: "STATE = 'AZ'",
45
      });
46

47
      const map = new WebMap({
48
        layers: [layer],
49
        portalItem: {
50
          id: "9cf503b654144873a8e33f996f91ba1d",
51
        },
52
      });
53

54
      const referenceScale = 9244650 * 2;
55

56
      viewElement.map = map;
57
      // Set dock options on the view's popup
58
      viewElement.popup = {
59
        dockEnabled: true,
60
        dockOptions: {
61
          breakpoint: false,
62
        },
63
      };
64
      viewElement.constraints = {
65
        snapToZoom: false,
66
      };
67

68
      await viewElement.viewOnReady();
69

70
      layer.when().then(createRelationshipRenderer).then(applyRenderer);
71

72
      function createRelationshipRenderer() {
73
        const params = {
74
          layer: layer,
75
          view: viewElement.view,
76
          field1: {
77
            field: "AVGHHSZ_CY",
78
            label: "Household size",
79
          },
80
          field2: {
81
            field: "AVGVAL_CY",
82
            label: "Home value",
83
          },
84
          focus: null,
85
          numClasses: 3,
86
          outlineOptimizationEnabled: true,
87
        };
88

89
        return relationshipRendererCreator.createRenderer(params);
26 collapsed lines
90
      }
91

92
      function applyRenderer(response) {
93
        const renderer = response.renderer;
94

95
        renderer.uniqueValueInfos.forEach(function (info) {
96
          switch (info.value) {
97
            case "HH":
98
              info.label = "Larger households; Costlier homes";
99
              break;
100
            case "HL":
101
              info.label = "Larger households; Cheaper homes";
102
              break;
103
            case "LH":
104
              info.label = "Smaller households; Costlier homes";
105
              break;
106
            case "LL":
107
              info.label = "Smaller households; Cheaper homes";
108
              break;
109
          }
110
        });
111
        layer.renderer = renderer;
112
      }
113
    </script>
114
  </body>
115
</html>

API support

Full support

Partial support

No support
	2D	3D	Arcade	Points	Lines	Polygons	Mesh
Unique types
Class breaks
Visual variables							¹
Time
Multivariate
Predominance
Dot density
Charts
Relationship
Smart Mapping		²			³	³	³

Color only
Size variable creators only supported for points
Size variable creators not supported in 3D

Data-driven stylesCharts Data-driven stylesSmart Mapping

What is a relationship style?

How a relationship style works

Examples

3x3 grid

Related samples and resources

Generate a relationship visualization

Update legend text

Smart Mapping with Arcade: Exploring relationships

API support