Using Display Boxes

[#1]

In this demonstration, we'll take a look at how the display boxes are organized in the report layer, and see how we can access the contents of those display boxes. So in section of the course journal, I'll click on Cure Time Data. So I'm just going to do a simple correlation analysis and simple linear regression with the Cure Time data with two of my Cure Time columns in the bivariate platform. And we'll see how we can use the Selection tool to explore the report and kind of understand that report layer. So I'll go to the Analyze menu and select Fit Y by X. And I'll put Cure Time in the Y role, and Cure Time in the X role, and then I'll click OK. And I'll go to the red triangle next to Bivariate Fit and select Density Ellipse. And I'll use the option. And then back in the red triangle menu at the top, I'll select Fit Line. So that gives us lots of components of our display tree. So interactively, we can use the Selection tool to select parts of the report. And we're actually selecting display boxes. So if I come up to my menu and toolbar, I can just get this big white plus sign, or you can type an S for Selection tool, or you can go to the Tools menu. So that changes my cursor. And if I want to select this graph, you might think that you would just click in the middle of it. But I'm actually only getting the frame box, which is one of the display boxes that makes up this part of the report. So then, I might think, oh, well, I have to click outside of it. And then I just get an access box which is, again, is another display box that makes up this part of the report. And so when I'm doing this interactively, I might have to try to get my cursor all the way out at the very edge to get all the components of that graph, although I don't have the legend. But I can get that as well if I wanted to. I can also select outline items. So I'm going to click on the Disclosure button. I can click on this even when I'm using the Selection tool. The outline disclosure buttons will still respond. But I could use the Selection tool now to select the entire outline item, or if I can click that again, to deselect-- to select individual columns within that outline item. And one of the things when you're scripting with the report layer is you may want to use the Select Message, which is going to do the same thing as the Selection tool interactively, to make sure that you're targeting the correct portion of that report layer before you start extracting values. So I'm going to switch back to my arrow cursor. And I can go up to the toolbar, or I can simply type an A. And a handy feature we have for understanding the display tree is a menu option called Show Tree Structure. And I'm just going to look at this for the Bivariate Normal Ellipse. Because there's no red triangle menu on this outline item, I can right click on the outline item. If I wanted to get this tree structure for the entire report, then the top outline item, because it has a red triangle menu, if I right click there, I just get the red triangle menu. So if I wanted the entire tree structure, I would right click on the Disclosure button. But that's a really big tree structure. So I prefer to work with the individual report tables. Although, if I wanted to understand the tree structure for this graph, of course, I'd have to go to that top level. But for the Bivariate Normal Ellipse outline item, I'm going to right click, and under Edit, select Show Tree Structure. Let me just move this side by side. So this is just outline items displaying the various display boxes that make up this part of the tree structure. And a nice feature is that it's connected to that report window, so that as I hover over various components in the tree structure, they're highlighted as you can see in that table. So that's another way that I can make sure that I am correctly targeting the display box I want. All of these display boxes simply have index values, although the outline box also includes the name. And we'll see how we can target these items with a little more information than just the index values. First though, let's grab the script to recreate this report and then get the report layer object reference. I'm going to close the tree structure window, go to the red triangle next to Bivariate Fit, and select Save Script To Script Window. And I'll go ahead and resize that. The one thing in here that you see is that SendToReport, which is just because I expanded the Bivariate Normal Ellipse outline item. So you can see there's a Close with a Boolean there. So if you-- you could get rid of this if you just wanted to run it again and not have that open. I'm going to keep it in. And now that I have a script to recreate this, I want to close the original report, because I don't want to confuse it with the one that will be produced when I create this instance of a bivariate object. So at the top of the script, I'm going to store the analysis layer object reference-- which is the result of launching the platform-- in the variable biv. So I assign that. And I'll just use the shorthand of current data table here, and send the message-- oops, I don't need to type that, do I? Because I already have that script written. And then I'll run the script. So that launches this new bivariate object. And then, on the last line of my Script Editor, I'm going to get that report layer object reference. So I'll store this in the variable rbiv. And I'll assign it the result of biv receiving the message "Report." And remember, there's an alternative syntax for that where Report actually has biv in parentheses as an argument after the name. And we'll see that example in an upcoming demonstration. So I want to run just this one line. Now, notice what's stored in rbiv. We had the platform name stored in biv. But in rbiv, we just have DisplayBox[OutlineBox]. So I don't have as much detail. I just know what kind of display box it is. But that's what the object references for the report layer are going to look like. Now, before I do anything else, I want to comment out lines through because I don't want to accidentally rerun the script, have a new window open with a bivariate fit, and then close the wrong window so that I close the one that's currently-- that its reference is currently stored in biv. I've done that before. And then, of course, it doesn't respond to messages, because it's not open anymore, even though a different one is open. So with that all selected, I'm going to right click. And under Advanced, I'm going to select Comment Block. And I'll just note that because I didn't have any other lines in the Script Editor after what I commented, it used the syntax of opening the comment with a forward slash asterisk, closing the comment with asterisk forward slash. If there were other lines, it would have commented at each line with two forward slashes individually. But I could still select them again and right click to uncomment all at once. So this does not need to be as wide, but I do want it to be a little bit taller. And I'll move it over to the side. And let's move the bivariate window outside of that. And I'll go to a new line. And actually, let me right click in the report window on Bivariate Normal Ellipse, Edit, Show Tree Structure. So this is outline box So when I subscript rbiv, I have the option to just use that index value. So OutlineBox, and then in parentheses and I'm going to send the message "Select." So this is how I can script instead of using the Selection tool. And I'll just run that line. And you can see that outline box has been selected. Now, if this is the outline item that I want to target, I don't want to keep it selected. I just use Select to verify that I am pointing in the right location. So I'm going to send the message "Deselect," run that line, and that deselects it. And let's suppose I want to drill down into the column of the means. That's so I can append another subscript for And I'll change the message back to "Select" and run that. And so that has selected the column of the means. Now, what's another way that I could refer to these display boxes that would be more explicit? Well, instead of calling it I can actually use the name of the outline. And in fact, that replaces the entire subscript here. Where it says I simply supply the character string. Now, this is a long character string. So I'm going to use that wildcard. I'll open my double quotes here and type "Bivariate Normal." And I'll just type the word Ellipse as well, and then the question mark so that I don't have to specify the P equals I'll close those double quotes. And then, for the number column box, maybe instead of using the index value, since there is a column header there-- unlike Summary of Fit, I would have to use an index value here. But there's a column header called Means. So I'm going to replace the I still do have to say it's a number column box. But I'm going to replace the with the character string Mean. And then I'll change the message to "Deselect." So I run that line, and that works as well. And in fact, I would recommend this syntax, because it's very explicit about which outline box we're looking at, about which column we're looking at. Let's take a look at this in the context of the parameter estimates. I'm going to close the tree structure from the Bivariate Normal Ellipse window, and then right click on Parameter Estimates and go to Edit, Show Tree Structure. So for the first subscript, I'll replace the content of that character string with Parameter Estimates. And let's suppose I want the column of the estimates. Well, if I use the name, which, again, is our recommended best practice when there is a column header, and I'll send the "Select" message, that works very nicely. Now here's why I'm showing you this example. If I look in the tree structure, the column of the estimates is So what would happen if I specified and tried to deselect that? Well, I get an error-- Cannot subscript Display Box and access or evaluation of rbiv, et cetera. It doesn't give me a huge amount of information. But I know from experience that what this means is that once I have pointed to the parameter estimates outline item, the counting of the column boxes starts fresh within that outline item. So this is really in the parameter estimates. If I run this now, it will work. If I wanted to simply subscript as the only subscript to rbiv, that would work, too. So there's lots of different ways to subscript. But again, we recommend being as explicit as possible by using the outline item name, and if there is a column header-- let me put the Estimate column header back in here-- using that to make sure that we are writing a script that will be robust to changes in the structure of the display tree. Those changes might be with a new version of JMP, or they might result from the user's preferences, having reports that show up above the table of interest and change the numbering of these column boxes or other display boxes. So whenever we can use an outline item name and a column header, we want to do that. Now selecting and deselecting, that's just for development. At some point, I might want to actually get these values. I'd like to retrieve the parameter estimates, potentially store them in a variable. I won't do that here, but you certainly could, and that might be what you want to do. So if I simply send the message "get" to the subscripted portion of my report layer, what's returned is a list with those two values. I could change that message to "get as matrix," and what's returned is a matrix of those values. Well, what if I don't care about the intercept? I only want the estimate for the slope. I want the second one. Well, one way to do that is to send the message "get" with a in parentheses, and I run that, and then I simply retrieve that second value. And an even more elegant way would be to not send a message at all, but once we've drilled down to the parameter estimates outline item, the estimate column box, I can subscript again and request the second item in that column, which returns the same results. So accessing the display box is a matter of either sending Report as a message to the variable storing the analysis layer object reference, or you can wrap that variable storing the analysis layer object reference in Report. And then, we use the subscripts to access the components of the display tree. And there's lots of different ways to subscript. Best practices are to be as explicit as possible when you are subscripting.

[SpannerHead]

Very helpful.  The ability to add a wildcard in a matrix was particularly useful.