summaryStatistics | API Reference | ArcGIS Maps SDK for JavaScript 4.31

Method Overview

Name	Return Type	Summary	Function
	Promise<SummaryStatisticsResult>	Returns an object containing statistics describing a set of values returned from a field (or expression) in a Layer.	summaryStatistics

Method Details

summaryStatistics Method summaryStatistics(params){Promise<SummaryStatisticsResult>}

Returns an object containing statistics describing a set of values returned from a field (or expression) in a Layer.

Parameters

Specification

params Object

See the table below for details of each parameter.

Specification

The layer from which to generate statistics for the given field.

field String

optional

The name of the numeric or string field for which the summary statistics will be generated. This property is ignored if a valueExpression is used.

valueExpression String

optional

An 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 the field property and therefore is used instead of an input field value.

sqlExpression String

optional

A SQL expression evaluating to a number.

sqlWhere String

optional

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.

normalizationType String

optional

Determines how the provided field values will be normalized. This parameter only normalizes data referenced by a field, and does not apply to values returned from a valueExpression or sqlExpression. See the table below for a list of possible values.

Possible Value	Description
field	Divides the data value using the value of the field specified in the `normalizationField` parameter. A `normalizationField` must be provided if this value is used.
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.
log	Computes the base 10 logarithm of the data values. This can be a useful approach for viewing highly skewed data distributions because it reduces the influence of outliers. Only positive values are computed. You should avoid this normalization type if your data contains a significant number of negative values.
natural-log	Computes the natural logarithm of the data values. This can be a useful approach for viewing highly skewed data distributions because it reduces the influence of outliers. Only positive values are computed. You should avoid this normalization type if your data contains a significant number of negative values.
square-root	Computes the square root of the data values. This can be a useful approach for viewing highly skewed data distributions because it reduces the influence of outliers. Only positive values are computed. You should avoid this normalization type if your data contains a significant number of negative values.

Possible Values:"field"|"log"|"percent-of-total"|"natural-log"|"square-root"

normalizationField String

optional

The field by which to normalize the values returned from the given field.

normalizationTotal Number

optional

Only applies if normalizationType is percent-of-total. Indicates the total amount with which to normalize field values.

minValue Number

optional

The minimum bounding value for the statistics calculation. Use this in conjunction with maxValue to generate statistics between lower and upper bounds.

maxValue Number

optional

The maximum bounding value for the statistics calculation. Use this in conjunction with minValue to generate statistics between lower and upper bounds.

view View

optional

A SceneView or MapView instance is required when a valueExpression is specified.

outStatisticTypes Object

optional

Since 4.31 Indicates the statistics to calculate. If not defined, all statistics are calculated by default. The object should have the following properties.

Specification

include OutStatisticType []

optional

The statistics to include in the calculation.

exclude OutStatisticType []

optional

The statistics to exclude from the calculation. Some statistics, such as median, are computationally expensive to calculate and may be excluded to improve performance.

filter FeatureFilter

optional

Since 4.25 When defined, only features included in the filter are considered in the attribute and spatial statistics calculations when determining the final renderer. This is useful when a lot of variation exists in the data that could result in undesired data ranges. A common use case would be to set a filter that only includes features in the current extent of the view where the data is most likely to be viewed. Currently, only geometry filters with an intersects spatial relationship are supported. All other filter types (including where) are ignored.

features Graphic []

Deprecated since version 4.23. Use useFeaturesInView instead.

optional

A subset of features for which to calculate the statistics.

useFeaturesInView Boolean

optional

Only applicable when the input layer is a service-backed FeatureLayer. When true, statistics will be calculated on the client from features visible in the view. If false, statistics will be requested from the service. Since version 4.23.

forBinning Boolean

optional

Indicates whether the generated statistics are for a binning or clustering 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<SummaryStatisticsResult>	Returns a promise that resolves to SummaryStatisticsResult.

Examples

summaryStatistics({
  layer: featureLayer,
  valueExpression: "( ($feature.POP2020 - $feature.POP2010) / $feature.POP2010 ) * 100"
  view: mapView
}).then(function(stats){
  colorSlider.statistics = stats;
});

summaryStatistics({
  layer: featureLayer,
  field: "Population",
  normalizationType: "natural-log",
  sqlWhere: "Population > 0",
  numBins: 100
}).then(function(stats){
  histogramWidget.average = stats.avg;
});

Type Definitions

OutStatisticType Type Definition OutStatisticType String

The type of statistic to include or exclude in the summary statistics calculation.

SummaryStatisticsResult Type Definition SummaryStatisticsResult

The statistics returned from the summaryStatistics() query.

Properties: avg Number

The average of all values returned from the field or expression.

count Number

The total number of features with a non-null value for the given field.

max Number

The maximum of all values returned from the field or expression.

median Number

The median of all values returned from the field or expression. Since version 4.22.

min Number

The minimum of all values returned from the field or expression.

stddev Number

The standard deviation calculated from values returned from the field or expression.

sum Number

The sum of all values returned from the field or expression.

variance Number

The calculated variance from all values returned from the field or expression.

nullcount Number

optional
The number of null values stored in the given field. Only applies to summary statistics calculated with a field value at version 4.20 or later.