In the previous post I illustrated a software advisor that can be used to automatically check the assumptions associated with a oneway analysis of variance. Now I am going to show you how you can write the code from scratch.
First some housekeeping. I need a folder structure to store all the files associated with this project. I’ve created a folder called Oneway Advisor and this contains two folders: Resources and Scripts.
The icons used to show status information will be stored in the resources folder. These are the icons that will be used:
You can right-click on them and save them to your resources folder.
All the JSL scripts (yes there will be more than one!) will be stored in the scripts folder.
Creating A New Script
So let’s start on the first piece of JSL. Open a new script window (the second icon on the JMP toolbar or select File>New>Script or press CTRL-T). This is the code that you need to write:
wrapSize = 220;
New Window("Oneway Advisor",
V List Box(
H List Box(
Text Box("Assumption Checker", <<Set Font Style("Bold"))
LineUp Box(NCol(2), Spacing(30,20),
Text Box("Data within each level of the grouping variable are normally distributed",<<Set Wrap(wrapSize)),
Button Box( "X"),
Text Box("Residuals are normally distributed",<<Set Wrap(wrapSize)),
Button Box( "X"),
Text Box("Data within each level of the grouping variable have equal variance",<<Set Wrap(wrapSize)),
Button Box( "X"),
Text Box("The data are independent, exhibiting no serial correlation",<<Set Wrap(wrapSize)),
Button Box( "X"),
To explain the code it is easiest to first show you what it looks like when it is run:
Note the following:
- There is a window, titled “Oneway Advisor”
- There is an additional title in bold: “Assumption Checker”
- The information in the window is organised in two columns and four rows – the first column contains text and the second contains a button with an ‘X’ (this is a placeholder which will later be replaced with an icon)
The New Window Function
The code can look intimidating, but there is a logical structure to it. Fundamentally we are creating a new window. This is an object that is created using the function New Window. The function has the following structure:
New Window( title, content )
Understanding Display Boxes
The content of a window consists of one or more display boxes. A display box either displays content (e.g. Text Box, Button Box) or controls the layout of content (e.g. V List Box, LineUp Box).
Display boxes are documented in the JMP help under the scripting index – to become productive writing JSL code it is important you become familiar with this essential resource! If you prefer, you can access this documentation online.
The content of the window is a Border Box. This applies a margin and ensures that the content is not flush against the edges of the window.
To indicate that the border box is contained within the window it is indented – compare lines 2 and 5 – use the TAB key to indent the text (use Alt-TAB to reverse the indent). JMP doesn’t care about this formatting but you will quickly get into a mess if you don’t have the discipline to write the code in a way that reflects the hierarchy of display boxes.
V List Box and H List Box
The content of the Border Box is a V List Box. This vertically aligns multiple pieces of content. You can see that it is contained inside the border box by the indentation. The V List Box contains an H List Box and a LineUp Box.
An H List Box aligns multiple pieces of content with a horizontal orientation. By producing a hierarchy of V List and H List boxes it is possible to exercise complete control of the layout of content within a window.
Sometimes we want to be able to fine-tune positioning of specific items of content. The Spacer Box takes a Size parameter which specifies (x,y) spacing in pixels. On line 8 of the code, the Spacer Box in combination with the H List Box (line 7) has the effect of adding a 30 pixel margin to the left of the Text Box on line 10.
The first piece of real content is the title “Assumption Checker” which is displayed using a Text Box.
Display Box Messages
Messages can be sent to a display box to change their properties. The text “Assumption Checker” is a title and is given emphasis by making the text bold. To do this a message Set Font Style is sent to the display box. Messages are sent using the “<<” notation.
The width of the lines of text that provide the assumption descriptions is controlled by sending the Set Wrap message to the associated Text Boxes. If the text exceeds the specified width (in pixels) then it will wrap onto an additional line. Rather than hardcode a value for this width, it has been specified by the variable wrapSize in line 1.
Typically a Button Box is used to display text on a button (or hyperlink) that can be clicked by the user. The click event can then be used to trigger the execution of a JSL script.
Buttons have a couple of other useful characteristics – they can have an icon associated with them and they can display tooltips (text messages that appear when the mouse “hovers” over the button. The Oneway Advisor will take advantage of these characteristics, but that is for a future step. For now a button with the label “X” is being displayed as a place-holder.
Notice that lines 12 through to 19 contain four Text Box, Button Box pairs. These are aligned into two columns using the LineUp Box. The number of columns is specifed by the NCol keyword and Spacing is used to add some padding between the display boxes contained within the LineUp Box.
Phew! Display boxes take a little while to get used to but ultimately it is much easier to write the JSL code than explain it in English! You should run the script to verify that it produces the illustrated output. If it doesn’t then there is a syntax error – the JMP log file (View>Log) will give you a clue as to the cause of the problem. There are a couple of common errors associated with using display boxes:
- The functions that create the display boxes have open and close brackets. They come in pairs. For each opening bracket there must be a corresponding close bracket – again the indents help here – for example, the V List Box on line 6 has a closing bracket on line 21.
- Display boxes need to be separated by commas (more correctly, arguments to functions need to be separated by commas, and each display box is just an argument – for example, for the H List Box on line 7 the Spacer Box is the first argument and the Text Box is the second argument).
Ultimately I want to save this script as “Oneway Advisor.jsl”. But it’s going to be subject to multiple iterations of refinement so for now let’s save it as “step1.jsl“.
17 May 2020 Update – I am planning to make this walk-through into an online course. If you would be interested in this please DM me on my twitter handle: @PegaAnalytics.