Tutorial Project 3: Data Tables and Bernoulli Trials

This project builds a 1-page Document that combines a number of new features of Mathwright32. In it, we will build a simple interaction in which the reader experiments with Bernoulli Trials.

Along the way, we introduce Data Tables, which are Microsoft Active Data Objects (ADO), and which add a great deal of interactive functionality to our Documents. The columns of Data Tables are identified with MathScript Vectors, and can thus be manipulated in a variety of mathematically perspicuous ways. Since Microsoft Access Data Tables are a new feature in Mathwright32, we devote the first part of this tutorial project to their description, and the explanation of how to use them.

The Documents supplied with Mathwright32 Author are by default in subdirectories of the Program Files\Bluejay Lispware\Mathwright32 Author directory. You may find this project on page 1 of the trials Document. Use Windows Explorer to browse to C:\Program Files\Bluejay Lispware\Mathwright32 Author\microworlds\trials. The detailed discussion of Data Tables that follows in a moment appears, along with the opportunity to experiment, on page 2 of trials.

We will also develop some other uses for graph2D windows, including labels, and showing how to create histograms of data (Bar Charts) to generate data both visually and interactively. And we will show how to pop up instructions and information that can guide the reader to understand the Story.

Data Tables and Microsoft Access Databases

The Data Table Object allows you to input data into columns which are associated with MathScript vectors. These Data Objects are Microsoft Access 97 Database Tables. Readers need not own Microsoft Access to view these Tables in their browsers. We make use of these databases as Active Data Objects (ADO). This means that you do not have to have a database program to use these data bases, but readers should have the Microsoft Access 97 Database installed as a Data Server.

Instruct readers that to be sure that their setup is ready to use them, they should go to the Control Panel, and under ODBC Data Sources, to be sure that the User DSN: MS Access 97 Database is selected. If not, they should type it in. Once this is done, they needn't think about this again.

Authors can use any data table that they find in a Document. Do this by following these steps:

Column number 1 is the column immediately to the right of it. Each of the other columns is associated with a MathScript vector with the same name. Its columns can hold 3 types of data, but each column should hold the same type. These types are: function_name, number, and string.

Update each column by clicking on the caption at the top of the column (where the name appears). You will see a small dialog asking what the data type of all of the entries in the column. In each column, all entries should be of the same type. Check the appropriate type for each. Be careful here. If you check the wrong type, you could get a long cascade of error messages.

Remember, without Microsoft Access, you will have to use the column names and the number of columns that you find in the database you use.

Now if you do have Microsoft Access then you can create the database file (.mdb) yourself. This way, you can name the columns, determine their size and number, and place entries in them. There are three important constraints: The first column should be called ID and should be an index column. The Table that you use must be named MyTable. And every column must have a unique single-word name.

Finally, we provide a 'generic' template database with 4 columns and 256 rows called: template.mdb that is ready use, in the Program Files\Bluejay Lispware\Mathwright32 Author directory. Even if you do not own Access, just copy this to your directory and rename and use it.

Once you have a Table, the name of the Access Database Table (.mdb file) is always printed at the top. It must be a single word. For the example on page 2 of trials, the Table was selected in the page script as we came into the page. You may see this if you open the page menu.

It reads:

select "data";

A data table (even if it is the only one on the page) must be selected before it is used. Its columns can hold 3 types of data, but each column should hold the same type. These types are: function, number, and string. In commands and functions, we encode the types as:

to indicate types.

The ID "column" on the far left is merely an index, and is not associated with a MathScript vector. All other columns represent MathScript vectors with the same name, but they must be updated, when the Table is created, and when the Reader changes them. Mathscript vectors, and data table columns are indexed with positive integers. The first index is always 1 (not 0).

In what follows, we give instructions that you will also find on page 2 of trials. You might like to open that Document (C:\Program Files\Bluejay Lispware\Mathwright32 Author\microworlds\trials) and follow along there.

The Commands and Functions: entry, getentry, getvector, and setvector

The basic command for placing data in a data object is: entry.

In the yellow command line at the bottom of page 2 of trials type (Press enter after each semicolon)

This enters three numbers in the first column, called column1 there.

The general syntax of entry is:

entry row, column, value;

Now column1 is a vector, as are column2 and column3. To see its value type:

print column1;

You see that it is still the original the length-1 vector [ 0.0 ]. There are two ways to update it. The first is to click on the column caption column1. Try it. The system asks whether the entries are names, numbers, or strings. Accept numbers.

Now type:

print column1;

And you see the vector [1, 4, 9]. This means that the vector with name column1 now has the value [1,4,9]. You may of course type entries into the table directly, but they will have to be updated to associate the screen values with the vectors.

Now try:

entry 1, 2, "this string";

The entry in row 1, column 2 is the string "this string". Update this as before by pressing the caption "column2". And type:

print column2;

You see: [this string] It is the vector whose single entry is "this string." If you type: print column2(1); You see: this string

Now the identification of data table columns with vectors is very powerful. You are probably asking: How do you update columns to the vectors with the same name under script control?

In column 3, type the numbers: 5, 6, 7. To do this, click the cell, and when you see the write symbol, type the number. Then click the next cell, and so on. When you are finished, be sure to dismiss the write symbol by clicking away from the cell. Type:

print column3;

And the vector column3 is not yet identified with the entries. Now execute in the command field:

print getvector(3,2);

You see: [5,6,7] The value of column3 is still [0], but the return value of getvector(column, type) is a Mathscript vector. If you had typed:

make column3 getvector(3,2);

you would have set the value of the vector column3 to the third column.

Now, the companion function to the command entry is getentry(row, column); This function simply returns the name, number, or string in the (row, column) position of the table. Thus,

print getentry(3,3);

returns 7, even though the column has not yet been updated.

Another useful function is: setvector(column, vector, type).

If you type:

setvector(1, [2,3,4,5], 2);

You set the first column to the vector of numbers [2,3,4,5]. This also updates the value of column1 to be [2, 3, 4, 5]. So if you type:

print column1;

you will see [2,3,4,5].

Project 3: Data Tables and Bernoulli Trials

This Project is based on the Mathwright WorkBook, Bernoulli Trials, that was written by Kyle Siegrist in 1994. As mentioned, you may find the completed project as page 1 of trials in C:\Program Files\Bluejay Lispware\Mathwright32 Author\microworlds\trials. Page 2 of that Document contains the exploration with Data Tables described above.

We will create the Document Directory in the Documents Folder first.

Step 1: Document Directory

Before you begin, be sure that the screen resolution is 800x600 or 1024x768. The Documents that you create may be displayed on reader machines or browsers in any resolution. You have no control over that. But if you create them in 800x600 or 1024x768 resolution, then they will display properly in 640x480, 800x600, or 1024x768 resolutions in the reader's machine or browser. This is especially important because, in the browsers, you may shrink or enlarge the page as you like to fit your web page. Along these lines, we remind you that if you use wallpaper bitmaps (and hotspots) then you may use either bitmaps, GIFs, or JPGs. And these should be 800x600, or 1024x768 pixels to match your screen resolution.

The first step in creating the trials Document is to create a directory called trials that will hold it. We use lowercase for all file names and directories. We follow this practice because most Documents will be served from web servers.

Another practice that we follow for reasons that will be clear when you read Project A on Packaging and Delivering your Document, is this: The name of the directory should be the same (lowercase) name as the name of your Document ( .lva file). We will create Documents in the C:\My Documents folder, because that is where Mathwright32 looks for them.

Thus, go to the Windows Explorer, select the C:\My Documents directory, then select File, New, Folder: and when asked for a name, type trials. This will create a directory: C:\My Documents\trials\ into which you will place the Document.

Step 2: Adding "handcursor.cur" and the other resources

If you browse in Windows Explorer to the home directory: Program Files/Bluejay Lispware/Mathwright32 Author you will find a little file called: handcursor.cur Whenever you create a new Document, copy this file and paste it into your new directory. While it is not needed for offline reading in Mathwright32, it is a necessary resource for MathwrightWeb. Thus, highlight it, and select: Edit, Copy. Then browse to your new directory, and select Edit, Paste.

While you are at it, there are a few other resources that we will need. You may copy them from C:\Program Files\Bluejay Lispware\Mathwright32 Author\microworlds\trials. The resources you will need are:

We will explain what each is as we come to it. Thus, you should have 6 files in your directory now.

Step 3: Creating the Document

Next, let's open Mathwright32 to create the trials Document. There are several ways to open Mathwright32 as we saw above. You may click on the Mathwright Author 32 icon above in the MWAuthor32 button on the Start Menu that was set up with the system, or you may go to Windows Explorer and click on mwauthor.exe in the Program Files/Bluejay Lispware/Mathwright32 Author subdirectory, or you may select Run..., then enter C:/Program Files/Bluejay Lispware/Mathwright32 Author\mwauthor.exe.

Any of these will open a blank copy of the program. Now, once the program is open, select WorkBook, New Document from the menu. The screen will turn white, and the page caption will change to: Untitled0: Page 1 of 1 This means that you have created a new Document. It has the temporary name: Untitled0.lva.

The next step is to save this (empty) book into the directory just created. Thus, Select WorkBook, Save As...

And type in the Dialog Box C:\My Documents\trials\trials.lva or, select the C:\My Documents\trials directory, then type trials in the dialog box as below. Save the Document. It is saved as trials.lva.

Step 4: Setting the Page color

Now, let's set the page color for the Document. The "default" page color for a book is white. Each new page that you place in a Document will have this default color. When you set the page color for the Document, you change the default background color to a new color. That changes the color of the current page, and of each new page that will be added subsequently.

Select Page, Page Background color... A dialog box will appear with a selection of colors to choose from. I Selected the blue one in the first row, sixth column. Choose whichever you like.

The screen should change color. This will be the default background color for all new pages. You may still change the background color for any particular page by selecting: Page, Page Background Color... on any page.

To give you an idea what your screen should look like when you are finished, the following is a picture of the completed project after a rather nice run.

Now, this is what we will be doing. The term "Bernoulli Trial" refers to a sequence of experiments, each of which has two possible outcomes, generically called success and failure. The experiments are independent, and the probability of success is the same for each one. This probability is denoted p and is called the success parameter of the process. The probability of failure on each trial, of course, is 1 - p, which is sometimes denoted q. In each trial (sequence of experiments) one counts the number of successes.

If one performs a large number, N, of such trials, each with the same fixed number, M, of experiments, one finishes with a certain number of times there were 0 successes, 1 success, 2 successes, ..., M successes. The sum of these numbers is N of course, and so one can divide each of these numbers by N to obtain a distribution of frequencies (numbers between 0 and 1) that add to 1. Such a distribution is depicted on the right above. The "average outcome" is the sum from 0 to M of the outcome x (frequency of that outcome).

There are many examples of Bernoulli Trials, such as tossing a coin (possibly biased) a fixed number of times, or sampling with replacement from a dichotomous population (that is, a population of two types of objects).

The trial on this page simulates tossing 20 coins where each coin has probability p of landing with heads showing. The outcome for each trial is the number of heads. And we run 200 such trials each time the Run Button is pushed. The aim is to see the distribution of frequencies, and how it depends on p. In general, the average outcome will be close to 20 x p.

Let's get to work!

Step 5: Adding the Data Table Object.

The first step in adding the trials.mdb database to the Document is to switch to Design Mode and draw a Data Table Object, about the same size as the one depicted above, and call it: trials. Then, return to Reader Mode. Your page should resemble:

Next, update the Val and Freq columns as numbers, by clicking on the caption at the top of each one. If you forget to update these columns, you will get a Java Exception Dialog. Don't panic. Click Continue, and then update the columns if this happens. You will be forgiven.

Finally, Save the Document.

That is all there is to it! You have added a Data Table named trials with columns named: Val and Freq to your Document. Remember that the actual data is stored in trials.mdb and you must supply that file in your directory as a resource in order for your readers to be able to see the table.

Step 6: Creating a WorkBook Script.

The next step is to create a WorkBook Script. For that, go to the WorkBook, WorkBook Script Menu:

and type the following script:

precision 7;
readfloat;

Then, press Compile... Press Execute... (to do it now) and then press Attach and Exit. Whenever you open the Document, the reading mode will be set to Decimal, and the precision displayed will be 7 places after the decimal.

Save the Document.

Step 7: Add a Graph2D gadget to show the Bar charts

We are going to create a Graph2D gadget called RelFreq. You can see it in the picture of the completed project above. So go to Design mode, and draw the gadget and name it RelFreq (Case is important). You may follow the steps in Project 2, Part 1 if you forgot how to do this. When you are finished, return to Reader Mode and your page resembles:

Save the Document.

Step 8: Set the Graph properties

Start by changing the horizontal and vertical extents of the window. The Graph2D screen represents a rectangle in the Cartesian Plane. This rectangle is a Cartesian product: [x1, x2] x [y1, y2]. The Horizontal extent is the interval, [x1, x2] and the vertical extent is the interval [y1, y2]. Right click the graph2D and select Horizontal Extent.

Supply the interval: [-2.0, 22.0]. The reading mode and precision that you set when you executed the WorkBook script determine the numbers actually used, so be sure that you executed the WorkBook script first.

Next, set the Vertical extent to [-0.1, 1.1].

Now the Rulings setting determines the distances between the coordinate lines in the horizontal and vertical directions respectively. Set these values to 2.0 units in the x direction, and 0.2 units in the y direction. These positive numbers are determined as a pair be selecting: Settings, Rulings... :

The last step in this phase is to set the pen width to 2. For that, go to the Settings, Pen Width menu:

and type 2 in the dialog.

This finishes the general settings for the graph2D for now. You may have noticed in the preview of the page that there are two labels in the graph2D. We take care of that now.

Save the Document.

Step 9: Put Labels in the graph2D gadget

We want to execute the following 3 commands just once.

select "RelFreq";
label [ 1 , 1 ] "Relative Frequencies from 200 Bernoulli Trials";
label [ 1 , 0.9 ] "Each trial gives a number from 0 to 20";

That will place the labels in the window. For this, we will impress a Script Window into service, but will not save that script. For simplicity, we'll simply open the (empty) Page Script window and type or paste the script above into it.

Press Execute... and then press Cancel. We do not want to attach this script because we will never use it again. If for some reason, you wanted later to remove these labels, you could execute the following script in the same way.

select "RelFreq";
unlabel "Relative Frequencies from 200 Bernoulli Trials";
unlabel "Each trial gives a number from 0 to 20";

The graph2D should now resemble:

Step 10: Add a trace bar

We want a trace bar at the bottom of the graph2D. Select Actions, Show Trace Bar... and click the Show Trace Bar option.

A row of fields and buttons appears along the bottom of the graph2D. If you check trace, the coordinates of the cursor will be shown continuously in the window below. This allows you to trace points. Uncheck to turn trace off. When you click the zoom-in button, you may draw a rectangle in the window, and when you release the mouse button, that rectangle becomes the entire screen. You may do this repeatedly. The zoom-out button undoes these zooms one at a time. Also the zoom-out option on the menu zooms all the way out to the original state in one step.

Save the Document.

Step 11: Add the Horizontal Slider

Let us add the Horizontal Slider (called "p") and the Label "Success Parameter:" just above it. For that, note where they should be, switch to Design Mode, and first, select Page, Snap to Grid...

Next, draw the Horizontal Slider. Name it p.

Return to Reader mode. You should see something like this: The Slider sits above an output window that reports the Slider value.

We now modify the Slider settings. We want the

You should now see.

Save the Document.

Step 12: Add the Label: "Success Parameter:" above the Slider

Return to Design Mode. Select Objects, Label Object and draw the label. Place it just above the Slider Gadget (Snap to Grid should help) as follows:

Returning to Reader mode, you see a white blank label just above the Slider. Right click the blank Label and select Edit the Label.

Nothing happens...or does it? Right click the blank label again, and you see that the rest of the menu has been enabled. Set the background color to match the screen background, and after setting the Font, and Text Color, type "Success Parameter:" Then Save the Document.and the Label will be returned to non-editable mode.

Your page should now resemble:

Step 13: Add an output TextBox below the graph2D

Return to Design Mode to draw a small TextBox named "out" below the graph2D gadget. Check the preview to see its size and placement, and use "Snap to Grid" to align it with the graph2D. Select Objects, TextBox Object, and draw the TextBox. Place it far enough below the graph2D Gadget to accomodate the trace bar. Then return to Reader mode and right click the out TextBox, and select Appearance, Scrollbars... Then, select none in the dialog box. We will not need scrollbars for this TextBox.

Save the Document.

Step 14: The "Run" Button and its Script

Return to Design Mode to draw the "Run" Button. Select Objects, Button Gadget, and draw the Button. Place it far enough below the Slider Gadget to accomodate the output field. Then return to Reader mode and right-click to select Actions, Edit Script... Place the following Script (We explain it in detail below.) in the window. You may copy (Ctrl-C) and paste (Ctrl-V) it. Then Compile the Script, and Attach and Exit.

Button Script:

select "RelFreq";
'Clear the Graph2D Window: Relative Frequency '
clear;
select "trials";
'Initialize the Freq Column to 0s'
do
i=1
while i<=21 {
entry i 2 0;
let i be i+1;
}
'Loop through 200 trials'
let prob be 32767*Getscroll("p");
Repeat 200 {
Let X be 0;
Repeat 20 {
'Random() generates numbers between 0 and 32767'
If Random() <= prob Then {let X be X + 1}
}
'Update the second column after each trial. The value of the trial is X between 0 and 10'
do
flag = true
j=1
while and(flag, j<=21) {
If X==j-1 then {
set entry j 2 to getentry(j,2)+1/200;
flag := false;
}
let j be j+1;
} 'Finish 200 repetitions'
}

'Now draw the histogram, and compute the mean value m'
let m be 0;
do
k := 1
while k<=21 {
polygon[[k-3/2,k-3/2,k-1/2,k-1/2],[0,getentry(k,2),getentry(k,2),0]] color yellow fill blue;
let m be m+(k-1)*getentry(k,2);
let k be k+1;
}
draw the line from [m,0] to [m,1] using color red;
cleartext in "out";
printon "The average outcome is: ", m;

Script Explained:

The following lines select the graph2D and clear it, and then select the Data Table, "trials", and fill the second column (Freq) with 0s.

select "RelFreq";
clear;

 
select "trials";
do
i=1
while i <= 21 {
entry i 2 0;
let i be i+1;
}

Next, we get the Success Parameter in the variable prob.
let prob be 32767*Getscroll("p");

And we repeat for 200 trials the following 20 experiments:

  1. Count successes with variable X for each trial.

  2. After each trial, update the Data Table (set entry j 2 to getentry(j,2)+1/200;)

Let X be 0;

Count successes:

 
Repeat 20 {

If Random() <= prob Then {let X be X + 1}

}

Record the result for this trial:

 
do
flag = true
j=1
while and(flag, j<=21) {
If X==j-1 then {
set entry j 2 to getentry(j,2)+1/200;
flag := false;
}
let j be j+1;
}

Finally, draw the Histogram. For that, we use the Polygon Command, reading the heights from the Data Table itself. Needless to say, we could have streamlined the whole procedure by using vectors directly, rather than a Data Table, but the author's intention was, presumably, to represent the process dynamically. It would also have been possible to update the two columns just before this step using Setvector, and then to draw the histogram by reading the vector in the background.

let m be 0;
do
k := 1
while k <= 21 {
polygon[[k-3/2,k-3/2,k-1/2,k-1/2],[0,getentry(k,2),getentry(k,2),0]] color yellow fill blue;
let m be m+(k-1)*getentry(k,2);
let k be k+1;
}
draw the line from [m,0] to [m,1] using color red;
cleartext in "out";
printon "The average outcome is: ", m;

Save the Document.

Step 15: Add Popup Instructions

The last step in this project is to create Popup Instructions. For this, we will use the Create command, which is very powerful. It allows you to create a floating Popup Window under program control. These Popup Windows are subtly different from "ordinary" Display Objects. They "float" on the screen and can be resized. When you leave the page, they disappear, and Readers can dismiss them from their menus by selecting the Close item. Ordinary Display Objects cannot be closed by Readers. The syntax of the Create Command as explained elsewhere in this Help file is as follows. The Destroy Command is the dual of this, and destroys objects.

create name type mode left top right bottom action;

If the argument is a Program Name, the program it refers to should take no arguments. If the object is a PushButton, CheckBox, TextLine or ScrollBar, then the program becomes the script for the object. Left mouse click (or Enter for TextLine) causes the script to be executed.

If the object is not a scrollbar, pushbutton, textline or checkbox, then the program is simply evaluated once, when the object is created. For example, the program might put text into a Text Field or draw a graph in a graphics window. The object being created cannot be selected, however.

If the argument is a String, it becomes the Seed Text for: Commandfield, TextBox, TextLine, CheckBox. If the Object is a Graph2D, the string is interpreted as a path to wallpaper which is loaded after the Graph2D is created. Otherwise if the object is a MathEdit, the string is interpreted as the path to an .MEW file which is loaded after the object is created.

With this said, go to Design mode and draw a PushButton called "Information". We have lined it up using Snap to grid with the Run button above it and the out TextBox to its right. Next, return to Reader mode. Add the following Script.

destroy "Information" "mathedit";
create "Information" "mathedit" 3 5 25 95 75 "message.mew";

The first line guarantees that the Reader will not create multiple popups by pushing the button over and over. If the system does not find a MathEdit named Information, Destroy does not give an error, but if it does, then the first line removes it.

The second line uses the resource: "message.mew" as seed text and pictures for the MathEdit just created. In general, you can create your own messages by writing a script like this and pushing the button. When the blank MathEdit pops up, you may write your message in it and save it to disk using: Save As... on the MathEdit menu.

Save the Document.

End of Project 3