sensors4plumes (version 0.9.3)

optimiseSD_global: Derive one or all globally optimal sampling designs for plume detection

Description

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.

Usage

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
  )

Arguments

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.

Value

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

Details

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.

References

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

Examples

# NOT RUN {
# 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
)
# }
# 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)))
# }