Chapter 2: Stitching It Together
Stitching Saved Scripts Together
Combining Summary Data with an Analysis
Combining Data Import, Summary, and Two Analyses
Saving the Analysis Script to an Add-In
After reading chapter 1, you should know how to get scripts from JMP and combine them into a single Script window. In this chapter, we show you how to stitch the individual scripts together with a few JSL tricks, so that a single script will complete a variety of tasks for you at the click of a button.
In this chapter, you will learn about the following:
● stitching together a Summary table and one analysis
● stitching together the import of Excel file data, a Summary table, and two analyses
● creating a custom add-in that will execute a script
Your manager is thrilled with the information that you have been giving her. Now, in addition to what you have already been producing weekly, she wants the data summarized, along with some further analysis.
In the previous chapter, you learned how to make JMP write the scripts for you. You also learned how to put two independent scripts together so that they are executed consecutively.
Now, we will continue to show you how easy it is to combine multiple scripts. However, this time you will have to do a small amount of coding to ensure that the scripts will run together successfully.
In this exercise, we create each of the following interactively, and then capture scripts that JMP generates for us:
● summary table from the original data
● Graph Builder Line Chart
Interactive Steps
Our first task is to use the Excel Wizard to import an Excel file containing data about a class of students. Next, we summarize the data by creating a Summary table that produces the mean height for each age by gender.
1. We first check the Excel import preferences to ensure that the Excel Wizard will be invoked when opening an Excel file. Select File ► Preferences. Select General in the left panel. Set the Excel Open Method to Use Excel Wizard. Set the Use Excel Labels as Heading to Use best guess. Click OK to apply and close the Preferences window.
Figure 2.1 Excel Preferences
2. From the Help menu, select Sample Data.
Figure 2.2 Access Sample Data Index
3. Click the Open the Sample Import Data Directory button in the Sample Data Index window.
Figure 2.3 Sample Import Data Directory Selection
4. In the Open window, select the Bigclass.xls file, and then click Open to open the data table.
Figure 2.4 Select and Open the Bigclass.xls file
5. The Excel Import Wizard window opens. Change the Individual Worksheet Settings to match those in Figure 2.5, if necessary, and then click the Import button.
Figure 2.5 Excel Import Wizard Window
6. The Bigclass table will open, as shown in Figure 2.6.
Figure 2.6 Bigclass Data Table
7. Close the Sample Data Index window.
8. From the Tables menu, select Summary.
Figure 2.7 Select Summary Table
9. In the resulting window:
a. Select the height column.
b. Click the Statistics button, and then select Mean.
c. Select the age column, and then click the Group button.
d. Select the sex column, and then click the Subgroup button.
e. Click OK.
Figure 2.8 Summary Window
10. The summary table named Bigclass By (age) is created.
Figure 2.9 Bigclass By (age) Summary Table
Next, we create a Graph Builder Line Chart with connected lines to identify any trends.
11. With the Bigclass By (age) data table as the active table, select Graph ► Graph Builder.
Figure 2.10 Graph Builder Menu Selection
12. In the resulting Graph Builder window, click the Dialog button.
Figure 2.11 Selecting the Dialog Option
13. In the Dialog window:
a. Select the Mean(height, F) and Mean(height, M) columns.
b. Click the Y button.
c. Select the age column, and then click the X button.
d. In the Options panel, select Points and Line.
e. Click OK.
Figure 2.12 Graph Builder Dialog Window
14. When the Graph Builder Line Chart appears, click the Done button.
Figure 2.13 Click Done Button
Now, we have created the Summary table and the Graph Builder Line Chart.
Figure 2.14 Summary Table and Graph Builder Line Chart
Next, we will extract the scripts that JMP generated for us and combine them in a single script.
Extracting the Scripts
As you saw in chapter 1, table scripts are a bit different in that you cannot simply save the script to a Script window like we could if we were saving the script from an analysis. Therefore, we need to open a new Script window where the scripts can be pasted.
1. From the File menu, select New ► Script.
2. From the Window menu, select Bigclass By (age) to locate the Summary table.
3. When the Summary data table is in view, open the Source table script by right-clicking the green triangle, and then selecting Edit.
Figure 2.15 Edit Summary Source Script
4. In the resulting window, select the entire script and copy it by right-clicking the script and selecting Copy.
Figure 2.16 View of Summary Source Script
5. Click OK to dismiss the Source Table Script window.
6. From the Window menu, select Script to locate your new Script window.
7. Paste the script by clicking the Edit menu and selecting Paste.
8. Add a semicolon after the last closing parenthesis.
Figure 2.17 Pasted Summary Script
|
|
Notice that the previous Script window displays line numbers. You can turn on the line numbers option by right-clicking the Script window and selecting Show Line Numbers from the context menu. |
Next, we copy the Graph Builder Line Chart script.
1. From the Window menu, select Bigclass By (age)- Graph Builder of Mean(height, F), Mean(height, M) by Age to locate the Graph Builder Line Chart report.
2. In the Graph Builder window, click the red triangle, and then select Save Script ► To Clipboard.
Figure 2.18 Copy Graph Builder Line Chart script
3. Go back to the Script window and press the Enter key a couple of times to move the cursor down a few lines.
4. Paste the script into the Script window by selecting Edit ► Paste.
Figure 2.19 Paste Graph Builder Line Chart Script
5. Add a semicolon after the last closing parenthesis.
6. Use the Window menu to locate the Bigclass By (age)- Graph Builder of Mean(height, F), Mean(height, M) by Age report window, and then close it. Repeat these steps to locate and close the Bigclass By (age) data table.
Coding Changes
Now this script looks pretty good, but there is a potential problem. This code depends on the current data table being the Summary table. Although this example script might run without error, in real life, JMP will probably be doing more in the background, which could cause a change in the current data table. We will discuss background tasks in more detail as we go along.
If the current data table gets changed and you run this code, JMP will return error messages to the log as shown here.
Specified Column not found in data table. in access or evaluation of 'Y' , Y( :Name( "Mean(height, F)" ) ) /*###*/ Exception in platform launch in access or evaluation of 'Graph Builder' , Graph Builder(/*###*/Size( 528, 454 ), Show Control Panel( 0 ), Variables( X( :age ), Y( :Name( "Mean(height, F)" ) ), Y( :Name( "Mean(height, M)" ), Position( 1 ) ) ), Elements( Points( X, Y( 1 ), Y( 2 ), Legend( 1 ) ), Line( X, Y( 1 ), Y( 2 ), Legend( 2 ) ) ) ) In the following script, error marked by /*###*/ Graph Builder( Size( 528, 454 ), Show Control Panel( 0 ), Variables( X( :age ), Y( :Name( "Mean(height, F)" ) ) /*###*/, Y( :Name( "Mean(height, M)" ), Position( 1 ) ) ), Elements( Points( X, Y( 1 ), Y( 2 ), Legend( 1 ) ), Line( X, Y( 1 ), Y( 2 ), Legend( 2 ) ) ) )
What does all that mean?
These error messages indicate that JMP cannot find the columns Mean(height, F) and Mean(height, M). These columns are not found because JMP is looking at the original Big Class data table, rather than at the Summary table.
How do we correct this?
First, we assign a name (you can think of it as a nickname) to the Summary table using an assignment statement. This name is also known as a global variable. Global variables are references you assign that remain throughout the JMP session. A discussion of global and local JSL variables is covered in chapter 4.
|
Unlike other languages, JMP does not require that you first declare the global variable. Simply assign it to an object, such as a data table, and start using it! |
1. In the script, set the Summary table name to be sumDT, as shown in Figure 2.20.
Figure 2.20 Data Table Name Assignment
In this example, sumDT will continue to represent the Bigclass By (age) Summary table until the data table is closed, sumDT is redefined, or you close JMP.
Next, we tell JMP that the Graph Builder Line Chart should be created using the data stored in the Summary table rather than in the original Bigclass data table.
In order to accomplish this task, it is important to understand that JSL is a powerful language that is built upon the concept of sending messages to JMP objects in order to tell them what to do.
Here is the basic form of a JSL statement:
object << Message( Argument );
where << is the send operator.
1. In the script, send the Graph Builder message to the Summary data table by adding sumDT (as the object) and the send operator (<<), as shown in Figure 2.21. You can assign a reference to the Graph Builder output here, as well. This is helpful if you need to reference the Graph Builder object later in your script.
Figure 2.21 Data Table Specified
|
|
It is an important scripting habit to be what we call data-table specific in your scripts. By sending platform messages to a specific data table reference, you ensure that JMP always looks for the data in the table specified. |
After making these changes, the code will run successfully.
1. From the Edit menu, select Run Script.
Figure 2.22 Sample 2 Results
2. With the Script window active, click the File menu, and then select Save As.
3. Navigate to the same location as the previous example, name the script Sample2.jsl, and then click Save.
Figure 2.23 Save Sample2.jsl
Now that you’ve seen how easy it is to combine scripts of various tasks into one script, we are going to show you something a little more interesting. In this sample, we put together a script that brings in elements from the two scripts that you previously saved.
|
|
If you are following along from the previous sample, close all open analyses, and close the Script window. To do this, click the Window menu, and then select Close All. |
Extracting the Scripts
Because we are bringing in scripts that we stored in JSL files, there won’t be any scripts to capture interactively from JMP. Instead, we will open Sample1.jsl and Sample2.jsl and extract the desired sections of code in order to build the new script.
To begin, open a new Script window by clicking on the File menu and selecting New ► Script. This is where we will build the main script.
Next, extract the code from the Sample1.jsl file:
1. From the File menu, select Open.
2. Ensure the Files of type field is set to All JMP Files.
3. Navigate to the location where you saved the Sample1.jsl file, and then select the file.
4. Click Open.
5. Select the entire script, and then copy it by right-clicking and selecting Copy from the menu.
6. Go back to your main Script window by selecting Window ► Script.
7. Paste the script by selecting Edit ► Paste.
Figure 2.24 Paste Sample1.jsl
4. Locate and close the Sample1 Script window by selecting Window ► Sample1. Then from the File menu, select Close.
So far in the script, we have instructed JMP to import a text file and create a Distribution analysis from it. Next, we will paste in the script from Sample 2 at the end of our current script.
1. From the File menu, select Open.
2. Ensure the Files of type field is set to All JMP Files.
3. Navigate to the location where you saved the Sample2.jsl file, and then select the file.
4. Click Open.
5. Select the entire script, then copy by right-clicking and selecting Copy from the menu.
6. Go back to your main Script window by selecting Window ► Script.
7. Press the Enter key a couple of times to move the cursor down a few lines below the Distribution.
8. Paste the script by selecting Edit ► Paste.
Figure 2.25 Paste Sample2.jsl
9. Locate and close the Sample2 Script window by selecting Sample2 from the Window menu. Then from the File menu, select Close.
Coding Changes
Now, once again we have created a script that looks good but will not run successfully.
Why not? The messages in the log provide a significant hint, as shown here:
And farther down you can locate the error by the /*###*/ marks.
|
|
If your Log window is closed, you can view it by selecting Log from the View menu. |
The problem in this example is that the data table that we want to create our Summary table from is not named Bigclass, but rather Bigclass_L. There are a couple of ways to correct this problem.
● Use the exact table name by specifying it in the Data Table() argument:
sumDt = Data Table( "Bigclass_L" ) << Summary(
Group( :age ),
Mean( :height ),
Subgroup( :sex ),
Freq( "None" ),
Weight( "None" )
);
● Assign a variable to the data table when it is imported, and use the variable name in place of the Data Table() function. This option might require slightly more coding, but actually allows for greater flexibility. See Figure 2.26.
Figure 2.26 Final Script
After making the changes noted in Figure 2.26, run your script to see the results.
Figure 2.27 Final Results
Now that you have a script that does everything your manager wants, save the script to your desired location, and name it WeeklyReport.jsl.
You are finished! You have put together an entire script that will do the following:
● import text data
● create a Distribution of the data
● summarize the data
● create a Graph Builder Line Chart from the summarized data
And all of this has been done with very little code written by you!
You could keep your WeeklyReport script as a JSL file, because JSL files are a great place to store scripts so that they can be opened and executed in the future.
Or perhaps you would rather click a menu item and have JMP perform all those tasks for you at once. This is possible by adding your script as an item in the Add-Ins menu.
In this section, we demonstrate how you can save your script as a JMP add-in. In fact, you could share the JMP add-in with your manager and co-workers so that they will be able to run their own reports.
To create and save the add-in, follow these steps:
1. From the File menu, select New ► Add-In.
2. Select the General Info tab.
a. Enter an Add-In Name for your add-in. This name will appear in the View ► Add-Ins window. We will use My Weekly Report as the name.
b. Enter an Add-In ID, which is a unique string that starts with a character; is no longer than 64 characters; consists only of letters, numbers, periods, and underscores; and has no spaces. The format recommended as shown in Figure 2.28 is called reverse-DNS. Using this format ensures that the Add-In ID is unique. We will use com.ABCcompany.myaddin.
c. Enter the version of the add-in.
d. Enter the minimum JMP version that the add-in works on.
e. Select whether your script runs on Windows, Macintosh, or both JMP operating systems.
f. The Uninstall before reinstalling box should remain selected. This will prevent multiple copies of the same add-in.
g. As the title suggests, checking the Install after save box instructs JMP to install the add-in after you save it. If this box is not selected, then the add-in will not be accessible from the Add-Ins menu until you install it.
Figure 2.28 General Tab
3. Click the Menu Items tab.
4. Click the Add Command button.
There are four areas under Details that affect your menu item:
● General
◦ Enter the Menu Item Name as you wish for it to appear in the Add-In menu. We selected My Weekly Report as the menu item name.
◦ The Tooltip for menu item enables you to specify some additional detail about the menu item in a pop-up tooltip. This field is optional.
● Action
◦ Next, you have the option of copying and pasting your script into the Run this JSL window or selecting Run JSL in this file and browsing to select your script file. To ensure there are no accidental copy or paste errors, click the button for Run JSL in this file, and then click the Browse button. Locate your WeeklyReport.jsl file and click Open.
◦ The check box for using the “Here” namespace is optional. We recommend leaving the default check in place to keep all of your JSL variables local to the script. Again, we will discuss global and local variables in chapter 4.
● Icon
◦ This optional setting enables you to specify an icon that will appear next to your menu item. For this example, we will not use an icon.
● Shortcut
◦ The Shortcut setting enables you to specify a keyboard shortcut that will invoke the menu item. For this example we will not specify a shortcut.
To continue creating and saving the add-in, follow the next steps:
1. Click Save As, and then navigate to a location of choice to save the .jmpaddinfile.
2. Click Close to dismiss the Add-In window.
Figure 2.29 Menu Items Tab
The add-in for running the WeeklyReport.jsl file is set up and saved.
Now, test it to be sure it works properly.
● Make sure you have closed all the open data tables in reports by clicking the Window menu and selecting Close All.
● From the Add-Ins menu, select My Weekly Report (you might have named your add-in differently).
Figure 2.30 Add-Ins Menu Item Selection
The results should be the same as when you run the WeeklyReport.jsl by selecting Edit ► Run Script, but the menu item makes the process much easier now.
Figure 2.31 Weekly Report Results Using Add-In
These are the basics that should enable you to start scripting very quickly. Keep the following key points in mind:
● Perform your analysis interactively first.
● Extract scripts from JMP as the foundation for your script.
● Stitch the scripts together by assigning variable names to objects such as data tables and reports.
● Don’t forget to add semicolons between statements.