require(["esri/smartMapping/statistics/summaryStatistics"], (summaryStatistics) => { /* code goes here */ });
import summaryStatistics from "@arcgis/core/smartMapping/statistics/summaryStatistics.js";
esri/smartMapping/statistics/summaryStatistics
Function for generating attribute statistics in a Layer based on values returned from a given field.
Known Limitations
- SceneLayers must have the
supportsRenderer
andsupportsLayerQuery
capabilities enabled unless a predefined statistics object is provided to thestatistics
parameter of the method. To check a SceneLayer's capabilities, use the getFieldInfoUsage() method. - You cannot generate statistics using SQL expressions for client-side FeatureLayers in a SceneView.
- The
normalizationType
parameter only normalizes data returned by afield
. It does not apply to values returned from avalueExpression
orsqlExpression
.
Method Overview
Name | Return Type | Summary | Function |
---|---|---|---|
Returns an object containing statistics describing a set of values returned from a field (or expression) in a Layer. | summaryStatistics |
Method Details
-
summaryStatistics
summaryStatistics(params){Promise<SummaryStatisticsResult>}
-
Returns an object containing statistics describing a set of values returned from a field (or expression) in a Layer.
ParametersSpecificationparams ObjectSee the table below for details of each parameter.
Specificationlayer FeatureLayer|SceneLayer|CSVLayer|PointCloudLayer|GeoJSONLayer|WFSLayer|OGCFeatureLayer|StreamLayer|OrientedImageryLayer|CatalogFootprintLayer|CatalogLayer|KnowledgeGraphSublayerThe layer from which to generate statistics for the given
field
.field StringoptionalThe 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 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.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.
normalizationType StringoptionalDetermines how the provided
field
values will be normalized. This parameter only normalizes data referenced by afield
, and does not apply to values returned from avalueExpression
orsqlExpression
. 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. AnormalizationField
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 StringoptionalThe field by which to normalize the values returned from the given
field
.normalizationTotal NumberoptionalOnly applies if
normalizationType
ispercent-of-total
. Indicates the total amount with which to normalize field values.minValue NumberoptionalThe minimum bounding value for the statistics calculation. Use this in conjunction with
maxValue
to generate statistics between lower and upper bounds.maxValue NumberoptionalThe maximum bounding value for the statistics calculation. Use this in conjunction with
minValue
to generate statistics between lower and upper bounds.view ViewoptionalA SceneView or MapView instance is required when a
valueExpression
is specified.filter FeatureFilteroptionalA feature filter used to filter statistic queries by geometry. This parameter is only used for filtering statistics by geometry. Any attribute filters set on the
FeatureFilter.where
property are ignored. Currently, only theintersects
spatial relationship is supported. This is useful if you already define a feature filter by geometry on your layer and want to calculate statistics for the included features. Since version 4.25.Deprecated since version 4.23. UseuseFeaturesInView
instead.A subset of features for which to calculate the statistics.
useFeaturesInView BooleanoptionalOnly applicable when the input
layer
is a service-backed FeatureLayer. Whentrue
, statistics will be calculated on the client from features visible in the view. Iffalse
, statistics will be requested from the service. Since version 4.23.forBinning BooleanoptionalIndicates 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 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<SummaryStatisticsResult> Returns a promise that resolves to SummaryStatisticsResult. ExamplessummaryStatistics({ 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
-
The statistics returned from the summaryStatistics() query.
- Properties
-
avg Number
The average of all values returned from the field or expression.
count NumberThe total number of features with a non-null value for the given field.
max NumberThe maximum of all values returned from the field or expression.
median NumberThe median of all values returned from the field or expression. Since version 4.22.
min NumberThe minimum of all values returned from the field or expression.
stddev NumberThe standard deviation calculated from values returned from the field or expression.
sum NumberThe sum of all values returned from the field or expression.
variance NumberThe calculated variance from all values returned from the field or expression.
nullcount NumberThe 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.