GP-EVAL:  Evaluate function drawn from a Gaussian process.

GP-eval displays function values drawn at random from the Gaussian
processes defined by values for hyperparameters stored at various
iterations in a log file.  If no training data is specified, the
functions are drawn from the prior defined by the hyperparameters; if
there is training data, the functions are drawn from the conditional
process given this training data, or from the conditional process
given particular values for the function at the training points and/or
values for the noise variance at each training point, if these are
stored in the log file.  The points at which to evaluate the function
are either taken from a file, or are generated on a grid.

Note that although gp-eval is related to gp-pred, it differs in that
it does NOT average over iterations, and it generates functions at
random, rather than computing summaries such as the mean.  The gp-dgen
program is also related, and in some respects is more general.

Usage:

   gp-eval [ -l ] [ -t ] log-file range [ [-]N ] 
                         data-file [ "targets" ]

or:

   gp-eval [ -l ] [ -t ] log-file range [ [-]N ] 
                         { / low high grid-size } [ "targets" ]

N functions (default 1) are generated based on each iteration in the
named log-file, within the specified range.  The range has the usual
form, of "[low][:[high]][%mod]", with 'high' defaulting to 'low' if
the colon is absent, and to the end of the file if the colon is
present.  The random number seed used for the i'th function generated
for iteration t is 100*t+i, if no "-" precedes the value N, or just i,
if a "-" does precede N.  (The latter option may be useful to see how
the function generated by one seed varies with varying hyperparameter
values, though the effects are sensitive to the method used, based on
a Cholesky decomposition.)

For the first form, points at which to evaluate the functions are read
from the given file specification (which can have any of the forms
described in numin.doc), in the same way (and with the same
transformations) as training data is read.  In the second form each
group of the remaining arguments describes the grid along one input
dimension, with 'low' and 'high' being the range of the grid along
that dimension, and grid-size + 1 being the number of grid points
spread across that range.  The number of such argument groups must be
the same as the number of input dimensions, and currently cannot be
more than two.

The Gaussian process model in the log file must have only one output
value.

The output consists of a section for each function drawn, with
sections separated by blank lines.  Each section contains as many
lines as are in the data file, or as there are grid points.  If the
inputs are from a grid, each line contains the input values followed
by the output values.  If the inputs come from a file, eachh line
contains only the output values.  When a grid is used for more than
one input variable, a blank line is output between groups of points
where all but the last variable are the same.  There must be only one
output value.

If the -l option is not incldued, and latent values for training cases
are present, the functions are drawn from the conditional distribution
given these latent values.  If thee are no latent values, or if the -l
option is included, the functions are drawn from the conditional
distribution given the target values.  Note, however, that this is
possible only for regression models (ie, for "real" models).

If the -t option is included, or the final argument is "targets" (this
for backward compatibility), then rather than writing the function
values themselves, the program instead generates target values from
these outputs, as defined by the data model.  This option is currently
allowed only for real targets values.  The noise for these target
values will not be autocorrelated, though if the data model so
specifies, the generation of these values will be affected by
autocorrelation in the noise for the training cases (if any).

If the covariance does not include a jitter part, and there is no
noise added (ie, "targets" is not specified for a regression model),
then gp-eval will add a small amount (1e-6) to the diagonal of the
covariance to try to prevent numerical problems.  Round off error may
still make the covariance matrix appear to not be positive definite,
however, in which case a message about not being able to find the 
Cholesky decomposition will appear.

Note that the grid gives the actual values for the inputs.  Any
transformations that may have been specified with "data-spec" are
ignored.  (However, values from a data file are transformed as
specified by data-spec.)  Similarly, it is the raw function value (or
generated target value) that is displayed, without any transformation
(regardless of where the input values come from).

NOTE: The output produced with two inputs can be plotted as a surface
using "gnuplot".  Save the output of gp-eval in a file (eg, "plt"),
and then use the following gnuplot commands:

    set parametric
    set data style lines
    set hidden3d
    splot "plt"

The viewpoint can be changed with the "set view" and "replot" commands.

            Copyright (c) 1995-2004 by Radford M. Neal