optimMKV: Optimization of sample configurations for spatial...

In spsann: Optimization of Sample Configurations using Spatial Simulated Annealing

Description

Optimize a sample configuration for spatial interpolation with a known linear model. A criterion is defined so that the sample configuration minimizes the mean or maximum kriging variance (MKV).

Usage

optimMKV(points, candi, covars, eqn = z ~ 1, vgm, krige.stat = "mean",
  ..., schedule = scheduleSPSANN(), plotit = FALSE, track = FALSE,
  boundary, progress = "txt", verbose = FALSE)

objMKV(points, candi, covars, eqn = z ~ 1, vgm, krige.stat = "mean",
  ...)

Arguments

points	Integer value, integer vector, data frame or matrix, or list. Integer value. The number of points. These points will be randomly sampled from candi to form the starting sample configuration. Integer vector. The row indexes of candi that correspond to the points that form the starting sample configuration. The length of the vector defines the number of points. Data frame or matrix. An object with three columns in the following order: [, "id"], the row indexes of candi that correspond to each point, [, "x"], the projected x-coordinates, and [, "y"], the projected y-coordinates. List. An object with two named sub-arguments: fixed, a data frame or matrix with the projected x- and y-coordinates of the existing sample configuration – kept fixed during the optimization –, and free, an integer value defining the number of points that should be added to the existing sample configuration – free to move during the optimization.
candi	Data frame or matrix with the candidate locations for the jittered points. candi must have two columns in the following order: [, "x"], the projected x-coordinates, and [, "y"], the projected y-coordinates.
covars	Data frame or matrix with the covariates in the columns.
eqn	Formula string that defines the dependent variable z as a linear model of the independent variables contained in covars. Defaults to eqn = z ~ 1, that is, ordinary kriging. See the argument formula in the function krige for more information.
vgm	Object of class variogramModel. See the argument model in the function krige for more information.
krige.stat	Character value defining the statistic that should be used to summarize the kriging variance. Available options are "mean" and "max" for the mean and maximum kriging variance, respectively. Defaults to krige.stat = "mean".
...	further arguments passed to krige.
schedule	List with 11 named sub-arguments defining the control parameters of the cooling schedule. See scheduleSPSANN.
plotit	(Optional) Logical for plotting the optimization results, including a) the progress of the objective function, and b) the starting (gray circles) and current sample configuration (black dots), and the maximum jitter in the x- and y-coordinates. The plots are updated at each 10 jitters. When adding points to an existing sample configuration, fixed points are indicated using black crosses. Defaults to plotit = FALSE.
track	(Optional) Logical value. Should the evolution of the energy state be recorded and returned along with the result? If track = FALSE (the default), only the starting and ending energy states are returned along with the results.
boundary	(Optional) SpatialPolygon defining the boundary of the spatial domain. If missing and plotit = TRUE, boundary is estimated from candi.
progress	(Optional) Type of progress bar that should be used, with options "txt", for a text progress bar in the R console, "tk", to put up a Tk progress bar widget, and NULL to omit the progress bar. A Tk progress bar widget is useful when using parallel processors. Defaults to progress = "txt".
verbose	(Optional) Logical for printing messages about the progress of the optimization. Defaults to verbose = FALSE.

Details

Details about the mechanism used to generate a new sample configuration out of the current sample configuration by randomly perturbing the coordinates of a sample point are available in the help page of spJitter.

Value

optimMKV returns an object of class OptimizedSampleConfiguration: the optimized sample configuration with details about the optimization.

objMKV returns a numeric value: the energy state of the sample configuration – the objective function value.

Note

The distance between two points is computed as the Euclidean distance between them. This computation assumes that the optimization is operating in the two-dimensional Euclidean space, i.e. the coordinates of the sample points and candidate locations should not be provided as latitude/longitude. spsann has no mechanism to check if the coordinates are projected: the user is responsible for making sure that this requirement is attained.

This function is based on the method originally proposed by Heuvelink, Brus and de Gruijter (2006) and implemented in the R-package intamapInteractive by Edzer Pebesma and Jon Skoien.

Author(s)

Alessandro Samuel-Rosa [e-mail]

References

Brus, D. J.; Heuvelink, G. B. M. Optimization of sample patterns for universal kriging of environmental variables. Geoderma. v. 138, p. 86-95, 2007.

Heuvelink, G. B. M.; Brus, D. J.; de Gruijter, J. J. Optimization of sample configurations for digital mapping of soil properties with universal kriging. In: Lagacherie, P.; McBratney, A. & Voltz, M. (Eds.) Digital soil mapping - an introductory perspective. Elsevier, v. 31, p. 137-151, 2006.

Examples

## Not run: 
data(meuse.grid, package = "sp")
candi <- meuse.grid[1:1000, 1:2]
covars <- as.data.frame(meuse.grid)[1:1000, ]
vgm <- gstat::vgm(psill = 10, model = "Exp", range = 500, nugget = 8)
schedule <- scheduleSPSANN(
  initial.temperature = 10, chains = 1, x.max = 1540, y.max = 2060, 
  x.min = 0,  y.min = 0, cellsize = 40)
set.seed(2001)
res <- optimMKV(
  points = 10, candi = candi, covars = covars, eqn = z ~ dist, 
  vgm = vgm, schedule = schedule)
objSPSANN(res) - objMKV(
  points = res, candi = candi, covars = covars,  eqn = z ~ dist, 
  vgm = vgm)

## End(Not run)

Example output

---------------------------------------------------------------
Optimization of Sample Configurations using Spatial Simulated
Annealing 
spsann version 2.1-0 
(built on 2017-06-23) is now loaded                
---------------------------------------------------------------

[using universal kriging]

  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |========                                                              |  11%
  |                                                                            
  |================                                                      |  22%
  |                                                                            
  |=======================                                               |  33%
  |                                                                            
  |===============================                                       |  44%
  |                                                                            
  |=======================================                               |  56%
  |                                                                            
  |===============================================                       |  67%
  |                                                                            
  |======================================================                |  78%
  |                                                                            
  |==============================================================        |  89%
  |                                                                            
  |======================================================================| 100%
100% of acceptance in the 1st chain

running time = 0.37 seconds[using universal kriging]
 obj
   0

spsann documentation built on May 2, 2019, 1:36 p.m.