Skip to main content

Help Center
CREATE DASHBOARD command

See Crunch Automation basics for more information.

Overview

The CREATE DASHBOARD command allows you to use Crunch Automation scripts to create dashboards. CREATE is a bit of a misnomer — in fact, the syntax here defines a dashboard. You don’t create something and then manipulate it; instead, you make changes to the definition and redefine it.

A Crunch dashboard presents tables and graphs of live data along with commentary in a series of ‘tiles’ arranged into sections called ‘tabs’. Crunch Automation represents the complete declarative definition of the dashboard and all of its contents in text. The simplest dashboard contains a title, a single tab, and one or more tiles. A dashboard without any live data or analyses could describe and introduce a dataset or a folder (in fact, the same structure without any analysis tiles represents the folder homepage).

General syntax

CREATE DASHBOARD <dashboard name>
	<dashboard tab>+
	<dashboard groups>

Dashboard name and groups

Each dashboard has a title which cannot be empty and must be unique within that dataset. This is the only property of the dashboard itself:

  • dashboard name — Quoted string, which is the name of the dashboard to generate.
  • dashboard groups — GROUPS MULTI? VARIABLES <comma separated aliases>.
    • Allows you to configure the left sidebar filters. The optional MULTI keyword means that for each group you can pick multiple choices instead of just one.
    • The aliases indicated are limited to be categorical or multiple responses.

Dashboard scripts must begin with a CREATE DASHBOARD command. This tells Crunch that this script will define a dashboard and that no other Crunch Automation content will be present in this script. Each dashboard must have a name and must be unique among other dashboards in this dataset. This name will appear in the header of the dashboard and in the list of dashboards to which users can navigate. The name can be changed at a later stage via the web-app

Dashboard tabs

Dashboards must contain at least one tab to act as a container for the content. Dashboards with just one tab will not show any tabbed structure and will appear to the user to have no tabs. Dashboards with two or more tabs will display tabbed navigation. Tabs are useful for organizing dashboard content by theme (e.g., by region, sector, or topic) and help users to find useful content, especially for larger dashboards.

Each tab must have a non-empty name, even if only one tab is defined. The order in which tabs are defined in the script determines the order they appear in the dashboards interface. Dashboards will always open starting with the first script unless otherwise specified in the URL. Tabs can be empty, though this will just present a blank container to the user. Tiles cannot be placed outside of a tab. The only element of a dashboard that does not sit within a tab is the GROUPS panel (see below).

You must indicate:

  • at least one tab in the dashboard you create, and
  • each tab must contain at least one tile.
TAB <tab name> <dashboard tile(s)>
  • tab name — Quoted string with the tab name, which cannot be empty.

Dashboard tiles

Tiles are rectangular containers arranged in a grid of relative-sized squares (the absolute sizing of the dashboard, and therefore of each tile, depends on the size and resolution of the viewer’s display). The grid is 12-wide and as tall as needed to display the content.

Each tile has a title (which may be empty but not null) and must indicate its size and the type of its contents — markdown, video, iframe, or analysis. Tiles cannot be empty, though a markdown tile with no content will appear as empty. The bulk of this document will describe the analyses and the ways different customizations and display options are described in the script.

Currently, the dashboard description must be alone in a given script and cannot be combined with other Crunch Automation commands. Crunch Automation commands are presented in capitals for legibility but are not, in fact, case sensitive. Similarly, line breaks and indentation are added for legibility in this documentation but are ignored by the system

TILE <tile name> 
		<tile dimensions>
		(SUBTITLE <tile subtitle>)?
		(FOOTNOTE TEXT <tile footnote>)?
		<Tile body>

Tile body — Can include the following 4 types:

  • MARKDOWN <markdown body> – Must be a triple backtick (```) quoted multiline string.
  • VIDEO <url> – Quoted URL string, which validates that it’s a URL (not that it works).
  • IFRAME <url> – Quoted URL string, which validates that it’s a URL (not that it works).
  • Analysis (display) – Must indicate the type of analysis to make.
  • Groups

Tile analysis

In general, analyses are aggregations over rows of the underlying data, optionally weighted and filtered. The most common aggregation is weighted counts described as either a frequency (for one variable) or a crosstab for two or three variables. The counts can be displayed as they are or as percentages, in a table or a graph. Crunch array variables present their “subvariables” together to facilitate comparisons.

<Analysis type>
		FOR <variable alias> <optional dimension transforms>
		BY <variable alias> <optional dimension transforms>
		(TABBED BY <tabbed dimension>)?
		<analysis options>
		<analysis display>

Dashboard analyses (aggregations) are described largely in terms of the number of variables or dimensions involved, up to three:

  • FREQUENCY
  • CROSSTAB
  • TABBED CROSSTAB

To work with arrays, both categorical or numeric, the array keyword is added to indicate that the aggregation is to be done for each subvariable, and allows you to position the categories or values of the results by referring to subvariables or categories:

  • FREQUENCY ARRAY — the one-way frequency of each subvariable. These are commonly shown as tables or a series of stacked bars because each one sums to 100%.
  • CROSSTAB ARRAY
  • TABBED FREQUENCY ARRAY
  • DICHOTOMIZED ARRAY — this allows you to select categories of an array to collapse its categories dimension, showing each subvariable as a dichotomous selection (as if it were multiple response). This is useful for presenting comparisons between subvariables, selecting similar categories such as “Somewhat agree” and “Strongly agree” to present a summary view of agreement with a series of statements.
  • FUSED SCORECARD

Exceptions for each analysis type:

  • FUSED SCORECARD — The FOR dimension accepts a list of aliases instead of just one.
  • FREQUENCY ARRAY — The dimension does not refer to a variable alias, but a subdimension (SUBVARIABLES or CATEGORIES):
    • FREQUENCY ARRAY my_array SUBVARIABLES BY CATEGORIES

Optional dimension transforms

You can also use the following dimension transform values:

  • SELECT <categories list>
  • TITLED <string title> — Allows you to name the dimension referenced.
  • ROLLUP <mask> — To be used only with date variables and indicates the rollup resolution to transform continuous date variables into discrete categories.
  • INSERTIONS — Can be used multiple times to add multiple insertions such as nets or differences to this dimension.
  • HIDE <elements list> — Indicates a list of elements for this dimension. You can indicate which ones not to include in the final rendering of the tile.
  • HIDE EMPTY — By default, all elements in the dimension are shown. Using this transform, all that have a 0 value are not included.
  • SHOW ONLY <elements list> — Similar to HIDE, this permits you to indicate which are the only elements to be included.
  • LABELS — Allows you to override the display name for each element in the dimension instead of its default category/subvariable name.
  • COLORS — With a syntax similar to LABELS, this allows you to indicate in hex the color to use to render each of the elements in the final render.
  • SORTING — Allows a number of options to sort, including:
    • SORT BY LABEL
    • SORT ELEMENTS
    • SORT BY MEASURE
    • SORT BY MARGIN
    • SORT BY SUBTOTAL
    • ASCENDING/DESCENDING — Additionally, all SORT options can indicate ASCENDING/DESCENDING order and indicate which elements to fix at the beginning or end of the dimension using FIXED TOP and FIXED BOTTOM.

Analysis options

  • FILTERED BY — Allows you to indicate a FILTER_NAME(string) or FILTER_VALUE(variable, values) to indicate a filter to use.
  • WEIGHTED BY <alias> — Requires a numeric variable alias to assign the filter to use.
  • INCLUDE EMPTY

Analysis display

DISPLAY [AS BUNDLE|TABLE]

For example:

  • DISPLAY AS <chart type> VALUES <measure> <display bundle options>
  • DISPLAY TABLE CELLS <measure> <display table options>

See also

See the following articles to learn more about creating and working wiith dashboards in the Crunch web app:

Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles

Have more questions? Submit a request