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.  A
          single value is recycled.   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; the main
          difference is computational elegance.

          *Warning 1:* if 'method=1', argument 'power' (which might be
          intended to be passed to 'corr.matrix()') is ignored
          silently.

          *Warning 2:* 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.

          *Warning 3:* If argument 'distance.function' is not the
          default, and 'method' is the default (ie 1), then 'method'
          will be silently changed to 2 on the grounds that 'method=1'
          is meaningless unless the distance function is 'corr()'

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

    xold: Matrix, each row of which is an evaluated point

    yold: (optional) matrix, 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

     ...: In function 'corr.matrix()', extra arguments that are passed
          on to the distance function.  In the default case in which
          the distance.function is 'corr()', one _must_ pass 'scales',
          and one might wish to pass 'power'

_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

_N_o_t_e:

     It is worth reemphasising that supplying 'scales' makes matrix B
     diagonal.

     Thus, if 'scales' is supplied, 'B=diag(scales)' and

                          ommitted: see pdf


     Thus if x has units [X], the units of 'scales' are X^(-2).

     So if 'scales[i]' is big, even small displacements in 'x[i]' (that
     is, moving a small distance in parameter space, in the i-th
     dimension) will result in small correlations.  If 'scales[i]' is
     small, even large displacements in 'x[1]' will have large
     correlations

_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, but this only works
      # for distance.function=corr.

