import Histogram from "@arcgis/core/widgets/Histogram.js";const Histogram = await $arcgis.import("@arcgis/core/widgets/Histogram.js");- Since
- ArcGIS Maps SDK for JavaScript 4.12
Renders a histogram to visualize the spread of a dataset based on bins representing buckets, or sub-ranges, of data. Each HistogramBin is defined by a minimum and maximum value and a total count.
You can generate the underlying histogram's bins with the histogram module. In this scenario, you can use the fromHistogramResult() helper method to conveniently create the histogram from the result object.
const params = { layer: povLayer, field: "POP_POVERTY", normalizationField: "TOTPOP_CY", numBins: 30};
histogram(params) .then(function(histogramResult) { const histogram = Histogram.fromHistogramResult(histogramResult); histogram.container = "histogram"; }) .catch(function(error) { console.log("there was an error: ", error); });Other properties of this widget allow to display meaningful values on the histogram, such as the average and the dataLines properties.
See the image below for a summary of the configurable options available on this slider.
The barCreatedFunction property may be used to style the histogram bins based on the color of features in the renderer of a layer associated with the histogram.
- See also
Constructors
Constructor
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| properties | | |
Example
// typical usageconst histogram = new Histogram({ bins: [{ minValue: 0, maxValue: 20, count: 1 }, { minValue: 21, maxValue: 40, count: 60 },{ minValue: 41, maxValue: 60, count: 239 },{ minValue: 61, maxValue: 80, count: 88 },{ minValue: 81, maxValue: 100, count: 20 }], max: 100, min: 0, average: 44});Properties
| Property | Type | Class |
|---|---|---|
| | ||
| | ||
HistogramBin[] | null | undefined | | |
container inherited | HTMLElement | null | undefined | |
| | ||
DataLineInfos[] | null | undefined | | |
declaredClass readonly inherited | ||
destroyed readonly inherited | ||
Icon["icon"] | | |
id inherited | ||
| | ||
| | ||
| | ||
| | ||
| | ||
state readonly | | |
| | ||
visible inherited |
average
The statistical average of the data in the histogram. You would typically
get this value from the avg property of
SummaryStatisticsResult,
which is the result of the
summaryStatistics function.
When set, this value will render on the histogram with a symbol indicating it is the average.
- See also
Examples
// sets result returned from a smart mapping method// to the histogramhistogram.average = response.statistics.avg;histogram.average = 34.5; barCreatedFunction
- Type
- BarCreatedFunction | null | undefined
Function for styling bars representing histogram bins. This can be used to color bins with the same color of features in the view that fall into bins representing the same range of data.
Example
histogram.barCreatedFunction = function(index, element){ let bin = histogram.bins[index]; let midValue = ((bin.maxValue - bin.minValue) / 2) + bin.minValue; // colors the histogram bins with a custom function // (not defined here for brevity of the snippet) for interpolating // colors from data values to match the legend let color = getColorFromValue(midValue); element.setAttribute("fill", color.toHex());}; bins
- Type
- HistogramBin[] | null | undefined
An array of objects representing each bin in the histogram. This information is typically returned from the histogram function.
Examples
// sets the bins of the histogram from the bins in the histogram() resulthistogram.bins = histogramResult.bins;// Creates a histogram with 7 bins.histogram.bins = [ { minValue: 0, maxValue: 10, count: 4 }, { minValue: 10.1, maxValue: 20, count: 14 }, { minValue: 20.1, maxValue: 30, count: 9 }, { minValue: 30.1, maxValue: 40, count: 34 }, { minValue: 40.1, maxValue: 50, count: 351 }, { minValue: 50.1, maxValue: 60, count: 100 }, { minValue: 60.1, maxValue: 70, count: 1 }]; container
- Type
- HTMLElement | null | undefined
The ID or node representing the DOM element containing the widget. This property can only be set once. The following examples are all valid use case when working with widgets.
Examples
// Create the HTML div element programmatically at runtime and set to the widget's containerconst basemapGallery = new BasemapGallery({ view: view, container: document.createElement("div")});
// Add the widget to the top-right corner of the viewview.ui.add(basemapGallery, { position: "top-right"});// Specify an already-defined HTML div element in the widget's container
const basemapGallery = new BasemapGallery({ view: view, container: basemapGalleryDiv});
// Add the widget to the top-right corner of the viewview.ui.add(basemapGallery, { position: "top-right"});
// HTML markup<body> <div id="viewDiv"></div> <div id="basemapGalleryDiv"></div></body>// Specify the widget while adding to the view's UIconst basemapGallery = new BasemapGallery({ view: view});
// Add the widget to the top-right corner of the viewview.ui.add(basemapGallery, { position: "top-right"}); dataLineCreatedFunction
- Type
- DataLineCreatedFunction | null | undefined
Function that fires each time a data line is created. You can use this to style individual dataLines on the data axis.
Example
histogram.dataLineCreatedFunction = function (lineElement, labelElement, index) { lineElement.setAttribute("y2", "25%"); lineElement.classList.add("line-style");}; dataLines
- Type
- DataLineInfos[] | null | undefined
When set, renders lines on the histogram that indicate important or meaningful values to the end user.
Examples
// will render lines at the 25th, 50th, 75th, and 99th percentileshistogram.dataLines = [{ value: 30, label: "25 pctl"}, { value: 45, label: "50 pctl"}, { value: 65, label: "75 pctl"}, { value: 89, label: "99 pctl"}];// calculate standard deviations from mean using stats// returned from smart mapping statistic methodsconst stddevs = smartMappingUtils.getDeviationValues(stats.stddev, stats.avg, 2);histogram.dataLines = stddevs.map(function(stddev){ return { value: stddev };}); icon
- Type
- Icon["icon"]
- Since
- ArcGIS Maps SDK for JavaScript 4.27
Icon displayed in the widget's button.
- Default value
- "graph-histogram"
labelFormatFunction
- Type
- HistogramLabelFormatFunction | null | undefined
A function used to format labels on the histogram. Overrides the default label formatter.
Example
// For thumb values, rounds each label to whole numbers.slider.labelFormatFunction = function(value) { return value.toFixed(0);} layout
- Type
- Layout
Determines the orientation of the Histogram widget.
- Default value
- "horizontal"
Example
histogram.layout = "vertical"; viewModel
- Type
- HistogramViewModel
The view model for the Histogram widget. This is a class that contains all the logic (properties and methods) that controls this widget's behavior. See the HistogramViewModel class to access all properties and methods on the Histogram widget.
visible
- Type
- boolean
Indicates whether the widget is visible.
If false, the widget will no longer be rendered in the web document. This may affect the layout of other elements or widgets in the document. For example, if this widget is
the first of three widgets associated to the upper right hand corner of the DefaultUI, then the other widgets will reposition when this widget is made invisible.
For more information, refer to the css display value of "none".
- Default value
- true
Example
// Hides the widget in the viewwidget.visible = false;Methods
| Method | Signature | Class |
|---|---|---|
fromHistogramResult static | fromHistogramResult(result: HistogramResult): Histogram | |
classes inherited | classes(...classNames: ((string | null | undefined) | ((string[] | Record<string, boolean>) | null | undefined) | false | null | undefined)[]): string | |
destroy inherited | destroy(): void | |
emit inherited | emit<Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean | |
hasEventListener inherited | hasEventListener<Type extends EventNames<this>>(type: Type): boolean | |
isFulfilled inherited | isFulfilled(): boolean | |
isRejected inherited | isRejected(): boolean | |
isResolved inherited | isResolved(): boolean | |
on inherited | on<Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle | |
postInitialize inherited | postInitialize(): void | |
render inherited | render(): any | null | |
renderNow inherited | renderNow(): void | |
scheduleRender inherited | scheduleRender(): void | |
when inherited | when<TResult1 = this, TResult2 = never>(onFulfilled?: OnFulfilledCallback<this, TResult1> | null | undefined, onRejected?: OnRejectedCallback<TResult2> | null | undefined): Promise<TResult1 | TResult2> |
fromHistogramResult
- Signature
-
fromHistogramResult (result: HistogramResult): Histogram
A convenience function used to create a Histogram widget instance from the result of the histogram statistics function.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| result | The result of the histogram statistics function used to generate a histogram for a field or expression from a layer. | |
Example
let colorParams = { layer: povLayer, basemap: map.basemap, field: "POP_POVERTY", normalizationField: "TOTPOP_CY", theme: "above-and-below"};
let stats = null;
colorRendererCreator .createContinuousRenderer(colorParams) .then(function(response) { // set the renderer to the layer and add it to the map stats = response.statistics;
return histogram({ layer: povLayer, field: "POP_POVERTY", normalizationField: "TOTPOP_CY", numBins: 100 }); }) .then(function(histogramResult) {
let histogram = Histogram.fromHistogramResult(histogramResult); histogram.container = "histogram"; histogram.average = stats.avg; }) .catch(function(error) { console.log("there was an error: ", error); }); classes
- Signature
-
classes (...classNames: ((string | null | undefined) | ((string[] | Record<string, boolean>) | null | undefined) | false | null | undefined)[]): string
A utility method used for building the value for a widget's class property.
This aids in simplifying css class setup.
Parameters
- Returns
- string
The computed class name.
Example
// .tsx syntax showing how to set css classes while rendering the widget
render() { const dynamicClasses = { [css.flip]: this.flip, [css.primary]: this.primary };
return ( <div class={classes(css.root, css.mixin, dynamicClasses)} /> );} emit
- Signature
-
emit <Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean
- Type parameters
- <Type extends EventNames<this>>
Emits an event on the instance. This method should only be used when creating subclasses of this class.
hasEventListener
- Signature
-
hasEventListener <Type extends EventNames<this>>(type: Type): boolean
- Type parameters
- <Type extends EventNames<this>>
Indicates whether there is an event listener on the instance that matches the provided event name.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| type | Type | The name of the event. | |
- Returns
- boolean
Returns true if the class supports the input event.
isFulfilled
- Signature
-
isFulfilled (): boolean
isFulfilled() may be used to verify if creating an instance of the class is fulfilled (either resolved or rejected).
If it is fulfilled, true will be returned.
- Returns
- boolean
Indicates whether creating an instance of the class has been fulfilled (either resolved or rejected).
isRejected
- Signature
-
isRejected (): boolean
isRejected() may be used to verify if creating an instance of the class is rejected.
If it is rejected, true will be returned.
- Returns
- boolean
Indicates whether creating an instance of the class has been rejected.
isResolved
- Signature
-
isResolved (): boolean
isResolved() may be used to verify if creating an instance of the class is resolved.
If it is resolved, true will be returned.
- Returns
- boolean
Indicates whether creating an instance of the class has been resolved.
on
- Signature
-
on <Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle
- Type parameters
- <Type extends EventNames<this>>
Registers an event handler on the instance. Call this method to hook an event with a listener.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| type | Type | An event or an array of events to listen for. | |
| listener | EventedCallback<this["@eventTypes"][Type]> | The function to call when the event fires. | |
- Returns
- ResourceHandle
Returns an event handler with a
remove()method that should be called to stop listening for the event(s).Property Type Description remove Function When called, removes the listener from the event.
Example
view.on("click", function(event){ // event is the event handle returned after the event fires. console.log(event.mapPoint);}); when
- Signature
-
when <TResult1 = this, TResult2 = never>(onFulfilled?: OnFulfilledCallback<this, TResult1> | null | undefined, onRejected?: OnRejectedCallback<TResult2> | null | undefined): Promise<TResult1 | TResult2>
when() may be leveraged once an instance of the class is created. This method takes two input parameters: an onFulfilled function and an onRejected function.
The onFulfilled executes when the instance of the class loads. The
onRejected executes if the instance of the class fails to load.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| onFulfilled | OnFulfilledCallback<this, TResult1> | null | undefined | The function to call when the promise resolves. | |
| onRejected | The function to execute when the promise fails. | |
- Returns
- Promise<TResult1 | TResult2>
Returns a new promise for the result of
onFulfilledthat may be used to chain additional functions.
Example
// Although this example uses MapView, any class instance that is a promise may use when() in the same waylet view = new MapView();view.when(function(){ // This function will execute once the promise is resolved}, function(error){ // This function will execute if the promise is rejected due to an error});