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.

Project Folders

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.

Icons

The icons used to show status information will be stored in the resources folder.  These are the icons that will be used:

                indicates that the assumption is valid

                indicates that the assumption is not valid

                indicates that the assumption has not been checked

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:

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.

Border Box

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.

Spacer Box

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.

Text Box

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.

Button Box

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.

LineUp Box

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.

Common Errors

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

Continue to step 2.

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.