Custom Visualizations

From the Formulate module, you can create sharable custom visuals, that other users can leverage in their data discoveries. Custom Visualizations allow users to create their own data visualization logic to draw query results using representations that are not covered by the built-in library of standard charts and visualizations.

Custom visuals are created in Formulate, and can then be used in Discover to represent your data discoveries. Here, they are designed in concert with the Custom Visual APIs to program the way the engine will draw the query results to screen. As with any other visual, a custom visual saved as a data discovery can then be used in presentations, and publications.

Note: this feature is available only with Enterprise licensing.

Build a Custom Visual

To access the custom visual builder, go to Formulate, and select Visual. This will open the Custom Visual wizard, where you can build your visualization. To start, open the Formulate module and then choose the sample data model to use for testing your custom logic.

Note: at any point you can click the Apply button to see a preview of your custom visual, however, you must be sure to add hierarchies and measures to the query in order to see a preview:

Step 1

From the Metadata panel, you can name your custom visual, add a description, and upload an icon.

Step 2

Work through the Custom Visuals wizard, starting at the Drop Zones tab. This is where you can specify what drop zones should appear when your custom visual is selected in Discover; select the required drop zones. You can then define:

  • Caption: the name of the drop zone.
  • Required: select Required if the custom visual shouldn't be draw if there is no chip added to the specified drop zone.
  • Chip Type: choose whether the specified drop zone must contain a hierarchy, or a measure. If the drop zone should be enabled for both hierarchies and measures, choose None.
  • Priority: select the order in which drop zones should be utilized for the specified chip type. For instance, assign a Hierarchy chip type to Columns, Rows, and Filters. Then assign a Priority of 1 to Columns, 2 to Rows, and 3 to Filters; when hierarchies are selected via double-click from the Dimensions panel in Discover, the first chip will be automatically added to Columns, the second to Rows, and the third to Filters.

Step 3

From the Script tab, you can write the script for your custom visual. You can also download a custom visual script by opening the Marketplace in the ribbon. Click Apply to apply changes to the preview.

Use the Explain Script function (arrow) to understand the current script by producing an AI-generated explanation of what it does. Each time you click the Explain Script button, a new explanation is generated. This explanation can be generated regardless of the method used to generate the script. For more information, see Explain Script.

This explanation can be copied, and then pasted into the node Description field, for instance.

  • Apply: apply changes made in the currently selected panel. Click this button after making changes in each panel, to update the preview as you work.
  • Apply to All: apply changes made in all panels. Click this button to see all changes in the preview, regardless of the selected panel.
Step 4

When you've finished configuring the visual, click the save icon above the canvas. Save your visual to the CMS.

Once you've saved your visual, it will appear in the custom visuals pop-out from the canvas menu, and can be used as a visualization.

You can access the custom visual's logic from the CMS the asset is saved under the name given when it was saved to the CMS. Like other assets, you can open it, edit it, and open its Actions Panel.

Custom Visual Scripting and API

There are two ways to create custom visuals:

  • Download a visual from the Marketplace (in the ribbon) for a fully scripted solution
  • Add your own custom visual script in the Script panel

You can add your own script from the Script panel. The template in the Script window contains several API functions. Of these, the MyCustomVisual function must be implemented, and the custom visual must be built in one chunk (not trellised).

You can reference any other external JavaScript library to build your own visualizations, including D3, High charts and Plotly.

It is important to understand that blue chips (hierarchies) affect the number of data points in a query, but orange chips (measures) don't.

Custom Visual Marketplace

The Custom Visual marketplace includes many charts that have been either developed by Pyramid or by Partners. The following chart types have been developed by Pyramid, are included OOTB with the product deployment and operate like any other normal chart included in the product. They represent examples of how to develop a custom visualization with the API.

  • Diverging Stacked Bar Chart
  • Aster Plot
  • Heat Grid
  • Measure Waterfall
  • Chord Diagram
  • Network Diagram
  • Gantt Chart
  • 2D Density plot
  • 3D scatter plot
  • Tabular Grid
  • Data Card

Securing Custom Visuals

By default, all users will see your custom visual in Discover, even if it was saved in My Content. From the Profiles tab in the Admin console, permissions for custom visuals can be changed in order to govern which roles can create and view them.