simulationsApply: Apply functions value-wise, location-wise, or plume-wise to...

In KristinaHelle/sensors4plumes: Test and Optimise Sampling Designs Based on Plume Simulations

Description

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.

Usage

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, ...)

Arguments

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

Details

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.

Value

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.

Author(s)

Kristina B. Helle, [e-mail]

Examples

## 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)

KristinaHelle/sensors4plumes documentation built on May 7, 2019, 12:31 p.m.