spsann (version 2.2.0)

optimUSER: Optimization of sample configurations using a user-defined objective function

Description

Optimize a sample configuration using a user-defined objective function.

Usage

optimUSER(points, candi, fun, ..., schedule = scheduleSPSANN(),
  plotit = FALSE, track = FALSE, boundary, progress = "txt",
  verbose = FALSE)

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.

fun

A function defining the objective function that should be used to evaluate the energy state of the system configuration at each random perturbation of a candidate sample point. See ‘Details’ for more information.

...

Other arguments passed to the objective function. See ‘Details’ for more information.

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.

Value

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

Details

The user-defined objective function fun must be an object of class function and include the argument points. The argument points is defined in optimUSER as a matrix with three columns: [, 1] the identification of each sample point given by the respective row indexes of candi, [, 2] the x-coordinates, and [, 3] the y-coordinates. The identification is useful to retrieve information from any data matrix used by the objective function defined by the user.

Examples

# NOT RUN {
# This example takes more than 5 seconds
require(sp)
require(SpatialTools)
data(meuse.grid)
candi <- meuse.grid[, 1:2]
schedule <- scheduleSPSANN(chains = 1, initial.temperature = 30,
                           x.max = 1540, y.max = 2060, x.min = 0, 
                           y.min = 0, cellsize = 40)

# Define the objective function - number of points per lag distance class
objUSER <-
  function (points, lags, n_lags, n_pts) {
    dm <- SpatialTools::dist1(points[, 2:3])
    ppl <- vector()
    for (i in 1:n_lags) {
      n <- which(dm > lags[i] & dm <= lags[i + 1], arr.ind = TRUE)
      ppl[i] <- length(unique(c(n)))
    }
    distri <- rep(n_pts, n_lags)
    res <- sum(distri - ppl)
  }
lags <- seq(1, 1000, length.out = 10)

# Run the optimization using the user-defined objective function
set.seed(2001)
timeUSER <- Sys.time()
resUSER <- optimUSER(points = 10, fun = objUSER, lags = lags, n_lags = 9,
                     n_pts = 10, candi = candi, schedule = schedule)
timeUSER <- Sys.time() - timeUSER

# Run the optimization using the respective function implemented in spsann
set.seed(2001)
timePPL <- Sys.time()
resPPL <- optimPPL(points = 10, candi = candi, lags = lags, 
                   schedule = schedule)
timePPL <- Sys.time() - timePPL

# Compare results
timeUSER
timePPL
lapply(list(resUSER, resPPL), countPPL, candi = candi, lags = lags)
objSPSANN(resUSER) - objSPSANN(resPPL)
# }