% User documentation for the EYE project.
%
% Begun 26 Feb 96
% Copyright Mary Soon Lee 1996
%------------------------------------------------------------------
\documentstyle[psfig]{article}

\title{EYE Documentation: Version 0.0}
\author{}

\begin{document} 
 
\maketitle 
 
\section{Introduction}

EYE is a tool to help people apply machine learning and statistical
techniques.  It enables people to use advanced techniques without
needing to master the underlying algorithms.  Instead EYE has a simple
interface where the user presents the raw data, and then applies EYE to
perform the desired analysis.  Options include:
\begin{itemize}
\item {\bf blackbox}: searches for a model that accurately explains the data.
\item{\bf optimize}: finds a set of inputs that will optimize a given
  criterion, for instance to maximize the sum of the outputs.
\item {\bf predict}: predicts future behavior from past data.
\end{itemize}
See Section~\ref{compendium} for a compendium of EYE options.

This document explains how to use EYE.  If you are in a hurry to begin,
you need only read section~\ref{example} and section~\ref{starting}.
Later sections describe the online help facility, additional user
interface tools, and the advanced interface to EYE.

To illustrate the use of EYE, we consider the example of a gardener
trying to grow prize-winning flowers.

\subsection{An Example: The Gardener}
\label{example}

Suppose a gardener with an interest in machine learning wants to grow
prize-winning flowers.  She's kept records of her past attempts: what
fertilizers she used, how much she watered the seedlings, the
temperature of the greenhouse, what height the flowers grew to, how
brightly-colored they were.

The gardener decides to use EYE to help her.  She has several new plant
regimens in mind, and wants EYE to predict how well each one will
perform.  She's also curious to see what regimen EYE itself will
recommend if she asks it to maximize the brightness of the flowers,
subject to the constraint that the flowers must be at least thirty
centimeters in height.

\section{Getting Started: How to Get EYE Running}
\label{starting}

This section provides all the information you need to start using EYE.

EYE can run under either Windows 95 or Windows NT on a PC.  To start it,
bring up an MS-DOS Command Prompt window, move to the directory where
you saved the EYE executable (by using the cd command), and type EYE.
This will bring up the EYE window with the initial welcome screen.

The simplest way to use EYE is via the GMBL menu\footnote{For the
curious, GMBL stands for General Memory Based Learning, the machine
learning approach that underpins the EYE code.} on the main menu bar.
Click the GMBL menu label with the left mouse button, and then click the
first menu item, ``Run GMBL.''  This brings up the following dialog box:

\centerline{\psfig{file=simpledialog.ps,height=3in}}

Suppose the gardener introduced in section~\ref{example} wants to see
how the flower-height depends on the various factors in the plant
regimen (the quantity of green-grow fertilizer, the number of
mineral-drops, the amount of water, and the temperature of the
greenhouse).  To find out, first type garden.mbl into the datafile slot
of the dialog box to tell EYE to use the gardening data.  Now select the
{\bf graph} option from the main listbox by clicking it with the left
mouse button.  The dialog box should now look like this:

\centerline{\psfig{file=simpledialog2.ps,height=3in}}

Press the RUN button.  A black eye appears while EYE analyzes the
data, and then EYE displays four graphs, showing how the flower-height
varies with each of the four factors in turn, while the other factors
are held constant.  Notice that the bottom-right graph, corresponding
to the effect of temperature, is a flat line.  This shows that the
flower-height is unaffected by the temperature---at least for the
regimens the gardener has tried in the past.

To run EYE again, select the ``Run GMBL'' option from the GMBL menu as
before.  The same dialog box will appear, with the datafile already
filled in as garden.mbl.  Perhaps this time the gardener, being an
intrepid soul, wants to see if EYE can find a model that explains the
data.  To follow in her footsteps, select the {\bf blackbox} option
from the listbox and then press the RUN button.

The black eye appears, showing that EYE is at work, and results start
scrolling down the screen.  EYE is busy searching for a good model for
the data.  The {\bf blackbox} option performs this search without any
prompting from the user.  It tries out function approximators such as
nearest neighbor, kernel regression, and attribute subsets---autonomously
tuning their parameters and deciding which model to test next.

After a few seconds, the black eye disappears, and the text stops
scrolling.  You can now examine EYE's report on the {\bf blackbox}
search.  The overall evaluation should be visible at the bottom of the
scrollable window.  It should look something like this\footnote{Because
EYE uses random numbers to make such decisions as which data should be
used in the testset, the precise results will vary from one run to the
next.}:

\begin{verbatim}
4.  Evaluation.

        Now, if we simply predicted the global average, 
        the mean-abs testset error would be 5.67.

        The best thing we've found so far in the
        searches reduces that by 96%.
\end{verbatim}

This tells us that EYE has found a model for the data whose average
prediction error is just four percent of that for the global average
model.

You have now learned almost all that you need to know to start applying
EYE to your own data.  Just select ``Run GMBL,'' type in the datafile,
select the option you want, and press the RUN button.  There is only one
more thing you need to know: how to get EYE to use your own data.

\subsection{Datafiles}

% !!!!
Paragraph about datafiles (standard format: one data point per line).
The file menu.   

As you run EYE, you may spot unfamiliar terms appearing on the screen,
such as {\bf gmstring} or {\bf loohist}.  The following section
describes how to get online help that will explain cryptic terms like
these.  Later sections describe such things as how to switch to the
previous screen, how to halt EYE mid way through a computation, and how
to use the advanced interface to gain additional control.

\section{Getting Help}
\label{help}

\section{A Medley of Other Controls}
The eye cursor.
The blackbox image.
\subsection{Halting EYE}
\subsection{Where Did the Last Screen Go?}
\subsection{Colors and Fonts}

\section{An Advanced Interface to EYE}
\subsection{A Note on Data Formats}

\section{A Compendium of EYE Functions} 
\label{compendium}

\section{Schenley Park Research, Inc.}

\end{document}