Gauge

In CDP Data Visualization, Gauge visuals are powerful tools for communicating performance against set targets, projected trends, and a qualitative assessment of the measurement.

Gauges show minimum and maximum values on an evenly distributed scale, and qualitative ranges for classifying the primary measurement as different colors, which is very useful for visually distinguishing them from one another.

Gauges are semi-circular by default, and include many setting adjustments.

You can review the following three examples of gauge charts to see their structure:

Example 1: Measure < Projection < Compare To: In this scenario, both the measurement and its projected future value are less than the target value.
Example 2: Measure < Compare To < Projection: In this scenario, the measurement is less than the target value, but its projection is expected to exceed the target.
Example 3: Compare To < Measure < Projection: In this scenario, the measurement has already exceeded the target value, and the projection is even greater.

The long dark inner arc of the visual represents the value on the Measure shelf. It is the feature measurement of the visual. In Example 3, the last section appears in dark blue because the value of Measure is greater than the Compare To value.
The extension of the same arc is the expected value of the measure at a future date, supplied by the Projection shelf of the visual. The overlay of colors and their opacity leads to different effects depending on the relative values of Measure, Projection, and Compare To shelves:
- In Example 1, this appears in pale blue and does not terminate the arc. This is because the value on the Projection shelf is less than the Compare To value.
- In Example 2, Projection appears in darker grey as extension beyond the lower Compare To value (in pale blue).
- In Example 3, Projection again appears in darker grey, but this time as an extension beyond the darker blue arc that shows by how much the Measure exceeds the lower Compare To value.
The Compare To shelf shows the target value for the measurement. In these examples, it has a value of 800 for all gauges.
The secondary outer arc shows the Qualitative Ranges that form the upper limits of the 'goodness' for the current measurement. From the origin to the upper value, they specify relative levels of performance success. You may define anywhere from 0 to 4 qualitative ranges.
The Label shelf overrides default labeling taken from the Measure shelf. This is an opportunity to clarify what is being measured, as well as the units of measurement. This shelf accepts a maximum of two values.

Like other CDP Data Visualization visuals, the Gauge visual may be trellised using X and Y shelves, have additional fields on the Tooltips shelf, and use Filters. For more information, see Shelves for gauge visuals.

We are working with the District Performance dataset, built on a datafile that contains the California School District APIs from 2012 and 2013. The range of possible scores varies from a low of 200 to a high of 1000. However, the statewide API performance target is 800.

Start a new visual based on dataset District Performance.

For more information, see Adding data, Creating datasets, and Creating a visual.
In the visuals menu, find and click Gauge.

The shelves of the visual changed. The Measures shelf is mandatory.
Populate the shelves from the available fields (Dimensions, Measures) in the DATA menu.
1. For the Measure shelf, add the field Api13.
2. Customize the expression to calculated the waited average of the field, based on the number of students tested in each district (field Valid).
  1. Click the (right-arrow) icon to the left of the field, and select the [ ] Enter/Edit Expression option.
  2. In the Enter/Edit Expression modal window, change the expression to the following formula:
```
floor(sum([Api13]*[Valid])/sum([Valid]))
```
  3. Click VALIDATE & SAVE to ensure that everything works.
3. For the Compare To shelf, add the field Api13.
4. Customize the expression to change it to the state-wide target of API=800.
  1. Click the (right-arrow) icon to the left of the field, and select the [ ] Enter/Edit Expression option.
  2. In the Enter/Edit Expression modal window, change the expression to the scalar value of 800.
  3. Click VALIDATE & SAVE to ensure that everything works.
5. For the Qualitative Ranges shelf, add the field Api13.
6. Specify the equation that returns the upper limit of the first qualitative range. For this visual, the example uses simple scalar values.
  1. Click the (right-arrow) icon to the left of the field, and select the [ ] Enter/Edit Expression option.
  2. In the Enter/Edit Expression modal window, change the expression to the scalar value of 600.
  3. Click VALIDATE & SAVE to ensure that everything works.
7. Optional: To create other ranges:
  1. Click the (right-arrow) icon to the left of the field, and select the Duplicate option.
  2. Open the Enter/Edit Expression modal window for the duplicate and change the value.
  3. Click VALIDATE & SAVE.
  In this example, we defined three ranges: at 600, 700. and 800, and we aliased the qualitative ranges as Poor, Improving, and Satisfactory, in that order.
  
  An alternative to specifying qualitative ranges through the shelf is to calculate them as percentages of the Compare To field. To do that, follow the instructions in.Specifying qualitative range as percentages.
8. For the Projection shelf, add the field Api13.
9. Specify the equation that projects the current measurement to some future date by clicking the (right-arrow) icon to the left of the field, selecting the [ ] Enter/Edit Expression option, and changing the expression to the following SQL clause:
```
if(  sum([Api13]*[Valid])/sum([Valid])>800,
     sum([Api13]*[Valid])/sum([Valid])+25,
     sum([Api13]*[Valid])/sum([Valid]) + 50)
```
10. For the Label shelf, add the field Api13, and convert the expression to the following SQL clause:
```
concat("API: ", cast(floor(sum([Api13]*[Valid])/sum([Valid])) as string))
```
  You can add the field Cname under the first field and change its aggregation to max([Cname]).
11. For the Tooltips shelf, add more fields here to provide additional information.
  In this example, the following tooltips are used:
  - floor(sum([Api12]*[Valid])/sum([Valid]))
  - floor(sum([Api13]*[Valid])/sum([Valid])) - floor(sum([Api12]*[Valid])/sum([Valid]))
  - sum([Valid])
  It is good practice to apply an alias to these fields. In this example, the following aliases are used: 2012 API Score, 2012 -> 2013 Growth, and Students.
12. For the Filters shelf, add the filters youo need.
  
  In this example the following filters are used: Cname for name of the County, selecting the values Alameda, Kings, Marin, Mendocino, Sierra, and Siskiyou.
13. For the Y shelf, add the field Cname (county name) to trellis the visual, and lias it as County.
Optional: Click the Settings menu, select Trellis, and de-select the Show trellis borders option.
Click the Settings menu, select Marks, and select the Include a gauge line option. For more information, see Displaying the gauge needle.
Optional: Click the Colors menu, and select different options for Foreground Color, Pointer Color, and Background Color from the color palette menu. You may change the Projection Opacity and Background Opacity options too. In this example, they haven't been changed.
Optional: Alias the fields. In this example, the names of the shelves are used for each alias.
Click REFRESH VISUAL.

The new Gauge visual appears.
Change the title to District Performance, by County - Gauge.
- Click (pencil icon) next to the title of the visualization to edit it, and enter the new name.
- You can click (pencil icon) below the title of the visualization to add a brief description of the visual.
At the top left corner of the Dashboard Designer, click SAVE.

To adjust the gauge display, check all the available settings for this visual.