Creating a Basic Chart
Dashboard charts can be created using the
chart keyword. For example, if you wanted to create a chart based on your respondents’ gender, you would use the following syntax:
chart Gender of Respondents row s1.r1 Male row s1.r2 Female
By default, this will create the below bar chart:
Defining Chart Rows
Based on Numerical Element Labels
When referencing answer options that are not labeled with valid Python identifiers, such as rows labeled with numbers only, you can convert your data point references to Python conditions, and use the Pythonic
.attr() function to reference your elements.
For example, given a gender question (
Q1) with the following answer options:
<row label="1">Male</row> <row label="2">Female</row>
Q1.2 aren't valid Python identifiers, you can instead reference these answer options as follows:
Chart Gender of Respondents type pie row 'Q1.attr("1")' Male row 'Q1.attr("2")' Female
Note: Because the
.attr() function requires double quotes to reference the numeric labels, you would need to surround your Python condition with single quotes to avoid having the two quotation sets clash.
Using Multiple Rows at Once
You can also use the keyword rows to add multiple rows to a chart, and these can be identified using name-spaced row labels or ranges:
rows [row] [row] ... rows [questionLabel.startingRow]-[endingRow]
For example, the two segments below, which are based on the same color selection question (
Q2), would produce the same result:
chart Favorite Color rows Q2.r1 Q2.r2 Q2.r3 Q2.r4 Q2.r5 chart Favorite Color rows Q2.r1-r5
When specifying multiple answer options using the
rows keyword, the row text for the chart is automatically picked up from the referenced answer option text.
Note: Even if you are referencing multiple answer options at the same time, you should not surround them with quotes, as you would be referencing data points rather than complex Python conditions.
Using Dynamic Row References
When using the rows keyword, there may be cases where you want to dynamically reference a condition specific to each row. For example, consider the following question type:
<radio label="d6"> <title>On a scale of 1 to 5, how would you rate each of the following car brands ?</title> <row label="r1">Toyota</row> <row label="r2">Ford</row> <row label="r3">Honda</row> <row label="r4">Tesla</row> <row label="r5">Chevrolet</row> <col label="c1">1</col> <col label="c2">2</col> <col label="c3">3</col> <col label="c4">4</col> </radio>
Where you want to look only at the top 2 ratings for each brand. Usually, you would define each row separately with a complex Python condition to reference both c4 and c5:
chart Top Vehicle Satisfaction row "d6.r1.c4 or d6.r1.c5" Toyota row "d6.r2.c4 or d6.r2.c5" Ford row "d6.r3.c4 or d6.r3.c5" Honda row "d6.r4.c4 or d6.r4.c5" Tesla row "d6.r5.c4 or d6.r5.c5" Chevrolet
However, you can shorten the amount of code you need to write by using the inbuilt templating system:
chart Top Vehicle Satisfaction rows code="$.c9 or $.c10" d6.r1-r5
This code produces the same result because the default condition logic is overridden using the code keyword and the dollar sign (
$). The dollar sign is a copy of the default condition and everything else is additional logic.
rows d6.r1-r5 produces 5 rows with the default conditions
d6.r5. The system stores these default conditions into the dollar sign variable and enables you to extend the logic using the
code attribute. The example below produces the same result and should help you better understand how the code attribute works, but it is not nearly as efficient as either of the two examples above:
chart Top Vehicle Satisfaction row code="$.c9 or $.c10" d6.r1 Toyota row code="$.c9 or $.c10" d6.r2 Ford row code="$.c9 or $.c10" d6.r3 Honda row code="$.c9 or $.c10" d6.r4 Tesla row code="$.c9 or $.c10" d6.r5 Chevrolet
Selecting a Chart Type
As seen above, the default chart type within dashboards is a bar graph, but charts are dynamic and can be reset using the keyword
type, you can set a chart to appear as any one of the following base chart types:
Vertical Bar Chart:
Horizontal Bar Chart:
Gauge Chart / Pie Chart with Gauge:
Scatter Plot Chart:
scatter plot charts are more advanced charts that require additional modifications.
As an example, if you wanted to convert the earlier bar chart to a pie chart, you can add the
type keyword as a part of your chart definition:
chart Gender of Respondents type pie row s1.r1 Male row s1.r2 Female
This will change your chart from a bar graph, to the below pie:
Customizing Chart Colors
By default, the color selection uses the following colors:
palette configures the default color palette used for banner segment colors in charts and pie slices. Color codes follow the standard hexadecimal character format without the preceding hash (
#) per code. When a chart needs more colors than specified, the coloring will restart from the beginning.
palette <color> <color> …
Note: Hexadecimal characters should NOT be prefixed with a hash (
#) when referenced in the dashboard editor, as the system will interpret any text following the hash as a comment.
chart Gender of Respondents rows Q1.r1-r2 palette FFA0FA 47BEFF
Note: The palette system can use up to 10 colors as arguments.
Creating Charts Based on 2D Questions
Note: Creating charts for two-dimensional questions uses the dashboard banner functionality. Click here to learn more about banners.
It is possible to display a grid question within a single chart. To create this display, you would use the
conds attribute on each row you would like to include and define multiple conditions for these rows that correspond to each segment of the chart.
If you wanted to view the data for a rating question evaluating your service’s “availability”, ”speed”, and ”stability”, you will need to use the following steps:
Creating the Chart Rows
When creating charts based on grid questions, the first thing you need to do is define your chart rows. For 2D questions, you need to define your rows based on the question’s columns, even if that may be counterintuitive. The reason for this is that you need to specify each explicit intersection between the rows and columns of your grid, to count the individual cells that respondents can select.
When specifying your column references, you also need to use the
.any vector logic attribute, to make sure that your ratings encompass all three possible services.
chart Rating type column row q3.c1.any Poor row q3.c2.any Fair row q3.c3.any Good row q3.c4.any Excellent
While the above rows display all of the ratings given, they do not account for each individual service, so your percentages will end up way over 100% in total. What you want to do next, is make sure that each rating is only counted when given to a specific service.
Modifying Chart Rows to Include Cell Intersections
The next modification you need to do to your chart is to explicitly define which cells are to be counted towards each row when pulling the data for each row. This can be done using the
In this case, you need to specify all the possible rows that can be selected for each row as follows:
row conds="q3.c1.r1, q3.c1.r2, q3.c1.r3" q3.c1.any Poor row conds="q3.c2.r1, q3.c2.r2, q3.c2.r3" q3.c2.any Fair row conds="q3.c3.r1, q3.c3.r2, q3.c3.r3" q3.c3.any Good row conds="q3.c4.r1, q3.c4.r2, q3.c4.r3" q3.c4.any Excellent
conds attribute only lists the rows as part of the related column in the data point reference.
Using Banners to Create the Second Chart Dimension
The final modification you want to do is create a banner, the segments of which you will use to form the columns in your chart.
Note: Click here to learn more about creating banners.
As you already have your chart rows referencing the columns in your question, your banner segments will now reference the question’s rows:
banner.local segment q3.r1.any "Availability" segment q3.r2.any "Speed" segment q3.r3.any "Stability"
Similarly to your column data references, you would use vector logic to make sure that any rating given to your service category is counted.
Transposing the Chart
You can add the
transpose keyword to your chart setup if you want to flip the dimension of the chart.
Enabling Chart Stacking (optional)
chartopt keyword, you can enable column stacking with the following syntax:
chartopt plotOptions.column.stacking 'normal'
Putting it All Together
The final result of all the modifications that you can input to your chart can be seen below:
chart Rating type column banner.local segment q3.r1.any "Availability" segment q3.r2.any "Speed" segment q3.r3.any "Stability" transpose row conds="q3.c1.r1, q3.c1.r2, q3.c1.r3" q3.c1.any Poor row conds="q3.c2.r1, q3.c2.r2, q3.c2.r3" q3.c2.any Fair row conds="q3.c3.r1, q3.c3.r2, q3.c3.r3" q3.c3.any Good row conds="q3.c4.r1, q3.c4.r2, q3.c4.r3" q3.c4.any Excellent chartopt plotOptions.column.stacking 'normal'
This will produce the following output:
Customizing Chart Data
Specifying the Unit of Measurement for Datapoints
There are a variety of data display options available when creating a dashboard chart. Here, you can find information on specifying units of measurement, plotting multiple sets of data, adding bases, and even how to show a grid question directly within a chart.
Note: The default unit of measurement for non-numeric input data is a percentage (
pct). If you would like to use a different unit of measurement for non-numeric data, you can use the
chart.data attribute to specify one of the following alternatives:
count: This will show the overall response count (n=xxxx) of the datapoint.
hpct: This will display horizontal percentages, instead of the default vertical percentages.
effbase: This will show the effective base of the data point when weighting is applied.
chart Chart with Counts chart.data count type bar rows q1.r5-r10
The code above would create a chart similar to the below, where each bar is labeled with total counts, instead of percentages:
Tip: You can access this information on a dashboard when you click the “Quick Reference” link located in the top-left corner of the dashboard editor.
The default unit of measurement for numeric input data is the mean (
mean) of the data. If you would like to use a different unit of measurement for numeric data, you can use the
chart.stat attribute to specify one of the following alternatives:
stddev: This will show the standard deviation of the datapoint.
median: This will show the median of the datapoint.
sum: This will show the sum of the datapoint.
stderr: This will show the standard error of the datapoint.
count: This will show the count of the datapoint.
pct: This will show the percentage of the datapoint.
Note: Click here to learn more about applying statistics in dashboard charts and charts.
Plotting Two Sets of Data
It is possible to plot two sets of data on a single chart, but you must first program each set of data into a separate chart.
Note: When combining data sets, there are no restrictions to the chart type or compat level; however, for best results, it is recommended that you use a line chart when combining two sets of data.
Once you have each set of data programmed into its own chart, you can use the following steps to combine the two sets of data into a single chart:
- Set the attribute
hide=1on the first chart.
- Set the attribute
combineWith=xxxxon the second chart where "
xxxx" is the ID of the hidden chart.
Note: For line charts, add
chartopts chart.alignTicks false to the dashboard syntax (if you do not set this attribute on a line chart, the datapoints will stack on top of each other).
chart id=5 hide=1 "Counts" type line chart.data count chartopts chart.alignTicks false chart.stat formula stats formula formula (mean / 5) * 100 row q8.r1.c1 row q8.r2.c1 row q8.r3.c1 row q8.r4.c1 row q8.r5.c1 banner.local segment "q4.r1" "Car Salesman Q8" segment "q4.r2" "Architect Q8" chart id=6 combinewith=5 "Q8/Q9 Combined Data" type line chart.data count chartopts chart.alignTicks false chart.stat formula stats formula formula (mean / 5) * 100 row q9.r1.c1 "Row 1" row q9.r2.c1 "Row 2" row q9.r3.c1 "Row 3" row q9.r4.c1 "Row 4" row q9.r5.c1 "Row 5" banner.local segment "q4.r1" "Car Salesman Q9" segment "q4.r2" "Architect Q9"
Note: The first chart must have an
id and be defined before the chart that uses "
combineWith". The “
hide=1" attribute will only work on a chart that is combined with another.
The code above would produce the line chart below:
There are some limitations and additional considerations when combining data sets in a chart. See below for details:
- Local banner groups and local filter groups with drop-down menus are not supported in charts using multiple data sources.
- Charts with multiple data sources cannot be exported, and will only be available within the dashboard itself.
- Due to the overall complexity of this functionality, it is not recommended to use multiple data sources when chart stacking or when using NPS charts.
- Only two charts can be combined at one time.
Adding Bases Within a Chart
It is possible to add the base (count) of a datapoint within a chart. The keyword
showbase allows you to add the base below a bar or column in its chart.
Note: When using the
showbase keyword make sure that the dashboard's compat is set to level 2+.
To enable the base display, you would need to set
showbase 1. When
showbase is enabled, “
N=XXX” displays below the bar or column where
XXX is the total base for the column/bar.
Note: The NPS add-on automatically shows the base if
chart.data is set to "count".
chart Chart Showing Base showbase 1 type column rows q1.r5-r10
This produces the following results: