An introduction to RLPlot scripting

RLPlot supports a "C"-style scripting language with all elements of the scripts being inside the spreadsheet

Execution modes

The immediate mode is entered when a formula is entered into a spread sheet cell. Formulas start with a "=" as first character of the cell.
The program mode is entered from immediate mode my calling the eval(), exec(), or call() function.

Syntax summary

Separating statements
Each statement is terminated by either a comma, ',', or a semicolon, ';'. Typically each line is terminated by a semicolon. The possibility to separate statements by a comma should be restricted to cases where it is necessary by the overall syntax.

Parenthesis
Round parenthesis, '(' and ')', are used to overrule operator precedence and they also enclose arguments of a function call.
Curly parenthesis, '{' and '}', enclose a block statement. Block statements are used to structure the code and are required for conditional execution blocks: They follow an if, else, for, or while statement.
Square parenthesis, '[' and ']', are used with arrays. They enclose an index for the array, accessing a single element of the array.

Function arguments
Arguments to functions are separated by ',' or ';'. If arguments may be interpreted as a list, possibly a list with variable length, ',' is used. For multiple list or mixed types ';' is used. If a function expects a fixed number of arguments, either ',' or ';' can be used. See the function descriptions for details.

Comments
Cells starting with a double slash, '//', are treated as comment. All cells following on the same line or row are also treated as comment.

International character sets
No attempt has been made to allow country specific characters. They are allowed inside string constants only. For variable names use 'A..Z', 'a..z', '0..9', and '_' only. Names must not contain spaces or punctuation characters.

Loops

The number of iteration for all loops is limited by maxiter(). This provides against infininite loops.

FOR loop: syntax1
Using this syntax the 'for'-token is followed by three statments enclosed in round parenthesis. During execution the first of these three statements is executed once. The third statement and an optional block statement after the last parenthesis are executed as long as the seond statement is true.

example:

s = 0; a = a1:a11; for(i = 0; i < count(a); i++) {     s += a[i];     } ...

FOR loop: syntax2
This notation steps through an array and assigns its values to a variable. The following example is equivalent to the above.

example:

s = 0; a = a1:a11; for(v in a) {     s += v;     } ...

WHILE loop
The 'while'-token is followed by an expression enclosed in round parenthesis followed by block statement. The block statement is executed as often and as long as the expression following the 'while' token is true. The following example is equivalent to the above examples.

example:

i = s = 0; a = a1:a11; while(i < count(a)) {     s += a[i]; i++;     } ...

Flow control

return
The return statement exits the current script. An optional argument may be given. With no argument the result of the last operation is returned.

break
Break exits the current block statement.

if(exp){code}
if(exp){code1}else{code2}
If initiates conditional execution. The statement is followed by an expression enclosed in round parenthesis followed by an execution block. The block is executed only if the first expression is true. The execution block may be followed by an optional 'else' statement and a second execution block. This second block is executed only if the first expression evaluates to false. The following example is eqivalent to the above examples.

example:

i = 0; a = a1:a11; while(i < count(a)) {     if(i > 0) {         s += a[i];         }     else {         s = a[0];         }     i++;     } ...

Example 1: Using a single fomula for a range of calulations

This example demonstrates the use of eval(), exec(), and call() to apply the same calculation on a range of data. The formula for this example is given in cell b1. Note that this formula is a text value. All three possibilities give the same result. When the formula occupies only one cell of the spread sheet, as in this example, the function eval() is probably the right choice.

		A	B	C	D
	1		log10(a)
	2
	3	12	=a=a3;eval($b$1)	=a=a3;call("b1:b1")	=a="a="+a3;exec("b1:b1";a)
	4	110	=a=a4;eval($b$1)	=a=a4;call("b1:b1")	=a="a="+a4;exec("b1:b1";a)
	5	53	=a=a5;eval($b$1)	=a=a5;call("b1:b1")	=a="a="+a5;exec("b1:b1";a)
	6	67	=a=a6;eval($b$1)	=a=a6;call("b1:b1")	=a="a="+a6;exec("b1:b1";a)
	7	675	=a=a7;eval($b$1)	=a=a7;call("b1:b1")	=a="a="+a7;exec("b1:b1";a)

displays as:

		A	B	C	D
	1		log10(a)
	2
	3	12	1.07918	1.07918	1.07918
	4	110	2.04139	2.04139	2.04139
	5	53	1.72428	1.72428	1.72428
	6	67	1.82607	1.82607	1.82607
	7	675	2.8293	2.8293	2.8293

changing cell 'b1' only, fom 'log10(a)' to 'sqrt(a)', changes the whole display to:

		A	B	C	D
	1		sqrt(a)
	2
	3	12	3.4641	3.4641	3.4641
	4	110	10.4881	10.4881	10.4881
	5	53	7.28011	7.28011	7.28011
	6	67	8.18535	8.18535	8.18535
	7	675	25.9808	25.9808	25.9808

Example 2: Bootstrapping a mean

Bootstrapping is a resampling technique to determine the accuracy or confidence interval of a parameter, being less sensitive to the actual distribution of the data than parametric solutions. In this example the arithmetic mean is bootstrapped an the mean and 95% confidence interval are given. Changing cell 'd4' to 'true' starts execution.
download bootstrap_mean.rlw

Notes:
1) For asymetric distributions the result can be asymetric. Actual results may vary, but this variation may be reduced by increasing the number of iterations.
2) The value in 'd4' is a semaphore. The script is only executed if this value is 'true'. The semaphore is reset to 'false' in cell 'f12'. If this cell is changed to '//d4 = false' or deleted, the script is executed every time when the spreadsheet is recalculated.

after execution the spreadsheet displays as:

Note:
The values in 'd8', 'd9', and 'd10' vary slightly upon each execution of the script because the random number generator is free running.

Example 3: Bootstrapping a correlation coefficient

This example gives a more elaborate design than in example 2. Execution is started by changing the value of the semaphore in 'd3' from 'false' to 'true'. It is reset to 'false' by the script in 'f29'.
The script first checks the data for valid pairs and creates a primary index. This primary index contains the values 0 .. n-1. The script is now iterating 1000times, calculating 1000 correlations, using a resample of the primary index to create a resample of the valid data pairs. The 95% confidence interval for the correleation coefficient is obviously given by the 1000 sorted coefficients between the 25^th and 975^th value.
The results of the scripts are returned in cells 'd6:d9'. Actual values may vary between calculations because the random number generator is free running. The correlation between column 'A' and column 'B' is significant on the 95% level because zero is not in between 'lo 95%' and 'hi 95%'.
download bootstrap_corr.rlw