Chapter 3: The Double Layer Cake

Overview

Folding Back the Layers of the Results

The Analysis Layer

The Report Layer

Presentation Options

Display Boxes

Accessing Items in a Report

Adding Items to a Report

Removing Items from a Report

Saving Report Tables

Summary

You now have the script to import your data and create your report. Once again, your manager says she wants you to add a few refinements, maybe add a few items, and delete some others. In order to manipulate the elements of a report, you need to understand how it is constructed. In this chapter, you will learn about the following:

●        folding back the layers of the results

●        the analysis layer

●        the report layer

JMP creates a platform object when you launch any platform from the Analyze or Graph menus. When developing scripts, it is important to understand how the platform object is constructed in order to customize it using JSL. Think of the platform object as consisting of two layers, similar to a double layer cake:

●        The analysis layer provides access to all the options available through the red triangle menus.

●        The report layer provides access to all the options available through context menus. In other words, these are the options that are available when you right-click within the platform results.

Let’s consider each level, starting with the analysis layer.

The options for the analysis layer can be viewed in the red triangle icon drop-down menu of the report. For example, after you launch the Distribution platform and create a report, click the red triangle icon to the left of the response variable, and you will see a menu with a number of options that can be turned on and off, as designated by the presence or absence of checkmarks.

This example assumes that the distribution platform has the default preferences in place.    

Figure 3.1  Menu That Shows the Platform Options for Distributions

As you know, when you select an option that was not previously selected, more information is added to the report. In this example, a Normal Quantile plot was requested.  

Figure 3.2  The Normal Quantile Plot Is Added

The same options that you select or deselect interactively in the red triangle icon menu can also be applied in JSL.

There are two methods for including platform options in JSL.  

●        You can specify the options in the platform launch:

dist = dt << Distribution(

       Y( :height ),

       Normal Quantile Plot( 1 ),

       Outlier Box Plot( 0 )

);

●        Or you can send messages to the platform object after the launch:

dist << Normal Quantile Plot( 1 );

 

dist << Outlier Box Plot( 0 );

The options can be turned on by using “1” as the argument, and turned off by using “0” as the argument.

In JSL, using “1” in an argument indicates “true” and turns an option on, and using “0” in an argument means “false” and turns an option off.

Figure 3.3  Menu and Script

Besides looking at the drop-down menus, how can you find out all the options available for a platform object? One method is to execute a Show Properties command and view the log for the details:

dist = dt << Distribution( Y( :height ) );
Show Properties( dist );

Figure 3.4 The Log Window

Figure 3.4 shows the Log window that results after you perform the Show Properties command on the Distribution reference. This output is handy, but a little difficult to read.

We highly recommend becoming familiar with the Scripting Index, accessed from the Help menu. We will cover the Scripting Index with more detail in chapter 5.

Select Help ► Scripting Index, and then click the All Categories button and select Objects from the drop-down menu.

Figure 3.5Selecting Objects in the Scripting Index

Scroll down the column on the left side of the Scripting Index and select the Distribution platform object from the list (see Figure 3.6).

Figure 3.6Highlighting of Distribution in the Object Scripting Index  

 

As Figure 3.6 shows, when you highlight Distribution in the Objects category, the messages that are available for that platform object are displayed.

Note that some options in the Show Properties Log windows are followed by the designation [Scripting Only]. This designation means that the option is available only through scripting, and you cannot access it through the interactive interface. Therefore, it is to your advantage to review the details for an object either through the Show Properties command or through the Scripting Index. Otherwise, you might miss something that could be useful for your scripting project.

The report layer consists of presentation options and display boxes. Let’s look at each of these items in detail.

Interactively, you can make changes to the report layer by right-clicking and selecting options from the context menu. For example, you can add a legend or change the background color.

Figure 3.7 Context Menu Launched from a Bivariate Plot

 

How do you access these same options using JSL? 

Earlier in this chapter, you used the platform object when accessing the analysis layer. To do the same for the report layer, you need to send the Report command to the platform object. Let’s look at two methods for performing this task. 

In the following code, a reference is first created for the Bivariate results that we arbitrarily named biv.

biv = dt << Bivariate( Y( :weight ), X( :height ) );

To access the report layer:

●        One method is to send the Report message to the Bivariate reference and name it repBiv:

repBiv = biv << Report;

●        You can also wrap the Report() function around the platform reference:

repBiv = Report( biv );  

Now we have the first step in accessing the report layer. However, before we can send messages with the report reference, we must understand how the report is organized and constructed. 

The basic building blocks of any JMP report are the display boxes. There are many types of display boxes, and each has its own set of messages. How do you know which display boxes are used in a report? And if there is more than one of that type of display box, how do you know which one to reference? You might not be able to determine this by looking at the report.

JMP actually has a built-in feature that shows the arrangement of the display boxes. To view this feature, right-click the topmost gray disclosure icon in a report. From the drop-down menu, select Edit ► Show Tree Structure.

Figure 3.8 Tree Structure of a Bivariate Report

 

JMP draws a diagram showing the hierarchical organization of the different display boxes that make up the report. If you scroll down in the report, you will see the OutlineBox, AxisBox, FrameBox, and PictureBox. These are basic display boxes found in most reports, and there is a number associated with each one. Knowing the type and number of the display box enables you to reference individual display boxes in a JMP report. Let’s explore using some of the common types of display boxes.  

FrameBox

Suppose you want to enlarge your Bivariate plot. To change the size of the graph interactively, you could right-click the plot and select Size/Scale ► Frame Size in the context menu (see Figure 3.9).

Figure 3.9  Accessing the Frame Size Interactively

A window appears where you can specify the horizontal and vertical size of the plot in pixels.  

Figure 3.10  The Frame Size Window

 

To perform this same action in JSL, first determine what type of display box you need to reference. In the display tree, the display box that holds the plot is the FrameBox, and it is the first FrameBox created in the report. Therefore, it is referenced as FrameBox(1).

Figure 3.11  Display Tree of the Bivariate Report

To determine what message to send to this FrameBox, go to the Display Box Scripting Index by selecting Help ► Scripting Index.  In the Scripting Index window, click the All Categories button and select Display Boxes in the drop-down menu.

Figure 3.12  Selecting the Display Boxes Index Option

 

Scroll down to and select FrameBox in the left column.  

Figure 3.13  Messages for FrameBox

Note that many of the options have the same names as can be found on the interactive menu. In the list of available messages for FrameBox, there is one for Frame Size, under the Size/Scale topic. Note also, on the far right of the Scripting Index window, a section that shows syntax, and below it, one or more examples where the syntax is used.  These are important features that are discussed in chapter 5.

The following scripting statements are needed to create the plot and change the frame size of the Bivariate plot:

biv = dt << Bivariate( Y( :weight ), X( :height ) );
repBiv = biv << Report;
repBiv[FrameBox( 1 )] << Frame Size( 250, 400 );

When you see square brackets in a script in the context of a report, it means that something is being subscripted. In the preceding example, we are navigating the report layer by referencing the first FrameBox within the report. We will discuss Display Boxes in more detail in chapter 7.

Figure 3.14  The Results of Executing the Script

 

AxisBox

Perhaps you want to change the scale of the X axis of a graph. Interactively, you can right-mouse click the axis and select Axis Settings.

Figure 3.15  Accessing Axis Settings Interactively

 

A window appears in which you can change the Minimum, Maximum, and Increment of the X-axis scale (see Figure 3.16), among other axis settings.

Figure 3.16  X Axis Specification Window

 

To send a message to an AxisBox, determine which AxisBox represents the X axis by looking again at the tree structure for this report. The X axis is represented by AxisBox(2).

Figure 3.17  X Axis Is AxisBox(2)

 

Go back to the Display Box Scripting Index and locate AxisBox in the left column. 

Figure 3.18  AxisBox Messages

 

Look at the messages for AxisBox. Scrolling down the list, you will find the messages for Min, Max, and Inc. There are two ways to send these messages to the AxisBox. One way is to send the message  as a combined Axis Settings() command: 

repBiv[Axisbox( 2 )] << Axis Settings( 
   Min( 45 ), 
   Max( 70 ), 
   Inc( 10 ) 
); 

If you only wanted to change one of the settings, you could send the message as an individual command:

repBiv[Axisbox( 2 )] << Min( 45 );
repBiv[Axisbox( 2 )] << Max( 70 );
repBiv[Axisbox( 2 )] << Inc( 10 );

OutlineBox

Let’s talk about a basic structure that is part of all JMP platform-generated reports: the OutlineBox. The OutlineBox represents a node, which is a single component of a JMP report. The typical JMP report has several of these nodes that are arranged vertically to form a hierarchy.

Figure 3.19  OutlineBox Hierarchy In a Oneway Report

 

Note that in Figure 3.19, the contents of the Summary of Fit node are visible, while those of Pooled t Test, Analysis of Variance, and Means for Oneway Anova are not. To open those last three nodes interactively, you can click the gray disclosure icon on the left of each outline node. Clicking the gray disclosure icon toggles a node open or closed.

To perform the same action using JSL, you need to send a message to the OutlineBox of interest. For example, in Figure 3.20, when the report is created, all Outline Boxes are open. 

ow = dt << Oneway( 
    Y( :height ), 
    X( :sex ), 
    Means( 1 ), 
    Box Plots( 0 ), 
    Mean Diamonds( 1 ) 
); 

Figure 3.20 Oneway with Open OutlineBox Nodes

 

To close the Pooled t Test node, you need to find the right OutlineBox in the report. In addition to the report message to the Oneway reference, you can refer to the specific OutlineBox by its text string:

Report( ow )["Pooled t Test"]  

This method of referencing an OutlineBox by its title is preferred over specifying OutlineBox(n), which references the node by its number. This method eliminates the possibility of the incorrect node being referenced in the case of a user having a preference setting or even a different version of JMP where the box numbering is different. Please see chapter 7 for more information.

What message to the OutlineBox will close the node? Check the Display Boxes Scripting Index by selecting Help ► Scripting Index.  In the Scripting Index window, click the All Categories button and select Display Boxes in the drop-down menu. In the left column, select OutlineBox, and then select Close in the middle column.  In the column on the right, you will see the syntax needed to send the Close message to an OutlineBox:

obj << Close( bool );

The argument for Close is “bool”.  Remember that in scripting, the word Boolean means using “1” in an argument to indicate “true” and using “0” in an argument to indicate “false”. In this case, to close the node, use “1”:

Report( ow )["Pooled t Test"] << Close( 1 );

Figure 3.21  Oneway Report with Closed OutlineBox Node

 

How do you get a value out of a report and place it in a variable so that you can use it in another part of your script? We will show you an example where you extract the R-squared value from a Oneway report.

The following JSL code is used to generate the report shown in Figure 3.22:

dt = Open( "$SAMPLE_DATA/Big Class.jmp" );
ow = dt << Oneway( Y( :height ), X( :sex ), 
                 Means( 1 ), Mean Diamonds( 1 ) );

Figure 3.22 Oneway Report 

 

The R-squared value appears under the Summary of Fit outline node of the report. 

To drill down to the value, you need to know more about the construction of the information in the Summary of Fit area. The best way to get started is to look at the tree structure. This time, right-click the gray triangle next to Summary of Fit and select Edit ► Show Tree Structure.

Selecting the tree structure from here shows only the Display Boxes that are included under this OutlineBox node.

Figure 3.23  Tree Structure for Summary of Fit Area

 

In the tree structure in Figure 3.23, locate the TableBox. The TableBox is the container for the Summary of Fit table. Here it comprises a StringColBox and a NumberColBox. The value that we want to access is the first value in the NumberColBox. Use subscripts to drill down to that value as follows: 

myRsquare = Report( ow )["Summary of Fit"][Number Col Box( 1 )][1]; 
 
Show( myRsquare ); 

The following output appears in the Log window:

You have successfully extracted the R-squared value from the Summary of Fit table.

Suppose you want to add a few notes to the report. For example, to add a note at the bottom of an OutlineBox node, use the Append message:

ow = dt << Oneway(
   Y( :height ),
   X( :sex ),
   Means( 1 ),
   Mean Diamonds( 1 )
); 
 
Report( ow )["Summary of Fit"] << Append( 
   Text Box( "Note the number of observations" )
); 

Figure 3.24 Text Appended to an OutlineBox

To place the text at the top of the node, use the Prepend message as follows:

Report( ow )["Summary of Fit"] << Prepend( 
   Text Box( "Note the number of observations" )
); 

Figure 3.25  Text Prepended to an OutlineBox

 

It is also possible to remove items from a report. Although it is possible to delete an entire Outline Box and its contents from a report created by a JMP platform, it is not recommended.  If a section has been deleted that JMP attempts to reference later, stability is affected and unexpected behaviors might occur.

Suppose you wanted to remove the picture shown in the Pooled t Test node. Instead of deleting that section, let’s search the tree structure to determine what type of Display Box it is and then what messages are available to help us.

1.       Right-click the gray disclosure icon beside the Pooled t Test Outline node and select Edit ► Show Tree Structure.

2.       Scroll down the tree structure and locate the image that you want to hide. 

3.       As you hold your mouse pointer over the FrameBox, notice that the corresponding area is highlighted in the report.

4.       In this case, we want the entire area hidden.  Hold your mouse pointer over the PictureBox and notice that it highlights all of the area that we want to hide.

Figure 3.26  Tree Structure with Report Highlighting

5.       Open the Scripting Index (Help ► Scripting Index).  In the Scripting Index window, click the All Categories button and select Display Boxes in the drop-down menu.

6.       Scroll down to and select PictureBox in the left column.

7.       Scroll down to and select Visibility in the messages list.

Notice that the Visibility message enables you to make a Display Box hidden, collapsed, or visible again. 

8.       Try the following to collapse the PictureBox.  Notice that PictureBox(1) is referenced because it is the first PictureBox under the Pooled t Test Outline node.  For more information about relative referencing, please see the topic in chapter 7.

Report( ow )["Pooled t Test"][PictureBox(1)] << Visibility( "Collapse" );

The image no longer appears on the report!

JMP gives you the convenience of saving report tables as data tables interactively by right-clicking a section of the report and then selecting Make into data table.

Figure 3.27Context Menu Selection for Making a Data Table

 

This action can be done in JSL, too:

ow = dt << Oneway(
   Y( :height ),
   X( :sex ),
   Means( 1 ),
   Mean Diamonds( 1 )
);  
 
Report( ow )["Summary of Fit"][Table Box( 1 )] << Make Into Data Table; 

Here a reference was made to the TableBox. The TableBox is the container for the table, as seen in the tree structure, and it typically includes StringColBoxes and NumberColBoxes. When sending the Make Into Data Table message to the TableBox, the contents of both StringColBoxes and NumberColBoxes are included in the new table.

Figure 3.28  Tree Structure Diagram for the Summary of Fit Node

 

 

When using a By variable, a report object for each By member is packaged in the same report window: 

ow = dt << Oneway(
   Y( :height ),
   X( :sex ),
   Means( 1 ),
   Mean Diamonds( 1 ), 
   By( :age )
); 

Figure 3.29  By Variable Report

You can see how this works by using the Show command on the Oneway reference:

Show( ow ); 
 
/*:
 
ow = {Oneway[], Oneway[], Oneway[], Oneway[], Oneway[], Oneway[]}; 

Here you can see that ow represents a list of Oneway[] platform objects.

JMP provides a convenient method for making one table for all the related member nodes. For example, interactively, you would right-click in one of the Summary of Fit report tables, and then select Make Combined Data Table to create one data table for all the Summary of Fit data in the report. This can be done in JSL, also. Because ow represents a list of Oneway analyses, we must use a subscript to identify one of the Oneway analyses that we want to access. Note that the first Oneway object is referenced as ow[1]:

Report( ow[1] )["Summary of Fit"][Table Box( 1 )] << Make Combined Data Table; 

The new data table contains the data from every report table that has columns of the same name and includes columns for each level of the By variable and the X and Y.

Figure 3.30 Table with Combined Summary of Fit Data from All By Members of the Report

 

Now you have learned the basics of the JMP report and how the data and the display boxes for the data form the report. More importantly, you have observed how to modify the elements through scripting. 

What’s next?

Next, we will dive deeper into the fundamental concepts of the JSL language.  Go get another cup of coffee!