Skip to main content

Help Center
Adding Compare Groups to a Dashboard Script

Introduction

Compare groups let a dashboard show the same results for two audiences (groups of respondents) side by side. Viewers choose the audiences once, in a selector bar at the top of the dashboard, and every chart updates to compare them.

Use compare groups when you want to:

  • Build one reusable dashboard that profiles any audience (group of respondents) against a comparison group. For example, a target audience compared with the full sample.
  • Let viewers change the audiences themselves, without editing any tiles.
  • Maintain one script instead of building a separate dashboard for each audience.

How it works:

  1. You add a COMPARE GROUPS block to the dashboard script. It defines the groups once, for the whole dashboard. For example, a target group and a control group.
  2. You adjust each tile so it can show the groups:
    • Make sure the tile is a plain frequency (FREQUENCY FOR <variable>) with no BY clause.
    • Display the tile as a chart (DISPLAY PLOT), not a table.
    • Set up the chart so the bars show the percentage for each group, with one colour per group.
  3. Every frequency tile in the dashboard then picks up the groups automatically. You don't need to list the groups inside each tile.
  4. Viewers pick a filter for each group in the selector bar. The names of the chosen filters then appear in the chart legends.

The rest of this article explains in details how to set Compare groups up in a dashboard.

 

1. What compare groups do

A compare group is a named sub-population — a filter that picks out part of your
respondents. When you add compare groups to a frequency tile, each group becomes its own
column, so instead of one overall result you get a side-by-side comparison:

                Segment A    Segment B
  Cats            40%          55%
  Dogs            60%          45%

You declare the groups once, at the dashboard level, and every frequency tile in the
dashboard picks them up automatically.

 

2. The one rule to remember: frequency only

In a linked dashboard, compare groups only work with plain FREQUENCY analyses.

If any analysis tile is anything other than a plain frequency (for example a crosstab FOR … BY …, a frequency array, or a numeric summary), the script is rejected with an error like:

Analysis type '<type>' is not supported with compare groups. Supported types: frequency

So before adding compare groups, make sure every tile in the dashboard is written as:

FREQUENCY FOR <variable>

A plain frequency has a FOR clause and no BY clause. The moment you add BY, it is a
crosstab and compare groups are no longer allowed.

Note that non-analysis tiles such as Summary or Rich text are allowed.

 

3. The dashboard-level COMPARE GROUPS block

Declare compare groups once, at the dashboard level — immediately after the dashboard
title, before the first TAB. The groups then apply to every frequency tile in the
dashboard.

The block is the keyword COMPARE GROUPS followed by one line per group. Each line is a
label in quotes followed by a TEMPLATE_FILTER reference to a dataset-filter template
parameter:

COMPARE GROUPS
    "Nationally representative" TEMPLATE_FILTER("target")
    "Nationally representative" TEMPLATE_FILTER("control")

Rules:

  • The labels in quotes are placeholders which are replaced in the UI with filters users select in the comparison widget. You can use “nationally representative” or “total sample” or another label that suits your dataset.
  • TEMPLATE_FILTER("…") references a dataset-filter template parameter by name. They are also placeholders. We recommend you use “target” and “control” in your script.

  • A template filter only takes effect once the template argument is actually supplied. Until
    the template is instantiated (i.e. until a filter is selected in the selector bar for each
    parameter), the tiles render as plain frequencies with no comparison.

     

4. The required tile display: DISPLAY PLOT

Compare-group frequency tiles are displayed as a plot, not a table. Each compare group
becomes a category on the plot, and the frequency variable's categories become the
series/colour. Use this DISPLAY PLOT block on every tile that is compared:

DISPLAY PLOT
  ENCODING
    COLOR=ROW_CATEGORIES 
    X=COL_CATEGORIES
    Y=COL_PERCENTS
  LAYERS
    BAR
      LABEL=COL_PERCENTS
      LABEL_POSITION=OUTSIDE
  INCLUDE EMPTY
  DECIMALS PERCENTAGES 0 MOE 1 OTHER 0
  AXIS VALUES
    HIDE AXIS
  AXIS CATEGORIES
    SWAPPED
    POSITION INSIDE
    BAND_SIZE NULL -1

Not every option is mandatory — ENCODING and a LAYERS layer are the core of a plot; the
rest (INCLUDE EMPTY, DECIMALS, AXIS VALUES, AXIS CATEGORIES) are optional refinements
you add only when you want that behaviour. Here is what each one means.

DISPLAY PLOT

Renders the tile as a chart instead of a table (DISPLAY TABLE). Required for the
compare-group visualisation described here.

ENCODING — maps data to visual channels

ENCODING says which part of the result drives each visual channel. For a compare-group
frequency:

  • COLOR=ROW_CATEGORIES — colour each bar by the frequency variable's categories (the
    "rows" of the underlying result, e.g. Cats / Dogs).
  • X=COL_CATEGORIES — put the compare groups along the X axis (the "columns" of the result;
    the compare groups are the column dimension).
  • Y=COL_PERCENTS — the bar height is the column percentage (the per-group percentage).

You can encode other measures on Y (for example a count), but COL_PERCENTS is the usual
choice for a group comparison because each group's column sums to 100%.

LAYERS — the chart geometry

LAYERS lists the geometric layers drawn on the plot. Here a single BAR layer gives a bar
chart. Each layer can carry label options:

  • BAR — draw bars (other layer types exist, e.g. line; BAR is standard for this
    comparison).
  • LABEL=COL_PERCENTS — print the column-percentage value on each bar as a data label.
  • LABEL_POSITION=OUTSIDE — where to place that label relative to the bar. Common values:
    OUTSIDE (just beyond the bar), INSIDE (within the bar), and END (at the end of the
    bar). The worked examples in section 7 use END.

Both LABEL and LABEL_POSITION are optional — omit them for bars with no printed values.

INCLUDE EMPTY

Show categories that have no data (zero / empty results) instead of dropping them. Useful so
that every group shows the same set of bars even when a category is empty for one group.
Omit it to hide empty categories.

DECIMALS PERCENTAGES 0 MOE 1 OTHER 0

Controls how many decimal places each kind of number is rounded to in the display:

  • PERCENTAGES 0 — percentages shown with 0 decimals (e.g. 40%, not 40.0%).
  • MOE 1 — margin-of-error values shown with 1 decimal.
  • OTHER 0 — all other numbers (e.g. counts) shown with 0 decimals.

Each of the three is optional; include only the ones you want to override from the default.

AXIS VALUES — the value (measure) axis

Options for the axis that carries the measure (here the percentage). The example hides it:

  • HIDE AXIS — hide the value axis line/scale entirely. This is common when you are already
    printing the value on each bar via LABEL, so the axis would be redundant.

AXIS CATEGORIES — the category axis

Options for the axis that carries the categories (here the compare groups). The example uses
three:

  • SWAPPED — swap the orientation of the category axis (e.g. turn vertical bars into
    horizontal bars, or flip the category/value axes).
  • POSITION INSIDE — draw the category labels on the inside of the plot area. The
    alternative positions move the labels elsewhere relative to the axis.
  • BAND_SIZE NULL -1 — set the plot's category "band" sizing. BAND_SIZE takes two values,
    a minimum and a maximum: NULL leaves the minimum unset (automatic), and -1 sets the
    maximum. Use this to control how wide each category band (and therefore each bar/group) is
    drawn. Omit BAND_SIZE entirely to let the plot size bands automatically.

All of AXIS VALUES and AXIS CATEGORIES and their sub-options are optional — add only the
ones you need.

 

5. The starting script (no compare groups)

Here is a minimal linked dashboard with a single frequency tile and no comparison:

CREATE DASHBOARD "My dashboard"
  TAB "My Tab"
    TILE "Pets" WIDTH 6 HEIGHT 4
      FREQUENCY FOR pets
      DISPLAY TABLE
        CELLS COL_PERCENT
;

This is a valid candidate for compare groups because the tile is already a plain
FREQUENCY FOR pets — no BY clause. Note it currently uses DISPLAY TABLE; when we add
compare groups we switch it to the DISPLAY PLOT block from section 4.

 

6. Step-by-step: adding compare groups

Step 1 — Check every tile is a plain frequency

Confirm each tile reads FREQUENCY FOR <variable> with no BY. If a tile is a crosstab or
another analysis type, rewrite it as a frequency first — otherwise the script will be
rejected once compare groups are present.

Step 2 — Add the dashboard-level COMPARE GROUPS block

Insert the block immediately after the dashboard title, before the first TAB:

CREATE DASHBOARD "My dashboard"
  COMPARE GROUPS
    "Nationally representative" TEMPLATE_FILTER("target")
    "Nationally representative" TEMPLATE_FILTER("control")
  TAB "My Tab"
    ...

Step 3 — Switch each compared tile to DISPLAY PLOT

Keep the tile's FREQUENCY FOR … line as-is, but replace its display with the DISPLAY PLOT
block from section 4. Compare-group tiles are shown as a plot (not a table), with the groups
on the category axis.

Step 4 — Save and let validation run

On save, the script is checked for the frequency-only rule and that the referenced template
parameters are valid.

 

7. Full before / after scripts

These are real scripts for a "Gender" frequency tile (FREQUENCY FOR pdl_gender), shown
without and then with compare groups. The example walks through three states: the plain
frequency, the compare-groups version before any audience is selected (placeholder labels
visible), and the same tile after audiences are picked in the selector bar. Compare what
changes in the script: the COMPARE GROUPS block is added at the top, and the tile's plot
ENCODING / AXIS is adjusted so the groups drive the comparison.

BEFORE — no compare groups

CREATE DASHBOARD "compare"
  TAB "1"
    TILE "Summary" LEFT 0 WIDTH 12 HEIGHT AUTO
      SUMMARY

    TILE "Gender" WIDTH 6 HEIGHT 4
      SUBTITLE ""
      FREQUENCY
        FOR gender
      DISPLAY PLOT
        ENCODING
          X=PERCENTS
          Y=CATEGORIES
          COLOR=CATEGORIES
        LAYERS
          BAR
            LABEL=PERCENTS
            LABEL_POSITION=END
        DECIMALS PERCENTAGES 2 MOE 1 OTHER 0
        AXIS CATEGORIES
          TITLE HIDE
          SUBTITLE HIDE
          BAND_SIZE NULL -1;

Renders as:

 

A horizontal bar chart with two bars — Male 43.56% and Female 56.44% —
each bar a different colour (the gender categories drive the colour via
COLOR=CATEGORIES). The percentage value sits at the end of each bar (LABEL_POSITION=END),
the value axis runs 0–60, the category labels (Male / Female) are on the left, and the base
size N 201,282 is shown bottom-right. There is no legend because there are no groups
yet.

Note this "before" already uses DISPLAY PLOT with the single-frequency encoding
(X=PERCENTS, Y=CATEGORIES, COLOR=CATEGORIES) — not a table.

AFTER — compare groups added (before selecting audiences)

Two things changed:

  1. A dashboard-level COMPARE GROUPS block was added after the title, with two
    template-filter groups ("label1" TEMPLATE_FILTER("target") and
    "label2" TEMPLATE_FILTER("control")).
  2. The tile's plot encoding was switched to the compare-group form: the groups go on the
    colour (COLOR=COL_CATEGORIES), the percentage on the X axis (X=COL_PERCENTS), the
    pdl_gender categories on the Y axis (Y=ROW_CATEGORIES), and the category axis gained
    SWAPPED.

The FREQUENCY FOR gender line itself is unchanged.

CREATE DASHBOARD "compare"
  COMPARE GROUPS
    "Nationally representative" TEMPLATE_FILTER("target")
    "Nationally representative" TEMPLATE_FILTER("control")
  TAB "1"
    TILE "Summary" LEFT 0 WIDTH 12 HEIGHT AUTO
      SUMMARY

    TILE "Gender" WIDTH 6 HEIGHT 4
      SUBTITLE ""
      FREQUENCY
        FOR gender
      DISPLAY PLOT
        ENCODING
          COLOR=ROW_CATEGORIES
          X=COL_CATEGORIES
          Y=COL_PERCENTS
        LAYERS
          BAR
            LABEL=COL_PERCENTS
            LABEL_POSITION=END
        DECIMALS PERCENTAGES 2 MOE 1 OTHER 0
        AXIS CATEGORIES
          SWAPPED
          TITLE HIDE
          SUBTITLE HIDE
          BAND_SIZE NULL -1;

Renders as:

The tile now carries a legend (top-left) with a group swatch, and the bars are coloured
by group rather than by gender category.

AFTER — audiences selected in the compare-groups selector bar

When a viewer opens the dashboard in the web app, a compare-groups selector bar appears
above the tiles with a Target audience and a Control audience picker (plus a
View index value toggle). Here the viewer has set Target audience = abc1 and
Control audience = Nationally representative:

Now the tile shows the two groups side by side for each gender category:

  • Legend: abc1 (N 27,564) and label2 (N 201,282).
  • Male: abc1 55.51% vs Nationally representative 43.56%.
  • Female: abc1 44.49% vs Nationally representative 56.44%.

The AI Summary tile at the top (SUMMARY) also updates to describe the selected audience.

AFTER — both audiences selected (every placeholder replaced)

Once the viewer also sets the Control audience (here to z22), the last placeholder
is gone:

  • Selector bar: Target audience = abc1, Control audience = z22.

  • Legend: abc1 (N 27,564) and z22 (N 27,564) — the label2 placeholder has now been
    replaced by the selected control filter name z22.

     

8. What changes inside each tile

Here is what changes for each tile when the dashboard-level COMPARE GROUPS block is added:

  • The analysis stays a FREQUENCY FOR <variable>. You do not add a BY clause and you
    do not list the groups inside the tile — the dashboard-level COMPARE GROUPS block supplies
    the comparison.
  • The groups become the compared categories. Where a plain frequency has one overall
    result, the tile now shows one category per compare group. The group names shown to the
    viewer come from the filters selected in the compare-groups selector bar — the script's
    labels are only placeholders.
  • The display changes to DISPLAY PLOT. Compare-group tiles are shown as a plot, not a
    DISPLAY TABLE. Use the plot block from section 4: the compare groups go on the category
    axis (X=COL_CATEGORIES), the frequency variable's categories drive the colour
    (COLOR=ROW_CATEGORIES), and the bar height is the per-group percentage (Y=COL_PERCENTS).
Was this article helpful?
0 out of 0 found this helpful
Return to top
Have more questions? Submit a request