optimSPAN: Optimization of sample configurations for variogram and...
In spsann: Optimization of Sample Configurations using Spatial Simulated Annealing

Description Usage Arguments Details Value Note Author(s) See Also Examples

Optimize a sample configuration for variogram and spatial trend identification and estimation, and for spatial interpolation. An utility function U is defined so that the sample points cover, extend over, spread over, SPAN the feature, variogram and geographic spaces. The utility function is obtained aggregating four objective functions: CORR, DIST, PPL, and MSSD.

optimSPAN(points, candi, covars, strata.type = "area",
  use.coords = FALSE, lags = 7, lags.type = "exponential",
  lags.base = 2, cutoff, criterion = "distribution", distri,
  pairs = FALSE, schedule = scheduleSPSANN(), plotit = FALSE,
  track = FALSE, boundary, progress = "txt", verbose = FALSE,
  weights, nadir = list(sim = NULL, seeds = NULL, user = NULL, abs =
  NULL), utopia = list(user = NULL, abs = NULL))

objSPAN(points, candi, covars, strata.type = "area",
  use.coords = FALSE, lags = 7, lags.type = "exponential",
  lags.base = 2, cutoff, criterion = "distribution", distri,
  pairs = FALSE, x.max, x.min, y.max, y.min, weights, nadir = list(sim
  = NULL, seeds = NULL, user = NULL, abs = NULL), utopia = list(user =
  NULL, abs = NULL))

`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.
`strata.type`	(Optional) Character value setting the type of stratification that should be used to create the marginal sampling strata (or factor levels) for the numeric covariates. Available options are `"area"`, for equal-area, and `"range"`, for equal-range. Defaults to `strata.type = "area"`.
`use.coords`	(Optional) Logical value. Should the spatial x- and y-coordinates be used as covariates? Defaults to `use.coords = FALSE`.
`lags`	Integer value, the number of lag-distance classes. Alternatively, a vector of numeric values with the lower and upper bounds of each lag-distance class, the lowest value being larger than zero (e.g. 0.0001). Defaults to `lags = 7`.
`lags.type`	Character value, the type of lag-distance classes, with options `"equidistant"` and `"exponential"`. Defaults to `lags.type = "exponential"`.
`lags.base`	Numeric value, base of the exponential expression used to create exponentially spaced lag-distance classes. Used only when `lags.type = "exponential"`. Defaults to `lags.base = 2`.
`cutoff`	Numeric value, the maximum distance up to which lag-distance classes are created. Used only when `lags` is an integer value. If missing, it is set to be equal to the length of the diagonal of the rectangle with sides `x.max` and `y.max` as defined in `scheduleSPSANN`.
`criterion`	Character value, the feature used to describe the energy state of the system configuration, with options `"minimum"` and `"distribution"`. Defaults to `objective = "distribution"`.
`distri`	Numeric vector, the distribution of points or point-pairs per lag-distance class that should be attained at the end of the optimization. Used only when `criterion = "distribution"`. Defaults to a uniform distribution.
`pairs`	Logical value. Should the sample configuration be optimized regarding the number of point-pairs per lag-distance class? Defaults to `pairs = FALSE`.
`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`.
`weights`	List with named sub-arguments. The weights assigned to each one of the objective functions that form the multi-objective combinatorial optimization problem. They must be named after the respective objective function to which they apply. The weights must be equal to or larger than 0 and sum to 1.
`nadir`	List with named sub-arguments. Three options are available: 1) `sim` – the number of simulations that should be used to estimate the nadir point, and `seeds` – vector defining the random seeds for each simulation; 2) `user` – a list of user-defined nadir values named after the respective objective functions to which they apply; 3) `abs` – logical for calculating the nadir point internally (experimental).
`utopia`	List with named sub-arguments. Two options are available: 1) `user` – a list of user-defined values named after the respective objective functions to which they apply; 2) `abs` – logical for calculating the utopia point internally (experimental).
`x.max, x.min, y.max, y.min`	Numeric value defining the minimum and maximum quantity of random noise to be added to the projected x- and y-coordinates. The minimum quantity should be equal to, at least, the minimum distance between two neighbouring candidate locations. The units are the same as of the projected x- and y-coordinates. If missing, they are estimated from `candi`.

The help page of minmaxPareto contains details on how spsann solves the multi-objective combinatorial optimization problem of finding a globally optimum sample configuration that meets multiple, possibly conflicting, sampling objectives.

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.

Visit the help pages of optimCORR, optimDIST, optimPPL, and optimMSSD to see the details of the objective functions that compose SPAN.

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

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

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.

Alessandro Samuel-Rosa alessandrosamuelrosa@gmail.com

optimCORR, optimDIST, optimPPL, optimMSSD

## Not run: 
# This example takes more than 5 seconds to run!
require(sp)
data(meuse.grid)
candi <- meuse.grid[, 1:2]
nadir <- list(sim = 10, seeds = 1:10)
utopia <- list(user = list(DIST = 0, CORR = 0, PPL = 0, MSSD = 0))
covars <- meuse.grid[, 5]
schedule <- scheduleSPSANN(chains = 1, initial.temperature = 1,
                           x.max = 1540, y.max = 2060, x.min = 0, 
                           y.min = 0, cellsize = 40)
weights <- list(CORR = 1/6, DIST = 1/6, PPL = 1/3, MSSD = 1/3)
set.seed(2001)
res <- optimSPAN(
  points = 10, candi = candi, covars = covars, nadir = nadir, weights = weights,
    use.coords = TRUE, utopia = utopia, schedule = schedule)
objSPSANN(res) -
  objSPAN(points = res, candi = candi, covars = covars, nadir = nadir,
            use.coords = TRUE, utopia = utopia, weights = weights)

## End(Not run)