Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: FeatureLayerStatistics

require(["esri/plugins/FeatureLayerStatistics"], function(FeatureLayerStatistics) { /* code goes here */ });

Description

(Added at v3.13)
This module defines a class and a feature layer plugin that is used to calculate feature layer statistics. The return value of this module is a class, but the class has static functions that allows it to be added as a plugin to a feature layer. When this module is added as a plugin, it adds an instance of the class as a new property to the feature layer called stats.
require([ "esri/layers/FeatureLayer" ], function(FeatureLayer) {

  var featureLayer = new FeatureLayer("//services.arcgis.com/V6ZHFr6zdgNZuVG0/ArcGIS/rest/services/USA_Counties/FeatureServer/0");

  featureLayer
    .addPlugin("esri/plugins/FeatureLayerStatistics")
    .then(function() {
      featureLayer
        .statisticsPlugin
        .getUniqueValues({ field: "STATE_NAME" })
        .then(function(result) {
          console.log("Unique values: ", result.uniqueValueInfos);
        });
    });
});

Samples

Search for samples that use this class.

Constructors

NameSummary
new FeatureLayerStatistics(params)Creates a new object that is used to calculate statistics about features in a feature layer.

Methods

NameReturn typeSummary
add(layer, options?)NoneThis function is called internally when the plugin is added to a feature layer.
getClassBreaks(params)PromiseCalculate class breaks for data stored in the given field.
getFieldStatistics(params)PromiseCalculate basic statistics for data stored in the given field.
getHeatmapStatistics(options?)PromiseCalculate heatmap statistics.
getHistogram(params)PromiseCalculate histogram for data stored in the given field.
getSampleFeatures(options?)PromiseGet a random sampling of features in this layer.
getSpatialStatistics(params)PromiseReturns a promise that resolves to an object containing spatial statistics for an array of input features.
getSuggestedScaleRange(options?)PromiseFind optimal scale range for viewing this layer.
getUniqueValues(params)PromiseFind unique values available for the given field.
remove(layer)NoneThis function is called internally when the plugin is removed from a feature layer.
Constructor Details

new FeatureLayerStatistics(params)

Creates a new object that is used to calculate statistics about features in a feature layer.
Parameters:
<Object> params Required Parameters that define the FeatureLayerStatistics. See params table below for details.
params properties:
<FeatureLayer> layer Required The feature layer that will be the source for calculating statistics.
Sample:
require(["esri/layers/FeatureLayer","esri/plugins/FeatureLayerStatistics"], 
  function(FeatureLayer, FeatureLayerStatistics) {

    var featureLayer = new FeatureLayer("//services.arcgis.com/V6ZHFr6zdgNZuVG0/ArcGIS/rest/services/USA_Counties/FeatureServer/0");

    var featureLayerStats = new FeatureLayerStatistics({ layer: featureLayer });

    featureLayerStats
      .getUniqueValues({ field: "STATE_NAME" })
      .then(function(result) {
        console.log("Unique values: ", result.uniqueValueInfos);
      });
  });
Method Details

add(layer, options?)

This function is called internally when the plugin is added to a feature layer.

Note: This is a static method.

Parameters:
<FeatureLayer> layer Required The target FeatureLayer that have the plugin added.
<Object> options Optional Additional options that will be passed into the FeatureLayerStatistics constructor when it is added as a plugin to the target FeatureLayer.

getClassBreaks(params)

Calculate class breaks for data stored in the given field. See the Object Specifications table below for the structure of the params object and Promise.
Return type: Promise
Parameters:
<Object> params Required See the Object Specifications table below for the structure of the params object.
Object Specifications:
<params>
<String> classificationMethod Optional Indicates the classification method used to create the class breaks. The following methods are supported: equal-interval, natural-breaks, quantile and standard-deviation. Default is equal-interval.
<String> field Required Name of the attribute field.
<String> normalizationField Optional Name of the attribute field used to normalize the data. Applicable only when normalizationType is field.
<String> normalizationType Optional Indicates how data values are normalized. The following types are supported: field, log, percent-of-total. When normalized using a field, you need to specify normalizationField.
<Number> numClasses Optional Number of class breaks. Ignored when classificationMethod is standard-deviation. Default is 5.
<Number> standardDeviationInterval Optional Standard deviation interval. The following values are supported: 1, 0.5, 0.33 and 0.25. Applicable only when classificationMethod is standard-deviation.
<String> valueExpression Optional An Arcade expression evaluating to a number. This expression can reference field values using the $feature global variable and perform mathematical calculations and logical evaluations at runtime. The class breaks returned from this method are generated from the values returned from the Arcade expression. When a valueExpression is provided the field option is not needed.
<Promise>
<Object[]> classBreakInfos An array of objects each describing a class break. Each object will have the following properties: minValue, maxValue. Additionally, the following properties are available when classificationMethod is standard-deviation: minStdDev, maxStdDev and hasAvg.
<Number> maxValue Maximum value used for class breaks.
<Number> minValue Minimum value used for class breaks.
<Number> normalizationTotal Sum of all data values used to normalize data. Available only when normalizationType is percent-of-total.
<Boolean> partialData Indicates that statistics were generated for a subset, or sampling, of features on the client rather than queried against the service.
Sample:
require([
  "esri/layers/FeatureLayer",
  "esri/plugins/FeatureLayerStatistics",
  "dojo/domReady!"
], function (FeatureLayer, FeatureLayerStatistics){

  var featureLayer = new FeatureLayer("//services.arcgis.com/V6ZHFr6zdgNZuVG0/ArcGIS/rest/services/USA_Counties/FeatureServer/0");
  var featureLayerStats = new FeatureLayerStatistics({layer: featureLayer});
  var featureLayerStatsParams = {field: "AGE_5_17"};

  featureLayerStats.getClassBreaks(featureLayerStatsParams).then(function (result){
    console.log("Successfully calculated %s for field %s, %o", "class breaks", featureLayerStatsParams["field"], result);
  }).otherwise(function (error){
    console.log("An error occurred while calculating %s, Error: %o", "class breaks", error);
  });

});

getFieldStatistics(params)

Calculate basic statistics for data stored in the given field. The following statistics are supported: min, max, count, sum, avg, stddev, variance. See the Object Specifications table below for the structure of the params object and Promise.
Return type: Promise
Parameters:
<Object> params Required See the Object Specifications table below for the structure of the params object.
Object Specifications:
<params>
<String> field Required Name of the attribute field.
<String> sqlExpression Optional A SQL expression evaluating to a number. When a sqlExpression is provided, an equivalent valueExpression is required and the field option is not needed. The logic of the valueExpression must match the logic of the sqlExpression.
<String> sqlWhere 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.
<String> valueExpression Optional An Arcade expression evaluating to a number. This expression can reference field values using the $feature global variable and perform mathematical calculations and logical evaluations at runtime. The statistics returned from this method are generated from the values returned from this Arcade expression. When a valueExpression is provided the field option is not needed.
<Promise>
<Number> avg The average of all the values contained in the attribute field.
<Number> count The number of records associated with the attribute field.
<Number> max The maximum value contained in the attribute field.
<Number> min The minimum value contained in the attribute field.
<Boolean> partialData Indicates that statistics were generated for a subset, or sampling, of features on the client.
<Number> stddev The standard deviation of the values contained in the attribute field. A statistical measure of the spread of values from their mean, calculated as the square root of the sum of the squared deviations from the mean value, divided by the number of elements minus one. The standard deviation for a distribution is the square root of the variance.
<Number> sum The sum of all the values contained in the attribute field.
<Number> variance The variance of the values contained in the attribute field. A numeric description of how values in a distribution vary or deviate from the mean. The larger the variance, the greater the dispersion of values around the mean. The standard deviation for a distribution is the square root of the variance.
Sample:
require([
  "esri/layers/FeatureLayer",
  "esri/plugins/FeatureLayerStatistics",
  "dojo/domReady!"
], function (FeatureLayer, FeatureLayerStatistics){

  var featureLayer = new FeatureLayer("//services.arcgis.com/V6ZHFr6zdgNZuVG0/ArcGIS/rest/services/USA_Counties/FeatureServer/0");
  var featureLayerStats = new FeatureLayerStatistics({layer: featureLayer});
  var featureLayerStatsParams = {field: "AGE_5_17"};

  featureLayerStats.getFieldStatistics(featureLayerStatsParams).then(function (result){
    console.log("Successfully calculated %s for field %s, %o", "field statistics", featureLayerStatsParams["field"], result);
  }).otherwise(function (error){
    console.log("An error occurred while calculating %s, Error: %o", "field statistics", error);
  });

});

getHeatmapStatistics(options?)

Calculate heatmap statistics. The following statistics are supported: min, max, avg, stddev. See the Object Specifications table below for the structure of the params object and Promise.
Return type: Promise
Parameters:
<Object> options Optional See the Object Specifications table below for the structure of the options object.
Object Specifications:
<options>
<Number> blurRadius Optional Radius (in pixels) around each point over which the majority of the intensity value calculated for that point is spread out. Default is 10.
<String> field Optional Name of the attribute field used to calculate the weighted intensity of each point. When an attribute field is not specified, each point will have the same intensity value.
<Promise>
<Number> avg The average of all the values contained in the attribute field.
<Number> max The maximum value contained in the attribute field.
<Number> min The minimum value contained in the attribute field.
<Number> stddev The standard deviation of the values contained in the attribute field. A statistical measure of the spread of values from their mean, calculated as the square root of the sum of the squared deviations from the mean value, divided by the number of elements minus one. The standard deviation for a distribution is the square root of the variance.
Sample:
require([
  "esri/layers/FeatureLayer",
  "esri/plugins/FeatureLayerStatistics",
  "dojo/domReady!"
], function (FeatureLayer, FeatureLayerStatistics){

  var featureLayer = new FeatureLayer("//services.arcgis.com/V6ZHFr6zdgNZuVG0/ArcGIS/rest/services/USA_Counties/FeatureServer/0");
  var featureLayerStats = new FeatureLayerStatistics({layer: featureLayer});
  var featureLayerStatsParams = {field: "AGE_5_17"};

  featureLayerStats.getHeatmapStatistics(featureLayerStatsParams).then(function (result){
    console.log("Successfully calculated %s for field %s, %o", "heatmap statistics", featureLayerStatsParams["field"], result);
  }).otherwise(function (error){
    console.log("An error occurred while calculating %s, Error: %o", "heatmap statistics", error);
  });

});

getHistogram(params)

Calculate histogram for data stored in the given field. See the Object Specifications table below for the structure of the params object and Promise.
Return type: Promise
Parameters:
<Object> params Required See the Object Specifications table below for the structure of the params object.
Object Specifications:
<params>
<String> classificationMethod Optional Indicates the classification method used to divide the range of values into bins. The following methods are supported: equal-interval, natural-breaks, quantile and standard-deviation. Default is equal-interval.
<String> field Required Name of the attribute field.
<String> normalizationField Optional Name of the attribute field used to normalize the data. Applicable only when normalizationType is field.
<String> normalizationType Optional Indicates how data values are normalized. The following types are supported: field, log, percent-of-total. When normalized using a field, you need to specify normalizationField.
<Number> numBins Optional Number of bins in the histogram. Ignored when classificationMethod is standard-deviation. Default is 10.
<String> sqlExpression Optional A SQL expression evaluating to a number. When a sqlExpression is provided, an equivalent valueExpression is required and the field option is not needed. The logic of the valueExpression must match the logic of the sqlExpression.
<String> sqlWhere Optional A SQL where clause used to filter features in the histogram. For example, this is useful in situations where you want to avoid dividing by zero as is the case with creating a predominance visualization.
<Number> standardDeviationInterval Optional Standard deviation interval. The following values are supported: 1, 0.5, 0.33 and 0.25. Applicable only when classificationMethod is standard-deviation.
<String> valueExpression Optional An Arcade expression evaluating to a number. This expression can reference field values using the $feature global variable and perform mathematical calculations and logical evaluations at runtime. The values returned from this expression are the data used to create the histogram. When a valueExpression is provided the field option is not needed.
<Promise>
<Object[]> bins Bins in the histogram. It contains the number of features that fall into each of the disjoint categories in the histogram. It is an array objects where each object has the following properties: count, minValue, maxValue.
<Number> maxValue Maximum value captured by the histogram.
<Number> minValue Minimum value captured by the histogram.
<Number> normalizationTotal Sum of all data values used to normalize data. Available only when normalizationType is percent-of-total.
<Boolean> partialData Indicates that statistics were generated for a subset, or sampling, of features on the client.
Sample:
require([
  "esri/layers/FeatureLayer",
  "esri/plugins/FeatureLayerStatistics",
  "dojo/domReady!"
], function (FeatureLayer, FeatureLayerStatistics){

  var featureLayer = new FeatureLayer("//services.arcgis.com/V6ZHFr6zdgNZuVG0/ArcGIS/rest/services/USA_Counties/FeatureServer/0");
  var featureLayerStats = new FeatureLayerStatistics({layer: featureLayer});
  var featureLayerStatsParams = {field: "AGE_5_17"};

  featureLayerStats.getHistogram(featureLayerStatsParams).then(function (result){
    console.log("Successfully calculated %s for field %s, %o", "the histogram", featureLayerStatsParams["field"], result);
  }).otherwise(function (error){
    console.log("An error occurred while calculating %s, Error: %o", "the histogram", error);
  });

});

getSampleFeatures(options?)

Get a random sampling of features in this layer. See the Object Specifications table below for the structure of the params object and Promise.
Return type: Promise
Parameters:
<Object> options Optional See the Object Specifications table below for the structure of the options object.
Object Specifications:
<options>
<Number> sampleSize Optional Number of features to retrieve. Default is 500
<Promise>
<Graphic[]> features An array of Graphic objects that represent the requested sampleSize.
Sample:
require([
  "esri/layers/FeatureLayer",
  "esri/plugins/FeatureLayerStatistics",
  "dojo/domReady!"
], function (FeatureLayer, FeatureLayerStatistics){

  var featureLayer = new FeatureLayer("//services.arcgis.com/V6ZHFr6zdgNZuVG0/ArcGIS/rest/services/USA_Counties/FeatureServer/0");
  var featureLayerStats = new FeatureLayerStatistics({layer: featureLayer});
  var featureLayerStatsSampleSize = {sampleSize: 50};

  featureLayerStats.getSampleFeatures(featureLayerStatsSampleSize).then(function (result){
    console.log("Successfully sampled %s features, %o", featureLayerStatsSampleSize["sampleSize"], result);
  }).otherwise(function (error){
    console.log("An error occurred while %s, Error: %o", "sampling features", error);
  });

});

getSpatialStatistics(params)

Returns a promise that resolves to an object containing spatial statistics for an array of input features. The type of statistics returned varies depending on the geometry of the layer's features.

For input point and multipoint features, see the pointStats object specification table below for a description of the return object. Each point in a multipoint feature is considered a separate point for distance calculation.

For input polyline features, see the polylineStats object specification table below for a description of the return object. The length of a multipart polyline feature is the sum of the length of each of its paths.

For input polygon features, see the polygonStats object specification table below for a description of the return object. The size of each polygon is approximate and is calculated by multiplying the width and the height of its extent and dividing by two.

(Added at v3.16)
Return type: Promise
Parameters:
<Object> params Required See the Object Specifications table below for the structure of the params object.
Object Specifications:
<params>
<Graphic[]> features Required The input graphics from which to calculate spatial statistics.
<pointStats>
<number> avgMaxDistance Required Distance between each point and its farthest point, averaged over all points in the input features.
<number> avgMinDistance Required The distance between each point and its closest point, averaged over all points in the input features.
<number> maxDistance Required Distance between the two farthest points in the input features.
<number> minDistance Required Distance between the two closest points in the input features.
<polygonStats>
<number> avgSize Required Average size of all polygons in the input features.
<number> maxSize Required Approximate size of the largest polygon in the input features.
<number> minSize Required Approximate size of the smallest polygon in the input features.
<polylineStats>
<number> avgLength Required Average length of all lines in the input features.
<number> maxLength Required Length of the longest line in the input features.
<number> minLength Required Length of the shortest line in the input features.
Sample:
require(["esri/layers/FeatureLayer","esri/plugins/FeatureLayerStatistics"], function(FeatureLayer, FeatureLayerStatistics) {

  var featureLayer = new FeatureLayer("//services.arcgis.com/V6ZHFr6zdgNZuVG0/ArcGIS/rest/services/USA_Counties/FeatureServer/0");

  var featureLayerStats = new FeatureLayerStatistics({ layer: featureLayer });

  var params = { features: featureLayer.graphics };

  featureLayerStats.getSpatialStatistics(params).then(function(result) {
    console.log("Spatial stats: ", result);
  });
});

getSuggestedScaleRange(options?)

Find optimal scale range for viewing this layer. See the Object Specifications table below for the structure of the params object and Promise.
Return type: Promise
Parameters:
<Object> options Optional See the Object Specifications table below for the structure of the options object.
Object Specifications:
<options>
<Number> sampleSize Optional Number of features used for calculating the scale range. Default is 500.
<Promise>
<Number> maxScale Suggested maximum scale for the layer.
<Number> minScale Suggested minimum scale for the layer.
Sample:
require([
  "esri/layers/FeatureLayer",
  "esri/plugins/FeatureLayerStatistics",
  "dojo/domReady!"
], function (FeatureLayer, FeatureLayerStatistics){

  var featureLayer = new FeatureLayer("//services.arcgis.com/V6ZHFr6zdgNZuVG0/ArcGIS/rest/services/USA_Counties/FeatureServer/0");
  var featureLayerStats = new FeatureLayerStatistics({layer: featureLayer});
  var featureLayerStatsParams = {field: "AGE_5_17"};

  featureLayerStats.getSuggestedScaleRange().then(function (result){
    console.log("Successfully calculated %s, %o", "suggested scale range", result);
  }).otherwise(function (error){
    console.log("An error occurred while calculating %s, Error: %o", "the suggested scale range", error);
  });

});

getUniqueValues(params)

Find unique values available for the given field. See the Object Specifications table below for the structure of the params object and Promise.
Return type: Promise
Parameters:
<Object> params Required See the Object Specifications table below for the structure of the params object.
Object Specifications:
<params>
<String> field Required Name of the attribute field.
<String> valueExpression Optional An Arcade expression evaluating to a number or a string. This expression can reference field values using the $feature global variable and perform mathematical calculations and logical evaluations at runtime. The unique values returned from this method are gathered from the values returned from this expression. When a valueExpression is provided the field option is not needed.
<Promise>
<Boolean> partialData Indicates that statistics were generated for a subset, or sampling, of features on the client rather than queried against the service.
<Object[]> uniqueValueInfos An array of objects each describing a unique value. Each object will have the following properties: value, count.
Sample:
require([
  "esri/layers/FeatureLayer",
  "esri/plugins/FeatureLayerStatistics",
  "dojo/domReady!"
], function (FeatureLayer, FeatureLayerStatistics){

  var featureLayer = new FeatureLayer("//services.arcgis.com/V6ZHFr6zdgNZuVG0/ArcGIS/rest/services/USA_Counties/FeatureServer/0");
  var featureLayerStats = new FeatureLayerStatistics({layer: featureLayer});
  var featureLayerStatsParams = {field: "AGE_5_17"};

  featureLayerStats.getUniqueValues(featureLayerStatsParams).then(function (result){
    console.log("Successfully calculated %s for field %s, %o", "unique values", featureLayerStatsParams["field"], result);
  }).otherwise(function (error){
    console.log("An error occurred while calculating %s, Error: %o", "unique values", error);
  });

});

remove(layer)

This function is called internally when the plugin is removed from a feature layer.

Note: This is a static method.

Parameters:
<FeatureLayer> layer Required The target FeatureLayer that will have the plugin removed.