Statistics101 Resampling Stats Commands

A simulation of a statistical or probability problem in the Resampling Stats language consists of a sequence of Resampling Stats commands. A Resampling Stats command usually consists of one text line that starts with the command name, followed by a list of arguments. The argument list consists of literals, variables, and keywords. The complete list of commands organized into categories can be found here.

Continuation Lines

Normally you will type each command and all its arguments on a single line. A line in the editor can be as long as needed. But sometimes you might want to divide a command over more than one line. You can do this by ending each line of the command except its last with the continuation character, which is the backslash ("\"). For example, the command

HISTOGRAM percent binsize 0.1 "Probability Density" "X value" distribution

could in the extreme, be written over several lines like this:

HISTOGRAM percent \
  binsize 0.1 \
  "Probability Density" \  'Y axis label
  "X value" \              'X axis label
  distribution             'Last line has no continuation marker

Note that the last line must not have a continuation character. If you have a comment on a continuation line, the comment must follow the continuation marker as in the first two comments in the above example. If you put the continuation marker after the comment, it will be considered part of the comment and ignored, resulting in a syntax error message. Also, do not break a line in the middle of a variable name, keyword, or quoted string.

Definitions

The basic data structure in Resampling Stats is the list, or vector, which is an ordered set of numbers. Each number in a vector is called an element. A vector consisting of just one number is also called a number. A sequence is a list of numbers, each of which differs by the same number, called the "stepsize", in the same direction from its predecessor.

A literal is a value in and of itself that has no name. There are several kinds of literals:

• A number literal is just an unnamed number. 12.34 is a literal number. So is 4.567E03, which is the scientific notation for the number 4567.0. Further comments on literal numbers:

  • The simplest rule to remember is to avoid spaces and plus signs within numbers. Plus signs are never allowed in front of a number, but are optional in the exponent of a number in scientific notation. Examples of valid numbers: 1.234E12, -3.456E-5, 12.345e+3. Example of an invalid scientific notation numbers: +1.234E12 (has a leading plus sign), 1.234 E12 (has a space before the "E").

  • A fractional number, such as 0.02 or 0.123 must have the zero prior to the decimal point. In other words, .02 and .123 are incorrect. In fact, the program will interpret them as having missing data. Thus, the command

COPY (1 .02 .123) myVector

will produce the result

myVector: (1.0 NaN 2.0 NaN 123.0)

• A list literal is represented in Resampling Stats as a set of numbers separated by one or more spaces (not commas) and enclosed within parentheses, such as (5 3 9 8 0 21 45).

• A sequence literal is specified by two or three numbers separated by commas. The first number becomes the first value in the sequence, the second number becomes the final value in the sequence, and the optional third number, called the "step" or "stepsize" specifies the difference between adjacent values. The step must be greater than zero. The comma is called the sequence operator. For example, the sequence of integers from 1 to 100 is represented by the literal 1,100. The sequence of integers from 20 down to 1 is represented by the literal 20,1. Note that the list literal (above) must be enclosed in parentheses, but the sequence literal must not be. The numbers may be integers, floating point numbers, or even named constants (see below). If only two numbers are used, then the difference between each adjacent pair of numbers in the sequence is one. If you want a different step size, you will add that as the third number. For example, 0,10,2 produces the sequence of even numbers between 0 and 10, inclusive. Another example, 2.5,7.5,0.5 produces the sequence (2.5 3.0 3.5 4.0 4.5 5.0 5.5 6.0 6.5 7.0 7.5).

• A multiple literal is specified by two numbers separated by a number sign, "#", in the format quantity#value. The number sign is called the multiple operator. For example, in its simplest form, 5#2 is interpreted as a list of 5 twos, i.e., it is equivalent to (2 2 2 2 2). See the COPY command for more information on the use of multiple specifications.

• Non-numerical literals are special characters which have significance within certain commands. Examples are # and %. Keywords, which are optional words that identify certain values to a command, are also non-numerical literals. Examples are: percent, used by the HISTOGRAM command, and divn used by the STDEV command.

• A missing data element literal is either a period (".") or "NaN". NaN stands for "Not a Number". These can be used in a data file to be read using the READ command or in a literal list in a program. For example, in the command COPY (1 2 3 NaN 5 . 7) data, the list has two missing values. The case (upper case or lower case) of NaN is not considered; therefore, "NAN", "nan", "nAn", etc., are all interpreted as "NaN". Missing data has the following behavior with regard to test operators (see Test Operators table) NaNs are equal to each other. For all other tests, they fail. For example, NaN is not equal to, greater than, or less than any actual number. NaN is not positive or negative infinity. This is different from their behavior in the original Resampling Stats where the missing values were equivalent to negative infinity.

A keyword is a word, recognized by Statistics101, which selects a feature of a command or alters the behavior of a command. For example, for the READ command, the keyword file is used to identify where the command should look for its data.

A variable in the Resampling Stats language is a named entity whose value is a list. A name begins with a letter and may be followed by any combination of letters, numbers, underscore ("_"), hyphen ("-") and dollar sign ("$"). Upper and lower case are not distinguished, so the names "name", "NAME", and "NaMe" are treated as identical. A feature added by Statistics101 to the Resampling Stats language is that variables can be used in many places where before only literal constants were allowed. For example, values are allowed on either or both sides of the "#" in multiple specifications and on either or both sides of the "," in sequence specifications. For example, var1#var2 is valid as long as var1 and var2 are defined earlier in the program. Variables are not allowed in lists, however. For example, (1 2 var1 3) is illegal because it contains the variable name var1.

A named constant is a number that has been given a name by the NAME command. The rules for valid names of named constants are the same as those for variables. Named constants can be used wherever literal numbers can be used. Thus if ace and king are named constants (say with values 1 and 13, respectively), they can be used in lists, e.g., (ace 3 4 5 king), in sequences, e.g., ace,king, and in multiple specifications, e.g., 4#ace. The named constant is a new feature added to the Resampling Stats language by Statistics101. There are two categories of named constants: Names and Named Values.

• Enums are named constants to which the user (you) has not assigned a value. Statistics101 assigns an arbitrary undisclosed value to the name. You use enums when the value of the element is not important. For example, it is not important what numbers are assigned to the names heads and tails; only that their values be different.

• Named Values are named constants to which you have assigned specific values. You use these when the number associated with the name is important. Examples of this are ace and king above, which were assigned the values 1 and 13.

As stated earlier, named constants can be used anywhere that normal numbers can be used. When they are used in sequences, such as ace,king , the sequence is determined by the order of the names between ace and king, inclusive, when they were defined in their NAME command, not by their assigned values, if any.

Throughout the Resampling Stats language, typographical case is not distinguished. Commands, keywords, and variable names may be upper case, lower case, or any combination. Thus, two variables whose names vary only in their case are the same variable. For example, myVar and MYVAR and MyVar are all considered the same.

The values of named constants and literals are established during "parse time" as Statistics101 analyzes and builds your program. The values of variables are determined at execution, or "run time", as your program is actually being executed. Therefore, the value of a sequence or multiple specification that uses variables will be undefined until run time whereas those using only literals or named constants will be defined at parse time. This is a technical point that may be of interest only to a very few users.

Command Description Syntax

All the commands of the Resampling Stats language that are implemented by Statistics101 are listed and described in the Command Description Table. Each command description has a one-line entry that describes its argument list. For example, the command syntax of the ADD command is the following:

ADD inputVector inputVector {inputVector} resultVariable

The following table explains how to interpret each part of the command syntax descriptions. Based on the table, the above command means that the ADD command takes at least two input vectors and one result variable. If you find it difficult to understand or apply the syntax description for a command, try using the Wizard for that command, which you can access via the F2 key or the Help>Wizards menu item.

ABS vector1 resultVector
Abs Vector1 ResultVector

ABS vector1 abs
PRINT abs

STDEV divn mySampleData myResult

RANKS descending inVector outVector

Tests

There are eight commands that require tests. These are COUNT, IF, MULTIPLES, RECODE, RUNS, TAGS, WEED, and WHILE. A test limits a command so that it only operate on input vector elements that pass the test. Most of the tests compare elements of a vector on the left of the test operator to a number on the right. Two of the tests (between and notBetween) compare elements of a vector on their left to two numbers on the right of the test operator. See the examples in the Test Operators table immediately below. The right-hand argument(s) of a test need not be a literal number(s). They may be vectors, but if they are, only the first element of the right-hand argument(s) is used by the test. Thus, if you have the command COUNT vec1 = vec2 result, only the first element in vec2 is used for the test against all the elements of vec1. The arguments of a test may also be named constants. As usual, the typographical case of the keywords is ignored, so for example, notBetween is the same as notbetween and NOTBetween.

COUNT Z > 5 result

COUNT Z < 5 result

COUNT Z <> 4 result

COUNT Z >= 5 result

COUNT Z <= 5 result

COUNT Z memberof aList result

COUNT Z notMemberOf aList result

Logical Expressions

The term "Logical Expressions" includes simple tests such as those above, and compound tests. "Compound tests" consist of several tests that are linked by the logical operators, AND, OR, XOR, and NOT. Logical expressions are used with the IF, ELSEIF, and WHILE commands. All the logical operators are described in the Logical Operators table, below. Here is an example of a snippet of code that does not use logical expressions:

   IF player1 = twin
      IF player2 = twin
         ADD 1 twinsMatchedCount twinsMatchedCount
      END
   END

Writing an equivalent snippet using a logical expression simplifies the code as follows:

   IF player1 = twin AND player2 = twin
         ADD 1 twinsMatchedCount twinsMatchedCount
   END

The operators AND, OR, and XOR are called "binary" operators because they take two operands, or arguments, one on each side. The NOT operator is called a "unary" operator because it takes only one operand, that on its right side. A logical expression may be of any complexity and length but it must be entirely on one line as must all Resampling Stats commands. As usual, the operators may be in upper case, lower case, or mixed case.

In the absence of parentheses, the order in which the logical operators are executed is determined by their default "precedence". Higher precedence operators are executed before lower precedence operators. The operators OR, and XOR are of equal, and lowest, precedence. AND is of higher precedence, and NOT is of highest precedence. The following examples will help to clarify the precedence rules. In the examples, the terms "test1" and "test2" etc. are used as a "shorthand" to represent tests of the form "a = b" or "a < b". Thus, a complete logical expression such as

a > b AND c = d OR e between 1 2 AND f < g

can be written like this in that shorthand:

test1 AND test2 OR test3 AND test4

This shorthand is just for the purposes of visually simplifying the following examples. It is not valid Resampling Stats syntax and cannot be used in the Statistics101 program. Using the shorthand, the logical expression represented by,

test1 AND test2 OR test3 AND test4

is equivalent to

(test1 AND test2) OR (test3 AND test4)

because of the default precedence rules. The two AND operators will be executed prior to the OR operator. Another example, this time adding a NOT:

test1 AND not test2 OR test3 AND test4

The above logical expression is equivalent to:

(test1 AND (not test2)) OR (test3 AND test4)

A good way to understand how the precedence rules apply in the absence of parentheses that override the defaults is this: First all NOTs bind to the test that follows them, second, all ANDs bind to their arguments, and third, all ORs bind to their arguments that are the results of the first two steps. In the second step, if there are several ANDs in sequence they are all grouped together as in this next comparison of equivalent expressions:

test1 AND test2 AND test3 OR test4 AND test5 AND test6

The above logical expression is equivalent to:

(test1 AND test2 AND test3) OR (test4 AND test5 AND test6)

Applying the rules to this next expression which has several ORs in sequence with an AND in the middle:

test1 OR test2 OR test3 AND test4 OR test5 OR test6

results in this equivalent expressed using parentheses:

test1 OR test2 OR (test3 AND test4) OR test5 OR test6

If you have any uncertainty about how the defaults apply in a complex logical expression that you write, you should use parentheses to force the expression to have the meaning you want.

IF NOT A = 4

IF A <> 4

IF A > 5 AND B between 1 2

IF A < 5 OR B <> C

IF A = 5 XOR B = 15