=====================================================================
= SeASR toolkit and documentation Copyright Justin Moore, (c) 2004  =
= SeASR is distributed under the GNU General Public License         =
= See the COPYING file for details                                  =
= Contact Justin Moore (justin@cs.duke.edu) with questions          =
=====================================================================

This README provides an overview of the Sensor Analysis and Synthetic 
Reproduction, or SeASR (si-zar), toolkit.  Given a trace of sensor 
readings, SeASR performs a statistical analysis of how the sensor values 
change and can help you generate an arbitrary number of traces with 
similar properties.  It is important to note that the tool primarily 
examines how values /change/, not that actual groupings of the values.  
Future versions may attempt to examine how the values change depending on 
the current value; for example, when one-minute load average is above 3.0, 
it is more likely to decrease than increase.  Such features are not 
currently implemented.

SeASR consists of one main script -- ./scripts/total_analysis.pl -- and 
several supporting programs and scripts.  This distribution comes with a 
sample data file to give you a feel for how SeASR works.  The end result 
of the total_analysis.pl script is the statistical model used as part of 
the ./mktrace/run_mktrace.pl input file.

SeASR has the following requirements:

- the glib-dev package
- a working logl() and expl() function (a.la. the C99 standard)
- gcc and perl

To run SeASR, do the following:

1. Edit ./scripts/total_analysis.pl and ./mktrace/run_mktrace.pl to set
BASEDIR to the path where you've installed the SeASR components.

2. Compile the three support applications:

$ cd create-markov/ ; make ; cd ..
$ cd em-cluster/ ; make ; cd ..
$ cd mktrace/ ; make ; cd ..

3. Try running the ./scripts/total_analysis.pl program on the sample data.

$ ./scripts/total_analysis.pl ./sample-readings.txt

The script will print a rather verbose execution log to stdout and stderr, 
most of which you can ignore.  If everything goes well, you will end up 
with a few leftover intermediate files in /tmp/, gnuplot script and data 
files in the current working directory, and part of a mktrace.conf file in 
the current working directory.  The base-mktrace file will have

o the average (start), minimum and maximum sensor reading values;
o the mean and standard deviation of the time intervals between readings,
    as well as the minimum and maximum time intervals;
o the mean, standard deviation, and magnitude of each Gaussian; and
o the Markov model for the sensor reading deltas change.

4. To create a synthetic trace, all you need to do is add a start time, 
end time, object ID, location ID, input type ID, and optional output 
formatting preferences to the base-mktrace file.  Then you can run

$ ./mktrace/run_mktrace.pl ./base-mktrace

NOTE: This /will/ create several output files in the current working 
directory, depending on your start and end times and the granularity of 
the output files (the 'output_time' option you specify).  You may want to 
consider creating a ./traces/ directory and then running

$ ./../mktrace/run_mktrace.pl ../base-mktrace

Happy synthetic trace reproduction!!
-jdm