histogram

AMD: require(["esri/smartMapping/statistics/histogram"], (histogram) => { /* code goes here */ });
ESM: import histogram from "@arcgis/core/smartMapping/statistics/histogram";
Function: esri/smartMapping/statistics/histogram
Since: ArcGIS API for JavaScript 4.2

Generates a histogram based on data in a Layer for a given field. The returned object can be used for displaying a histogram in the UI within visualization authoring applications and analytical apps that query and display statistics.

Known Limitations

  • Only FeatureLayer, SceneLayer, CSVLayer, GeoJSONLayer, PointCloudLayer, and WFSLayer layer types are currently supported, except in the following scenarios:
    • 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 statistics using SQL expressions for client-side FeatureLayers in a SceneView.
  • The normalizationType parameter only normalizes data returned by a field. It does not apply to values returned from a valueExpression or sqlExpression.

Moved from esri/renderers/smartMapping/... at 4.16.

Method Overview

Name Return Type Summary Function
Promise<HistogramResult>more details

Generates a histogram for data returned from a field in a given layer.

more detailshistogram

Method Details

histogram(params){Promise<HistogramResult>}

Generates a histogram for data returned from a field in a given layer. The returned object can be used for displaying a histogram to the UI in visualization authoring applications and analytical apps that query and display statistics.

Parameters:
Specification:
params Object

See the table below for details on parameters that may be passed to this function.

Specification:

The layer for which to generate a histogram.

field String
optional

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

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.

classificationMethod String
optional

The method for classifying the data. See the table below for a list of possible values.

Possible Value Description
natural-breaks Data values that cluster are placed into a single class. Class breaks occur where gaps exist between clusters. You should use this method if your data is unevenly distributed; that is, many features have the same or similar values and there are gaps between groups of values.
equal-interval Each class has an equal range of values; in other words, the difference between the high and low value is equal for each class. You should use this method if your data is evenly distributed and you want to emphasize the difference in values between the features.
quantile Each class has roughly the same number of features. If your data is evenly distributed and you want to emphasize the difference in relative position between features, you should use the quantile classification method. If, for example, the point values are divided into five classes, points in the highest class would fall into the top fifth of all points.
standard-deviation Class breaks are placed above and below the mean value at intervals of 1, 0.5, or 0.25 standard deviations until all the data values are included in a class.

Possible Values:"equal-interval"|"natural-breaks"|"quantile"|"standard-deviation"

standardDeviationInterval Number
optional

When classificationMethod = "standard-deviation", this sets the interval at which each class break should be set (e.g. 0.25, 0.33, 0.5, 1).

minValue Number
optional

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

maxValue Number
optional

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

numBins Number
optional
Default Value: 10

Indicates the number of classes to generate for the histogram.

valueExpression String
optional

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.

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.

view View
optional

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

features Graphic[]
optional

A subset of features for which to generate the histogram.

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<HistogramResult> Resolves to an instance of HistogramResult.
Examples:
histogram({
  layer: featureLayer,
  valueExpression: "( ($feature.POP2020 - $feature.POP2010) / $feature.POP2010 ) * 100"
  view: mapView,
  numBins: 30
}).then(function(histogramResult){
  colorSlider.histogram = histogramResult;
});
histogram({
  layer: featureLayer,
  field: "Population",
  normalizationType: "natural-log",
  sqlWhere: "Population > 0",
  numBins: 100
}).then(function(histogramResult){
  const histogramWidget = Histogram.fromHistogramResult(histogramResult);
});

Type Definitions

HistogramResult

The result returned from the histogram() method.

Properties:
bins Bin[]

An array of objects representing each bin in the histogram.

minValue Number

The minimum value returned by the field.

maxValue Number

The maximum value returned by the field.

normalizationTotal Number
optional

The number used to normalize all values when percent-of-total is specified as the normalizationType.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.