Authoring ArcGIS Dashboards using

NOTE: The arcgis.apps.dashboard module was officially deprecated with the ArcGIS API for Python 2.0.1 release. The classes in that module are not updated to reflect the current architecture of ArcGIS Dashboards. This guide will be removed from the documentation for the upcoming ArcGIS API for Python 2.4.0 release.

Introduction

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.

The 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.

Dashboard Elements

Header

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 title, 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_size, 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 menu_links parameter.

Side Panel

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. The 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 add_selector function.

Number Selector

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 set_defined_limits or set_statistics_limits function.

Date Picker

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 label parameter.

For a single date picker, the operator parameter can be set to describe the relation with value being picked. The 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 value parameter.

For a range date picker, default values can be specified passing min_value and max_value parameter. 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).

Category Selector

The category selector widget can be initialized as follows:

category_selector = CategorySelector()

The categories can be set using set_defined_values, set_feature_options or set_group_by_values function.

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 category_field parameter.

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.

side_panel.add_selector(category_selector)

Map Element

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.

WebMap(item)

A Map widget can be created using the existing arcgis.mapping.WebMap object. Once the object is created, we can enable and disable the properties pop_ups, navigation, legend, layer_visibility, basemap_switcher, search and zoom. The 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 sync_map and sync_widget functions.

Map Legend

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(map_widget)

A MapLegend widget can be initialised by passing a map widget or arcgis.mapping.WebMap object. The map legend widget picks the legend from the Map object and add a new element to the dashboard.

Serial Chart

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.

SerialChart(item, categories_from)

A SerialChart widget, similar to a PieChart widget works with arcgis.gis.Item or arcgis.mapping.WebMap object. For a WebMap object a specific layer id can be specified using the layer parameter. 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 "groupByValues" or "features".

The add_value_field function allows you to set the value field along with other properties of the serial chart. For 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. The 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 SerialCharData object.

The category_axis and value_axis getters give access to the CategoryAxisProperties and 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 sync_widget function.

Pie Chart

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)

A 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".

The PieChartData object accessible through the data getter in the widget allows you to set the properties related to data. If data is picked from groupByValues or features then the field can be set using the category_field setter. If the field is a date type field, then parse_dates can be set to True to parse the values appropriately.

For categories_from=fields the 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 value_field setter. 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 objectid_field setter.

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 slice getter. 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 legend getter.

Pie chart also supports events, using the Events object, accessible through the events getter. 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 sync_widget function.

Indicator

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:

Indicator(item)

An Indicator widget can be easily created by passing in an item of type arcgis.gis.Item or 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 value_type from statistic or feature. 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 offset and factor setters. 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.

Gauge

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.

Gauge(item)

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 arcgis.gis.WebMap object.

Once the Gauge object is initialized, data related properties can be set using the GaugeData object, accessible using data setter.

GaugeData allows setting the value_type from fixedvalue, statistic, feature, which describes the type of values being used. If the value_type is set to fixedvalue, then you can set the minimum, maximum value for the data using the min_value and max_value setters. In case value_type is set to statistic, then the type of statistic and statistic field to use can be set using the statistic or statistic_field setter. For value_type = feature the field from which the values have to be picked from can be set using the value_field setter. You can also set the offset or the value conversion factor using the offset and factor setters in the GaugeData object. Filters related to the widget can be added using the add_filter function.

GaugeProperties object, accessible through gauge_options allows you to select the style of the Gauge from progress and meter or shape from horseshoe and halfdonut.

Gauge widget has setters to set the max number of features to display and whether to show last updated time or not.

List

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(item)

A List widget works with an arcgis.gis.Item or 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_icon, list_text, selection_text_color etc.

A List widget also supports events, which can be set using the Events object, accessible through the events getter. 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 action type "zoom", "flash", "show_popup", "pan" or "filter".

Details

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.

Details(item, layer=0)

A Details widget works with an arcgis.gis.Item and 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 arcgis.mapping.WebMap object. The parameter 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 show_title, show_content, show_attachment, show_media etc.

Rich Text

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)

Embedded Content

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)

An EmbeddedContent widget can be used to embed a url of type "document", "image" or "video". 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.

Create Dashboard

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 light or dark using the theme setter. The header and side_panel setter accept SidePanel and 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. The layout setter can be used to set the layout of the widgets in the dashboard. Two helper functions add_row and add_column in the dashboard module are used to add widgets together in a row or a column.

The 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 layout setter.

dashboard.layout = add_row([element]) #pass the element object from any of the above created elements. 

Share Dashboard

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.

The save() function can be called to publish the dashboard as an item on the portal.

dashboard.save("Sample Dashboard")