optimiseSSNDesign: A function to optimise designs under pseudo-Bayesian utility...

In apear9/SSNdesign: An R Package for Optimal and Adaptive Sampling Designs on Stream Networks

Description

The function optimiseSSNDesign is the main workhorse function of the package SSNdesign. It works to construct optimal and adaptive designs using a greedy exchange algorithm under a variety of different circumstances.

Usage

optimiseSSNDesign(ssn, new.ssn.path, glmssn, n.points, legacy.sites,
  select.by = "auto", utility.function, prior.parameters, n.cores = 1,
  parallelism = "none", parallelism.seed = NULL, n.optim = 5,
  n.draws = 500, extra.arguments = list(), verbose = TRUE,
  record.designs = FALSE, ...)

Arguments

ssn	An object of class SpatialStreamNetwork. This object must contain all potential sampling sites in itsobspoints slot.
new.ssn.path	A path to a folder where the result can be stored. The folder name must end in .ssn. This function will throw an error if the argument matches the name of an existing folder.
glmssn	A fitted glmssn object. However, this model does not need to have been fitted to the SpatialStreamNetwork object in the argument ssn.
n.points	A numeric or a named numeric vector specifying the size of the final design(s). See Details for more information.
legacy.sites	A vector of the pids or locIDs of any 'legacy sites' which must appear in the final design. This argument is optional and should be left missing if not required. Note that the total number of sampling sites in the final design will still be n.points.
select.by	A string argument which specifies whether each pid represents a single design point or each locID. The options are "auto" (the function will autodetect whether there are multiple pids per locID and use locIDs as unique design points), "pid" or "locID". This argument defaults to "auto".
utility.function	A function with the signature 'utility.function'. See Details for more information.
prior.parameters	A list of functions or a matrix. If this argument is a list, the elements of this list specify independent priors for the covariance parameters in the glmssn object. If this argument is a matrix, the matrix contains the prior draws from any kind of prior (multivariate or independent) on the covariance parameters in the glmssn object. Note, in this case, the n.draws argument will be ignored because the matrix will have as many rows as there are prior draws. See Details for more information.
n.cores	The number of CPUs which should be used when running optimiseSSNDesign. This argument must agree with the argument parallelism. For example, this means that, if n.cores > 1 and parallelism = "none", this argument will be ignored and all computations will be performed sequentially. Defaults to 1.
parallelism	Must be one of "none", "windows", or "osx/linux". These arugments are insensitive to case. Note the argument must be selected appropriately for the operating system on the user's computer.
parallelism.seed	Either a numeric integer or NULL. This argument can be used to seed a random number generator which ensures reproducible calculations. This argument is effective regardless of whether parallel computations are being used.
n.optim	The number of times the Greedy Exchange Algorithm is iterated to find an optimal design. Any integer greater than or equal to 1 is permissible, though larger values will produce more reliable results. Defaults to 5.
n.draws	The number of Monte Carlo draws used to approximate the expected utility from the utility function per Muller (1999). Any values larger than 1 are permitted, though a minimum of 100 are recommended for the most stable results.
extra.arguments	A list of miscellaneous arguments and values which may be used to control the behaviour of the utility.function. See Details for more information.
verbose	Whether messages indicating the function's progress should be printed to the console. Defaults to TRUE.
record.designs	Whether the function should return all the designs evaluated. This is FALSE by default and should remain FALSE for larger examples due to the incredible amount of memory this requires.
...	Any additional arguments for the foreach iterator. The version of foreach from the package doRNG is used.

Details

There are several aspects of this function that require explanations beyond the brief descriptions of the arguments above.

• n.points: this argument can be a single number or a vector. If the user supplies a single number, then, regardless of the number of isolated networks present in the ssn object, a total of n.points sites will be selected across ALL these networks. That is, the networks are not treated as separate design problems. However, if the user supplies a vector, things become more complicated. Firstly, the vector must be named. The names of the elements correspond to networks in the ssn argument and the element itself is the number of sites which should be selected within that network. The n.points argument may therefore look like this: c("1" = 5, "3" = 6). In this example, the user is asking for 5 sites to be chosen from network 1 and 6 from network 3. It also shows that there is no need to select sites in every network. One final caveat is that no sites will appear in ssn.new for any networks which are skipped over.

• utility.function: there are a number of pre-defined utility functions such as DOptimality and KOptimality. See THIS PAGE for an exhaustive list. Instructions for creating user-defined utility functions can also be found through that link.

• prior.parameters: the number of elements in the prior.parameters list must be the same as the number of covariance parameters in the fitted glmssn which is also passed to this function. For example, if the only covariance parameter is the nugget (i.e. there is no spatial autocorrelation), then prior.parameters would be a list with one element. Each list element must be structured as an anonymous function as follows: prior.parameters[[i]] <- function(x) runif(x). The random sample function does not have to be runif. The key message is that the function must only have a single argument, which is the number of draws to be taken from a random sample function. The function constructLogNormalPriors is able to construct lists of log-normal priors from glmssn objects.

• extra.arguments: this is an argument that is mostly exploited internally by optimiseSSNDesign, since the list structure is convenient for storing myriad objects such as design and distance matrices involved in the computation of the expected utility. However, some utility functions, such as CPOptimality, have additional parameters that they expect from the extra.arguments list. In particular, CPOptimality expects extra.arguments$h, a step-size argument that it uses in the forward-finite differencing of the covariance matrix. (It needs to do this to estimate the expected Fisher information matrix, which the utility function relies on.)

Value

A list with the following elements: 1. ssn.old, the original and unaltered ssn. 2. ssn.new, the original ssn modified such that it contains only the sites in the optimal design. 3. call, the code block used to run optimiseSSNDesign. 4. glmssn, the original and unmodified glmssn. 5. legacy.sites, a vector containing the locID or pid values of any legacy sites. 6. utility.function, the original and unmodified utility function used to optimise the design. 7. prior.draws, a matrix containing the simulated values of the covariance parameters drawn from the priors. 8. n.draws, a numeric indicating the number of Monte Carlo draws that were used when evaluating the expected utility of each design. 9. random.seed, the random seed specified in the parallelism.seed argument. 10. final.points, a vector of the locID or pid values for the sites included in the final design. 11. best.designs.per.K.iteration, the same as final.points for each of the random starts. 12. trace.per.random.start, 13. designs, a list of all the designs evaluated when optimising the design. This will be empty unless record.designs = TRUE. 14. utilities, a list of all the expected utility values of the designs evaluated when optimising the design.

References

Muller, P. (1999). Simulation Based Optimal Design. Bayesian Statistics, 6, 1-13.

Examples

## Not run: 
## Simulate an ssn
s <- createSSN(c(100, 100), binomialDesign(c(25, 25)),
 path = paste(tempdir(), "s1.ssn", sep = "/"), importToR = TRUE)
createDistMat(s)
## Simulating data
s <- SimulateOnSSN(
 s, 
 getSSNdata.frame(s),
 formula = ~ 1, 
 coefficients = 1, 
 CorParms = c(1, 2, 1, 2, 1, 2, .1),
 addfunccol = "addfunccol"
)$ssn.object
## Model-fitting
m <- glmssn(Sim_Values ~ 1, s, addfunccol = "addfunccol")
## Construct a list of log-normal priors
p <- constructLogNormalPriors(m1)
## Use optimiseSSNDesign
r.together <- optimiseSSNDesign(
 ssn = s, new.ssn.path = paste(tempdir(), "s2.ssn", sep = "/"), glmssn = m, n.points = 25, 
 utility.function = DOptimality, prior.parameters = p, n.cores = 2, parallelism = "windows", 
parallelism.seed = 123, n.optim = 1, n.draws = 100)
r.apart <- optimiseSSNDesign(
 ssn = s, new.ssn.path = paste(tempdir(), "s3.ssn", sep = "/"), glmssn = m, 
 n.points = c("1" = 7, "2" = 8), utility.function = DOptimality, prior.parameters = p,
  n.cores = 2, parallelism = "windows", parallelism.seed = 123, n.optim = 1, n.draws = 100)

## End(Not run)

apear9/SSNdesign documentation built on Feb. 19, 2020, 4:29 a.m.