

   KKrriiggiinngg ssuurrffaaccee eessttiimmaattee

        krig(x, Y, cov.function, lambda=NA, cost=1, knots,
        weights=rep(1, length(Y)), m=2, return.matrices=T,
        nstep.cv=50, scale.type="user", x.center=rep(0, ncol(x)),
        x.scale=rep(1, ncol(x)), rho=NA, sigma2=NA, ...)

   AArrgguummeennttss::

          x: Matrix of independent variables.

          Y: Vector of dependent variables.

   cov.function: Covariance function for data in the form of an
             S-PLUS function (see exp.cov).

     lambda: Smoothing parameter that is the ratio of the error
             variance (sigma**2) to the scale parameter of the
             covariance function. If omitted this is estimated
             by GCV.

       cost: Cost value used in GCV criterion. Corresponds to a
             penalty for increased number of parameters.

      knots: Subset of data used in the fit.

    weights: Weights are proportional to the reciprocal vari-
             ance of the measurement error. The default is no
             weighting i.e. vector of unit weights.

          m: A polynomial function of degree (m-1) will be
             included in the model as the drift (or spatial
             trend) component.

   return.matrices: Matrices from the decompositions are
             returned. The default is T.

   nstep.cv: Number of grid points for minimum GCV search.

   scale.type: The independent variables and knots are scaled
             to the specified scale.type.  By default the scale
             type is "unit.sd", whereby the data is scaled to
             have mean 0 and standard deviation 1. Scale type
             of "range" scales the data to the interval (0,1)
             by forming (x-min(x))/range(x) for each x.  Scale
             type of "user" allows specification of an x.center
             and x.scale by the user. The default for "user" is
             mean 0 and standard deviation 1. Scale type of
             "unscaled" does not scale the data.

   x.center: Centering values are subtracted from each column
             of the x matrix.

    x.scale: Scale values that divided into each column after
             centering.

        rho: Scale factor for covariance.

     sigma2: Variance of e.

        ...: Optional arguments. Theta can be specified. If the
             cov.parameters are specified this list is assumed
             to be arguments to the covariance function.

   DDeessccrriippttiioonn::

        The kriging model is Y(x)= P(x) + Z(x) + e where Y is
        the dependent variable observed at location x, P is a
        low order polynomial, Z is a mean zero, Gaussian field
        with covariance function K and e is assumed to be inde-
        pendent normal errors. The estimated surface is the
        best linear unbiased estimate (BLUE) of P(x) + Z(x)
        given the observed data. For this estimate K, is taken
        to be rho*cov.function and the errors have variance
        sigma^2. If these parameters are omitted in the call,
        then they are estimated in the following way. If lambda
        is given, then sigma2 is estimated from the residual
        sum of squares divided by the degrees of freedom asso-
        ciated with the residuals.  Rho is found as the differ-
        ence between the sums of squares of the predicted val-
        ues having subtracted off the polynomial part and
        sigma2.

        WARNING: The covariance functions often have a nonlin-
        ear parameter that controls the strength of the corre-
        lations as a function of separation, usually refered to
        as the range parameter. This parameter must be speci-
        fied in the call to krig and will not be estimated.

   VVaalluuee::

        A list of class krig. This includes the predicted sur-
        face of fitted.values and the residuals. The results of
        the grid search to minimize the generalized cross vali-
        dation function is returned in gcv.grid.

       call: Call to the function

          y: Vector of dependent variables.

          x: Matrix of independent variables.

    weights: Vector of weights.

      knots: Locations used to define the basis functions.

   transform: List of components used in centering and scaling
             data.

         np: Total number of parameters in the model.

         nt: Number of parameters in the null space.

   matrices: List of matrices from the decompositions (D, G, u,
             X, qr.T).

   gcv.grid: Matrix of values used in the GCV grid search. The
             first column is the grid of lambda values used in
             the search, the second column is the trace of the
             A matrix, the third column is the GCV values and
             the fourth column is the estimated variance.

       cost: Cost value used in GCV criterion.

          m: Order of the polynomial space: highest degree
             polynomial is (m-1).

     eff.df: Effective degrees of freedom of the model.

   fitted.values: Predicted values from the fit.

   residuals: Residuals from the fit.

     lambda: Value of the smoothing parameter used in the fit.

      yname: Name of the response.

   cov.function: Covariance function of the model.

       beta: Estimated coefficients in the ridge regression
             format

          d: Esimated coefficients for the polynomial basis
             functions that span the null space

   fitted.values.null: Fitted values for just the polynomial
             part of the estimate

      trace: Effective number of parameters in model.

          c: Estimated coefficients for the basis functions
             derived from the covariance.

   coefficients: Same as the beta vector.

   just.solve: Logical describing if the data has been interpo-
             lated using the basis functions.

       shat: Estimated standard deviation of the measurement
             error (nugget effect).

     sigma2: Estimated variance of the measurement error
             (shat**2).

        rho: Scale factor for covariance.  COV(h(x),h(x')) =
             rho*cov.function(x,x')

   mean.var: Normalization of the covariance function used to
             find rho.

   best.model: Vector containing the value of lambda, the esti-
             mated variance of the measurement error and the
             scale factor for covariance used in the fit.

   RReeffeerreenncceess::

        See "Additive Models" by Hastie and Tibshirani, "Spa-
        tial Statistics" by Cressie and the FUNFITS manual.

   SSeeee AAllssoo::

        summary.krig, predict.krig, predict.se.krig, plot.krig,
        surface.krig

   EExxaammpplleess::

        #2-d example
        krig(ozone$x, ozone$y, exp.cov) -> fit # fitting a surface to ozone
        # measurements.
        plot(fit) # plots fit and residuals
        # data using a Gaussian covariance
        # first make up covariance function
        test.cov <- function(x1,x2){exp(-(rdist(x1,x2)/.5)**2)}
        krig(flame$x, flame$y, test.cov) -> fit.flame
        surface(fit.flame)

