constructSpaceFillingDesign: Get a space-filling design for a Spatial Stream Network

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

Description

This function finds a space-filling design on a Spatial Stream Network. It does so by optimising one of two space-filling utility functions: (1) the maximin utility function in spaceFillingMaxiMin or (2) the modified maximin utility proposed by Morris and Mitchell (1995) in spaceFillingMorrisMitchell.

The Greedy Exchange Algorithm is used to find the optimal design.

Usage

constructSpaceFillingDesign(ssn, new.ssn.path, n.points,
  type = "maximin", euclidean.distance = FALSE, p = 10,
  n.optim = 5, n.cores = 1, parallelism = "none",
  parallelism.seed = NULL, ...)

Arguments

ssn	An object of class SpatialStreamNetwork. Its obspoints slot must contain all the potential sampling sites for the stream network.
new.ssn.path	A path to a folder where the result can be stored.
n.points	A numeric or a named numeric vector specifying the size of the final design(s). See Details for more information.
type	A character string. Either "maximin" or "morris.mitchell".
euclidean.distance	A logical. This specifies whether Euclidean distance should be used to construct the space-filling designs, instead of hydrological distance within the stream network. Defaults to FALSE.
p	A numeric. This is a weighting power used by the morris.micthell utility function. It is ignored when type = "maximin". This number must be greater than or equal to 1.
n.optim	A numeric integer. The number of times the Greedy Exchange Algorithm (Falk et al., 2014) 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 (while multiplying run-time). Defaults to 5.
n.cores	The number of CPUs which should be used when executing this function. This argument must agree with the argument parallelism. For example, if n.cores > 1 and parallelism is "none", this argument will be ignored and all computations will be performed sequentially. Defaults to 1.
parallelism	A character which must be one of "none", "windows", "linux/osx". These can be spelled with in any case or in any combination of cases. Note the argument must be selected appropriately for the operating system on the user's computer. Definitely do not select "linux/osx" when running this function on a Windows operating system.
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.
...	Any additional arguments for the foreach iterator. The version of foreach from the package doRNG is used.

Details

The argument n.points 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.

Value

A list of four 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) final.points, a vector of the locIDs or pids for the sampling sites present in the optimal design; and 4) utilities, a list of n.optim elements containing the expected utilities computed at every iteration of the Greedy Exchange Algorithm.

References

Falk, M., Pettitt, A., McGree, J.M. (2014). Sampling designs on stream networks using the pseudo-Bayesian approach. Environmental and Ecological Statistics, 21(4), 751-773.

Morris, M.D. & Mitchell, T.J. (1995). Exploratory Designs for Computational Experiments. Journal of Statistical Planning and Inference, 43, 381-402.

Examples

## Not run: 

 # Create a simulated SpatialStreamNetwork object
 s <- createSSN(50, binomialDesign(100), 
 path = tempPath("s.ssn"), importToR = TRUE)
 createDistMat(s)
 
 # Construct a space filling design
 space.filling <- constructSpaceFillingDesign(s, 
 tempPath("r.ssn"), 50, "maximin")
 
 # Plot result to check
 plot(space.filling$ssn.new)
 

## End(Not run)
  

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