Get References to Display Box Objects
When you launch a platform, the results are in two places: a visible report, made of display boxes, and an invisible object, called a platform, that accepts commands (or messages).
One of the messages that you can send a platform is the Report message. The Report message retrieves the display box that holds the report.
The red triangle menu at the top of the report is connected to the platform object and is the way you interactively send messages to the platform.
To fit the mean in the Bivariate platform, assign a reference to the Bivariate platform.
dt = Open( "$SAMPLE_DATA/Big Class.jmp" );
biv = dt << Bivariate( // biv references the analysis layer
X( height ),
Y( weight ),
Fit Mean,
Fit Polynomial( 4 )
);
To get a reference to the display box that represents the view of the platform, use the Report message. For example, add this expression to the preceding script:
rbiv = biv << Report; // rbiv references the report layer
Now you can manipulate the display boxes in the report layer as described in the following sections.
See What You Can Do with a Display Box
The following example creates a Bivariate report and stores its reference in the rbiv report object. It then puts the rbiv report object in a frame box and assigns the fbx variable.
dt = Open( "$SAMPLE_DATA/Big Class.jmp" );
biv = dt << Bivariate( // biv references the analysis layer
Y( :weight ),
X( :height ),
Fit Mean( {Line Color( {57, 177, 67} )} )
);
rbiv = biv << Report; // assign rbiv to the report layer
fbx = rbiv[Frame Box( 1 )];
After fbx has been defined, you can send it a message.
fbx << Set Background Color( blue ); // colors the frame box in blue
The Set Background Color message works the same as right-clicking in the graph and selecting Background Color > Blue.
To find out which messages you can send to a frame box, select Help > Scripting Index and search for “frame box”.
Figure 11.6 Scripting Index Display Boxes List
Running the Show Properties() function is an alternative to using the Scripting Index. The messages for the specified display box are printed to the log.
dt = Open( "$SAMPLE_DATA/Big Class.jmp" );
biv = dt << Bivariate( Y( :weight ), X( :height ) );Show Properties( biv );Show Points [Boolean] [Default On]
Histogram Borders [Boolean]
Fit Mean [Action](Fits a flat line at the mean.)
...
Many messages are the same as items in the pop-up menu for a given object. The next section, Construct Custom Windows, discusses messages for common display boxes in more detail.
Create a Reference by Subscripting
Use the subscript operator to navigate to a specific display box in the report. The best practice is to refer to the display box with an index number. The following expression identifies the second outline box in the display tree:
var = Outline Box[2];
Another way to navigate a report is to search for a text string. The following expression identifies the report that has the specified text string:
var = report[text];This expression finds the display box in rpt that has the title text. Note that text must be the complete title, not just a substring of the title. The text argument can also be any expression that evaluates to a text string. This approach is less reliable than referring to the display box with a subscript because the string in a report can easily change.
Typically, you want to assign the identified part of the report to a variable so that you can send messages to it easily. For example, to find the Analysis of Variance outline box in the Bivariate report, use this expression:
var = rbiv["Analysis of Variance"];
The sections below describe other methods for using a subscript operator to locate display boxes.
Wildcard String
You can use a wildcard character (such as “?”) with a substring to match the rest of the outline title. The wildcard character “?” represents places in the search string where you want to match any sequence of any characters. The following script searches for a string that ends with “Mean”, finds “Fit Mean”, and then opens the Fit Mean outline:
dt = Open( "$SAMPLE_DATA/Big Class.jmp" );
biv = dt << Bivariate(Y( :weight ),
X( :height ),
Fit Mean( {Line Color( {57, 177, 67} )} ), Fit Polynomial( 4 ));
rbiv = biv << Report; // return a reference to the Bivariate report
out1 = rbiv["? Mean"]; // find "Fit Mean" in the Bivariate report
out1 << Close( 0 ); // open the Fit Mean outline
Box Type and Wildcard String
Another method for locating display boxes is to include the display box and wildcard search string in the substring operator.
var = rbiv[Display Box( "?text" )];This expression finds the outline box that contains the specified text string in the rbiv report. The out1 variable assigns a reference to the outline box.
out1 = rbiv[Outline Box( "? Mean" )];
Box Type and Index Number
Another method for locating display boxes uses the boxType and an index number, n.
rpt[Display Box ( n )];
The expression above finds the nth of the specified display box of the type boxType. For example, this expression finds the first outline box in the rbiv report and assigns it to the out1 variable:
out1 = rbiv[Outline Box( 1 )];
This method is less reliable across releases because the number of a display box might change.
Tip: To determine the index number of a display box, view the tree structure as described in Show the Display Tree.
Nested Display Boxes
To reference a display box that appears several layers down in a report, use this format:
var = rpt[arg1][arg2][arg3][...];
The expression above matches the last argument to a display box that is contained by the next to last argument’s outline node, which is in turn contained by the argument before the next to last, and so on. In other words, it is a way of digging down into the hierarchy of an outline tree to identify a nested display box.
If you want to identify an item nested several layers down in an outline box, use a subscript with more than one argument of any of the above types. After locating the first item, JMP looks inside that item for the next, and so on.
rpt[arg1][arg2][arg3] // finds the first item then the next starting after that location, and so on
rpt[arg1, arg2, arg3] // different syntax, same result
Note that you can string together subscripts that have text or index numbers. The expression below finds the “Parameter Estimate” inside the outline node “Polynomial Fit Degree=4” and selects the third display box in the first table of the outline node.
out = rbiv["Polynomial Fit Degree=4"]["Parameter Estimates"][1][3] << Select;
Example of Creating a Report shows how to extract parameter estimates from the report.
Subscripting Display Boxes for Compatibility
JMP might add or remove display boxes in a report from release to release, causing numbered subscripts to choose a different box. Using a string to index a box, followed by a numbered subscript to pick a specific child box, is more reliable across releases.
dt = Open( "$SAMPLE_DATA/Big Class.jmp" );
rp = dt << Bivariate(Y( :weight ),
X( :height ),
Fit Line( {Line Color( {213, 72, 87} )} ));
Print("C.Total DF=",
// string references the parent box
Report( rp )[Outline Box( "Analysis of Variance" )][
Number Col Box( 1 )][3] // subscript references the child box
);
Figure 11.7 Subscripted Display Box
The numbered subscripts (in the preceding example) are relative to the named box, which makes them less likely to change. However, this also means that the absolute numbers in Show Tree Structure can’t be used directly.