require(["esri/smartMapping/statistics/histogram"], (histogram) => { /* code goes here */ });
import histogram from "@arcgis/core/smartMapping/statistics/histogram.js";
esri/smartMapping/statistics/histogram
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
- 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 |
---|---|---|---|
Generates a histogram for data returned from a | histogram |
Method Details
-
histogram
histogram(params){Promise<HistogramResult>}
-
Generates a histogram for data returned from a
field
in a givenlayer
. 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.ParametersSpecificationparams ObjectSee the table below for details on parameters that may be passed to this function.
Specificationlayer FeatureLayer|SceneLayer|CSVLayer|PointCloudLayer|GeoJSONLayer|WFSLayer|OGCFeatureLayer|StreamLayer|OrientedImageryLayer|CatalogFootprintLayer|CatalogLayer|KnowledgeGraphSublayerThe layer for which to generate a histogram.
field StringoptionalThe name of the numeric field for which the histogram will be generated. This property is ignored if a
valueExpression
is used.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.classificationMethod StringoptionalThe 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
, or0.25
standard deviations until all the data values are included in a class.Possible Values:"equal-interval"|"natural-breaks"|"quantile"|"standard-deviation"
standardDeviationInterval NumberoptionalWhen
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 NumberoptionalThe minimum bounding value for the histogram. Use this in conjunction with
maxValue
to generate a histogram between custom lower and upper bounds.maxValue NumberoptionalThe maximum bounding value for the histogram. Use this in conjunction with
minValue
to generate a histogram between custom lower and upper bounds.numBins NumberoptionalDefault Value: 10Indicates the number of classes to generate for the histogram.
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.
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 generate the histogram.
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<HistogramResult> Resolves to an instance of HistogramResult. Exampleshistogram({ 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
-
The result returned from the histogram() method.
- Properties
-
An array of objects representing each bin in the histogram.
minValue NumberThe minimum value returned by the field.
maxValue NumberThe maximum value returned by the field.
normalizationTotal NumberThe number used to normalize all values when
percent-of-total
is specified as thenormalizationType
.