
==========================
Instructions for avgCol.pl
--updated 16/11/08
==========================

This is a perl script which can be used to average the output of
another program which prints columns of numbers to STDOUT (which is
what System.out.println does in Java). Columns are separated by
whitespace and rows by line breaks.

The script runs the other program n times, collects its output, and
prints out columns of averaged numbers.

This script also appends an initial column as an index.

To use the script under unix you must have perl installed so that it
executes from the command prompt and you must also make the averaging
script executable, which you can do with: chmod u+x avgCol.pl

---------
Arguments
---------

Run script with two arguments (optional 3rd):
arg 1: command to run to start the other program
arg 2: number of repeats
arg 3: prefix

for example (in unix):

./avgCol.pl "java myApplication appArg1 appArg2" 30

where appArg1 and appArg2 are passed to myApplication's
main method as Strings.

------
Inputs
------

The averaging script parses the STDOUT output from the command it runs, 
ignoring the STDERR output. The input it expects is a column of numbers 
separated by line breaks. 

The script should ignore any lines which do not begin with a number,
so you can print out comments.

You will often want to print different things to STDOUT
(e.g. debugging information, a value function, a policy...) and to
then extract only the information you want. You can tell the averaging
script which lines should be averaged by prefixing them with a special
string in the output, and telling the averaging script what this
prefix is. In the following example the prefix is "error: ".

./avgCol.pl "java MCAssignment" 30 "error: "

would pick the four error lines from the following:

blah blah blah blah blah blah
error: 4.5
irrelevant: 32
h blah bla
blah blah blah blah
error: 2
blah blah blah blah blah blah
error: 1
irrelevant: 32
h blah bla
blah blah blah blah
error: 0.7623

-------
Outputs
-------

The output from the script has the following form for ease of use in 
gnuplot:

0 3.2
1 2.3
2 2.15
3 2.12

The first column is an index generated by the averaging script and the
second contains the averaged values from the first column of the
source it was given.

In unix you can capture the output of the script (or any program
which writes to STDOUT) in a file by redirecting it like this:

./avgCol.pl "java MCAssignment" 30 "error: " > output.txt

In windows you probably have to cut and paste the output.


-------------------
Use with RL library
-------------------

Not all the experiments defined by the libraryproduce output that is
suitable for averaging with the script. However, the ones which play
games of tic-tac-toe and print columns of win/lose/draw statistics
are suitable.

For example, to average 10 runs of a randomly-playing agent against a
Monte Carlo reinforcement learner, edit the main method in
MCAssignment.java so that it calls playRandomAndMC(). Then recompile
the library with:

javac MCAssignment.java

Finally, you can start the experiment and capture the output in a file
called "data" with:

./avgCol.pl "java MCAssignment" 10 > data

You can now inspect data with any text editor or spreadsheet, or plot
it with gnuplot. If gnuplot is installed and you have copied the
plotTTT script to the /code directory you can plot the data file
created above with:

gnuplot plotTTT

