Using the Custom Dialog Builder in IBM SPSS Statistics to Create Custom UIs that Produce Specialized Output
The Custom Dialog Builder (a.k.a. “CDB”) feature in IBM SPSS Statistics has long existed as a means to produce custom user interfaces that generate syntax that drives user-defined backend extensions. This is a valuable capability that enables educators, administrators, and others to tailor the software with their own procedures: See the online Extensions topic for more information.
In this posting I will demonstrate two less well-known capabilities of the CDB that also work in Compatibility Mode: The ability to customize existing procedures to make the creation UI simpler and to consolidate output from more than one procedure. As the creator and implementer of the original CDB back in the early 2000s, it is my pleasure to return to this tool in this blog posting to revisit some of the cool features there.
When using the Custom Dialog Builder, custom dialog UIs can be created that are independent of custom backend extensions. This enables us to take existing procedures and present them in new ways for specific purposes. For example professors may wish to tailor their students’ dialog UIs to adhere more closely to lessons; senior analysts who want to roll out standard analyses for their teams to use; etc.
What we are Producing
For this example we will create a custom dialog UI that consolidates features from the Descriptives and the Frequencies procedures. In it we will simplify the user interface needed to generate both DESCRIPTIVES and FREQUENCIES syntax, and we will also hide and rename selected output items to produce a simple and targeted output document. Full disclosure: I am not a data scientist and thus cannot speak to the statistical value of this specific example as it is being described here for demonstrative purposes only. The techniques used however, apply generally to any procedure or output and should thus prove useful for a variety of user scenarios.
We will start with the broadband_1.sav sample data file that comes with the Statistics application. That dataset contains a number of columns representing specific segments of the market at particular month/year points. In this example we wish to leverage the feature in Descriptives in which the variable output table ordered by descending means. That capability is not present in the Frequencies procedure, which itself supports a Histogram with a normal curve that is not supported in Descriptives. In this posting we will be combining those two features using a single creation dialog and presenting output in a simple and unified display.
Step 1: Launch the CDB Authoring Tool
So let’s begin. First we will open the Custom Dialog Builder in Compatibility mode in order to able to work with Statistics versions prior to version 24. This is accomplished by selecting the “Extensions -> Utilities -> Custom Dialog Builder (Compatibility mode)” main menu item:
Step 2: Build the CDB Specification
We are then presented with the CDB authoring mode UI, which looks like this. Note the left-side palette from which controls are dragged to the canvas:
Step 2a: Set Up Variable Lists
We can now drag controls from the left-side palette onto the authoring canvas. For this example we will allow users to select only numeric variables with the measurement level set to scale. To accomplish this we first drag out a Source List control from the palette, then we add a Target List control to receive variable selections beside it.
Next we open the Variable Filter dialog by selecting the target list and choosing the Variable Filter button as shown below. Here we want to select only non-string type variables that have a Scale measurement level:
Step 2b: Add Histogram Options and Setup Control Properties
In the next step we will add the ability to generate a histogram for a selected variable. We will also allow the user to add a normal curve on the generated chart. To do that we drag another target list onto the canvas and drop it below the first target list. We then drag a checkbox control below the second target list to allow normal curve creation.
As circled below, each canvas control contains an associated property editor. In this case we use histogram_variable as the unique identifier for the histogram target list. We also setup a control title, tooltip and mnemonic key as seen here:
Note too that we have made both variable target lists in this UI Required for execution, which means that the OK and Paste buttons on the custom dialog will only be enabled when there is at least one variable present in each list.
The Syntax field in the property editor is for describing the syntax that each control generates. The default is %%ThisValue%%, which indicates that we wish for the default syntax be generated for this control. In the case of target variable lists %%ThisValue% equates to a space-delimited list of selected variable names. In general one uses the ThisValue constant or other control identifiers between double percent symbols (%%identifier%%) to setup replacement values within any generated syntax.
We can also now set the identifiers, labels, tooltips, etc., for the other controls. Of interest in the case of the Normal Curve checkbox is the fact that checkboxes have two possible syntax snippets they can generate. In this case when the checkbox is selected we generate the term NORMAL, and when the checkbox is unselected we do not generate any additional syntax:
Step 3: Create the Syntax Template
Custom dialogs generate Statistics syntax. To associate this dialog with the syntax that it will generate, we need to set up a template in the Syntax Template panel of the CDB.
For this example we are combining elements from both the Descriptives and the Frequencies procedures. We start with the basic specification we want, then add replacement values that are sourced from our UI. Here we have DESCRIPTIVES syntax in which the list of possible values for the VARIABLES keyword are presented in a menu whenever one holds down the control key and presses the spacebar at the same time:
When complete our syntax template contains hard-coded values for the statistics in our Descriptives output, with variables sorted by descending means. There is also a histogram from the Frequencies procedure in which the tables have been suppressed. We will also add two OUTPUT MODIFY commands at the end of the syntax template to hide the logs and to delete the Statistics table from the Frequencies procedure.
Step 4: Test the Custom Dialog
The next step is to test our custom dialog to ensure that it performs properly. Fortunately, the CDB comes equipped with a built-in test harness that allows authors to check their work and the generated syntax before deploying the dialog. We accomplish this by pressing the Preview toolbar button near the top of the CDB authoring tool:
Now we can execute the dialog and see it as it will appear when deployed. A sample dataset is provided with the preview test harness to allow authors to exercise rules and syntax. In this case we can see our variable filters are working properly when we attempt to add any non-numeric or non-scale variables to the target list:
Step 5: Test the Generated Syntax
We can also test the generated syntax at this time. To do that we complete the required specifications for the dialog and then press the Paste button. Here we can see the syntax is generated as expected. We cannot execute that syntax yet however, since the variables used are only metadata from the dummy Test Harness dataset.
Step 6: Locate the New Custom Dialog in the Menu System and Deploy
We can now decide where we would like our new custom dialog to appear in the menu system. To accomplish this we deselect all controls on the canvas, which has the effect of activating the property editor for the entire dialog (“Dialog Properties” below). There we see a Menu Location property button which we press to activate the Menu Location dialog.
The entire Statistics menu hierarchy is represented in this dialog, thereby enabling us to select the exact position for our new menu item. We can also set the menu item label, an optional icon, and whether there should be a menu item separator above or below the new menu item:
When your custom dialog is ready, deploying it is a snap – simply press the Install toolbar button:
You can also save your CDB specification in a .spd file for later use. Press the Save toolbar button to create files that are portable representations of custom dialogs. These can be sent and imported as a unit into other instances of SPSS Statistics, or opened again later for enhancing existing specifications. We can close the Custom Dialog Builder for now.
Step 7: Putting it all Together
Now we can open the broadband_1.sav sample data file in order to test the procedure UI and the output. This can be done either by browsing to the samples folder and selecting the file, or by issuing the following syntax command from a syntax window (the path is specific to MacOS):
GET FILE='/Applications/IBM SPSS Statistics/SubscriptionNew/Samples/English/broadband_1.sav'.
One of the nice features with custom dialog deployment is the ability to deploy new UIs in real time without requiring a restart of the application. Once you have finished deploying and/or saving your new custom dialog from the CDB, simply close the authoring tool and look in the main menus for your newly deployed dialog:
You can then select the new menu item to use your dialog. Here we use the variables representing regional market subscribers for the Descriptives table, and use the “Total Number of Subscribers” variable to generate the histogram:
When pasted, the syntax generated from the above dialog looks like this:
When we then execute the above syntax we receive the following output. Note the variables in the Descriptive Statistics table sorted by descending means:
In this posting we have exercised some of the capabilities of the Custom Dialog Builder when used without backend Extensions. Using syntax from existing procedures, this tool enables interesting combinations of syntax and output that can be tailored to specific requirements. The following online Help topic contains more information on using the CDB: https://www.ibm.com/support/knowledgecenter/en/SSLVMB_26.0.0/statistics_mainhelp_ddita/spss/base/idh_idd_uibuilder.html
This is just a sampling of what one can accomplish with the CDB; a powerful tool for customizing the user interface of IBM SPSS Statistics, one that can be used in a variety of ways.