Positional factory function for class deodorant.gp_toolbox.trained-gp-obj.

Takes the output of a gp prediction function and converts the variance
terms to standard deviation terms for both original derivative

Created a trained-gp-obj record that is used for efficient
prediction of gp at future points.

Accepts:     prior-mean-func
             cov-fn                  Same form as sent to gp train
             points                  Vector of pairs of [x y] observations
             alpha                   Vector of hyperparameters in same form as sent to gp train

Optional Inputs:
             grad-prior-mean-fn-x    Gradient of prior mean function.  Needed for some derivative
                                     calculations but not for basic use.
             grad-prior-cov-fn-x     Gradient of prior covariance function.  Needed for some derivative
                                     calculations but not for basic use.

Returns:     trained-gp-obj

Note that current usage of BOPP does not set these optional inputs.  They would be needed for anything
that requires taking gradients with respect to the GP inputs, for example solving the acquisition
function using gradient methods and left in for potential future convenience / other toolbox use.

Calculates the gradient of the gp-log-likelihood with
respect to the hyperparameters.

Accepts:  grad-cov-fn  - Function to return grad of covariance func wrt
                         the hyperparameters returned as DxNxN matrix
          x-diff-sq    - see gp-train
          L            - see gp-train
          psi          - see gp-train

Calculates the gp-log-likelihood given L, psi and y-bar

Calculates the mean and standard deviation from a weighted
sum of gps, i.e. a gp mixture model.  Note that the resulting
distribution is not a Gaussian, (the marginals are mixtures of
Gaussians) but the mean and covariance is still analytic.

Accepts:
 gp-predictors - A collection of gp prediction functions
 gp-weights - The relative weights of the gps
 xs - Positions to calculate the estimates at

Returns:
 mus - The means of the points
 sigs - The standard deviations of the points

Makes gp predictions for mu and
covariance for multiple points simultaneously.

Accepts   gp        - of type trained-gp-obj
          x*        - new points to evaluate   (MxD matrix)
          & args    - if (first args) is true then the full covariance matrix
                      is returned instead of just the marginal variance

Returns   mu        - predicted means (M length vector)
          cov       - (MxM matrix) corresponding to the covariance between the prediction points

Makes gp predictions for mu and marginal standard deviation
for multiple points simultaneously.

Accepts   gp        - of type trained-gp-obj
          x*        - new points to evaluate   (MxD matrix)

Returns   mu        - predicted means (M length vector)
          sig       - marginal predicted standard deviations

Makes gp predictions for mu, var, grad-mu and grad-var
given a gp-object and a single query point

Accepts    gp        - of type trained-gp-obj
           x*        - new points to evaluate   (D length vector)

Returns    mu        - predicted means                        (vector of length 1)
           var       - marginal predicted vartion             (vector of length 1)
           grad-mu   - derivative of the mean with respect to the dimensions of predicted points. (D length vector)
           grad-var  - derivative of the variance with respect to the dimensions of predicted points. (D length vector)

Generates samples from a trained-gp-obj

Accepts   gp          - of type trained-gp-obj
          x*          - points to evaluate   (MxD matrix)
          n-samples   - number of samples to generate

Returns   f*          - sampled values for gp output (n-samples x M matrix).  Note that the y ~ N(f*,sigma-n^2)
          dist-f*     - mvn distribution object that allows for further efficient sampling if required

Trains a gp, returns L and psi - the lower triangular matrix
and vector of differences required for prediction.

Accepts: cov-fn - a function taking inputs of x-diff-sq and
                  a vector of hyperparameters (not including noise
                  parameter and therefore corresponding to (rest alpha))
         x-diff-sq - a NxDxN matrix of squared distances of points
         y-bar  - observations minus the value of the prior mean function
                  at those points
         alpha  - a vector of hyperparameters ordered as
                 [log-sig-n log-sig-f-k1 log-rho-k1-dim-1 log-rho-k1-dim-2 ... log-sig-f-k2 ...]

Returns:  L     - lower triangular matrix used for gp prediction
          psi   - inv-K times y-bar

Factory function for class deodorant.gp_toolbox.trained-gp-obj, taking a map of keywords to field values.

Subtracts the GP mean. Accepts a mean-fn from arguments [x] to a
scalar y, along with a collection of points [x y]. Returns a vector
of values (- y (mean-fn x)).