relationship

Method Overview

Method Details

createRenderer(params){Promise<RendererResult>}

Generates a relationship renderer (bivariate choropleth) based on a set of competing numeric fields.

Each feature's category is determined based on the result of an Arcade expression generated internally by this method. You are required provide a layer, view, field1 name, and field2 name to generate this renderer. Optionally, you can set the focus to change the rotation of the legend and the numClasses parameter to change the grid size of the legend.

Other options are provided for convenience for more involved custom visualization authoring applications.

Parameters

Specification

params Object Input parameters for generating a relationship visualization based on a pair of numeric field(s). See the table below for details of each parameter. Specification layer FeatureLayer|SceneLayer|CSVLayer|GeoJSONLayer|WFSLayer|OGCFeatureLayer The layer for which the visualization is generated. view View The view instance in which the visualization will be rendered. field1 Object A numeric field that will be used to explore its relationship with field2. In the default visualization, the values of this field are rendered along the vertical axis of the Legend. Specification field String The name of a numeric field. normalizationField String optional The name of a numeric field used to normalize the given field. In choropleth visualizations it is best practice to normalize your data values if they haven't already been normalized. maxValue Number optional The maximum bound of values to visualize in the given field. If a feature's value is greater than this value, then it will be assigned the default symbol of the renderer. minValue Number optional The minimum bound of values to visualize in the given field. If a feature's value is less than this value, then it will be assigned the default symbol of the renderer. label String optional The label used to describe the field or variable in the legend. field2 Object A numeric field that will be used to explore its relationship with field1. In the default visualization, the values of this field are rendered along the horizontal axis of the Legend. Specification field String The name of a numeric field. normalizationField String optional The name of a numeric field used to normalize the given field. In choropleth visualizations it is best practice to normalize your data values if they haven't already been normalized. maxValue Number optional The maximum bound of values to visualize in the given field. If a feature's value is greater than this value, then it will be assigned the default symbol of the renderer. minValue Number optional The minimum bound of values to visualize in the given field. If a feature's value is less than this value, then it will be assigned the default symbol of the renderer. label String optional The label used to describe the field or variable in the legend. classificationMethod String optional Default Value: quantile The method for classifying each field's data values. See classBreaks for more information about each classification type. Possible Values:"quantile"|"equal-interval"|"natural-breaks" focus String optional Default Value: null Determines the orientation of the Legend. This value does not change the renderer or symbology of any features in the layer. This affects the legend only. See the table below for a description of the possible values. See the class description at the top of this page for a more thorough explanation of how to read the legend. Value Example Description null The legend renders as a square. The top right corner of the legend indicates that values from both field1 and field2 are considered high. HH The legend renders as a diamond with the focus on the top corner where values from both field1 and field2 are considered high. HL The legend renders as a diamond with the focus on the top corner where values from field1 are high and values from field2 are low. LH The legend renders as a diamond with the focus on the top corner where values from field1 are low and values from field2 are high. LL The legend renders as a diamond with the focus on the top corner where values from both field1 and field2 are considered low. numClasses Number optional Default Value: 3 Indicates the number of classes by which to break up the values of each field. More classes give you more detail, but more colors, making the visualization more difficult to understand. There are only three possible values. 2 classes 3 classes 4 classes Possible Values: 2 | 3 | 4 outlineOptimizationEnabled Boolean optional Default Value: false For polygon layers only. Indicates whether the polygon outline width should vary based on view scale. When set, a valid MapView instance must be provided in the view parameter. This option is not supported for 3D SceneViews. sizeOptimizationEnabled Boolean optional Default Value: false For point and polyline layers only. Indicates whether symbol sizes should vary based on view scale. When set, a valid MapView instance must be provided in the view parameter. This option is not supported for 3D SceneViews. legendOptions Object optional Provides options for modifying Legend properties describing the visualization. Specification title String optional The title used to describe the renderer in the Legend. showLegend Boolean optional Indicates whether to include the renderer in the legend. relationshipScheme RelationshipScheme optional In authoring apps, the user may select a pre-defined relationship scheme. Pass the scheme object to this property to avoid getting one based on the background of the view. symbolType String optional Default Value: 2d The type of symbol to generate. This depends on the view in which you are working and the desired visualization. This parameter does not need to be specified for layers with a mesh geometry type. Possible values are described below. Value Description 2d Generates a visualization using 2D symbols such as SimpleMarkerSymbol, SimpleLineSymbol, or SimpleFillSymbol. Use this option if generating a visualization for data in a MapView. 3d-flat Generates a visualization using 3D symbols with flat symbol layers such as IconSymbol3DLayer, LineSymbol3DLayer, or FillSymbol3DLayer. Use this option if generating a 2D visualization for data in a SceneView. 3d-volumetric Generates a visualization using 3D symbols with volumetric symbol layers such as ObjectSymbol3DLayer, PathSymbol3DLayer, or ExtrudeSymbol3DLayer. Use this option if generating a 3D visualization for data in a SceneView. A SceneView instance must be provided to the view parameter if this option is used. 3d-volumetric-uniform Generates a visualization using uniformly sized 3D symbols with volumetric symbol layers. Use this option if generating a 3D visualization for data in a SceneView and the symbol should be sizes uniformly, for example with spheres. A SceneView instance must be provided to the view parameter if this option is used. Possible Values:"2d"|"3d-flat"|"3d-volumetric"|"3d-volumetric-uniform" defaultSymbolEnabled Boolean optional Default Value: true Enables the defaultSymbol on the renderer and assigns it to features with no value or that fall outside of the prescribed class breaks. colorMixMode String optional Default Value: replace This option only applies to generating renderers for mesh SceneLayers. Specifies how the symbol's color is applied to the geometry color/texture. See the documentation in FillSymbol3DLayer.material for more context. See the table below for possible values. Value Description tint Applies the symbol color to the desaturated geometry/texture color. replace Removes the geometry/texture color and applies the symbol color. multiply Multiplies geometry/texture color value with the symbol color value. The result is a darker color. Multiplying with white keeps the geometry color the same. forBinning Boolean optional Indicates whether the generated renderer is for a binning visualization. If true, then the input field(s) in this method should refer to aggregate fields defined in the featureReduction property of the layer. signal AbortSignal optional Allows for cancelable requests. If canceled, the promise will be rejected with an error named AbortError. See also AbortController.

Returns

Type	Description
Promise<RendererResult>	Resolves to an instance of RendererResult.

Example

const layer = new FeatureLayer({
  url: "https://services.arcgis.com/..."
});

// will create a bivariate choropleth visualization exploring the relationship
// between the % of the population classified as obese, and the %
// of the population diagnosed with diabetes

const params = {
  layer: layer,
  view: view,
  field1: {
    field: "POP_Diabetes",
    normalizationField: "TOTAL_POP"
  },
  field2: {
    field: "POP_Obesity",
    normalizationField: "TOTAL_POP"
  },
  focus: "HH",
  defaultSymbolEnabled: false
};

// when the promise resolves, apply the renderer to the layer
relationshipRendererCreator.createRenderer(params)
  .then(function(response){
    layer.renderer = response.renderer;
  });

updateRenderer(params){Promise<UniqueValueRenderer>}

Updates a relationship renderer (bivariate choropleth) generated from createRenderer() based on the given input parameters.

Parameters

Specification

params Object Input parameters for updating a relationship visualization created in createRenderer(). Specification field1 Object A numeric field used to explore its relationship with field2. In the default visualization, the values of this field are rendered along the vertical axis of the Legend. Specification field String The name of a numeric field. normalizationField String optional The name of a numeric field used to normalize the given field. In choropleth visualizations it is best practice to normalize your data values if they haven't already been normalized. classBreakInfos ClassBreak[] The class breaks for the first field used in the relationship visualization. label String optional The label used to describe the field or variable in the legend. field2 Object A numeric field used to explore its relationship with field1. In the default visualization, the values of this field are rendered along the horizontal axis of the Legend. Specification field String The name of a numeric field. normalizationField String optional The name of a numeric field used to normalize the given field. In choropleth visualizations it is best practice to normalize your data values if they haven't already been normalized. classBreakInfos ClassBreak[] The class breaks for the second field used in the relationship visualization. label String optional The label used to describe the field or variable in the legend. focus String optional Default Value: null Determines the orientation of the Legend. This value does not change the renderer or symbology of any features in the layer. This affects the legend only. See the table below for a description of the possible values. See the class description at the top of this page for a more thorough explanation of how to read the legend. Value Example Description null The legend renders as a square. The top right corner of the legend indicates that values from both field1 and field2 are considered high. HH The legend renders as a diamond with the focus on the top corner where values from both field1 and field2 are considered high. HL The legend renders as a diamond with the focus on the top corner where values from field1 are high and values from field2 are low. LH The legend renders as a diamond with the focus on the top corner where values from field1 are low and values from field2 are high. LL The legend renders as a diamond with the focus on the top corner where values from both field1 and field2 are considered low. numClasses Number Indicates the number of classes by which to break up the values of each field. More classes give you more detail, but more colors, making the visualization more difficult to understand. There are only three possible values. 2 classes 3 classes 4 classes Possible Values: 2 | 3 | 4 colors Color[] The array of colors to be used by the symbols in the uniqueValueInfos of the renderer. renderer UniqueValueRenderer The relationship renderer (generated from createRenderer()) to update with the other parameters provided in this method.

Returns

Type	Description
Promise<UniqueValueRenderer>	Resolves to the updated relationship renderer.

Type Definitions

RendererResult

The result object of the createRenderer() method. See the table below for details of each property.

Properties

renderer UniqueValueRenderer The renderer object representing the relationship visualization. Set this on a layer's renderer property to update its visualization.

classBreaks Object Describes each class break for both fields considered in the relationship visualization. Specification field1 ClassBreaksResult The class breaks generated for values in the field1 parameter. field2 ClassBreaksResult The class breaks generated for values in the field2 parameter.

uniqueValueInfos UniqueValueInfo[] Describes each container or bin used in the visualization. Each unique value info object describes a class break for field1 and field2. Therefore, features with the same color fall share will have values that fall in the same class break for field1 and the same class break for field2.

relationshipScheme RelationshipScheme The relationship scheme used by the renderer.

basemapId String The ID of the basemap used to determine the optimal fill colors of the features.

basemapTheme String Indicates whether the average color of the input view's basemap is light or dark.