Authoring ArcGIS Dashboards using arcgis.apps.dashboard
A dashboard is a view of geographic information and data that allows you to monitor events, make decisions, inform others, and see trends. Dashboards are designed to display multiple visualizations that work together on a single screen. They offer a comprehensive view of your data and provide key insights for at-a-glance decision-making.
arcgis.apps module includes Dashboard submodule to create dashboards programmatically. The
arcgis.apps.dashboard submodule contains classes for different widgets which can be configured and added to a dashboard.
Dashboards are composed of configurable elements, such as maps, lists, charts, gauges, and indicators etc. All of these elements can be added to a dashboard after it is configured by setting the properties and values for data. Most of the elements are equipped with getters and setters to access information. Each element has a title, name, description, width and height which can be set using the setters provided. Elements can be stacked or grouped together in various ways.
The Dashboard elements could be imported by running the following command:
from arcgis.apps.dashboard import Gauge, MapLegend, NumberSelector, PieChart, RichText, \ SidePanel,Indicator, List, SerialChart, CategorySelector, DatePicker, Details, EmbeddedContent
Let's understand each of the Dashboard elements in detail.
A header is a reserved area along the top of your dashboard that can be used for giving your dashboard a unique identity, applying corporate branding standards, and providing links to additional content. It can also be used in interactive dashboards to host one or more selectors. A dashboard can only have one header, and it's designed to always occupy the entire width of a dashboard.
Using the API, values for a Header can be set as shown below:
Header( title=None, subtitle=None, margin=True, size="medium", logo_image_url=None, logo_url=None, background_image_url=None, background_image_size="fit-width", background_image_position="left", signout_link=False, menu_links=None )
A header widget can be used to add a
subtitle for the dashboard. The
margin parameter is used to set margin around the header whereas the
size parameter can be used to set the overall size of the header. A logo can be embedded into the header using the
logo_image_url parameter and this logo can optionally be hyperlinked using the
logo_url parameter. It can also contain a background image, specified using
background_image_url. The size and position of the background can be set using the
background_image_position parameters respectively. The header can also contain a sign out link, set using the
signout_link parameter. It can also have multiple links, specified using the
The side panel is used in interactive dashboards to host one or more selectors. A dashboard can only have one side panel, which has a fixed size and position along the dashboard's edge, although you can configure it to be retractable at run time.
side_panel = SidePanel()
A Side Panel widget can be initialized without any parameters. Once initialized, the widget has setters to set the background and text color.
allow_sliding setter can be enabled to allow the side panel to have a sliding effect.
A number selector, category selector or a date picker can be added to the side panel using the
A number selector widget can be added to both Side Panel and Header widgets. A number selector can of two types, a range based number selector or single value picker.
number_selector = NumberSelector(range=True, label='Give a name to your selector', operator='less than')
range parameter can be set to True to create a range based number selector. A label to widget can be added using the
label parameter and
display_type parameter defines the interface of the widget, it can be anything from
"spinner", "slider", "input".
For a non-range or single value number selector an
operator parameter can be passed to define a relationship with the value selected. It can take values from
"equal", "not equal", "greater than", "greater than or equal", "less than", "less than or equal".
A factor for each increment can also be specified using a parameter
increment_factor while initializing.
The number selector is equipped with setters to allow setting up placeholder text for both range and single values selector.
The minimum and maximum limits for selector can be set using either using
A date picker widget can be added to both Side Panel and Header widgets. Date Picker can be of two types, a range date picker or a single date picker.
date_picker = DatePicker()
When initializing the
range parameter can be set to True to create a range date picker. A label for the widget can be added using the
For a single date picker, the
operator parameter can be set to describe the relation with value being picked.
operator parameter can take values from
is", "is not", "is before", "is or is before", "is after", "is or is after".
The default value for the single date picker can be specified using the
For a range date picker, default values can be specified passing
Accepted values for the default values are
None, "Today", or a fixed value in 24 hours format
(year, month, day, hour, minutes) or
(year, month, day).
The category selector widget can be initialized as follows:
category_selector = CategorySelector()
The categories can be set using
set_defined_values function takes in key-value pairs of labels and their corresponding values whereas
set_feature_options function can be used to set the category options from an
arcgis.gis.Item object. The
field_name parameter can be specified to select the field from which the values will be populated.
set_group_by_values function also works with an
arcgis.gis.Item object and the field can be specified using the
CategorySelectorProperties accessible using the
selector getter, helps in setting various properties related to the category selector widget like the preferred display, label, display threshold etc.
A category selector widget can be added to both Side Panel and Header widgets.
Maps play a central role in many dashboards. Not only are they often the most effective way to display your geographic information, but their operational layers can also be used by other data visualizations on the dashboard to create interesting, intuitive, and compelling information products.
A Map widget can be created using the existing
Once the object is created, we can enable and disable the properties
scale_bar property can be set to "none", "ruler", "scale" to define the type of scale.
Events object, accessible using the
events getter can be used to sync maps and widgets using the
In general, a map legend conveys the meaning of symbols that represent map features. It is particularly useful when the map has multiple operational or thematic layers. The legend element displays the legend of the web map you've created for your dashboard, just like the map element displays this web map.
MapLegend widget can be initialised by passing a map widget or
The map legend widget picks the legend from the Map object and add a new element to the dashboard.
A serial chart visualizes one or more series of data points along a horizontal (x) axis and a vertical (y) axis. Serial charts get their name from an ability to show more than one series of data. In the following chart, there are two series of data: one showing crime counts by day and the other showing a three-day rolling average of crime counts. Each series in a serial chart has a type that determines the way the data points are visualized. In the following example, the series showing crime counts by day has the bar type and the series showing the three-day rolling average of crime counts has the line type.
A SerialChart widget, similar to a PieChart widget works with
arcgis.mapping.WebMap object. For a
WebMap object a specific layer id can be specified using the
categories_from parameter can be from
"groupByValues", "features", "fields".
SerialChartData object, accessible using the
data getter, allows you to set the category field using the
category_field setter in case of
add_value_field function allows you to set the value field along with other properties of the serial chart.
groupByValues only one field is accepted, for
features multiple fields can be added one by one by calling the function and for
fields a list of fields is accepted.
SerialChartData object also provides setter to enable or disable hover text, labels, dates parsing and stacking.
You can also add filters, set the order by field, statistic, date parsing pattern and max number of features to display using the setters available in the
value_axis getters give access to the
ValueAxisProperties object which allow you to set axis related properties, for example font size, title, thickness, opacity etc.
The SerialChart widget also supports events, using the
events getter. Similar to PieChart once the events are enabled, it can be synced with a map for actions in
"zoom", "flash", "show_popup", "pan" or "filter" or with a widget using the
A pie chart is a circular chart divided into sections. Each section is proportional to the quantity it represents. A pie chart contains a single series of data points.
Use pie charts to show part-to-whole relationships or for data composition. Pie charts are not intended for comparing individual sections with each other or representing exact values (use a serial chart for that). Pie charts are also not meant to show more than seven or eight data points.
A donut chart is an alternative representation of a pie chart. It can be thought of as a column in a stacked bar graph in a circular shape. Donut charts are created by increasing the value for the Inner Radius (%) setting on the Chart tab of the pie chart element.
PieChart(item, layer=0, categories_from)
PieChart widget works with and
arcgis.gis.Item or a
arcgis.mapping.WebMap object. In case of
WebMap object a
layer parameter can be specified to select a layer id.
The Pie Chart widget can work with 3 types of data, divided using
categories_from parameter. The value of this parameter can be from
"groupByValues", "features", "fields".
PieChartData object accessible through the
data getter in the widget allows you to set the properties related to data.
If data is picked from
features then the field can be set using the
If the field is a date type field, then
parse_dates can be set to True to parse the values appropriately.
category_field setter accepts a list of fields.
In case of
features a value field also has to be set which can be done using the
PieChartData object also allows you to set the filters as well as allows you to select the statistics to apply. The object id field can also be modified using the
Text color, font size, start angle, inner radius and hover text are some properties related to the pie chart which can be modified using the
PieChartProperties object, accessible using the
pie getter in the widget.
Properties related to Pie chart slice can be modified using the
SliceProperties object, accessible through the
SliceProperties object allows you to set the opacity, default color, blank color, null color and grouping color. It also allows you to set the labels for null and blank values as well as the grouping percentage value.
OutlineProperties object, accessible through the
outline getter in the widget allows you to set the color, thickness and opacity of the outline.
Legend visibility and placement for the widget can be set using the
Legend object, accessible through the
Pie chart also supports events, using the
Events object, accessible through the
The events once enabled, can be synced with a map using the
sync_map function for actions in
"zoom", "flash", "show_popup", "pan" or "filter".
PieChart can also be synced with other widgets using the
An indicator is essentially a card that can be added to your dashboard. It can be used to show the numeric attributes of individual features, or it can be used to display a count, a sum, an average, a minimum, or a maximum summary statistic. Additionally, it can be configured to compare its computed value to a reference value. Last, it can be configured to show an icon or change its color only in response to conditional thresholds being met. The following are some examples of the many configurations possible with an indicator:
An Indicator widget can be easily created by passing in an
item of type
arcgis.mapping.WebMap. In case the
item is a WebMap, a parameter
layer can be specified to select a layer id.
IndicatorData, accessible through
data getter allows setting the
In case of
statistic the statistic type can be set using the
statistic setter and the field from which the values have to be picked from can be set using the
value_field setter. Offset and value conversion factor can also be set for the data using the
add_filter function allows setting up filters for the widget data.
Indicator also supports a
ReferenceData object, accessible through
reference getter which can be used to set a reference scale for the data.
Gauges are used to display a single metric within a quantitative context defined by minimum and maximum values. The metric can be derived from one of a feature's numeric fields or from a summary statistic. These quantitative context values can either be fixed or dynamic and based on feature values or summary statistics with or without applied filters. As with an indicator, a gauge shows the state of only one metric or value—unlike, for example, a pie chart, which can show the state of two or more values.
Gauges inform viewers of current situations rather than past or general trends. To show the latter, a gauge can be grouped with another element better suited to show values over time, such as a line chart. Gauges are also effective in interactive dashboards as the target of an action. When this occurs, actions performed on other elements, such as a selection on a list, can control the data available to be displayed on the gauge.
When configuring a gauge, you can choose from two styles: progress and meter.
A Gauge widget can be created by simply passing in the
arcgis.gis.Item object or
arcgis.mapping.WebMap object. A
layer parameter can be used to specify the layer id to pick from the item, if the item is and
Once the Gauge object is initialized, data related properties can be set using the
GaugeData object, accessible using
GaugeData allows setting the
feature, which describes the type of values being used.
value_type is set to
fixedvalue, then you can set the minimum, maximum value for the data using the
value_type is set to
statistic, then the type of statistic and statistic field to use can be set using the
feature the field from which the values have to be picked from can be set using the
You can also set the offset or the value conversion factor using the
factor setters in the
Filters related to the widget can be added using the
GaugeProperties object, accessible through
gauge_options allows you to select the
style of the Gauge from
Gauge widget has setters to set the max number of features to display and whether to show last updated time or not.
A list is used to show features or rows from a layer. When available, field formatting information in a list is based on information found in the layer's pop-up. However, as with all data-driven elements, you can create filters for lists to limit the amount of information they display. You can also limit the number of features displayed in a list at once. Additionally, you can specify the order in which the features are sorted in the list. For example, you can configure the list so that rows with certain attributes for a date-based field appear near the top, which is particularly important in real-time scenarios.
List widget works with an
arcgis.mapping.WebMap object. In case of
WebMap as specific layer id can be specified using the
layer parameter. Various properties of the
List widget can be set using the setters available, such as
List widget also supports events, which can be set using the
Events object, accessible through the
Any non-map widget can synced with a list of widgets using the
sync_widget function in
Events object. Any map widget can be synced using the
sync_map function with
"zoom", "flash", "show_popup", "pan" or "filter".
The details element is used to show information about features or rows from a layer. Its display is based on a layer's pop-up information. Each pop-up has four distinct parts: title, content, media, and attachments (see Configure pop-ups for details). When configuring the details element, each of these parts can be switched on or off.
As with all data-driven elements, you can create filters for the details element to limit the amount of information it displays. Also, as with the list element, you can limit the number of features displayed in the details element and sort the order in which features are presented. The latter means that you can, for example, specify that rows with important values for a date-based field appear at the front of the element's carousel. This is particularly important in real-time scenarios.
A Details widget works with an
arcgis.mapping.WebMap and can be used to render the information from the item in the widget.
item is the
arcgis.gis.Item object which contains the information to be rendered.
item can also be a
arcgis.mapping.WebMap object in which case the information from the Map is rendered. A specific layer number can be specified using the
layer parameter when using the
max_features_displayed controls the number of features to display in the widget.
The details objects allows to set how the content is displayed by use of setters such as
A RichText widget can be initialized using and HTML string. The HTML string is rendered directly in the widget.
html_text = "<p>Hello World!</p>" RichText(html_text)
The embedded content element makes it easy to embed documents, images, video, or other web content into your dashboard. Two configuration options are available. When you configure the element to be static, all you need is the URL of the content to be embedded. When you configure it by features, the element is data driven and you need to identify a data source. This means that each feature's attribute information can be used to dynamically construct a URL at run time. When configured by features, the embedded element can be the target of an action. Specifically, it can be the target of elements that support a selection change event.
EmbeddedContent(url, content_type, item, layer)
EmbeddedContent widget can be used to embed a url of type
"document", "image" or
EmbeddedContent widget can also be used to embed a url contained in a field of
arcgis.gis.Item object, in this case the
url parameter is the name of the field from which the url is picked from. The
layer parameter defines the layer id to pick from the item.
The dashboard object can be used to club the widgets together and publish a final dashboard.
The theme of the dashboard can be set to either
dark using the
theme setter. The
side_panel setter accept
Header objects for the dashboard.
from arcgis.apps.dashboard import Dashboard, add_column, add_row
dashboard = Dashboard()
Remaining widgets can be added to dashboard using the
layout setter can be used to set the layout of the widgets in the dashboard.
Two helper functions
add_column in the dashboard module are used to add widgets together in a row or a column.
add_row function takes in a list of widgets and height of the row, the
add_column function takes in a list of widgets and width of the column. The output from one function can be clubbed with other widgets and sent to the other function to create complex layouts easily. Once the final layout is ready, it can be set to the dashboard object using the
dashboard.layout = add_row([element]) #pass the element object from any of the above created elements.
Once the dashboard is assembled, you can share it with its intended audience. You can share dashboards publicly with everyone or only with people in your organization. You can promote your dashboard by providing a link to it or embedding it in another website or app.
save() function can be called to publish the dashboard as an item on the portal.