This object contains helper methods for generating data-driven visualizations with continuous size or class breaks based on a field value or expression from features in a Layer. The methods in this module generate renderer or visual variable objects that may be applied directly to a supported layer. The renderers specify how features should be visualized based on data values and sizes optimized based on the indicated basemap.

Known Limitations

Currently, 3D symbols can only be generated for layers with a point geometry type.

SceneLayers without the supportsRenderer and supportsLayerQuery capabilities enabled, unless a predefined statistics object is passed to the statistics 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.

This method generates an array of size visual variables with default stops that are optimally chosen based on the statistics queried for the indicated field or expression and mapped to appropriate sizes.

Method Details

Generates a continuous size Renderer representing the age of features based on one or more fields. The age of a feature is calculated based on a given startTime and endTime, one of which must be a date field in the input layer. This method generates an Arcade expression and calculates statistics on the output of the expression to accomplish this. The resulting renderer contains a continuous size visual variable that maps optimal sizes based on the indicated basemap to data values based on the resulting statistics of the expression.

You are required to provide a layer, view, startTime, and endTime to generate this renderer. Optionally, you can set a unit for the visualization. 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.

A statistics object generated from the summaryStatistics function. The createAgeRenderer() method generates an Arcade expression and executes a statistics query against the layer for the result of the expression. If statistics for the expression have already been generated, then pass the object here to avoid making a second statistics query.

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.

const layer = new FeatureLayer({
url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/311_Service_Requests_from_2015_50k/FeatureServer/0"
});
// visualization based age of incidents closed passed their due date// or the number of days an incident was overdue at the time of closure.const ageParams = {
layer: layer,
view: view,
basemap: map.basemap, // "gray"
startTime: "Due_Date",
endTime: "Closed_Date",
unit: "days"
};
// when the promise resolves, apply the renderer to the layer
sizeRendererCreator.createAgeRenderer(ageParams)
.then(function(response){
layer.renderer = response.renderer;
});

Generates a ClassBreaksRenderer that may be applied directly to the layer used to call this method. The resulting renderer defines the symbol size of each feature based on the value of the given field value. A default size scheme is determined based on the given basemap. Depending on the classificationMethod, class breaks (or data ranges) are generated based on the statistics of the data. Each feature is assigned a size based on the class break in which the value of the field falls.

In most cases you will provide a layer, basemap, field, and classificationMethod 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 sizes to use in the visualization. You can also use a valueExpression instead of a field 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.

The 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.

Indicates how the data is normalized. The data value obtained from the field is normalized in one of the following ways before it is compared with the class breaks. See the table below for a list of possible values.

Possible Value

Description

field

Divides the field value by the value of normalizationField. This value is set by default if the normalizationField is provided.

log

Computes the base 10 logarithm of the data value. This can be a useful approach for some data distributions because it reduces the influence of very large data values.

percent-of-total

Divides the data value by the sum of all data values then multiplies by 100. Use normalizationTotal to define the total value by which to normalize. This value is set by default if the normalizationTotal is provided.

With the exception of log normalization, data normalization creates a ratio by dividing two values. When comparing attribute values between features, normalization minimizes the effect of varying map areas and the number of observations. For example, dividing the 18 to 30 year old population by the area of a polygon feature yields a density value that can be compared evenly with other features, regardless of their size.

The classification method used for generating breaks. See the table below for a list of possible values.

Possible Value

Description

equal-interval

Divides the range of attribute values into equal-sized subranges. For example, if you specify three classes for a field whose values range from 0 to 300, this method will create three classes with ranges of 0–100, 101–200, and 201–300. Equal interval is best applied to familiar data ranges, such as percentages and temperature. This method emphasizes the amount of an attribute value relative to other values. For example, it could show if a store is part of the group of stores that make up the top one-third of all sales.

natural-breaks

Groups similar values that maximize the differences between classes. Features are divided into classes whose boundaries are set where there are relatively big differences in the data values. Natural breaks are data-specific classifications and not useful for comparing multiple maps built from different underlying information.

quantile

Assigns the same number of data values to each class. This is well suited to linearly distributed data. Because features are grouped in equal numbers in each class, the resulting map can often be misleading. Similar features can potentially be placed in adjacent classes, or features with widely different values can be put in the same class. You can minimize this distortion by increasing the number of classes.

standard-deviation

Creates class breaks with equal value ranges that are a proportion of the standard deviation. This is usually done at intervals of one, one-half, one-third, or one-fourth standard deviations from the mean.

An Arcade expression that returns a number. This expression can reference field values using the $feature global variable. This property overrides the field property and therefore is used instead of an input field value.

A 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.

The view instance in which the visualization will be rendered. A SceneView is required if symbolType = "3d-volumetric" or 3d-volumetric-uniform. The relevant SceneView or MapView is required when a valueExpression is specified.

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 sized uniformly, for example with spheres. A SceneView instance must be provided to the view parameter if this option is used.

Generates a Renderer that may be applied directly to the layer used to call this method. The renderer contains a continuous size visual variable that maps marker sizes to specific stop values based on queried statistics from the indicated field or expression.

In most cases you will provide a layer, basemap, and field 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 sizes to use in the visualization. You can also use a valueExpression instead of a field 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.

The 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.

An Arcade expression that returns a number. This expression can reference field values using the $feature global variable. This property overrides the field property and therefore is used instead of an input field value.

A 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.

A 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.

A 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 size visual variable.

The view instance in which the visualization will be rendered. A SceneView is required if symbolType = "3d-volumetric" or 3d-volumetric-uniform. The relevant SceneView or MapView is required when a valueExpression is specified.

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 sized uniformly, for example with spheres. A SceneView instance must be provided to the view parameter if this option is used.

This method generates an array of size visual variables with default stops that are optimally chosen based on the statistics queried for the indicated field or expression and mapped to appropriate sizes.

There are two different ways this method may be called. The most common case is by providing a layer, basemap, and field. This is the scenario where the statistics of the data aren't well known and the user doesn't know what sizes to use. You can optionally use a valueExpression 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 a sizeScheme if you don't want one picked for you. In this case the basemap and theme options would be ignored.

The resulting array of visual variables will contain exactly one size visual variable unless the axis parameter is set to "height".

The 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.

An Arcade expression that returns a number. This expression can reference field values using the $feature global variable. This property overrides the field property and therefore is used instead of an input field value.

A 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.

A 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.

A 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 size visual variable.

When set to all, a single size variable that scales uniformly in all dimensions is generated. When set to height, 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.

Indicates whether default values are 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.

Indicates whether default values are 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.

Indicates whether default values are 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.

Indicates 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.