corr                package:emulator                R Documentation

_c_o_r_r_e_l_a_t_i_o_n _f_u_n_c_t_i_o_n _f_o_r _c_a_l_c_u_l_a_t_i_n_g _A

_D_e_s_c_r_i_p_t_i_o_n:

     calculates the correlation function between two points in
     parameter space, thus determining the correlation matrix A.

_U_s_a_g_e:

     corr(x1, x2, scales=NULL , pos.def.matrix=NULL,
     power=2,coords="cartesian", spherical.distance.function=NULL)
     corr.matrix(xold, yold=NULL, method=1, distance.function=corr, ...)

_A_r_g_u_m_e_n_t_s:

      x1: First point

      x2: Second point

  scales: Vector specifying the diagonal elements of B (see below)

pos.def.matrix: Positive definite matrix to be used by 'corr.matrix()'
          for B. Exactly one of 'scales' and 'pos.definite.matrix'
          should be specified.  Supplying 'scales' specifies the
          diagonal elements of B (off diagonal elements are set to
          zero); supply 'pos.definite.matrix' in the general case. 
          Note that neither 'corr()' nor 'corr.matrix()' test for
          positive definiteness.

   power: In function 'corr()', the power to use in the exponent of the
          exponential.  In the case of a diagonal 'pos.def.matrix' (or,
          equivalently, using 'scales'), the default value of 2 gives
          the standard metric, viz exp(-(x-x')^2).

          For the general case of nondiagonal 'pos.def.matrix', the
          metric is exp(-abs( (x-x')^T B (x-x') )^(power/2)), thus
          reducing to the standard case for 'power'=2.

  coords: In function 'corr()', a character string, with default
          "cartesian" meaning to interpret the elements of 'x1' (and
          'x2') as coordinates in Cartesian space.  The only other
          acceptable value is currently "spherical", which means to
          interpret the first element of 'x1' as row number, and the
          second element as column number, on a spherical computational
          grid (such as used  by climate model Goldstein; see package
          'goldstein' for an example of this option in use). Spherical
          geometry is then used to calculate the geotetic (great
          circle) distance between point 'x1' and 'x2', with function
          'gcd()'.

  method: An integer with values 1, 2, or 3.  If 1, then use a fast
          matrix calculation that returns exp(-(x-x')^T B (x-x')).  If
          2 or 3, return the appropriate output from 'corr()', noting
          that ellipsis arguments are passed to 'corr()' (for example,
          'power' and 'scales').  The difference between 2 and 3 is a
          marginal difference in numerical efficiency.

          *Warning*: if 'method=1', arguments like 'power' are given to
          'corr.matrix()' are ignored silently.

          *Warning:* The code for 'method=2' (formerly the default),
          has a bug.  If 'yold' has only one row, then
          'corr.matrix(xold,yold,scales,method=2)' returns the
          transpose of what one would expect.  Methods 1 and 3 return
          the correct matrix. 

distance.function: Function to be used to calculate distances. Defaults
          to 'corr()'.

    xold: data frame each row of which is an evaluated point

    yold: (optional) data frame each row of which is an evaluated
          point.  If missing, use 'xold'

spherical.distance.function: In 'corr', a function to determine the
          distance between two points; used if 'coords'="spherical". A
          good one to choose is 'gcd()' (that is, Great Circle
          Distance) of the goldstein library.

     ...: extra arguments given to 'corr.matrix()' that are passed on
          to 'corr()' (such as 'scales' and 'power' if
          'distance.function=corr').

_D_e_t_a_i_l_s:

     Evaluates a slight generalization of Oakley's equation 2.12 for
     the correlation between eta(x) and eta(x'): exp(|(x-x')^T B
     (x-x')|^({power/2))}. This reduces to Oakley's form if 'power=2'.

_V_a_l_u_e:

     Returns the correlation function

_A_u_t_h_o_r(_s):

     Robin K. S. Hankin

_R_e_f_e_r_e_n_c_e_s:

     J. Oakley 1999. "Bayesian uncertainty analysis for complex
     computer codes", PhD thesis, University of Sheffield.

     J. Oakley and A. O'Hagan, 2002. "Bayesian Inference for the
     Uncertainty Distribution of Computer Model Outputs", Biometrika
     89(4), pp769-784

     R. K. S. Hankin 2005. "Introducing BACCO, an R bundle for Bayesian
     analysis of computer code output", Journal of Statistical
     Software, 14(16)

_E_x_a_m_p_l_e_s:

     corr(1:10,10:1,scales=rep(1,10), power=2)
     corr(1:10,10:1,pos.def.matrix=0.1+diag(10),power=2)
     x <- latin.hypercube(4,7)  #4 points in 7-dimensional space
     corr.matrix(x,scales=rep(1,7),power=1.5)

     x[1,1] <- 100
     corr.matrix(x,scales=rep(1,7), power=1.5)

     # note that all the first row and first column apart from the [1,1]th
     # element is zero (or very nearly so) because point number 1 is now very
     # far from the other points.

     #to use just a single dimension, remember to use the drop=FALSE argument:
     corr.matrix(x[,1,drop=FALSE],scales=rep(1,1),power=1.5)

     # For problems in 1D, coerce the independent variable to a matrix:
     m <- c(0.2 , 0.4,0.403,0.9)
     corr.matrix(cbind(m),scales=1)

     # now use a non-default value for distance.function.
     # Function f() below taken from Oakley's thesis page 12,
     # equation 2.10:

     f <- function(x,y,theta){
       d <- sum(abs(x-y))
       if(d >= theta){
         return(0)
       }else{
         return(1-d/theta)
       }
     }

     corr.matrix(xold=x, distance.function=f , method=2, theta=4)
      # Note the first row and first column is a single 1 and 3 zeroes
      # (because the first point, viz x[1,], is "far" from the other ponts).
      # Also note the method=2 argument here; method=1 is the fast slick
      # matrix method suggested by Doug and Jeremy.

