require(["esri/smartMapping/renderers/univariateColorSize"], (colorAndSizeRendererCreator) => { /* code goes here */ });
import * as colorAndSizeRendererCreator from "@arcgis/core/smartMapping/renderers/univariateColorSize.js";
esri/smartMapping/renderers/univariateColorSize
This object contains helper methods for generating data-driven univariate visualizations using both continuous color and continuous size based on a single field value or expression from features in a Layer. The createContinuousRenderer() method generates a Renderer object that may be applied directly to a supported layer. This renderer contains a continuous color and size ramp with optimal colors based on the view's background and mapped to specific break values based on the statistics of the indicated field or expression.
Alternately, you can use the createVisualVariable() method to generate a color and a size visual variable with default stops and colors that are optimally chosen based on the statistics of the indicated field.
Since thematic size may be difficult to interpret on its own in 3D extrusions, adding a color ramp representing the same data helps effectively communicate the story of the visualization so it's more easily understood by the audience.
Known Limitations
- Currently 3D symbols can only be generated for layers with a
point
geometry type. - SceneLayers with
mesh
geometryType or SceneLayers without thesupportsRenderer
andsupportsLayerQuery
capabilities enabled are not supported unless a predefined statistics object is passed to thestatistics
parameter of the method in conjunction with the layer. To check a SceneLayer's capabilities, use the getFieldInfoUsage() method. - You cannot generate renderers and visual variables using SQL expressions for client-side FeatureLayers in a SceneView.
- See also
Method Overview
Name | Return Type | Summary | Object |
---|---|---|---|
Generates a Renderer that may be applied directly to a Layer. | univariateColorSize | ||
This method generates color and size visual variables, both based on the same given field or expression. | univariateColorSize |
Method Details
-
createContinuousRenderer
createContinuousRenderer(params){Promise<ContinuousRendererResult>}
-
Generates a Renderer that may be applied directly to a Layer. The renderer contains continuous color and size visual variables that map symbols with optimal colors and sizes based on the view's background to stop values based on summary statistics from the indicated field or expression.
In most cases you will provide a
layer
,basemap
,field
, andtheme
to generate this renderer. This is a scenario in which the statistics of the data aren't well known and the user doesn't know what colors and sizes to use in the visualization. You can also use avalueExpression
instead of afield
to visualize features based on a value returned from a script executed at runtime.The other options are provided for convenience for more involved custom visualization authoring applications. For example, if you already generated statistics in another operation, you can pass the statistics object to the
statistics
parameter to avoid making an extra call to the server.ParametersSpecificationparams ObjectSee the table below for details of each parameter that may be passed to this method.
Specificationlayer FeatureLayer|SceneLayer|CSVLayer|GeoJSONLayer|WFSLayer|OGCFeatureLayer|StreamLayer|OrientedImageryLayer|CatalogFootprintLayer|KnowledgeGraphSublayerThe layer for which the visual variable is generated.
view ViewoptionalThe view where the input layer is rendered. This method inspects the view's background (i.e. basemap, web map background, or view container) to determine optimal colors for the output renderer. This parameter should always be set in practice, but if not provided this method will assume the generated renderer will display on a light background. This parameter is required when creating renderers using a
valueExpression
or for renderers intended for display in a SceneView.field StringoptionalThe name of the field whose data will be queried for statistics and used for the basis of the data-driven visualization. This property is ignored if a
valueExpression
is used.normalizationField StringoptionalThe name of the field to normalize the values of the given
field
. Providing a normalization field helps minimize some visualization errors and standardizes the data so all features are visualized with minimal bias due to area differences or count variation. This option is commonly used when visualizing densities.valueExpression StringoptionalAn Arcade expression following the specification defined by the Arcade Visualization Profile. Expressions may reference field values using the
$feature
profile variable and must return a number. This property overrides thefield
property and therefore is used instead of an inputfield
value.valueExpressionTitle StringoptionalText describing the value returned from the
valueExpression
. This is used by the Legend widget.theme StringoptionalDefault Value: high-to-lowSets the size stops and colors based on meaningful data values. Since version 4.18.
Value Description high-to-low The max data value is assigned the max size and color. The min data value is assigned the min size and color. All other values are interpolated. above The max data value is assigned the max size and color. The average data value, or zero, is assigned the min size and color. All other values between the max data value and the average are interpolated. This is useful for mapping an increase in a variable over time, like an increase in population, or unemployment between two dates. below The min data value is assigned the max size and color. The average data value, or zero, is assigned the min size and color. All other values between the min data value and the average are interpolated. This is useful for mapping a decline in a variable over time, like a decrease in population, or unemployment between two dates. above-and-below The min and max data values are assigned the max size and color. The average data value, or zero, is assigned the min size and color. A diverging color ramp is used. All other values between the min and max data values and the average are interpolated. This is useful for mapping a value's change over time and rates. Possible Values:"high-to-low"|"above"|"below"|"above-and-below"
sqlExpression StringoptionalA SQL expression evaluating to a number.
sqlWhere StringoptionalA SQL where clause used to filter features for the statistics query. For example, this is useful in situations where you want to avoid dividing by zero as is the case with creating a predominance visualization.
statistics SummaryStatisticsResultoptionalA statistics object generated from the summaryStatistics function. If statistics for the field have already been generated, then pass the object here to avoid making a second statistics query to the server.
minValue NumberoptionalA custom minimum value set by the user. Use this in conjunction with
maxValue
to generate statistics between lower and upper bounds. This will be the lowest stop in the returned visual variables.maxValue NumberoptionalA custom maximum value set by the user. Use this in conjunction with
minValue
to generate statistics between lower and upper bounds. This will be the uppermost stop in the returned visual variables.defaultSymbolEnabled BooleanoptionalEnables the
defaultSymbol
on the renderer and assigns it to features with no value and features that do not fall within the configured data range.colorOptions ObjectoptionalOptions for configuring the color portion of the visualization.
SpecificationcolorScheme ColorSchemeoptionalIn authoring apps, the user may select a pre-defined color scheme. Pass the scheme object to this property to avoid getting one based on a
theme
and thebasemap
.isContinuous BooleanoptionalDefault Value: falseOnly applies to the
above-and-below
theme. iftrue
, adds a ColorVariable with a diverging color ramp to the renderer. Since version 4.18.sizeOptions ObjectoptionalOptions for configuring the size portion of the visualization.
SpecificationsizeScheme SizeSchemeoptionalIn authoring apps, the user may select a pre-defined size scheme. Pass the scheme object to this property to avoid getting one based on the view's background.
sizeOptimizationEnabled BooleanoptionalDefault Value: falseIndicates 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.symbolOptions ObjectoptionalOptions for setting symbols for the
above-and-below
theme. Since version 4.18.ParametersSpecificationsymbolStyle StringoptionalSets above and below symbols based on pre-defined named symbol pairs.
Possible Values:"caret"|"circle-caret"|"arrow"|"circle-arrow"|"plus-minus"|"circle-plus-minus"|"square"|"circle"|"triangle"|"happy-sad"|"thumb"
symbols ObjectoptionalAllows you to specify custom symbols in the
above-and-below
theme.legendOptions ObjectoptionalProvides options for configuring the Legend representing the renderer generated from this method. Since version 4.18.
symbolType StringoptionalDefault Value: 2dThe type of symbol to generate. This depends on the view in which you are working and the desired visualization. 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 and only the symbol's height should be variable, for example with cylinders. 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"
forBinning BooleanoptionalIndicates 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 thefeatureReduction
property of the layer.signal AbortSignaloptionalAllows for cancelable requests. If canceled, the promise will be rejected with an error named
AbortError
. See also AbortController.ReturnsType Description Promise<ContinuousRendererResult> Resolves to an instance of ContinuousRendererResult. Examplesconst layer = new FeatureLayer({ url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/counties_politics_poverty/FeatureServer/0" }); // color/size univariate visualization based on field and normalization field const params = { layer: layer, view: view, field: "POP_POVERTY", normalizationField: "TOTPOP_CY" }; // when the promise resolves, apply the renderer to the layer colorAndSizeRendererCreator.createContinuousRenderer(params) .then(function(response){ layer.renderer = response.renderer; });
const layer = new FeatureLayer({ url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/counties_politics_poverty/FeatureServer/0" }); // above-and-below visualization based off Arcade expression const params = { layer: layer, valueExpression: "(($feature.votes_2016 - $feature.votes_2012) / $feature.votes_2016) * 100", valueExpressionTitle: "Change in votes from 2012-2016", view: view, theme: "above-and-below", colorOptions: { isContinuous: false }, symbolOptions: { symbolStyle: "arrow" } }; // when the promise resolves, apply the renderer to the layer colorAndSizeRendererCreator.createContinuousRenderer(params) .then(function(response){ layer.renderer = response.renderer; });
-
createVisualVariables
createVisualVariables(params){Promise<VisualVariablesResult>}
-
This method generates color and size visual variables, both based on the same given field or expression. These visual variables are generated with default stops that are optimally chosen based on the statistics queried for the indicated field or expression and colors based on the view's background.
There are two different ways this method may be called. The most common case is by providing a
layer
,view
, andfield
. This is the scenario where the statistics of the data aren't well known and the user doesn't know what colors to use. You can optionally use avalueExpression
instead of a field to visualize features based on a numeric value returned from a script executed at runtime.The other options are provided for convenience for more involved custom visualization authoring applications. For example, if you already generated statistics in another operation, you can pass the object in the
statistics
parameter to avoid making an extra call to the server. You can also provide acolorScheme
and/or asizeScheme
if you don't want one picked for you. In this case thetheme
option would be ignored.The resulting array of visual variables will contain one color visual variable, and one or two size visual variables depending on the value of the
sizeOptions.axis
parameter.ParametersSpecificationparams ObjectInput parameters for generating color and size visual variables based on data returned from a given field or expression. See the table below for details of each parameter.
Specificationlayer FeatureLayer|SceneLayer|CSVLayer|GeoJSONLayer|WFSLayer|OGCFeatureLayer|StreamLayer|OrientedImageryLayer|CatalogFootprintLayer|KnowledgeGraphSublayerThe layer for which the visual variable is generated.
view ViewoptionalThe view where the input layer is rendered. This method inspects the view's background (i.e. basemap, web map background, or view container) to determine optimal colors for the output renderer. This parameter should always be set in practice, but if not provided this method will assume the generated renderer will display on a light background. This parameter is required when creating renderers using a
valueExpression
or for renderers intended for display in a SceneView.field StringoptionalThe name of the field whose data will be queried for statistics and used for the basis of the data-driven visualization. This property is ignored if a
valueExpression
is used.normalizationField StringoptionalThe name of the field to normalize the values of the given
field
. Providing a normalization field helps minimize some visualization errors and standardizes the data so all features are visualized with minimal bias due to area differences or count variation. This option is commonly used when visualizing densities.valueExpression StringoptionalAn Arcade expression following the specification defined by the Arcade Visualization Profile. Expressions may reference field values using the
$feature
profile variable and must return a number. This property overrides thefield
property and therefore is used instead of an inputfield
value.valueExpressionTitle StringoptionalText describing the value returned from the
valueExpression
. This is used by the Legend widget.theme StringoptionalDefault Value: high-to-lowSets the size stops and colors based on meaningful data values.
Value Description high-to-low The max data value is assigned the max size and color. The min data value is assigned the min size and color. All other values are interpolated. above The max data value is assigned the max size and color. The average data value, or zero, is assigned the min size and color. All other values between the max data value and the average are interpolated. This is useful for mapping an increase in a variable over time, like an increase in population, or unemployment between two dates. below The min data value is assigned the max size and color. The average data value, or zero, is assigned the min size and color. All other values between the min data value and the average are interpolated. This is useful for mapping a decline in a variable over time, like a decrease in population, or unemployment between two dates. above-and-below The min and max data values are assigned the max size and color. The average data value, or zero, is assigned the min size and color. A diverging color ramp is used. All other values between the min and max data values and the average are interpolated. This is useful for mapping a value's change over time and rates. Possible Values:"high-to-low"|"above"|"below"|"above-and-below"
sqlExpression StringoptionalA SQL expression evaluating to a number.
sqlWhere StringoptionalA SQL where clause used to filter features for the statistics query. For example, this is useful in situations where you want to avoid dividing by zero as is the case with creating a predominance visualization.
statistics SummaryStatisticsResultoptionalA statistics object generated from the summaryStatistics function. If statistics for the field have already been generated, then pass the object here to avoid making a second statistics query to the server.
minValue NumberoptionalA custom minimum value set by the user. Use this in conjunction with
maxValue
to generate statistics between lower and upper bounds. This will be the lowest stop in the returned visual variables.maxValue NumberoptionalA custom maximum value set by the user. Use this in conjunction with
minValue
to generate statistics between lower and upper bounds. This will be the uppermost stop in the returned visual variables.colorOptions ObjectoptionalOptions for configuring the color portion of the visualization.
Specificationtheme StringoptionalDefault Value: high-to-lowDetermines which values will be emphasized in the continuous ramp and the map. Possible values are listed below.
Value Description Example high-to-low High values are emphasized with strong colors. above-and-below Values centered around a given point (e.g. the average) are visualized with weak colors while other values are emphasized with strong colors. centered-on Values centered around a given point (e.g. the average) are emphasized with strong colors while other values are visualized with weak colors. extremes High and low values are emphasized with strong colors. All others are visualized with weak colors. Possible Values:"high-to-low"|"above-and-below"|"centered-on"|"extremes"
colorScheme ColorSchemeoptionalIn authoring apps, the user may select a pre-defined color scheme. Pass the scheme object to this property to avoid getting one based on a
theme
and theview
.legendOptions ObjectoptionalProvides options for setting a title to a field when an expression is provided instead of a field name. This title will represent the field in the Legend.
isContinuous BooleanoptionalDefault Value: trueOnly applies to the
above-and-below
theme. iftrue
, adds a ColorVariable with a diverging color ramp to the renderer.sizeOptions ObjectoptionalOptions for configuring the size portion of the visualization.
Specificationaxis StringoptionalDefault Value: allWhen set to
all
, a single size variable that scales uniformly in all dimensions is generated. When set toheight
, the result contains two size visual variables: the first one sizes the height according to the field statistics, while the second defines a constant size for width and depth.Possible Values:"all"|"height"
sizeScheme SizeSchemeoptionalIn authoring apps, the user may select a pre-defined size scheme. Pass the scheme object to this property to avoid getting one based on the view's background.
legendOptions ObjectoptionalProvides options for setting a title to a field when an expression is provided instead of a field name. This title will represent the field in the Legend.
worldScale BooleanoptionalIndicates if the size units of the symbols will be in meters. This should be
true
when generating visualizations with 3D volumetric symbology. Aview
must be provided if this property is set totrue
.forBinning BooleanoptionalIndicates 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 thefeatureReduction
property of the layer.signal AbortSignaloptionalAllows for cancelable requests. If canceled, the promise will be rejected with an error named
AbortError
. See also AbortController.ReturnsType Description Promise<VisualVariablesResult> Resolves to an instance of VisualVariablesResult. Examplesconst layer = new FeatureLayer({ url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/counties_politics_poverty/FeatureServer/0" }); // color/size univariate visualization based on field and normalization field const params = { layer: layer, view: view, field: "POP_POVERTY", normalizationField: "TOTPOP_CY", theme: "above" }; // when the promise resolves, apply the visual variables to the renderer colorAndSizeRendererCreator.createVisualVariables(params) .then(function(response){ const renderer = layer.renderer.clone(); renderer.visualVariables = [ response.color.visualVariable, ...response.size.visualVariables ]; layer.renderer = renderer; });
const layer = new FeatureLayer({ url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/counties_politics_poverty/FeatureServer/0" }); // visualization based off an Arcade expression const params = { layer: layer, view: view, valueExpression: "($feature.POP_POVERTY / $feature.TOTPOP_CY) * 100", sqlExpression: "( POP_POVERTY / TOTPOP_CY ) * 100" }; // when the promise resolves, apply the visual variables to the renderer colorAndSizeRendererCreator.createVisualVariables(params) .then(function(response){ const renderer = layer.renderer.clone(); renderer.visualVariables = [ response.color.visualVariable, ...response.size.visualVariables ]; layer.renderer = renderer; });
Type Definitions
-
The result object of the createContinuousRenderer() method. See the table below for details of each property.
- Properties
-
renderer ClassBreaksRenderer
The renderer object configured to best match the view's background and the spread of the data. Set this on a layer's
renderer
property to update its visualization.color ObjectObject containing visual variable and scheme information for the color portion of the visualization.
- Specification
-
visualVariable ColorVariable
A color visual variable configured based on the statistics of the data and the color scheme.
colorScheme ColorSchemeThe color scheme used by the visual variable.
size ObjectObject containing visual variable and scheme information for the size portion of the visualization.
- Specification
-
visualVariables SizeVariable[]
The size visual variable(s) configured based on the statistics of the data and the view scale.
sizeScheme SizeSchemeThe size scheme used by the visual variable.
defaultValuesUsed BooleanIndicates whether default values were used in the absence of sufficient data and/or statistics from the layer. Default values are typically used when all features have the same field value or no value at all.
statistics SummaryStatisticsResultBasic statistics returned from a query to the service for the given field or expression.
basemapId StringThe ID of the basemap used to determine the optimal fill color of the features.
basemapTheme StringIndicates whether the average color of the input view's basemap is
light
ordark
.
-
The result object of the createVisualVariables() method. See the table below for details of each property.
- Properties
-
color Object
Object containing visual variable and scheme information for the color portion of the visualization.
- Specification
-
visualVariable ColorVariable
A color visual variable configured based on the statistics of the data and the color scheme.
colorScheme ColorSchemeThe color scheme used by the visual variable.
size ObjectObject containing visual variable and scheme information for the size portion of the visualization.
- Specification
-
visualVariables SizeVariable[]
The size visual variable(s) configured based on the statistics of the data and the view scale.
sizeScheme SizeSchemeThe size scheme used by the visual variable.
defaultValuesUsed BooleanIndicates whether default values were used in the absence of sufficient data and/or statistics from the layer. Default values are typically used when all features have the same field value or no value at all.
statistics SummaryStatisticsResultBasic statistics returned from a query to the service for the given field or expression.
basemapId StringThe ID of the basemap used to determine the optimal fill color of the features.
basemapTheme StringIndicates whether the average color of the input view's basemap is
light
ordark
.authoringInfo AuthoringInfoAuthoring information related to the creation of the visual variables. This includes inforamation related to UI inputs from sliders and selected themes.