histogram | API Reference | ArcGIS Maps SDK for JavaScript

Method Overview

Name	Return Type	Summary	Function
	Promise<HistogramResult>	Generates a histogram for data returned from a `field` in a given `layer`.	histogram

Method Details

histogram Method 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. When a client-side layer type is provided, attribute and spatial statistics are calculated only from features in the view's extent. When a server-side layer type is provided, the statistics are calculated from the entire layer, unless a valueExpression is provided.

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 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. The view parameter is required if specifying a valueExpression. When using a valueExpression, client-side statistics are calculated based on the features in the view's extent. To generate statistics for the entire layer, set an equivalent sqlExpression.

sqlExpression String

optional

A SQL expression evaluating to a number. When provided, statistics are queried from the server for the entire layer. Only use this parameter when querying statistics based on an equivalent valueExpression. This parameter is ignored for client-side layer types.

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 MapView|SceneView

optional

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

filter FeatureFilter

optional

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

features Graphic []

Deprecated since version 4.23. Use useFeaturesInView instead.

optional

A subset of features for which to generate the histogram.

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|null|undefined

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 a HistogramResult object.

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);
});