\section{Examples}
\label{sec:examples}
The software distribution comes with a directory of examples.
These examples are meant to illustrate different features
of the Aspirin/MIGRAINES system. The examples {\em sonar} and
{\em nettalk} are well known neural network applications.
The data has been made available by the authors of
these applications {\bf for research purposes only}
\footnote{This data was acquired via the {\bf nnbench} mailing
list, Scott Fahlman moderator.}.

Each example has a group of README files that describe
the usage of  Aspirin/MIGRAINES. Read these carefully
to understand how to run the programs generated by
{\tt bpmake}.

In each directory is a file called {\tt Learn} which
is an executable shell script.
The {\tt Learn}
files are meant as examples of how to set up the
networks to learn.
Read the {\tt Learn} files and 
then execute them. Upon successful completion 
of a learning run a
dump file called {\tt Network.Finished}
will be written to the directory. 
The weights in the final network can be viewed through
a plotting package. All the {\tt Learn}
files use Gnuplot3 as the plotting
package, although almost any plotting
package may be used.
In particular, the 
patterns that the weights have formed
are of interest. 


Each example directory also contains a {\tt Runs}
directory which contains files of runs of the {\tt Learn}
script on different machines.

\subsection*{BAYES}
This example shows that a backprop neural network
can learn to approximate the optimal bayesian
decision surface. Four normal random variables
that represent different classes
are used to train the network. Plots are generated
showing the decision surface and the input distributions.
The optimal bayesian decision surface follows the
basin of the valleys between the different input
random variables. The plots show that the neural network
has learned to place the decision surface along these
valleys. 

This example illustrates the use of a
\verb+user_init.c+ file to create your
own data generators.


\subsection*{CHARACTERS}
This example contains data used in 
``An Analysis of Noise Tolerance 
for a Neural Network Recognition System''~\cite{ref:noise}.
The network in this example
learns to recognize the letters {\bf A,B,C,D}
independent of rotation and in the presence
of noise. This is a very simplified version
of the experiment described in~\cite{ref:noise}.

This example illustrates the use of tessellation
and multiple black boxes. This example does not
{\em require} multiple black boxes. This
is a situation where one might want 
multiple black boxes so, once trained, 
they can be used
as modules in other networks.

The data used is in Type1 files generated on a Sun
workstation (IEEE 32 bit big-endian floats).

\subsection*{ENCODE}
This example is also taken from~\cite{ref:pdp}.
The goal of this network is to map a binary
set of inputs to the same binary set of outputs
using a small number (e.g. $\log_2(n)$) of hidden
nodes.

After training the network
examine the weights connecting the hidden layer
to the output. Many times these
weights converge to a binary number encoding.
If the magnitudes of the weights are ignored
and just the signs considered, then
you can read these as the binary numbers
0 through 7.

\subsection*{DETECT}
This network detects a sign wave in noise.
This example illustrates the use of the
\verb+user_init.c+ file to create your
own data generators.

\subsection*{IRIS}
The data set to be used was published by Fisher~\cite{ref:fisher1} and has been used 
widely as a testbed for statistical analysis techniques. The sepal length, 
sepal width, petal length, and petal width were measured on 50 iris specimens 
from each of 3 species, Iris setosa, Iris versicolor, and Iris virginica.

\subsection*{MONK's Problems}
The MONK's problem were the basis of a first international comparison
of learning algorithms. The result of this comparison is summarized in
``The MONK's Problems - A Performance Comparison of Different Learning
algorithms''~\cite{ref:monk}.

The MONK's problems are derived from a domain in which each training
example is represented by six discrete-valued attributes. Each problem
involves learning a binary function defined over this domain, from a
sample of training examples of this function. Experiments were
performed with and without noise in the training examples.

The example included is the backpropagation neural network trained
on the three problem sets.



\subsection*{NETTALK}
This example contains the data used in ``Parallel networks that 
learn to pronounce English text''~\cite{ref:sejnowski1}.
The network is trained on a database of text to phoneme
mappings. The original system described in~\cite{ref:sejnowski1}
could output the phonemes to a 
DECTalk\footnote{Digital Equipment Corporation, {\em DTC-01-AA}.}
 system for
actual audio playback of the text. Read the file
README.nettalk for a full description.

This example illustrates the use of the \verb+user_init.c+
file to build your own data generators. Also, a complete
stand-alone application called \verb+Performance+ is
included. This program links to the simulation and 
measures the performance of the network using the 
``Best Guess'' metric. 


\subsection*{PERF}
This example is a large network. It is used
only for benchmarking


\subsection*{RINGING}
This example illustrates the use of an
autoregressive~\cite{ref:leighton2}(see \ref{sec:appendix.ar}) network
to learn a time varying function. In this
case a exponentially decaying sinusoid.


\subsection*{SEQUENCE}
This example illustrates the use of an
autoregressive network
to learn to recognize sequences of events.
The training
set consists of sequences of tokens. The network is trained
using the AR backpropagation algorithm~\cite{ref:leighton2}(see \ref{sec:appendix.ar})
to recognize a particular 
sequence within the training data. This cannot be done using the 
*same* architecture without AR nodes. It is tested for generalization
on the test set.

A simple feedforward network that will do this is in the file
ff.aspirin. Notice that delays are required on the input.
This is the typical approach to recognizing sequences, but
scales badly. If you need to recognize a very long sequence
(or your data is highly sampled) then the number of delays
(and 1st layer weights) can grow very large. The feedforward
network has 10 ($\sim$30\%) more weights than the AR network.
Normally both input delays and AR delays are used in AR backprop
networks for temporal recognition.

The idea of AR backprop is that the input delay window 
can remain small and AR ``memories'' can be used recognize
the temporal characteristics of the signal. 

The best solution for some problems is to use both (an ARMA network).

In this example, the AR network can separate~\footnote{There exists a threshold that
will separate the classes} the data with
no delays on the input. The feedforward network with delays
separates the data very well, but requires an input retina
as long as the sequence.

\subsection*{SONAR}
\begin{figure}
	\begin{center}
	 \ \psfig{file=PSfigures/Principal.ps,width=5in} 
	\end{center}	
	\label{fig:Principal}
	\caption{ Principal Components Analysis of Hidden Layer for Sonar Example}
\end{figure}
This example contains the data used in ``Analysis of Hidden Units
in a Layered Network Trained to Classify Sonar Targets''~\cite{ref:gorman1}.
In this example the neural network learns to separate
processed sonar returns from rocks and mines on the ocean
floor.  Read the file {\tt README.sonar} for a full description.

This example makes use of the {\tt analyze}
program to perform principal components
analysis and canonical discriminate analysis
to visualize the clustering performed
by the hidden layer.

\subsection*{SPIRAL}
\begin{figure}
	\begin{center}
	 \ \psfig{file=PSfigures/Spiral.ps,width=5in}
	\end{center}	
	\label{fig:Spiral}
	\caption{ The Spiral Problem }
\end{figure}
This an example of a very hard pattern recognition
problem. The data in this example are the x and y
coordinates of two spirals. In the actual data file
the coordinates for each spiral have an additional 
number associated with them which denotes to which
spiral the coordinate belongs to (i.e., 0.5 for
one spiral and -0.5 for the other). The two
spirals
coil three times around the origin and around one another.
The goal of this example is to train the network 
to map an x,y coordinate into the proper spiral.
The network is trained by giving it x and y and the target
classification for some of the points along 
these intertwined spirals. This problem
was originally conceived by this group at MITRE
and is described by Lang, {\em et al} in~\cite{ref:lang}. Read
the file {\tt README.spiral} for more details.

This example illustrates the use of user defined nodes
and user defined error functions.

\subsection*{WINE}
This example is taken from the ``UCI Repository Of 
Machine Learning Databases and Domain Theories'' 
(ics.uci.edu: pub/machine-learning-databases).
The purpose is to determine the origin of wines
by chemical analysis using 13 attributes (all continuous).
There are 3 classes.


\subsection*{XOR}
\begin{figure}
	\begin{center}
	 \ \psfig{file=PSfigures/ExecGnuXor.ps,width=5in}
	\caption{ Weight Evolution (from Gnuplot 3) }
	\end{center}	
	\label{fig:xor}
\end{figure}
This is an example taken from~\cite{ref:pdp}
whose historical significance dates back to
Minsky and Papert's book {\tt \underline{Perceptrons}}~\cite{ref:minsky}.
The largest criticism of the perceptron was
the inability of this method to converge
when the classes are not linearly separable.
The exclusive-or (XOR) problem is to map 1 0 to 1,
0 1 to 1, 0 0 to 0 and 1 1 to 0. This problem is not linearly
separable. Since the backpropagation method
can solve this problem it has overcome
a major shortcoming of perceptrons.

This example illustrates a simple Aspirin file
used with an ASCII data file. Notice
the skip level connections. The {\tt .df} file
controls the loading of the data files into
the network. The MIGRAINES file {\tt xor.cmd}
causes the weights to be dumped to file
as a function of learning iteration.
