Links

Using Parameters

Beginning in OmniSci Release 5.6, in addition to using static values and data selection, you can now use Immerse parameters to change chart values.

Overview

Parameters are a powerful tool for manipulating charts in Immerse. You can use parameters to do the following:
  • Quick switching of measures and dimensions on a chart from a centralized location on the dashboard.
  • Scenario analysis using parameters in custom SQL, for quick iteration and replacement of values in the custom SQL formula (typically measures)
  • Perform projections, estimations, and scenario planning
  • Control chart-specific filters on multiple charts at a time, which is helpful for comparison use cases
  • Customize the dashboard for the end user; parameters enable all tabs to reference the same data (parameterizing filters across tabs)
The following figure shows the Parameters pane on the dashboard. The parameters defined (Left Map Display and Right Map Display) enable you to change values that previously could only be altered at the individual chart level.

Setting Up Parameters

Use the Parameter pane to create and manage parameters in Immerse. _**_The Parameters pane provides access to the Parameters Manager, which you use to create, modify, and delete parameter definitions. You can also use the Parameters pane to add and remove parameters to and from a dashboard or dashboard tab, edit a parameter, and make a parameter dashboard-wide or localized to the selected dashboard tab.
To open the Parameters pane, click the Parameters tab on the dashboard.

Creating a New Parameter

In the Parameters pane, click Add parameter to open the Parameter Manager. You can also click the Open parameters manager icon in the upper-right corner of the pane.
If you click Add parameter in a dashboard that has existing parameters, the parameters that have been created for that dashboard are listed. To create a new parameter, click Create new at the bottom of the parameters list, or click the Open parameters manager icon.

Using the Parameter Manager

Use the Parameter Manager to create, modify, and delete parameters.
The left pane lists the parameters in use on the dashboard. In the example above, no parameters exist yet, so the list is blank. You can also search for parameters and create a new parameters from the left pane.
In the Parameter Manager, you create and define one of four parameter types, described in the following tabs:
Custom
Number
Column
Column Value
A custom parameter provides flexibility in defining default values, particularly SQL formulas.
  • Parameter name - Name of the parameter. Cannot be changed after parameter creation.
  • Default value - Default value of the parameter. Can be a formula, a numeric, or a string.
  • Description (optional) - Notes that help describe the parameter.
  • Parameter name - Name of the parameter. Cannot be changed after creation.
  • Default value - The default numerical value.
  • Min (optional) - Minimum numerical value.
  • Max (optional) - Maximum numerical value.
  • Description (optional) - Notes that describe the parameter and its use.
  • Parameter name - Name of the parameter. Cannot be changed after creation.
  • Source - Source table for the parameter.
  • Default value - The default column.
  • Description (optional) - Notes that help describe the parameter.
  • Parameter name - Name of the parameter. Cannot be changed after creation.
  • Source - Source table for the parameter.
  • Column - Name of the table column.
  • Default value - The default column value.
  • Description (optional) - Notes that help describe the parameter.
Once you create a parameter, it is added to the parameters list in the left pane of the Parameter Manager. Here, you can search for parameters, see their types and default values, list them in ascending or descending alphabetical order, or delete them.
You cannot delete a parameter that is being used by a chart on the dashboard.

Managing Parameters

In the Parameters pane, you can add and remove parameters, change their values, and determine whether they are applied locally to a tab or across all tabs on the dashboard. The pane shows the parameters used on that dashboard or tab.
To add parameters to a dashboard or tab, click Add Parameter and select the parameter from the list. You can also search for the parameter.
Clicking the More Options icon on a parameter to make a parameter local to a tab, edit the parameter (which opens the Parameter Manager), reset the value to the default, or remove the parameter from the tab.
You can also reset the value to the default by clicking the reset icon to the right of the parameter value. Hovering to the left of the value shows whether the parameter is synced across tabs or local to the open tab.
You can only remove the parameter if it is not being used by a chart on the tab or dashboard.

Working with Parameters

This section provides examples of setting up parameters in Immerse and demonstrates how parameters can be used in various scenarios. It walks through the setup of dashboard tabs and charts and shows how to add parameters and change values.

Example - Tweet Language

This simple example shows maps of tweets for different languages and uses parameters to change languages and make comparisons.

Setup

The Tweet Language example has two charts--Language and Comparison Language--that provide information from the tweets_2007_may database. Both charts have the same configuration, except for the filters applied:
Language
Comparison Language
Configuration summary:
  • Source: tweets_2007_may
  • Measures:
    • Lon: lon
    • Lat: lat
  • Filter (Language chart):
    • lang - Exact match ${Language}
Configuration summary:
  • Source: tweets_2007_may
  • Measures:
    • Lon: lon
    • Lat: lat
  • Filter (Comparison Language chart)
    • lang - Exact match $(Comparison Language)

Parameters

Opening the Parameters pane shows the following parameters used on this dashboard tab:
  • Comparison Language - Column value parameter from the column lang with default value es.
  • Language - Column value parameter from the column lang with default value en.
You can also see the details for these parameters by opening the Parameters Manager. Here, the Language parameter is selected. The left column shows all of the parameters used on the dashboard.

Changing the Charts with Parameters

Instead of opening the chart to make changes to the language displayed, you can make those changes in parameters. For example, the following dashboard tab shows Language as Portuguese (pt) and Comparison Language as French (fr), with geographical concentrations appearing where you might expect.

Example - Flight Comparison Use Case

Setup

The Comparison Use Case has six charts that provide information from the flights database:
  • Average distance for carrier 1
  • Average distance for carrier 2
  • Number of records by arrival timestamp for carrier 1
  • Number of records for arrival timestamp for carrier 2
  • Destination longitude and latitude for carrier 1
  • Destination longitude and latitude for carrier 2
The following tabs show the configuration details for each chart.
Avg Distance - Carrier 1
Avg Distance - Carrier 2
# Records by Arr_timestamp - Carrier 1
# Records by Arr_timestamp - Carrier 2
Dest_lon, Dest_lat - Carrier 1
Dest_lon, Dest_lat - Carrier 2

Parameters

Opening the Parameters pane shows the following parameters used on this dashboard tab:
  • Carrier 1 - Column value parameter from the column carrier_name with default value American Airlines.
  • Carrier 2 - Column value parameter from the column carrier_name with default value American Airlines.
  • Group by dimension - Column parameter with default value plane_model.
You can also see the details for these parameters by opening the Parameters Manager. Here, the Carrier 1 parameter is selected. The left column shows all of the parameters used on the dashboard.

Changing Charts Using Parameter Values

Parameters allow you to easily change the measures and dimensions on the Comparison Use Case tab.
For example, changing the name of the carrier in the parameter affects all charts on the tab. Here, Carrier 1 is changed to Alaska and Carrier 2 is changed to United. You can see how values have changed across all charts.
Now, let's change the Group by dimension to origin. Note that the only chart that changes is #Records by Arr_timestamp - Carrier 1, because it is the only chart with the custom dimension affected by this column change.