Creating Dashboard Charts

1: Creating a Basic Chart

Dashboard charts can be created using the chart keyword. For example, if you want to create a chart based on your participants' gender, use the following syntax (assuming that Q1 is your project's gender question):

chart Gender of Participants
row Q1.r1 Male
row Q1.r2 Female
row Q1.r3 Non-Binary
row Q1.r4 Self-Describe

By default, this creates a bar chart.

1.1: Defining Chart Rows

You can define chart rows based on numerical element labels, by using multiple rows at once, or by using dynamic row references.

1.1.1: 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>
<row label="3">Non-Binary / Third Gender</row>
<row label="4">I prefer to self-describe:</row>

Since Q1.1 and Q1.2 are not valid Python identifiers, you can instead reference these answer options as follows:

Chart Gender of Participants
   type pie
   row 'Q1.attr("1")' Male
   row 'Q1.attr("2")' Female
   row 'Q1.attr("3")' Non-Binary
   row 'Q1.attr("4")' Self-Describe

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.

1.1.2: Using Multiple Rows at Once

You can also use the keyword rows to add multiple rows to a chart., and tThese 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.

1.1.3: 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, where you want to look only at the top 2 ratings for each brand.:

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

For example, rows d6.r1-r5 produces 5 rows with the default conditions d6.r1, d6.r2, d6.r3, d6.r4, and 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

1.2: 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. Using type, you can set a chart to appear as any one of the following base chart types:

Vertical Bar Chart: `column`	Horizontal Bar Chart: `bar`

Line Chart: `line`	Area Chart: `area`

Pie Chart: `pie`	Gauge Chart / Pie Chart with Gauge: `gauge`

Scatter Plot Chart: `scatter plot`	Bubble Chart: `bubble`

Note: The bubble and 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 Participants
type pie
row Q1.r1 Male
row Q1.r2 Female
row Q1.r3 Non-Binary
row Q1.r3 Self-Describe

This will change your chart from a bar graph to a pie graph.

1.3: Customizing Chart Colors

By default, the color selection uses the following hex colors: #4572A7, #AA4643, #89A54E, #80699B, #0D96AE, #DB843D, #92A8D0, #A47D7C, and #B5CA92.

The color selection uses the following hex colors: #4572A7, #AA4643, #89A54E, #80699B, #D96AE, #DB843D, #92A8D, #A47D7C, and #B5CA92.

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

Example:

chart Gender of Participants
type pie
  rows Q1.r1-r4
  palette d2ffff 00253b e1ffb3 004d63

Note: The palette system can use up to 10 colors as arguments.

2: Creating Charts Based on 2D Questions

Note: Creating charts for two-dimensional questions uses the dashboard banner functionality. See Creating Dashboard Banners 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.

Example:

If you wante to view the data for a rating question evaluating your service’s “availability”, ”speed”, and ”stability”, you will need to use the following steps:

2.1: 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 eEach explicit intersection between the rows and columns of your grid must be specified, to count the individual cells that participants 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 nNext, is make sure that each rating is only counted when given to a specific service.

2.1.1: 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 conds="" attribute.

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

Note: Each conds attribute only lists the rows as part of the related column in the data point reference.

2.2: Using Banners to Create the Second Chart Dimension

The final modification you want to do is to create a banner. The banner's, the segments will of which you will use to form the columns in your chart.

Note: See Creating Dashboard Banners to learn more about creating banners.

As you already have your chart rows already referenceing 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 be make sure that any rating given to your service category is counted.

2.3: Transposing the Chart

You can add the transpose keyword to your chart setup if you want to flip the dimension of the chart.

2.4: Enabling Chart Stacking (optional)

Using the chartopt keyword, you can enable column stacking with the following syntax:

chartopt plotOptions.column.stacking 'normal'

2.5: 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:

3: Customizing Chart Data

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, and adding bases.

3.1: Specifying the Unit of Measurement for Datapoints

There are two different methods for specifying the unit of measurement, depending on if your data point is numeric or non-numeric. 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.

3.1.1: Non-numeric Datapoints

Note: The default unit of measurement for non-numeric input data is a percentage (pct). TIf 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.

Example:

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.

3.1.2: Numeric Datapoints

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: SThis will shows the standard deviation of the datapoint.
median: SThis will shows the median of the datapoint.
sum: SThis will shows the sum of the datapoint.
stderr: SThis will shows the standard error of the datapoint.
count: SThis will shows the count of the datapoint.
pct: SThis will shows the percentage of the datapoint.

Note: See Using Statistical Calculations In Dashboards to learn more about applying statistics in dashboard charts and charts.

3.2: 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=1 on the first chart.
Set the attribute combineWith=xxxx on the second chart where "xxxx" is the idID 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).

Example:

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 using combineWith 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.

3.3: 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 or greater+.

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

Example:

chart Chart Showing Base
showbase 1
type column
rows q1.r5-r10

This produces the following results:

Forsta Surveys Support

Articles in this section

In this article

1: Creating a Basic Chart

1.1: Defining Chart Rows

1.1.1: Based on Numerical Element Labels

1.1.2: Using Multiple Rows at Once

1.1.3: Using Dynamic Row References

1.2: Selecting a Chart Type

1.3: Customizing Chart Colors

2: Creating Charts Based on 2D Questions

2.1: Creating the Chart Rows

2.1.1: Modifying Chart Rows to Include Cell Intersections

2.2: Using Banners to Create the Second Chart Dimension

2.3: Transposing the Chart

2.4: Enabling Chart Stacking (optional)

2.5: Putting it All Together

3: Customizing Chart Data

3.1: Specifying the Unit of Measurement for Datapoints

3.1.1: Non-numeric Datapoints

3.1.2: Numeric Datapoints

3.2: Plotting Two Sets of Data

3.3: Adding Bases Within a Chart