Iteration in Scripts

So this demonstration illustrates how to use the For function for iteration. And so far, we've used the Script Editor with the log to test our scripts and observe the results. But now we want to look at that using the debugger. So I have a script editor window open, and I'm going to start by typing Names Default to Here. And I'll put that Boolean I'm not adding spaces right now. I'm going to actually type everything on one line and then let the automatic reformat clean things up for me. So I'll type a semicolon and then For, open parentheses, a equal semicolon, b equal semicolon, i equal comma-- so I'm initializing three variables. Then I'm going to type the test, which is i less than comma, and then I'm going to update both b and i. So b will update-- b+ equal So that's in-place assignment function, the add to function, which will overwrite the current value of b and increase it by a semicolon because I'm updating two things, and then i++, that ++, again, being the post-increment operator which adds to i in place. And then a comma, and then the body of this simple loop will be the Show function. And I'll just show a, comma, b, comma-- and then I'll actually invoke the multiply function using the operator-- so a times b. And then I'll close all my parentheses, add that semicolon, and I'll right-click and Reformat. Now one thing-- well, two things to notice here-- one is that JMP added in some extra semicolons for me. It saw that I was gluing functions together in this first argument. It saw that I was gluing functions together in the third argument. And so it added these semicolons. They don't hurt. In practice, I would probably remove those from my script because they're not necessary unless I was going to be adding-- gluing more functions together. And the other thing I might do is rearrange this so each argument has its own line. But I want this to match up with what I have in the course PDF when we go into the debugger. So I'm going to leave it the way JMP reformatted it except for getting rid of those semicolons. So there's several ways that we can start the debugger. You can go to the Edit menu, and there is a Debug Script option. You can see the keyboard shortcut is Ctrl+Shift+R. You can click the Debug toolbar button, here in the Script Editor window. Or you can right-click and select Debug Script. And since that's the last one I'm showing you, I'll go ahead and use that method. So this debugger is a second instance of JMP. And the original instance of JMP is temporarily suspended. So if there's any kind of interaction, like a dialog box that your script requires, the debugger window will be suspended until you perform that action. And then the control gets returned to the debugger once that's complete. And then once you're done with the debugger, you simply close it. You can just use the X in the upper-right corner or the Stop button here in the toolbar. And that will return you to the original instance of JMP. So to begin, I'm just going to run this loop through, as is, without putting in any breakpoints. And there are two buttons here. One is Run, and the other is Run without breakpoints. And since I don't have any breakpoints right now, those are going to do the same thing. If I have breakpoints that I want to use them now, I'll use this button on the far left. So I'll click that. And it lets me know the program execution is terminated unless I restart, which I will do shortly. The only option is to close the debugger. But before I restart, I want to go to the Locals tab down here in the panel below where the script is displayed. And the default name space is Here, which is what I invoked on line And you can see that at the end of running the script, the value of a is The value of b is And the value of i is So now I want to use the debugger to look at the values of a, and b, and i at each step of the iteration. So I'm going to click that Restart button. And I want to add a breakpoint at line And to do that, I click just to the right of the line number. And you can have as many breakpoints as you want. In this simple script, we really only need the one. So what that means is that we're going to evaluate line and set that Here name space. And then within the for loop, we will evaluate the initialization argument. We'll evaluate the test. We'll evaluate the body of the for loop, which is just the Show function. And then we'll pause, and we'll see the values in the Locals tab. Let me switch back over to that. And then when I click Run again, we'll update, do the test, run the body, and pause, and see those values. And we'll continue doing that until the test fails and we exit the loop. So I want to not have anything selected. And I'm going to use the left-hand Run button. Again, I don't want to run it without breakpoints. So I'll run this. And you can see that we've stopped at line after evaluating that. And the values of, a, b, and i are and respectively. To run through the next step of the iteration, I click the Run button again. And now I see the values of a, b, and i are and respectively. And I can run one more time. And we reach the final values of a, b, and i. And I get the message the program execution has terminated. And I can either restart if I wanted to do anything else. I can click the Stop button. Or I could close using the X in the upper right-hand corner. And I'll go ahead and click the Stop button. So that returns control then to my original session of JMP. Now let's imagine that we have measured the cure time of some compound that's in production. And every run is sampled at five times during production, and we determine this cure time for each sample. And we want to look at the distribution for the cure times for each sample. So in the Course Journal, in section I'm going to click Cure Time Data. And one of the things that we recommend when scripting is to try things interactively to begin to make sure that what you're trying to do is feasible. So I want histograms for Cure Time through And so I'm just going to do a simple example to start. I'll go to the Analyze menu, select Distribution. And I'll put Cure Time in that Y role. And again, remember that the role here is Y. And I'll click OK. And so looking at this, I think, well, this is great. This is exactly what I want for all five of my cure time distributions. So that's the platform I want to use. And I put together a little template of a script that would recreate this report. Let me go back to the Home window and open that up. So this script with the distribution platform launch, that Y role, and then the column function with Cure Time as the character string will recreate that report. And so I'm going to write a loop based on this template. So I'll go ahead and close this Cure Time window and navigate back to my Script Editor and clear the contents, so I can just use the same window. And again, I'll begin my script with Names Default to Here. And as before, I will let JMP clean up the script for me with the automatic reformatting. So my for loop will start with the argument c. And I'm going to assign a value of to c. That's the only variable I'm going to initialize. I'll type a comma. The test will be c less than equal the number of columns. And just a reminder that a best practice, if you're working with a large data table, potentially, would be to count the number of columns outside of the loop, store that result in a variable, and then have that variable be what you're comparing c to. In this case, it's five columns because we're starting with the second one. It's five columns total. So I'm not worried too much about redoing this count every single time. But a best practice would be to pull that out. I'll type a comma after that. The update argument will just be c and the post-increment operator, the two plus signs, another comma, and then I'm going to type Distribution in parentheses, y, open parentheses again, type column, and then just put c-- the counter-- in those parentheses. And I'm going to arrow over now just to make sure that I've got all my parentheses matched. Actually, if I was missing a closing parenthesis here, and I tried to reformat, I would get a message that there was something missing. So reformatting actually is a simple way to do some debugging. I'll type the semicolon. And then I'll go ahead and use the Reformat Script button. And then I'll go ahead and run the script. And what I get with the script written as it is is a separate window for each observation of the cure time values because I'm launching distribution-- if we come back to the Script Editor window-- I'm launching the distribution platform again at every step of the iteration. But if you're familiar with distribution-- and I'm going to go back to the Analyze menu, select Distribution, and put all five of the cure time values in that Y role. If you're familiar with distribution, you know that you can get all of those in the same window. So in the Journal, there's a script that's been pre-written to loop through to build up that Y role with all of the column names and produce the same report with all five distributions in the same window. So before I start that, I want to go ahead and close all these report windows. I'm going to come up to the menu bar and under Window, select Close All Reports. And then I'll find the Journal. And I want to click on the script, Cure Time Distributions. And we're going to go through this in the Debugger. So I'll talk about what's happening at each step in that Debugger environment rather than in the Script Editor window here. So I'll right-click and select Debug Script. Again, recall that there are multiple ways that we can launch the Debugger. And I want to add a breakpoint at line to look at what happens at each step of the iteration like we did in the simple example previously. And I also want to add a watch on the c variable and the yCol variable. So I'm going to go to the Watch tab. And I'm going to click the green plus sign to add a watch. So this is a way that I can look at specific variables in my script. Now here, I don't have very many variables. But if you had a big script with a lot of variables, and there are only a few that you needed to keep an eye on while you were debugging, using the Watch tab is a great way to do that. So I'll click that green plus sign to add the watch. I'll type the variable c and click OK. And then I also want to add a watch on the variable yCol And I'll click OK. Now before I start running this, I do want to talk a little bit about what is happening throughout the script. And then we'll see that as we go through the process of running the debugger. So the very first line is creating a variable called yCol. And yCol is going to store the Y analysis role of the distribution platform followed by empty parentheses because my loop is going to build up this expression by adding the column names into the parentheses after that Y role. And I'm quoting it with the Expr because if you just tried to say yCol and assign the value y with parentheses after it, you'd get an error because JMP doesn't recognize this as a variable that's been defined. It doesn't recognize it as a function. So I just want to get this literal value stored in yCol without JMP trying to evaluate it. So that's what line will do. Lines through are my for loop, where we start with column We iterate until we run out of columns. And again, in a production level script, particularly if there might be larger data tables, we want to count the number of columns outside of the loop, put that in a variable. And then the body of the for loop is simply adding column c, so column this first round into the expression stored in yCol. And Insert Into will not try to evaluate its first argument. So I don't have to do anything special with the yCol variable. It simply looks at it and then does the operation, in this case, adding column into the parentheses after the y. The Show function is just for illustration purposes for us to see what's happening at each step. That piece, if I wasn't using the Debugger, that would show up in the log. So I've got the watch on the values, which is the equivalent of using the Show function. We Update. We test, and we, assuming that c is still less than or equal to the number of columns, we insert the next column into yCol. Then once the loop has completed, in other words, we run out of columns, we have a final line of code, which I'm going to talk about this from the inside out. We want to use the Insert Function to modify the distribution expression. We use Insert rather than Insert Into because distribution is a platform launch built into JMP. A user cannot actually modify distribution itself. We can modify an expression that uses distribution. So we use insert. And then we wrap distribution in the Expr function, so that JMP does not try to evaluate distribution. If I launched-- I'll just highlight this-- If I just ran this piece of this line of code, JMP would say, hey, you haven't given me the required argument in the Y role. So it would give me the distribution platform launch. And then the user would put their columns in, but we would not actually-- it would defeat the purpose of our script, right? So that's the first argument. The second argument-- if I just put yCol in as the second argument, JMP would try to evaluate that. And it would see-- you'll see what it's going to look like after we've done the loop. But it would see just that capital Y with parentheses and a bunch of column names. And that's not something JMP knows what to do with. It doesn't recognize that as a variable name or a function. So Name Expr enables me to look at what's stored and yCol without trying to evaluate it. And that unevaluated expression stored in yCol is what will be put into the parentheses following distribution. Then because, once I do that, the distribution with the Y role in all the columns is still quoted, we wrap the whole thing in Eval. And we can go through when we get back into the regular instance of JMP and break that down a little bit more. So I have my watches. And currently, the variables are undefined. So that's what shows up as the value. Let's run to the first break point. And so after that first run through before we update, c is storing the value of And now yCol, instead of just a Y with empty parentheses, it has Column Cure Time And remember from my little template you can see in the background there-- I can't navigate to it because the Debugger is active-- but that is what would produce that distribution for just the one column. So I'll run again through the next iteration. Now c is equal to and the y analysis role is starting two cure time columns. I'll run again. Now we have three. And I can continue doing that. You can see in the log in the background that those results are showing up because of the Show function. So I'll continue doing that until we exit the loop. And all five cure time columns are stored-- and this is easier to see in the log in your regular session of JMP-- but those are all stored in yCol now. So the program execution has terminated. I'm going to go ahead and click Stop in the Debugger. And so that last line now has been evaluated. And I have the cure time distributions with all five histograms in the same window. Now let's go back to the Script Editor window briefly again to talk about this line because I think it's important to think about how we build expressions from the inside out. So I'm going to run this and create a bunch of errors just to make sure that that's clear why we wrote this out the way we did. So I'm going to comment out the pre-written line. So going back to how I was describing this when we're in the debugger instance, I'm going to type the word Insert. And when you're new to scripting, it might be a little trial and error of when to use Insert, when use Insert Into. But again, in this case, I'm trying to-- I need to launch a platform with specific analysis roles or specific columns in the analysis role. But I can't modify a platform. I can only modify user-created variables. Those are called L values. So let's try this. I'm going to type Distribution for that launch, open the parentheses, close the parentheses, type a comma, and try to insert yCol. Again, I'm coming at this from a naive perspective that I want what's stored in yCol and the parentheses after distribution. So let's see what happens when I run this one line. [ERROR CHIME] I get an error, Name unresolved. Y in access or evaluation of Y of all the columns. So if I dismiss that, that just means that JMP tried to evaluate this. It couldn't. So we got an error. So this didn't complete. So again, the function we use when we need to retrieve a stored expression or a quoted expression without evaluating it is Name Expr. So I'm going to wrap-- oops-- open parentheses. I'm going to wrap yCol in Name Expr. And you might test this. So what happens. If I just ran yCol, you saw the error we just got. If I run Name Expr yCol, then you can see in the log-- oops, I'm trying to resize this. You can see in the log that JMP doesn't give me an error with that. It just returns that quoted expression. So now when I try to run line oh, well, this time, the problem is that-- so JMP didn't have a problem with the yCol variable this time. But now it saw distribution without that required value. So I don't want JMP to launch this platform. I'll cancel out of that. I want to wrap distribution in Expr, so JMP won't try to evaluate that at all. And again, you can highlight that and run it just to test it, OK, that doesn't cause any problems. And now when I run this, if I look in the log, there's the line of code that I ran. Here's the result, distribution with a Y role and all of the columns contained within that. So then the last piece, as you saw in line is to wrap this entire thing-- and this is just one way to do this-- but to wrap the entire line in the Eval function. And I run that. And there's another distribution window with all of the distribution reports. So I just wanted to go through making some errors as I developed this just because I think that helps people to understand why we write these things out the way we do. Now one other thing I'll mention is that we would generally recommend-- when I did that first cure time distribution, if you recall, I went to Analyze, Distribution, I simply put Cure Time in the Y role, and clicked OK. We would often recommend that you just grab the script that JMP would write for you for this and use that as the basis, in this case, for writing this loop. And the only reason I didn't do that with the distributions is that the syntax where I just have that y analysis role is an older syntax. If I were to go to the red triangle next to distributions and select Save Script to Script Window, the newer syntax specifies whether it's a continuous or nominal distribution individually for each column. And so it's just a little bit more scripting in that loop than with the older syntax. The older syntax works fine. But I would probably recommend using this newer syntax. It's just a slightly more complicated loop. But with most platforms, it's going to be just fine to take the script that JMP writes for us. I'm going to close this script window. And we're going to look at one more example of doing something interactively. This time, I will capture that script. Although, my loop is pre-written. Let's suppose I wanted to look at control charts of all five of the cure time values. And so I'll start interactively by going to my Analyze menu. Under Quality and Process, I'll select Control Chart Builder. I want to put Day in that sub-group role and Cure Time in the Y role. And that automatically, the Control Chart builder gives me the individual measurement and moving range chart of Cure Time So that's my starting point. I'm going to click Done to hide the Control Panel. And then I'm going to go to the red triangle next to Control Chart Builder and Save Script to a Script Window. So this Script Editor window-- this Script Editor window. now contains the Control Chart Builder that will recreate that result. Now just to make it match up with my pre-written script, I'm going to delete line that sets the size. You don't have to do this, of course. I'm just simplifying this for the demonstration purposes. So what we see is there's the Control chart builder is the platform launch. And then we have some options. We're hiding the Control Panel by using that Boolean We're not showing capability. And then there's this variables role. And the variables role has a subgroup. That's going to be the same for all of the cure time values. And then it has a Y role with the cure time, in this case, Cure Time So what we actually need to do is build up three things. We need to build up that y analysis role with the cure time columns, build up the variables piece of this by adding-- once we have all the cure time columns in the Y role-- adding that in here. And then get that variables piece into the Control Chart Builder launch. So let's go back to the journal and click Cure Time Control Charts. So again, it's three pieces building up the y analysis role. And that's just like what we did-- these lines through are just like what we did, what we saw in distribution. And I'm just using a different naming convention on the variables. Then we want to build up the variables piece. And so I'm just using the Insert Function. I've got variables with the sub-group Day, which is going to be the same for all the cure time values. But I don't want JMP to try to evaluate the word variables. I'll get an error. So I'll use Expr. And then just like in distribution in that script, I'm retrieving the list of columns that's stored in yExpr and adding that into the variables piece. Then in this script, I'm actually building the basic template for the Control Chart Builder without the variables piece and storing that in the variable ccExpr. And finally, I'm going to add the variables line. So again, if we look at that code in the background, that variables line is going to get added into the Control Chart Builder launch. And in this case, I just used Name Expr for both of these because they're quoted expressions I've already defined. I store that result in its own variable rather than wrapping this Insert Function in eval. And then I use cc in my script, and that will evaluate that built expression. Let's go ahead, though, and take this into the Debugger. So I'll right-click and select Debug. I'm going to navigate to the Watch tab. And I want to get rid of the current watch variables from my other scripts, so I'll just click the button to delete all watches. And then I'm going to add four watches for the four variables in this script. So I'll click the green plus. And first, I'll type yExpr, and I'll click OK. And I'll click the green plus again, and I'll add varExpr. And it doesn't matter that I capitalized that, but I just want to be consistent with what's in the text here in the script. So I'll click OK. I want to add ccExpr. Click OK. And finally, I want to add cc, and click OK. I'm going to put three breakpoints because I want to stop at three different locations here. So the first breakpoint will be on line And that's going to let me see what's happening at each step of the iteration. The next breakpoint will be on line So we'll pause to be able to see what's stored in varExpr. And then finally, we'll put a breakpoint on line to see what's stored in cc. And then once we dismiss this, that will be evaluated. I'll use the Step Over button to execute the debugger. So I click that. And line gets evaluated, and we get to the loop. And if we look in the Watch tab below, you can see what's stored and yExpr right now. And then when I click Step Over again, we go to the first break point. When I click Step Over a third time, now you can see that the yExpr has Column Cure Time in it. I'll click Step Over again to go to that breakpoint. Click once more. And now we've inserted Cure Time into that Y role. So I'll continue doing that until we are done with the for loop. And if you viewed this, you would see that all five cure time columns are in that Y role. Now line will define varExpr. So now that's variables with sub-group Day and then the Y role with all of those columns. I'll click Step Over again, and that takes us to where we have defined ccExpr. And you can see that in the Watch tab as well, that that's just storing the Control Chart Builder launch but missing a vital piece of it. And then line is where we put everything together. So I'll Step Over one more time. And now, if you wanted to examine this, the Control Chart Builder, Show Control Panel, et cetera, has the values stored in varExpr added to it. I'll click Step Over one more time. The program execution terminates. I'll click Stop. And now back in my regular session of JMP, you can see that I've got the individual measurement and moving range charts for your cure time and so on. So these examples, we're looking at using the For function, employing the Expr, Name Expr functions using Insert, and also then just looking at how we can use the debugger in these simple contexts. I'm going to come back to the Journal and click Delete All Save None without saving changes to any of my script windows. And that will wrap up this demonstration.