optimiseSD_global: Derive one or all globally optimal sampling designs for plume...
In sensors4plumes: Test and Optimise Sampling Designs Based on Plume Simulations

Description Usage Arguments Details Value Author(s) References Examples

This optimisation works only for a special cost function: if the values are logical and indicating for each plume if it can be detected at any sensor location and cost is the fraction of plumes not detected by any sensor. In this case it can derive one or all global optima. It may take very long (hours to weeks) for cases of realistic size (hundreds of locations, more than 2 sensors). The algorithm is described in detail in the reference.

optimiseSD_global(simulations, costFun = NA,
  locationsAll = 1:nLocations(simulations), locationsFix = integer(0),
  locationsInitial = integer(0),
  aimCost = NA, aimNumber = NA,
  nameSave = NA, plot = FALSE, verbatim = FALSE,
  detectable = 1, maxIterations = NA,
  findAllOptima = FALSE, findSensorNumber = FALSE
  )

Some arguments are the same for all optimisation algorithms, they are marked by a *, for detail see optimiseSD

`simulations`	`*`
`costFun`	`*` ignored, as optimisation can only optimise plume detection
`locationsAll`	`*`
`locationsFix`	`*`
`locationsInitial`	`*` ignored, only if `aimNumber` missing it is defined by length of `locationsInitial`
`aimCost`	`*`, ignored
`aimNumber`	`*`
`nameSave`	`*`
`plot`	not implemented yet
`verbatim`	if more output is to be written to the console
`detectable`	which layer of the values of `simulations` to use, character or integer
`maxIterations`	stop when this number of sensor sets was tested (if `findAllOptima = TRUE` this is applied to each search i.e. to the one to find the maximal number of detectable plumes and to the one to find all optima); if `maxIterations` is below the number of sensor sets to actually be tested, the result may not be the global optimum.
`findAllOptima`	logical, if all optima to be found - requires to internally run search twice.
`findSensorNumber`	logical, only relevant if `findAllOptima = FALSE` and all plumes are detected; in this case `findSensorNumber = TRUE` calls further searches to determine the minimal number of sensors required to detect all plumes. If `findAllOptima = TRUE` these searches are run in any case.

In general the function is used within the wrapper optimiseSD. The non-*-parameters are specific to optimiseSD_global, they may be changed beforehand via replaceDefault with type = "optimisationFun.optimiseSD"; all other parameters are forwarded from optimiseSD.

If aimCost is given, the algorithm stops when the aim is reached by the best sampling design. In this case, nothing is returned, but the populations are saved (at nameSave and if nothing indicated at "opt_genetic.Rdata"), see examples how to extract the sampling designs in this case.

A list, the first two entries are common to all optimisation algorithms, they are marked with *, see optimiseSD for details.

`SD`	`*` best sampling designs
`evaluation`	`*` cost and size of `SD`
`report`	a list with more details about the optimisation `detectable` the matrix of 0 and 1 used in the optimisation after selecting only locations in `locationsAll`, deleting locations in `locationsFix` and containing only plumes that cannot be detected at `locationsFix` but at `locationsAll` `first` results of the first run to find the detection limit, `lowerLimit` is this limit plus 1 `all` results of the run to find all optimal sampling designs

Kristina B. Helle, kristina.helle@uni-muenster.de

K.B. Helle, E. Pebesma (2015). Optimising sampling designs for the maximum coverage problem of plume detection. Spatial Statistics (13), 21-44.

# prepare data
# test case from reference
detectionMatrix = matrix(c(0,1,0,0,0,1,
                          1,0,1,0,0,0,
                          0,1,1,1,0,0,
                          1,0,0,0,0,0,
                          0,0,0,1,1,0,
                          1,1,0,0,0,0,
                          0,0,1,0,0,1),
                        nrow = 7, ncol = 6, byrow = TRUE)
data(SimulationsSmall)
completeExample = Simulations(
  locations = SimulationsSmall@locations[1:7,],
  plumes = SimulationsSmall@plumes[1:6,],
  values = raster(x = detectionMatrix,
             xmn = -90, xmx = 90, ymn = -90, ymx = 90,
             crs = "+init=epsg:4326"))

# the function is to be used inside of optimiseSD
# change algorithm specific parameters 'detectable', 'findAllOptima'
optSDglobal = replaceDefault(
  fun = optimiseSD_global,
  newDefaults = list(
    detectable = 1,
    findAllOptima = TRUE
    ),
  type = "optimisationFun.optimiseSD"
)

# run optimisation
## Not run: 
# takes some (little) time
optSD_global = optimiseSD(
  simulations = completeExample,
  aimNumber = 3,
  costFun = NA,
  optimisationFun = optSDglobal[[1]],
  nameSave = NA
)

## End(Not run)
## this result is also in data(SDglobal)

data(SDglobal)
# visualise result
## which plumes are detected?
detAtSensors = matrix(completeExample@values[SDglobal$SD[[1]][1,],],
  byrow = TRUE, nrow = 3)
undetedtedPlumes = ! apply(FUN = any, X = detAtSensors, MARGIN = 2)
## cost is fraction of undetected plumes
sum(undetedtedPlumes)/nPlumes(completeExample) == SDglobal$cost

## map of undetected plumes
detectablePlumesLoc = matrix(getValues(completeExample@values),
  byrow = TRUE, ncol = nPlumes(completeExample))
completeExample@locations@data$detectable = apply(FUN = sum, X = detectablePlumesLoc,
	MARGIN = 1)

SDopt = as(subsetSDF(completeExample@locations,
                   locations =  SDglobal$SD[[1]][1,]),
         "SpatialPointsDataFrame")

spplot(completeExample@locations, zcol = "detectable",
  sp.layout = list(list("sp.points",
  SpatialPoints(coords = coordinates(SDopt), proj4string = CRS(proj4string(SDopt))),
                        col = 3, cex = 2, lwd = 1.5)))