CondSimu            package:RandomFields            R Documentation

_C_o_n_d_i_t_i_o_n_a_l _S_i_m_u_l_a_t_i_o_n

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

     the function returns conditional simulations of a random field

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

     CondSimu(krige.method, x, y=NULL, z=NULL, T=NULL, grid,
              gridtriple=FALSE, model, param, method=NULL, given, data,
              trend, n=1, register=0, 
              err.model=NULL, err.param=NULL, err.method=NULL,
              err.register=1, tol=1E-5, pch=".", na.rm=FALSE)

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

krige.method: Assumptions on the random field which corresponds to the
          respective kriging method; currently 'S' (simple kriging) and
           'O' (ordinary kriging) are implemented.

       x: matrix or vector of 'x' coordinates; points to be kriged.

       y: vector of 'y' coordinates.

       z: vector of 'z' coordinates.

       T: vector in grid triple form for the time coordinates.

    grid: logical; determines whether the vectors 'x', 'y', and 'z'
          should be interpreted as a grid definition, see Details.

gridtriple: logical.  Only relevant if 'grid==TRUE'.  If
          'gridtriple==TRUE' then 'x', 'y', and 'z' are of the form
          'c(start,end,step)'; if 'gridtriple==FALSE' then 'x', 'y',
          and 'z' must be vectors of ascending values.

   model: string; covariance model of the random field.  See
          'CovarianceFct', or type 'PrintModelList()' to get all
          options for 'model'.

          See 'CovarianceFct' for 'model' being a list. 

   param: parameter vector: 'param=c(mean, variance, nugget,
          scale,...)'; the parameters must be given in this order;
          further parameters are to be added in case of a parametrised
          class of covariance functions, see 'CovarianceFct'; the value
          of 'mean' must be finite in the case of simple kriging, and
          is ignored otherwise.

          See 'CovarianceFct' for 'param' being 'NULL' or list. 

  method: 'NULL' or string; method used for simulating, see
          'RFMethods', or type 'PrintMethodList()' to get all options.

   given: matrix or vector of locations where data are available; note
          that it is not possible to give the points in form of a grid
          definition.

    data: the values measured.

   trend: Not programmed yet. (used by universal kriging)

       n: number of realisations to generate.

register: 0:9; place where intermediate calculations are stored; the
          numbers are aliases for 10 internal registers; see 'GaussRF'
          for further details.

err.model: covariance function for the error model. String or list. See
          'model' for details. 

err.param: parameters for the error model. See also 'param'. 

err.method: Only relevant if 'err.model' is not 'NULL'. Then it must be
          given if and only if 'method' is given; see 'method' for
          details.

err.register: see 'register' for details.

     tol: considered only if 'grid=TRUE'; tolerated distances of a
          given point to the nearest grid point to be regarded as being
          zero; see Details.

     pch: character.  The included kriging procedure can be quite time
          consuming.  The character 'pch' is printed after roughly each
          80th part of calculation.

   na.rm: logical. If 'TRUE' then 'NA's are removed from the given
          data.

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

     The same way as 'GaussRF' the function 'CondSimu' allows for
     simulating on grids or arbitrary locations.  However simulation on
     a grid is sometimes performed as if the points were at arbitrary
     locations, what may imply a great reduction in speed.  This
     happens when the 'given' locations do not lay on the specified
     grid, since in an intermediate step simulation has to be performed
     simultaneously on both the grid defined by 'x', 'y', 'z', and the
     locations of 'given'.

     Comments on specific parameters

        *  'grid==FALSE' : the vectors 'x', 'y', and 'z' are
           interpreted as vectors of coordinates

        *  '(grid==TRUE) && (gridtriple==FALSE)' : the vectors 'x',
           'y', and 'z' are increasing sequences with identical lags
           for each sequence.  A corresponding grid is created (as
           given by 'expand.grid'). 

        *  '(grid==TRUE) && (gridtriple==FALSE)' : the vectors 'x',
           'y', and 'z' are triples of the form (start,end,step)
           defining a grid (as given by
           'expand.grid(seq(x$start,x$end,x$step),
           seq(y$start,y$end,y$step), seq(z$start,z$end,z$step))')

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

     The returned object depends on the parameters 'n' and 'grid':
      'n==1':
      * 'grid==FALSE'.  A vector of simulated values is returned
     (independent of the dimension of the random field)
      * 'grid==TRUE'.  An array of the dimension of the random field is
     returned.

     'n>1':
      * 'grid==FALSE'.  A matrix is returned.  The columns contain the
     repetitions.
      * 'grid==TRUE'.  An array of dimension d+1, where d is the
     dimension of the random field as given by 'x', 'y', and 'z', is
     returned.  The last dimension contains the repetitions.

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

     Martin Schlather, martin.schlather@cu.lu <URL:
     http://www.cu.lu/~schlathe>

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

     Chiles, J.-P. and Delfiner, P. (1999) _Geostatistics. Modeling
     Spatial Uncertainty._ New York: Wiley.

     Cressie, N.A.C. (1993) _Statistics for Spatial Data._ New York:
     Wiley.

     Goovaerts, P. (1997) _Geostatistics for Natural Resources
     Evaluation._ New York: Oxford University Press.

     Wackernagel, H. (1998) _Multivariate Geostatistics._ Berlin:
     Springer, 2nd edition.

_S_e_e _A_l_s_o:

     'CovarianceFct', 'GaussRF', 'Kriging' 'RandomFields',

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

     ## creating random variables first
     ## here, a grid is chosen, but any arbitrary points for which
     ## data are given are fine.  Indeed if the data are given on a
     ## grid, the grid has to be expanded before calling `CondSimu',
     ## see below.
     ## However, locations where values are to be simulated,
     ## should be given in form of a grid definition whenever
     ## possible 
     param <- c(0, 1, 0, 1)
     model <- "exponential"
     RFparameters(PracticalRange=FALSE)
     p <- 1:7
     data <- GaussRF(x=p, y=p, grid=TRUE, model=model, param=param)
     get(getOption("device"))(height=4,width=4);
     get(getOption("device"))(height=4,width=4);
     get(getOption("device"))(height=4,width=4);

     # another grid, where values are to be simulated
     step <- 0.25 # or 0.3
     x <-  seq(0, 7, step)

     # standardisation of the output
     lim <- range( c(x, p) )
     zlim <- c(-2.6, 2.6)
     colour <- rainbow(100)

     ## visualise generated spatial data
     dev.set(2)
     image(p, p, data, xlim=lim, ylim=lim, zlim=zlim, col=colour)

     #conditional simulation
     krige.method <- "O" ## random field assumption corresponding to
                         ## those of ordinary kriging
     cz <- CondSimu(krige.method, x, x,  grid=TRUE,
                    model=model, param=param,
                    given=expand.grid(p,p),# if data are given on a grid
                                           # then expand the grid first
                    data=data)
     range(cz)
     dev.set(3)
     image(x, x, cz, col=colour, xlim=lim, ylim=lim, zlim=zlim)

     #conditional simulation with error term
     cze <- CondSimu(krige.method, x, x,  grid=TRUE,
                     model=model, param=c(0, 1/2, 0, 1),
                     err.model="gauss", err.param=c(0, 1/2, 0, 1),
                     given=expand.grid(p,p),
                     data=data)
     range(cze)
     dev.set(4)
     image(x, x, cze, col=colour, xlim=lim, ylim=lim, zlim=zlim)

