Skip to content

Drawing Custom Charts

Subscription Tier Required

This feature requires the Premier subscription tier or higher.

Although GS comes with a variety of built-in charts, sometimes additional visualizations are desired. GS allows you to create custom charts using Plotly Settings, giving you nearly unlimited customization and analysis potential.

In this guide, you will create a dial gauge indicator to display the Cpk of a Characteristic.

You should be familiar with the principles of Dashboard Scripting before getting started.

Prerequisites

This guide assumes that you have at least one Characteristic which has enough data to determine the Cpk.

Create the Dashboard

To begin, create a new Dashboard. The fastest way to create a new Dashboard is to navigate to the Quick Chart menu entry, which acts as a shortcut for a new Dashboard.

Add a Retrieval

Next, add a Retrieval:

  1. Press the Add Retrieval button. An image showing the location of the Add Retrieval button on the Dashboard
  2. Fill in the Retrieval Name with CPK Demo.
  3. Change the Script ID to cpkDemo. An image showing the Name and Script ID fields
  4. Modify the Date field to a range which includes data for your Characteristic. An image showing the date field
  5. Change the Retrieval Type to Characteristic.
  6. Select your Characteristic in the Characteristics field. An image showing the characteristic field
  7. (Optional) Update the Maximum Records to Retrieve per Standard to include enough data for a reasonable Cpk.
  8. Press Confirm. An image showing the confirm button

Add a Scripted Chart

Add a Scripted Chart and resize it to the full width of the Dashboard. Change the Script ID to dialGauge and the Label to CPK.

An image showing the Scripted Chart button

Scripting

Now that the Dashboard has been set up, you can begin scripting. Create a new Dashboard Script and give it a memorable name. If this interface is unfamiliar, review the Dashboard Scripting Principles and Code Editor articles.

An image showing the location of the Dashboard Script action

An image showing the location of the add button in the Dashboard Script overlay

The tasks we will use scripting to accomplish are:

  1. Listening to the Dashboard Ready function.
  2. Creating a new AlsoRetrieveApi.
  3. Binding to the AlsoRetrieveApi to draw the dial gauge when the Retrieval runs.
  4. Drawing the dial gauge.

Binding to the Dashboard Ready Function

In the newly created Dashboard scipt, add an onReady event handler:

gsApi.dashboard.onReady(async () => {

});

This event fires when the Dashboard has fully loaded. Attempting to interact with Retrievals or Dashboard Items before the Dashboard is ready will result in errors.

Creating the AlsoRetrieveAPI

Inside of the onReady event, create a new AlsoRetrieveApi. Typically, a given Retrieval will only fetch data for the Dashboard Items which utilize it. However, by creating an AlsoRetrieveApi, it is possible to force the Retrieval to fetch additional data:

gsApi.dashboard.onReady(async () => {
    const alsoRetrieveAPI = await gsApi.dashboard.retrieval('cpkDemo').alsoRetrieveWhenRefreshed([{
        type: 'stats', // Inform the retrieval that it must fetch stats in addition to anything else being fetched
        splitBy: ['characteristic'], // One detail per Characteristic
        id: 'dial-cpk', // A unique ID to use to access the data later
        stats: { spc: ['cpk'] } // The requested stats
    }]);
});

Information

It is typically a bad idea to bind to an event while inside the handler of another event, as this will result in duplicate handlers being created. However, because the onReady event will only fire once, other events may be created while executing this event. Unlike most other GS APIs, the AlsoRetrieveApi requires that the Dashboard is ready before it may be created.

This API contains an event which runs every time the Retrieval has finished retrieving data, and provides access to the requested data:

alsoRetrieveAPI.onRetrieved(async (e) => {
    const cpk = e.data.response.stats?.['dial-cpk'].spc?.[0].stats.cpk;
});

The data inside of the event argument contains a response object. The response object has a list of the possible properties that could have also been retrieved. For this guide, we have requested additional stats. Inside of the stats object is a mapping of the user-provided unique IDs to their responses. Because we passed in the ID dial-cpk, that will be returned in the response.

Inside of this object are the possible data types for each stat. Cpk is an SPC stat. This object would typically contain one set of stats for each unique grouping in the provided splitBy. As we only selected a single Characteristic, there is only one grouping. From there, we retrieve the cpk statistic.

Feel free to explore the various properties on the response, or see AlsoRetrieveFinishedEventData for more information.

Drawing the Chart

Now that the Cpk has been obtained, draw the Dial Gauge. This code is a modified version of the Plotly Gauge example. Note that any valid Plotly object may be passed in to the draw function of the Scripted Chart. For more information about the properties being used, see the Plotly Indicator Reference.

alsoRetrieveAPI.onRetrieved(async (e) => {
    const cpk = e.data.response.stats?.['dial-cpk'].spc?.[0].stats.cpk;
    await gsApi.dashboard.scriptedChart('dialGauge').draw([{
        data: [
            {
                type: "indicator",
                mode: "gauge+number",
                value: cpk,
                gauge: {
                    axis: { range: [null, 2.5], tickwidth: 1, tickcolor: "darkblue" },
                    bar: { color: "darkblue" },
                    bgcolor: "white",
                    borderwidth: 2,
                    bordercolor: "gray",
                    steps: [
                        { range: [0, 1], color: "red" },
                        { range: [1, 1.333333], color: "orange" },
                        { range: [1.333333, 2.5], color: "green" }
                    ],
                }
            }
        ],
        layout: {}
    }]);
});

Testing the Dashboard

Save and View the Dashboard. If you have not previously saved the Dashboard, fill in the Name overlay with Custom CPK Gauge. The Dashboard should load with a single Dial Gauge.

An image showing the final dial gauge

Additional Exercises

On your own, attempt to:

  • Modify the thresholds and colors of the Gauge.
  • Use a Retrieval for multiple Characteristics, and draw a separate Gauge for each one.
  • Keep track of the previous reading, and change the gauge to include a delta value showing the difference between readings.

Final Code

gsApi.dashboard.onReady(async () => {
    const alsoRetrieveAPI = await gsApi.dashboard.retrieval('cpkDemo').alsoRetrieveWhenRefreshed([{
        type: 'stats', // Inform the retrieval that it must fetch stats in addition to anything else being fetched
        splitBy: ['characteristic'], // One detail per Characteristic
        id: 'dial-cpk', // A unique ID to use to access the data later
        stats: { spc: ['cpk'] } // The requested stats
    }]);

    alsoRetrieveAPI.onRetrieved(async (e) => {
        const cpk = e.data.response.stats?.['dial-cpk'].spc?.[0].stats.cpk;

        await gsApi.dashboard.scriptedChart('dialGauge').draw([{
            data: [
                {
                    type: "indicator",
                    mode: "gauge+number",
                    value: cpk,
                    gauge: {
                        axis: { range: [null, 2.5], tickwidth: 1, tickcolor: "darkblue" },
                        bar: { color: "darkblue" },
                        bgcolor: "white",
                        borderwidth: 2,
                        bordercolor: "gray",
                        steps: [
                            { range: [0, 1], color: "red" },
                            { range: [1, 1.333333], color: "orange" },
                            { range: [1.333333, 2.5], color: "green" }
                        ],
                    }
                }
            ],
            layout: {}
        }]);
    });
});