Display Box Object References

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).

Figure 11.6 Scripting Index Display Box 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 View 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=",

	Report( rp )[Outline Box( "Analysis of Variance" )][

	// string references the parent box

	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.