simulationsApply: Apply functions value-wise, location-wise, or plume-wise to...
In sensors4plumes: Test and Optimise Sampling Designs Based on Plume Simulations

Description Usage Arguments Details Value Author(s) Examples

Apply functions to the @values of Simulations objects or to Raster* objects. Functions can be applied to any margin: value-wise, plume-wise, or location-wise. The results can be summarised by a second function. Processing of the data may be done in blocks, this allows to process data that does not fit into memory. However, this only works if input and output of a single function fit into memory.

simulationsApply(simulations, 
  locations = 1:nLocations(simulations), 
  plumes = 1:nPlumes(simulations), 
  kinds = 1:nKinds(simulations), 
  fun = NA, fun_p = NA, fun_l = NA, fun_pl = NA, 
  fun_Rp = NA, fun_Rl = NA, fun_Rpl = NA, fun_Rpl_cellStats = NA, 
  nameSave = "simulationsApply", overwrite = FALSE,
  chunksize = 1e+7, keepSubset = FALSE, ...)

`simulations`	Simulations object or Raster* object
`locations`	indices of locations, i.e. rows of `simulations@values` to be taken into account
`plumes`	indices of plumes, i.e. columns of `simulations@values` to be taken into account
`kinds`	index or name of the layer of `simulations@values` to be used
`fun`	function to be applied to all values of the subset at once, see details
`fun_p`	function to be applied plume-wise, see details
`fun_l`	function to be applied location-wise, see details
`fun_pl`	function to be applied value-wise, see details
`fun_Rp`	function to be applied to the result of `fun_p`, see details
`fun_Rl`	function to be applied to the result of `fun_l`, see details
`fun_Rpl`	function to be applied to the result of `fun_pl`, see details
`fun_Rpl_cellStats`	character string of function to be applied to the result of `fun_pl` via `cellStats`, must be one of `c("sum", "mean", "min", "max", "sd", "skew", "rms")`
`nameSave`	filename for the raster file in case the result does not fit into memory; if `FALSE` the function stops with a warning and does not create a file
`overwrite`	boolean, if the file at `nameSave` may be overwritten
`chunksize`	maximal number of cells to be processed at once – forwarded to `blockSize` inside
`keepSubset`	boolean, if the subset of the values of `simulations` generated by `locations` and `plumes` is to be kept
`...`	further parameters to be passed on to called functions

The defaults for locations, plumes and kinds only work for simulations of class Simulations. If it is of class raster, the user has to provide these parameters. If plumes or locations contain an index several times, these plumes / locations are considered that many times, also order is kept. Invalid indices cause stop with warning.

The functions must have a certain form, else the function stops with a warning: they need the parameters x for the input values and nout, the length of the output (to generate the arrays to hold the results). Several functions to be applied can be specified. However, fun_Rp, fun_Rl, and fun_Rpl make only sense if the functions that generate their input are specified. fun_Rp and fun_Rl need the additional parameter weight, inside of simulationsApply this parameter is set to the data frames associated with the plumes or locations, respectively: you may refer to names of these data frames inside the functions (default is overwritten); if simulations is a raster object, no values are inserted as weight – the parameter must be given, but unless it has default values you cannot refer to it in the function. fun_Rpl needs the parameters weight_l and weight_p which are replaced by the data frames associated with locations and plumes. All functions are checked by replaceDefault automatically with type = "fun.simulationsApply"; fun_Rp, fun_Rl with type = "funR.simulationsApply" and fun_Rpl with type = "funRR.simulationsApply".

The output of fun, fun_p, or fun_l is supposed to be small enough to keep it in memory; if not, it stops with a warning. The results of fun_pl may be too big to keep in memory. If nameSave is a filename, these data are saved as raster files. The subset of values (defined by plumes and locations) is only kept if it fits into memory.

List of values and arrays (dimensions: references (locations, plumes), output parameters of the function): "result_global": result of fun "result_plumes": result of fun_p "result_locations": result of fun_l "result_global_plumes": result of fun_Rp "result_global_locations": result of fun_Rl "result_locationsplumes": result of fun_pl; RasterBrick "result_global_locationsplumes": result of fun_Rpl "result_global_locationsplumes": result of fun_Rpl_cellStats "subset": subset of data, according to plumes and locations If some function cannot be applied (wrong parameters, input not in memory...), the result of this function is not returned with a warning.

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

## Not run: 
## may create files
demo(radioactivePlumes_addProperties)

# number of not detected plumes for given set of 10 sensors, 
# weighted by total dose of plumes
sensors = sample.int(nLocations(radioactivePlumes), 10)
  
nondetection = function(x, threshold = 1e-7, nout = 1){ 
  all(x[,2] < threshold)
}

sumWeighted = function(x, weight, nout = 1){
  sum(x * weight$totalDose)
}

weightedSumUndetectedAtSensors = simulationsApply(
  simulations = radioactivePlumes,
  locations = sensors,
  fun_p = nondetection,
  fun_Rp = sumWeighted
)

# map of average time until detection of plumes
# if a plume never reaches a location it is counted as being there after a week
meanDetectionTime = function(x, nout = 1){
  y = x
  y[is.na(x)] = 7 * 86400 
  z = mean(y, na.rm = TRUE)
}

mapMeanDetectionTime = simulationsApply(
  simulations = radioactivePlumes,
  kinds = 3,
  fun_l = meanDetectionTime
)
radioactivePlumes@locations@data$meanDetectionTime = 
  mapMeanDetectionTime[["result_locations"]]
spplot(radioactivePlumes@locations, zcol = "meanDetectionTime")

# general ratio and difference of 'maxdose' and 'finaldose'
ratioMaxFinal =  function(x, nout = 2){
  ratio = x[2]/x[1]
  diff = x[2] - x[1]
  ratio[!is.finite(ratio)] = NA
  out = c(ratio, diff)
}
valuesRatio = simulationsApply(
  simulations = radioactivePlumes,
  fun_pl = ratioMaxFinal,
  fun_Rpl_cellStats = "mean",
  nameSave = "ratio"
)
hist(valuesRatio[["result_locationsplumes"]], 1, 
  xlim = c(0,1), breaks = c(seq(0, 1, 0.01), 10000))
hist(valuesRatio[["result_locationsplumes"]], 2, 
  xlim = c(-0.001, 0.001), breaks = c(-1000, seq(-0.001, 0.001, 0.0001), 1000))


## End(Not run)