Using Parameters
In addition to using static values and data selection, you can use Heavy Immerse parameters to change chart values.
Overview
Parameters are a powerful tool for manipulating charts in Heavy Immerse. You can use parameters to do the following:
Quickly switch measures and dimensions on a chart from a centralized location on the dashboard.
Analyze scenarios using parameters in custom SQL, for quick iteration and replacement of values in a custom SQL formula (typically measures).
Perform projections, estimations, and 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
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 new parameters from the left pane.
You can also open the Parameter Manager from a chart by typing ${ at the end of the chart title. Any existing parameters are shown in a dropdown box.
In the Parameter Manager, you create and define one of four parameter types, described in the following tabs:
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.
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.
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.
Click 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, add the parameter as a pane on the dashboard, 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.
Working with Parameters
This section provides examples of setting up parameters in Heavy 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 - Creating and Changing Flights Charts
This example shows a flight origin and destination chart that you can create, change, and analyze using parameters.
Setup
First, create a chart with the following configuration:
Source: flights
Base dimension: origin_city
Group-by dimension: plane_engine_type
Base measure: # Records
Bar settings: Horizontal, stacked
Parameters
Open the Parameter Manager and create the following parameters:
Type: column
Source: flights
Default value: origin_city
Creating a Chart Using Parameters
You can replicate this chart using the parameters you defined.
On the dashboard, create a new Combo chart.
The defined parameters now appear in the Dimension dropdown lists. Select a1 as the Base dimension and a2 as the Group-by dimension, and #Records as the Base measure.
The dashboard shows two identical charts, but the chart created with parameters has some advantages. For example, you can change the Base and Group-by dimensions without editing the chart. Here, the column in parameter a1 is changed to destination city and the column in parameter a2 is changed to plane type:
The chart created using parameters dynamically changes to reflect the change in column value, and its title reflects the new definition.
Creating a Custom Measure
You can use parameters to create a custom measure.
Open the Custom Measure Editor, define the custom measure avg(flights.depdelay*${m1}) using the departure delay column and parameter m1:
Apply the custom measure, and observe the changes to the chart.
Adjusting the m1 slider dynamically changes the values on the chart. You can add the custom measure information to the chart title by typing ${ and then selecting m1 from the dropdown list. Now, the chart title reflects the custom measure value.
Performing Comparative Analysis
You can perform comparisons easily by duplicating a chart that uses parameters.
Create a copy of the parameter-generated chart and save it to the dashboard.
Now, let's use the car1 and car2 parameters to create filters that you can apply to identical charts and see the differences that occur based on the filter. In the original chart, create a filter defined by the car1 parameter:
For the duplicate chart, create a filter defined by parameter car2.
Now the charts use filters defined with parameters. You can change the parameter values to make comparisons between different carriers.
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:
Configuration summary:
Source: tweets_ds_geo
Measures:
Lon: lon
Lat: lat
Filter (Language chart):
lang - Exact match ${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.
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.
Using a URL to Load a Dashboard with Parameters
You can open dashboards using a specialized URL that contains a list of HEAVY.AI parameters. Using the following format, you can load the dashboard in a specific state with values for the parameters you want to apply:
<dashboard_URL>?<tab>&<parameter.parameter_name1=parameter_value1>&
<parameter.parameter_name2=parameter_value2>& ... >dashboard_URLis the Immerse dashboard URL. In the query string that follows, param_name is the name of the defined parameter, and param_value is the assigned value for the parameter.
Parameter URLs provide a high level of flexibility. For example, using URLs, you can set a dashboard dashboard state to vary for different users based on permissions.
For example, the following dashboard tab shows three Bar charts and defined parameters a1 (destination city), a2 (plane type), car1 (Southwest Airlines), and car2 (Skywest).
If you want to open a version of the dashboard where car1 is defined as American Airlines instead of the default Southwest Airlines, you can append ¶meter.car1=American+Airlines to the URL:
Notes
If a parameter values has spaces, replace the spaces with + or %20.
Any hidden parameters would be unhidden after query parameters are overwritten with the value defined in the URL.
Any existing parameters are unaffected if not defined in the URL.
Last updated