variog                 package:geoR                 R Documentation

_C_o_m_p_u_t_e _E_m_p_i_r_i_c_a_l _V_a_r_i_o_g_r_a_m_s

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

     Computes sample (empirical) variograms with options for  the
     _classical_ or _robust_ estimators. Output can be returned as a
     'binned variogram', a ' variogram cloud' or a 'smoothed
     variogram'. Data transformation (Box-Cox) is allowed. ``Trends''
     can be specified and are fitted by ordinary least squares in which
     case the variograms are computed using the residuals.

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

     variog(geodata, coords = geodata$coords, data = geodata$data, 
            uvec = "default", breaks = "default",
            trend = "cte", lambda = 1,
            option = c("bin", "cloud", "smooth"),
            estimator.type = c("classical", "modulus"), 
            nugget.tolerance, max.dist, pairs.min = 2,
            bin.cloud = FALSE, direction = "omnidirectional", tolerance = pi/8,
            unit.angle = c("radians","degrees"), angles = FALSE, messages, ...) 

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

 geodata: a list containing element 'coords' as described next.
          Typically an object of the class '"geodata"' - a 'geoR'
          data-set. If not provided the arguments 'coords' must be
          provided instead.  

  coords: an n x 2 matrix containing coordinates of the n data
          locations in each row. Defaults to 'geodata$coords', if
          provided.

    data: a vector or matrix with data values. If a matrix is provided,
          each column is regarded as one variable or realization.
          Defaults to 'geodata$data', if provided.

    uvec: a vector with values used to define the variogram binning.
          Only used when 'option = "bin"'. See 'DETAILS' below for more
          details on how to specify the bins. 

  breaks: a vector with values to define the variogram binning. Only
          used when 'option = "bin"'. See 'DETAILS' below for more
          details on how to specify the bins. 

   trend: specifies the mean part of the model. See documentation of
          'trend.spatial' for further details. Defaults to '"cte"'.  

  lambda: values of the Box-Cox transformation parameter. Defaults to 1
          (no transformation). If another value is provided the
          variogram is computed after transforming the  data. A case of
          particular interest is lambda = 0 which corresponds to
          log-transformation.  

  option: defines the output type: the options '"bin"' returns values
          of binned variogram, '"cloud"' returns the variogram cloud
          and '"smooth"' returns the kernel smoothed variogram.
          Defaults to '"bin"'.

estimator.type: '"classical"' computes the classical method of moments
          estimator.  '"modulus"' returns the variogram estimator
          suggested by Hawkins and Cressie (see Cressie, 1993, pg 75).
          Defaults to '"classical"'.  

nugget.tolerance: a numeric value. Points which are separated by a
          distance less than this value are considered co-located.
          Defaults to zero.  

max.dist: a numerical value defining the maximum distance for the
          variogram. Pairs of locations separated for distance larger
          than this value are ignored for the variogram calculation. If
          not provided defaults takes the maximum distance among all
          pairs of data locations.  

pairs.min: a integer number defining the minimum numbers of pairs for
          the bins. For 'option = "bin"', bins with number of pairs
          smaller than this value are ignored. Defaults to 'NULL'.  

bin.cloud: logical. If 'TRUE' and 'option = "bin"' the cloud values for
          each class are included in the output. Defaults to 'FALSE'.  

direction: a numerical value for the directional (azimuth) angle. This
          used to specify directional variograms. Default defines the
          omnidirectional variogram. The value must be in the interval
          [0, pi] radians ([0, 180] degrees).  

tolerance: numerical value for the tolerance angle, when computing
          directional variograms. The value must be in the interval [0,
          pi/2] radians ([0, 90] degrees).  Defaults to pi/8.  

unit.angle: defines the unit for the specification of angles in the two
          previous arguments. Options are '"radians"' and '"degrees"',
          with default to '"radians"'. 

  angles: Logical with default to 'FALSE'. If 'TRUE' the function also
          returns the angles between the pairs of points
          (unimplemented). 

messages: logical. Indicates whether status messages should be printed
          on the screen (or output device) while the function is
          running.  

     ...: arguments to be passed to the function 'ksmooth', if 'option
          = "smooth"'.  

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

     Variograms are widely used in geostatistical analysis for
     exploratory purposes, to estimate covariance parameters and/or to
     compare theoretical and fitted models against sample variograms.

     *Estimators*
      The two estimators currently implemented are:

        *  _classical_ (method of moments) estimator:

            gamma(h) = (1/2N_h) sum [Y(x_i+h) - Y(x_i)]^2


        *  Hawkins and Cressie's _modulus_ estimator

 gamma(h) = ([(1/N_h)sum_{i=1}^{N_h} |Y(x_{i+h}) - Y(x_i)|^(1/2)]^4)/(0.914 + (0.988/N_h))


     *Defining the bins*

     _The defaults_
      If arguments 'breaks' and 'uvec' are not provided, the binning is
     defined as follows:

        1.  read the argument 'max.dist'. If not provided it is set to
           the maximum distance between the pairs of points.

        2.  the center of the bins are initially defined by the
           sequence 'u = seq(0, max.dist, l = 13)'.

        3.  the interval spanned by each bin is given by the mid-points
           between the centers of the bins.

     If an vector is passed to the argument 'breaks' its elements are
     taken as the limits of the bins (classes of distance) and the
     argument 'uvec' is ignored.

     _Variations on the default_
      The default definition of the bins is different for some
     particular cases.

        1.  if there are  coincident data locations the bins follows
           the default above but one more bin is added at the origin
           (distance zero) for the collocated points.

        2.  if the argument 'nugget.tolerance' is provided the
           separation distance between all pairs in the interval [0,
           nugget.tolerance] are set to zero. The first bin distance is
           set to zero ('u[1] = 0'). The remaining bins follows the
           default.

        3.  if a scalar is provided to the argument 'uvec' the default
           number of bins is defined by this number.

        4.  if a vector is provided to the argument 'uvec', its
           elements are taken as central points of the bins.

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

     An object of the 'class' 'variogram' which is a list with the
     following components: 

      u : a vector with distances.  

      v : a vector with estimated variogram values at distances given
          in 'u'.  

      n : number of pairs in each bin, if 'option = "bin"'.  

     sd : standard deviation of the values in each bin.  

bins.lim : limits defining the interval spanned by each bin.  

ind.bin : a logical vector indicating whether the number of pairs in
          each bin is greater or equal to the value in the argument
          'pairs.min'.  

var.mark : variance of the data.  

beta.ols : parameters of the mean part of the model fitted by ordinary
          least squares.  

output.type : echoes the 'option' argument.  

max.dist: maximum distance between pairs allowed in the variogram
          calculations.

estimator.type : echoes the type of estimator used.  

 n.data : number of data.  

  lambda: value of the transformation parameter.  

   trend: trend specification.  

nugget.tolerance: value of the nugget tolerance argument.  

direction : direction for which the variogram was computed.  

tolerance : tolerance angle for directional variogram.  

   uvec : lags provided in the function call.  

   call : the function call.  

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

     Paulo J. Ribeiro Jr. paulojus@leg.ufpr.br, 
      Peter J. Diggle p.diggle@lancaster.ac.uk.

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

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

     Further information on the package 'geoR' can be found at:
      <URL: http://www.leg.ufpr.br/geoR>.

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

     'variog4' for more on computation of directional variograms, 
     'variog.model.env' and 'variog.mc.env' for variogram envelopes,
     'variofit'  for variogram based parameter estimation and
     'plot.variogram' for graphical output.

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

     #
     # computing variograms:
     #
     # binned variogram
     vario.b <- variog(s100, max.dist=1)
     # variogram cloud
     vario.c <- variog(s100, max.dist=1, op="cloud")
     #binned variogram and stores the cloud
     vario.bc <- variog(s100, max.dist=1, bin.cloud=TRUE)
     # smoothed variogram
     vario.s <- variog(s100, max.dist=1, op="sm", band=0.2)
     #
     #
     # plotting the variograms:
     par(mfrow=c(2,2))
     plot(vario.b, main="binned variogram") 
     plot(vario.c, main="variogram cloud")
     plot(vario.bc, bin.cloud=TRUE, main="clouds for binned variogram")  
     plot(vario.s, main="smoothed variogram") 

     # computing a directional variogram
     vario.0 <- variog(s100, max.dist=1, dir=0, tol=pi/8)
     plot(vario.b, type="l", lty=2)
     lines(vario.0)
     legend(0, 1.2, legend=c("omnidirectional", expression(0 * degree)), lty=c(2,1))

