variog {geoR} | R Documentation

## Compute Empirical Variograms

### Description

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.

### Usage

    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, ...)

### Arguments

`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"`.

### Details

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.

### Value

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.

### Author(s)

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

### References

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

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

### See Also

`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.

### Examples

    #
    # 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))

[Package geoR version 1.6-19 Index]