R: Simulation of Random Fields

RFsimulate {RandomFields} | R Documentation

## Simulation of Random Fields

### Description

This function simulates unconditional random fields:

- univariate and multivariat, spatial and spatio-temporal Gaussian random fields

- fields based on Gaussian fields such as Chi2 fields or Binary fields, see RP.

- stationary Poisson fields

- stationary max-stable random fields.

It also simulates conditional random fields for

- univariate and multivariat, spatial and spatio-temporal Gaussian random fields

Here, only the simulation of Gaussian random fields is described. For other kind of random fields (binary, max-stable, etc.) or more sophisticated approches see RFsimulateAdvanced.

### Usage

    RFsimulate(model, x, y=NULL, z=NULL, T=NULL, grid=NULL,
      distances, dim, data, given=NULL, err.model, n=1, ...)

### Arguments

`model` | object of class `RMmodel`, `RFformula` or `formula`; specifies the model to be simulated; the best is to consider the examples below, first. if of class `RMmodel`, `model` specifies a covariance or variogram model of a Gaussian random field; type `RFgetModelNames(type="variogram")` for a list of available models; see also `RMmodel` if of class `RFformula` or `formula` , `submodel` specifies a linear mixed model where random effects can be modelled by Gaussian random fields; see `RFformula` for details on model specification. for (many) more options see RFsimulateAdvanced.
`x` | vector of x coordinates, or object of class `GridTopology` or `raster`; For more options see RFsimulateAdvanced.
`y` | optional vector of y coordinates
`z` | optional vector of z coordinates
`T` | optional vector of time coordinates, `T` must always be an equidistant vector. Instead of `T=seq(from=From, by=By, len=Len)` one may also write `T=c(From, By, Len)`.
`grid` | logical; `RandomFields` can find itself the correct value in nearly all cases, so that usually `grid` need not be given. See also RFsimulateAdvanced.
`distances` | another alternative to pass the (relative) coordinates, see RFsimulateAdvanced.
`dim` | Only used if `distances` are given.
`data` | For conditional simulation and random imputing only. If `data` is missing, unconditional simulation is performed. Matrix, data.frame or object of class `RFsp`; coordinates and response values of measurements in case that conditional simulation is to be performed; If `given` is not given and `data` is a matrix or `data` is a data.frame, then the first columns are interpreted as coordinate vectors, and the last column(s) as (multiple) measurement(s) of the field; if the argument `x` is missing, `data` may contain `NA`s, which are then replaced by conditionally simulated values (random imputing); for details on matching of variable names see Details; if of class `RFsp`
`given` | optional, matrix or list. If `given` matrix then the coordinates can be given separately, namely by `given` where, in each row, a single location is given. If `given` is a list, it may consist of `x`, `y`, `z`, `T`, `grid`. If `given` is provided, `data` must be a matrix or an array containing the data only.
`err.model` | For conditional simulation and random imputing only. Usually `err.model=RMnugget(var=var)`, or not given at all (error-free measurements).
`n` | number of realizations to generate. For a very advanced feature, see the notes in RFsimulateAdvanced.
`...` | for advanced use: further options and control arguments for the simulation that are passed to and processed by `RFoptions`

### Details

By default, all Gaussian random fields have zero mean. Simulating with trend can be done by including `RMtrend` in the model, see the examples below.

If `data` is passed, conditional simulation based on simple kriging is performed:

- if of class `RFsp`, `ncol(data@coords)` must equal the dimension of the index space. If `data@data` contains only a single variable, variable names are optional. If `data@data` contains more than one variable, variables must be named and `model` must be given in the tilde notation `resp ~ ...` (see `RFformula`) and `"resp"` must be contained in `names(data@data)`.

- If `data` is a matrix or a data.frame, either `ncol(data)` equals (dimension of index space + 1) and the order of the columns is (x, y, z, T, response) or, if `data` contains more than one response variable (i.e. `ncol(data) > (dimension of index space + 1)`), `colnames(data)` must contain `colnames(x)` or those of `"x", "y", "z", "T"` that are not missing. The response variable name is matched with `model`, which must be given in the tilde notation. If `"x", "y", "z", "T"` are missing and `data` contains `NA`s, `colnames(data)` must contain an element which starts with ‘data’; the corresponding column and those behind it are interpreted as the given data and those before the corresponding column are interpreted as the coordinates.

- if `x` is missing, `RFsimulate` searches for `NA`s in the data and performs a conditional simulation for them.

Specification of `err.model`: In geostatistics we have two different interpretations of a nugget effect: small scale variability and measurement error. The result of conditional simulation usually does not include the measurement error. Hence the measurement error `err.model` must be given separately. For sake of generality, any model (and not only the nugget effect) is allowed. Consequently, `err.model` is ignored when unconditional simulation is performed.

### Value

By default, an object of the virtual class `RFsp`; result is of class `RMmodel`.

- `RFspatialGridDataFrame` if the space-time dimension is greater than 1 and the coordinates are on a grid,

- `RFgridDataFrame` if the space-time dimension equals 1 and the coordinates are on a grid,

- `RFspatialPointsDataFrame` if the space-time dimension is greater than 1 and the coordinates are not on a grid,

- `RFpointsDataFrame` if the space-time dimension equals 1 and the coordinates are not on a grid.

In case of a multivariate

If `n > 1` the repetitions make the last dimension.

See RFsimulateAdvanced for additional options.

### Note

Several advanced options can be found in sections ‘General options’ and ‘coords’ of `RFoptions`. In particular, option `spConform=FALSE` leads to a simpler (and faster!) output, see `RFoptions` for details.

### Author(s)

Martin Schlather, schlather@math.uni-mannheim.de http://ms.math.uni-mannheim.de/de/publications/software

### References

Gneiting, T. and Schlather, M. (2013) Statistical modeling with covariance functions. In preparation.

Lantuejoul, Ch. (2002) Geostatistical simulation. New York: Springer.

Schlather, M. (1999) An introduction to positive definite functions and to unconditional simulation of random fields. Technical report ST 99-10, Dept. of Maths and Statistics, Lancaster University.

See RFsimulateAdvanced for more specific literature.

### See Also

`RFempiricalvariogram`, `RFfit`, `RFgetModelInfo`, `RFgui`, `RMmodel`, `RFoptions`, `RFsimulateAdvanced`, `RFsimulate.more.examples`

### Examples

    RFoptions(seed=0) ## *ANY* simulation will have the random seed 0; set
    ##                   RFoptions(seed=NA) to make them all random again

    #############################################################
    ## ##
    ## ONLY TWO VERY BASIC EXAMPLES ARE GIVEN HERE ##
    ## see ##
    ## ?RMsimulate.more.examples ##
    ## and ##
    ## ?RFsimulateAdvanced ##
    ## for more examples ##
    ## ##
    #############################################################

    #############################################################
    ## ##
    ## Unconditional simulation ##
    ## ##
    #############################################################

    ## first let us look at the list of implemented models
    RFgetModelNames(type="positive definite", domain="single variable",
                    iso="isotropic")

    ## our choice is the exponential model;
    ## the model includes nugget effect and the mean:
    model <- RMexp(var=5, scale=10) + # with variance 4 and scale 10
     RMnugget(var=1) + # nugget
     RMtrend(mean=0.5) # and mean

    ## define the locations:
    from <- 0
    to <- 20
    x.seq <- seq(from, to, length=200)
    y.seq <- seq(from, to, length=200)

    simu <- RFsimulate(model, x=x.seq, y=y.seq)
    plot(simu)

    #############################################################
    ## ##
    ## Conditional simulation ##
    ## ##
    #############################################################

    # first we simulate some random values at a
    # 100 random locations:
    n <- 100
    x <- runif(n=n, min=-1, max=1)
    y <- runif(n=n, min=-1, max=1)
    data <- RFsimulate(model = RMexp(), x=x, y=y, grid=FALSE)
    plot(data)

    # let simulate a field conditional on the above data
    x.seq.cond <- y.seq.cond <- seq(-1.5, 1.5, length=n)
    model <- RMexp()
    cond <- RFsimulate(model, x=x.seq.cond, y=y.seq.cond, data=data)
    plot(cond, data)

[Package RandomFields version 3.1.50 Index]