Whether you’re looking to create a fully customized new dashboard or you need to upgrade an existing one, this guide will help walk you through some of the more advanced programming options available within the dashboard editor.
If you have never before created a research dashboard, it is highly recommended that you first read Creating a Research Dashboard before diving into the advanced options outlined here. You may also supplement your understanding by watching the following training video on programming basic dashboards.
Duration: 25 minutes
1: Organizing a Dashboard
1.1: Creating Banners & Segments
By default, the full data set is shown within each element and only one column of data is presented. The keyword banner.local defines a set of banner segments and applies them to a table or chart. The values for banner.local follow a simple conditional syntax, wherein each segment is defined by its condition and title:
banner.local segment <condition> [title]
Example #1 - Segmenting a table:
With the below banner and segments applied, the table for smartphone ownership displays the data split between males and females:
table Smartphone ownership row Q3.r1 row Q3.r2 row Q3.r3 row Q3.r4 row Q3.r5 banner.local segment Q1.r1 Female segment Q1.r2 Male
Example #2 - Segmenting a chart:
Similarly, with the following banner and segments applied, the smartphone ownership chart displays the data split between males and females:
chart Smartphone ownership row Q3.r1 row Q3.r2 row Q3.r3 row Q3.r4 row Q3.r5 type pie banner.local segment Q1.r1 Female segment Q1.r2 Male
1.2: Adding Dynamic Splits to Charts & Tables
Note: When creating selectable splits make sure that the dashboard's compat is set to level 2+.
By default, banners and segments are applied prior to loading a dashboard, so each element will appear with programmed splits already in place. If you want to allow users the ability to toggle between data views manually within your dashboard, you would need to add a dynamic split to each element. You can use bannergroup.local to add dynamic splits to charts and tables.
Note: Local splits take priority over global splits.
Example #1 - Adding a dynamic split to a table:
Allowing users to toggle between viewing the age and smartphone ownership of respondents within a gender table:
table Gender of Respondents rows Q1.r1-r2 bannergroup.local banner.local Age segment "Q2.r1" "18 - 25" segment "Q2.r2" "26 - 35" segment "Q2.r3" "36 - 44" segment "Q2.r4" "45+" banner.local Smartphone Type segment "Q3.r1" "Android" segment "Q3.r2" "Blackberry" segment "Q3.r3" "iPhone" segment "Q3.r4" "Windows" segment "Q3.r5" "Other"
This code would apply a gear icon to the gender table which would prompt users with a “Split By” menu to toggle and apply different data views:
Once a split is applied, the table would dynamically change to a segmented view:
Example #2 - Adding a dynamic split to a chart:
Allowing users to toggle between viewing the age and smartphone ownership of respondents within a gender chart:
chart id=db-5 Gender Pie Chart rows Q1.r1-r2 type bar bannergroup.local banner.local Age segment "Q2.r1" "18 - 25" segment "Q2.r2" "26 - 35" segment "Q2.r3" "36 - 44" segment "Q2.r4" "45+" banner.local Smartphone Type segment "Q3.r1" "Android" segment "Q3.r2" "Blackberry" segment "Q3.r3" "iPhone" segment "Q3.r4" "Windows" segment "Q3.r5" "Other"
This code would apply a gear icon to the gender chart which would prompt users with a “Split By” menu to toggle and apply different data views:
Once a split is applied, the table would dynamically change to a segmented view:
You can also force a segmented view to show without a split by adding default=1 to a banner.local attribute. For example, if you wanted users to see the gender table split by age unless another banner is selected, you would use the following code:
table Gender of Respondents
banner.local default=1 Age
segment "Q2.r1" "18 - 25"
segment "Q2.r2" "26 - 35"
segment "Q2.r3" "36 - 44"
segment "Q2.r4" "45+"
banner.local Smartphone Type
segment "Q3.r1" "Android"
segment "Q3.r2" "Blackberry"
segment "Q3.r3" "iPhone"
segment "Q3.r4" "Windows"
segment "Q3.r5" "Other"
2: Data View Options
2.1: Adding Filters
The keyword filter allows you to restrict the respondent data included within a dashboard. If a filter does not have a title, it will always be applied and you will not be able to toggle it on/off.
Add default=1 to select a filter by default.
filter [default=1] <condition> [title]
filter id=db-9 default=1 Q5.r1 Only Social Media Users filter id=db-3 Q3.r1 Only Android Users filter id=db-4 Q3.r2 Only Blackberry Users filter id=db-5 Q3.r3 Only iPhone Users filter id=db-6 Q3.r4 Only Windows Users filter id=db-7 Q3.r5 Only Other Users
With filters added, users can click on the gear icon within the dashboard to choose and apply filters:
When viewing a dashboard with this configuration, users would be able to view the data by "Only Social Media Users", "Only Android Users", etc., or even with no filter at all. By default, the data is filtered by "Only Social Media Users":
You can filter the data by a respondent's status (qualified, terminated, and overquota). If no filter is applied, the status defaults to "all" including partials.
filter default=1 qualified Qualifieds only filter terminated Terminates only filter overquota Overquota only
With the above dashboard configuration, you can filter the data by "Qualifieds only", "Terminates only", "Overquota only" or no filter at all. By default, the data is filtered by "Qualifieds only":
2.1.1: Filtering by Date Range
If you want to filter by a date range, you can use filter datepicker.
While using this filter also make sure that the dashboard compat level is set to "2 (faster)" / "1 (Compat 123)" or higher.
When this filter is applied, a date picker is available for your input from the left drop-down filter panel when viewing the dashboard:
2.1.2: Filtering by Local Data
The keyword filter.local allows restricting respondents' data within a table or chart. This overrides all other filters.
chart Gender of Respondents rows Q1.r1-r2 filter.local Q1.r1
This chart only shows data for Q1.r1 because the chart's data is filtered to show only the data that matches the condition provided for the local filter:
2.1.3: Using Dynamic Grouped Filters
The keyword filtergroup allows you create dynamic grouped filters.
To view all of the existing tables or charts based on Males who primarily use an iPhone, or based on Females who primarily use a Blackberry, you would use the following code:
filtergroup Gender filter q1.r1 Males filter q1.r2 Females filtergroup Primary Smartphones filter q2.r1 iPhone filter q2.r2 Android filter q2.r3 Blackberry filter q2.r4 Windows filter q2.r5 Other
This creates two new filter groups available for toggling within the dashboard viewer:
By default, the logical relation between filters in a filtergroup is an “AND” statement.
You can change the relationship to a logical “OR” statement using the keyword argument multi=or.
To show data grouped by any smartphone, you would use the following code:
filtergroup multi=or Primary Smartphones filter q2.r1 iPhone filter q2.r2 Android filter q2.r3 Blackberry filter q2.r4 Windows filter q2.r5 Other
You can also add exclusivity to the filters by adding exclusive=1 to a filtergroup. The keyword argument "Exclusive" is an user interface (UI) setting only. It displays the filters in a filtergroup as mutually exclusive (whether or not they actually are) and allows the user to select at most one.
To make your smartphone filter selection mutually exclusive, you could use the following code:
filtergroup exclusive=1 Primary Smartphones filter q2.r1 iPhone filter q2.r2 Android filter q2.r3 Blackberry filter q2.r4 Windows filter q2.r5 Other
This changes the filter selection to a radio button:
2.1.4: Adding Drop-Down Menus for Selectable Filters
Note: When creating selectable local filters make sure that the dashboard compat level is set to 2+.
You can use filtergroup.local to add drop-downs for selectable filters on charts and tables. These filters are applied in addition to any global filters.
To add a drop-down togglable filter for region, you could use the following code:
filtergroup.local multi=or "Region" filter.local "q9.r31" "Greater London" filter.local "q9.r32" "South West" filter.local "q9.r33" "South East" filter.local "q9.r34" "East of England" filter.local "q9.r35" "East Midlands" filter.local "q9.r36" "West Midlands" filter.local "q9.r37" "Yorkshire and the Humber" filter.local "q9.r38" "North East" filter.local "q9.r39" "North West" filter.local "q9.r40" "Scotland" filter.local "q9.r41" "Wales" filter.local "q9.r42" "Northern Ireland"
When added to a chart or table definition, this would create a selectable drop-down filter on the element itself:
Specifying the Filters/Segments/Rows that are Shown with Certain Filters
The showif attribute can be added to rows, local filters and local segments so you can specify the filters/segments/rows that are shown with certain filters. The showif condition only applies if at least one filter from the same filtergroup is selected.
Note: When using a showif condition to display a row that is included in a sum or net, the sum or net and all its rows should have the same condition.
The following example shows certain filters/rows when the Desktop filter is applied and different filters/rows when the Mobile Device filter is applied. Both local filters and rows are changed based on the filter selection.
filtergroup multi=or exclusive=1 "Device Category" filter "vmobiledevice.r0 or vmobiledevice.r1 or vmobiledevice.r2 or vmobiledevice.r3" "Mobile Device" filter "vmobiledevice.r4" "Desktop" table "Table with conditional rows and filter" filtergroup.local filter.local vmobileos.r0 iOS filter.local vmobileos.r1 Android filter.local vmobileos.r3 Windows filter.local vmobileos.r0 Mac OS X or older row vmobiledevice.r0 Smartphone row vmobiledevice.r1 Featurephone row vmobiledevice.r2 Tablet row vmobiledevice.r3 Other mobile row vmobiledevice.r4 Desktop
When the Desktop filter is applied, only the OS filter and rows are shown:
When the Mobile Device filter is applied, both the device OS and type filters and rows are shown:
2.1.5: Nesting Filters
Note: When nesting filters make sure that the dashboard compat level is set to level 2+.
Filters can be nested to provide multiple levels by which you can drill-down your view of the data. You can create a nested filter when you add the filterlevel attribute to a filter and assign it a number (1,2,3 and so on). For example, to specify the top level of an hierarchy set filterlevel=1, then list any filters under that one that should be children of that filter. Then assign the next nesting level as filterlevel=2, and so on. Children of a filter are hidden in the filters drop-down menu until selected.
Additionally, you can specify a filterlabel as a description for the next drop-down. The filterlabel displays with the options "All" and "Multiple".
Note: The "All" and "Multiple" options do not display if the filtergroup is setup as "exclusive".
Creating a drill-down for country, state, county, province, and municipality would require using the following code:
filtergroup multi=or filterlabel="Country" "Region" filter filterlabel="State" filterlevel=1 "q11.r1" "United States of America" filter filterlabel="County" filterlevel=2 "q12.r1" "California" filter "q13.r2" "Fresno County" filter "q13.r3" "Kern County" filter "q13.r4" "Kings County" filter filterlabel="County" filterlevel=2 "q12.r2" "Nevada" filter "q14.r1" "Carson City" filter "q14.r2" "Clark County"
This would create a nested filter like the one displayed below:
And display the following options for the drop-down, including "All" and "Multiple":
2.2: Pulling Data from Multiple Surveys
By default, only the current survey data is loaded and accessible within a dashboard. The keyword survey allows the inclusion of data from another survey.
survey <path> [condition] [S1=T1] [S2=T2]
To include all data from the project path selfserve/9d3/12345, you would use the following code:
If needed, you could add other values to further define your data pool. For instance, if you wanted to view the same data, but only from respondents that have a positive value for vwave.r1, you could use the following code:
survey selfserve/9d3/12345 vwave.r1
You can also remap data points that you are planning to pull into your dashboard, which is helpful when projects have duplicate or very long label names.
The remapping feature is used to combine data from questions with different question labels that share the same structure. For example, if you have q1 and s1 as gender questions in separate surveys and want to map q1 to reference both the q1 data in your current study, as well as the s1 data in your imported study, you might use the following code:
survey selfserve/214e/161203 1 q1=s1
This allows you to use the following syntax in order to produce a table with the combined set of data:
table id=db-1 Gender rows q1.r1-r2
When importing data from other studies, you can filter tables and charts to only display data from a specific study using the survey path that you would like to pull from. The below example illustrates how to do that:
survey selfserve/214e/161203 table id=db-2 Gender 2 row "q1.r1 and survey=='selfserve/214e/161202'" Males Survey 1 row "q1.r1 and survey=='selfserve/214e/161203'" Males Survey 2 row q1.r1 Combined
2.3: Adding Weights
The keyword weight can be applied to a specific segment or globally to all surveys to add per-record weighting.
Note: The weight keyword is only available in compat level "2 (faster)" dashboards.
Per-record weighting requires that each respondent has a float-type question that contains the record weight to be applied. If you are using Crosstabs, you may have already uploaded a file with one or more weights; the contents of that file are available in the nweight question. However, you can use any question you want for weighting, as long as it has been programmed into the survey itself.
To apply global weighting to any segment without an explicit weight parameter, you can use the following code:
To weight a specific segment only, you would specify that segment within the weight argument:
banner Weighted versus Unweighted segment weight= Unweighted segment weight=vweight.r1.val Weighted (Algorithm 1) segment weight=vweight.r2.val Weighted (Algorithm 2)
Note: Configuring weights on a segment will override any global weight configuration. This is mostly used when you want to compare weighted and unweighted data for the same survey.
2.4: Adding Significance Testing
Note: The dashboard compat level must be set to "2 (Faster)" or higher for this feature to be available.
The keyword sigtest allows you to add significance testing to a dashboard. You can enable sigtest for the entire dashboard, or on a per table basis.
To enable significance testing, you would use the following code:
Note: When sigtest is enabled:
- stat testing is enabled on the table row and shown when a table is split by multiple segments.
- stat column identifies are show in the heading of the columns
- stat testing letters are shown in the applicable "square" matching cross tabs
To disable significance testing:
For information on reading report statistics: click here
2.5: Numeric Question Considerations
2.5.1: Null Values
Number questions that were not seen or (depending on question setup) not answered might have an empty value (or “None”). Such values are ignored when calculating statistics; however, you can recode them into your dashboard calculations using an .ival command.
For example, if q1.r1 is blank, the following code would recode it to a value of “0”:
2.5.2: Data Sources
The formula used to get the numeric value per respondent can read multiple numeric values. For example, to calculate the Net Promoter Score for a survey based on a 7-point question where r1 and r2 are promoters, and r6 and r7 are detractors, you could use the formula:
+100 if (q1.r1 or q1.r2) else -100 if (q1.r6 or q1.r7) else 0
This will generate a numeric value of +100 if q1.r1 or q1.r2 were selected; otherwise, a -100 value would display if q1.r6 or q.r7 were selected, and a “0” would display if any other options were selected.
What's Next for Creating a Dashboard?
Interested in learning more about customizing your dashboard? The following articles delve deeper into dashboard element and data options:
Whether you’re a dashboard pro or you’re just learning the basics, the below articles provide guided examples to help you refine your process: