adaptive_sample_auto: Spatially adaptive sampling. Idnentical to adaptive.sample...
In disarm-platform/disarm-r-package: A collection of spatial analysis functions related to the DiSARM project at UCSF
Description
Usage
Arguments
Details
Value
Note
Author(s)
References
See Also
Examples
Description
Draw an additional sample from a set of available locations in a defined geographical region, imposing a minimum distance between any two sampled units and taking into account existing data from previously sampled locations. The algorithm allows the user to specify either a prediction variance (PV) criterion or an exceedance probability (EP) criterion to choose new sampling locations. The function accepts either sf or sp objects.
Usage
1
2
3
Arguments
obj1
a sf or sp object of locations available for sampling, where each line contains the coordinates of a spatial location, a prediction variance or an exceedance probability at that location and, optionally, values of one or more covariates. NOTE that only one of the two quantities (i.e. PV or EP) is required to add samples adaptively. Locations that meet the specified selection criterion are equally likely to be sampled subject to spatial contraints. See criterion and Details for more information.
obj2
a sf or sp object of locations previously sampled. Each line corresponds to one spatial location. It must contain values of 2D coordinates and may also contain the values of one or more covariates. The initial sample locations design can be generated from random.sample, discrete.inhibit.sample, contin.inhibit.sample or some other design.
pred.var.col
a scalar of length one indicating the column number corresponding to prediction variance at each spatial location in obj1. This is required if criterion = "predvar". See 'criterion' and Details for information.
excd.prob.col
a scalar of length one indicating the column number corresponding to exceedance probabilities at each spatial location in obj1. This is required if criterion = "exceedprob". See 'criterion' and Details for information.
batch.size
a non-negative integer giving the number of adaptively chosen locations to be added to the existing sample (design).
delta
minimum permissible distance between any two locations in the sample.
criterion
criterion used for choosing new locations x^*. Use "predvar" for prediction variance or "exceedprob" for exceedance probablity. See the Details section for more information.
poly
'optional', a sf or sp polygon object in which the design sits. The default is the bounding box of points given by obj1.
plotit
'logical' specifying if graphical output is required. Default is plotit = TRUE.
Details
For the predictive target T = S(x) at a particular location x,
given an initial set of sampling locations X_0 = (x_1,…, x_{n0})
the available set of additional sampling locations is A_0 = X* \setminus X_0. To mimic spatially continuous sampling, the initial set should be a fine grid to cover the region of interest
Define the following notation:
-
{\cal X}^* is the set of all potential sampling locations, with number of elements n^*.
-
X_0 is the initial sample, with number of elements n_0.
-
b is the batch size.
-
n = n_0 + kb is the total sample size.
-
{\cal X}_j, j ≥ 1 is the set of locations added in the j^{th} batch, with number of elements b.
-
A_j = {\cal X}^* \setminus {\cal X}_0 \cup … \cup X_j is the set of available locations after addition of the j^{th} batch.
1. Prediction variance criterion.
For each x \in A_0, denote by PV(x) the prediction variance, \code{Var}(T|Y_0). The algorithm then proceeds as follows.
Step 1. Use a non-adaptive design to determine {\cal X}_0.
Step 2. Set j = 0.
Step 3. For each x \in A_j, calculate PV(x).
Step 3.(i) choose x^* = \code{arg max}_{A_j} PV(x),
Step 3.(ii) if ||x^* - x_i|| > δ, \forall i=1,…,n_0 + jb, add x^* to the design,
Step 4. Repeat step 3 until b locations have been added to form the set X_{j+1}.
Step 5. Set A_j = A_{j=1} \setminus {\cal X}_j and we update j to j + 1.
Step 6. Repeat steps 3 to 5 until the total number of sampled locations is n or A_j = \emptyset.
2. Exceedance probability criterion.
For each x \in A_0, denote by EP(x) the exceedance probability, P[\{T(x) > t | y_0\} - 0.5] for a specified threshold t. The algorithm proceeds as above, with changes only in step 3, as follows.
Step 3. For each x \in A_j, calculate EP(x).
Step 3.(i) choose x^* = \code{arg min}_{A_j}EP(x).
Value
A list with the following four components:
total.size: the total number of locations, n, sampled.
delta: the value of δ.
criterion: the sample selection criterion used for adaptive sampling.
sample.locs: a list of objects for sample locations. It has the following components.
curr.sample: a sf or sp object of dimension n by 2 containing all sampled locations, where n is the total sample size (initial plus newly added sample locations).
prev.sample: a sf or sp object of dimension n_{i} by 2 containing initial sample locations, where n_{i} < n.
added.sample: a sf or sp object of dimension n_{a} by 2 containing additional sample locations, i.e. adaptively sampled locations, where n_a = b, the batch size.
Note
The function can only add a single batch at a time.
Author(s)
Michael G. Chipeta mchipeta@mlw.mw
Peter J. Diggle p.diggle@lancaster.ac.uk
References
Chipeta M G, Terlouw D J, Phiri K S and Diggle P J. (2016a). Adaptive geostatistical design and analysis for prevalence surveys, Spatial Statistics 15, pp. 70-84.
Giorgi E and Diggle P J. (2017). PrevMap: an R package for prevalence mapping. Journal of Statistical Software. 78:1-29, doi: 10.18637/jss.v078.i08
Kabaghe A N, Chipeta M G, McCann R S, Phiri K S, Van Vugt M, Takken W, Diggle P J, and Terlouw D J. (2017). Adaptive geostatistical sampling enables efficient identification of malaria hotspots in repeated cross-sectional surveys in rural Malawi, PLoS One 12(2) pp. e0172266
See Also
discrete.inhibit.sample and contin.inhibit.sample
Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
#example using toy datasets
#1. sampling locations with associated prediction variance and exceedance probabilities
set.seed(1234)
xy.all <- expand.grid(x = seq(0,1, l = 10),y = seq(0,1, l = 10))
xy.all$predvar <- runif(100, min=0, max = 2.5)
xy.all$exceedprob <- runif(100, min = 0, max = 1)
obj1 <- sf::st_as_sf(xy.all, coords = c('x', 'y'))
#2. initial sample design
set.seed(1234)
xy.sample <- discrete.inhibit.sample(obj = obj1, size = 70,
delta = 0.075, k = 0,
plotit = TRUE)
init.design <- xy.sample$sample.locs
#3. adaptive sampling designs
#a. using prediction variance criterion
adapt.design.pv <- adaptive.sample(obj1 = obj1, obj2 = init.design,
pred.var.col = 1, criterion = "predvar",
delta = 0.1, batch.size = 10,
poly = NULL, plotit = TRUE)
#b. using exceedance probability criterion
adapt.design.ep <- adaptive.sample(obj1 = obj1, obj2 = init.design,
excd.prob.col = 2, criterion = "exceedprob",
delta = 0.1, batch.size = 10,
poly = NULL, plotit = TRUE)
## Not run:
data("sim.data")
library("PrevMap")
library("sf")
#1. Generate inhibitory design without close pairs using discrete.inhibit.sample().
set.seed(1234)
xy.sample <- discrete.inhibit.sample(obj = sim.data, size = 100, delta = 0.075,
k = 0, plotit = TRUE)
names(xy.sample)
init.design <- xy.sample$sample.locs
#2. Data analysis
knots <- as.matrix(expand.grid(seq(-0.2, 1.2, length = 15),
seq(-0.2, 1.2, length = 15)))
lr.mcmc <- control.mcmc.MCML(n.sim = 10000, burnin = 1000, thin = 6)
par0.lr <- c(0.001, 1, 0.4)
fit.MCML.lr <- binomial.logistic.MCML(y ~ 1,
units.m = ~units.m, coords = ~st_coordinates(init.design),
data = init.design, par0 = par0.lr, fixed.rel.nugget = 0,
start.cov.pars = par0.lr[3], control.mcmc = lr.mcmc,
low.rank = TRUE, knots = knots, kappa = 1.5,
method = "nlminb", messages = TRUE,
plot.correlogram = FALSE)
summary(fit.MCML.lr, log.cov.pars = FALSE)
# Note: parameter estimation above can and should be repeated several times with updated starting
# values for the covariance function.
#3. Plug-in prediction using estimated parameters
pred.MCML.lr <- spatial.pred.binomial.MCML(object = fit.MCML.lr,
control.mcmc = lr.mcmc,
grid.pred = st_coordinates(sim.data),
type = "joint", messages = TRUE,
scale.predictions = "prevalence",
standard.errors = TRUE, thresholds = 0.45,
scale.thresholds = "prevalence")
#4. Visualisation of analysis from initial sample
plot(pred.MCML.lr, type = "prevalence", summary = "predictions",
zlim = c(0, 1), main = "Prevalence - predictions")
contour(pred.MCML.lr, "prevalence", "predictions",
zlim = c(0, 1), levels = seq(0.1,0.9, 0.1), add = TRUE)
plot(pred.MCML.lr, summary = "exceedance.prob",
zlim = c(0, 1), main = "Prevalence - exceedance probability")
contour(pred.MCML.lr, summary = "exceedance.prob",
zlim = c(0, 1), levels = seq(0.1,0.3, 0.1), add = TRUE)
plot(pred.MCML.lr, type = "prevalence", summary = "standard.errors",
main = "Prevalence - standard errors")
#5. Adaptive sampling
#create data frame of ingredients to adaptive sampling from spatial predictions above
obj1 <- as.data.frame(cbind(pred.MCML.lr$grid,
c(pred.MCML.lr$prevalence$standard.errors)^2,
pred.MCML.lr$exceedance.prob))
colnames(obj1) <- c("x", "y", "pred.var", "exceed.prob")
obj1 <- sf::st_as_sf(obj1, coords = c('x', 'y'))
#adaptive sampling using prediction variance criterion.
adapt.design.pv <- adaptive.sample(obj1 = obj1, obj2 = init.design,
pred.var.col = 1, excd.prob.col = 2,
criterion = "predvar", delta = 0.08,
batch.size = 10, poly = NULL, plotit = TRUE)
#adaptive sampling using exceedance probability criterion.
adapt.design.ep <- adaptive.sample(obj1 = obj1, obj2 = init.design,
pred.var.col = 1, excd.prob.col = 2,
criterion = "exceedprob", delta = 0.08,
batch.size = 10, poly = NULL, plotit = TRUE)
## End(Not run)
disarm-platform/disarm-r-package documentation built on March 4, 2020, 11:13 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Description Usage Arguments Details Value Note Author(s) References See Also Examples
Description
Draw an additional sample from a set of available locations in a defined geographical region, imposing a minimum distance between any two sampled units and taking into account existing data from previously sampled locations. The algorithm allows the user to specify either a prediction variance (PV) criterion or an exceedance probability (EP) criterion to choose new sampling locations. The function accepts either sf or sp objects.
Usage
1 2 3 |
Arguments
obj1 |
a |
obj2 |
a |
pred.var.col |
a scalar of length one indicating the column number corresponding to prediction variance at each spatial location in |
excd.prob.col |
a scalar of length one indicating the column number corresponding to exceedance probabilities at each spatial location in |
batch.size |
a non-negative integer giving the number of adaptively chosen locations to be added to the existing sample (design). |
delta |
minimum permissible distance between any two locations in the sample. |
criterion |
criterion used for choosing new locations x^*. Use |
poly |
'optional', a |
plotit |
'logical' specifying if graphical output is required. Default is |
Details
For the predictive target T = S(x) at a particular location x,
given an initial set of sampling locations X_0 = (x_1,…, x_{n0})
the available set of additional sampling locations is A_0 = X* \setminus X_0. To mimic spatially continuous sampling, the initial set should be a fine grid to cover the region of interest
Define the following notation:
-
{\cal X}^* is the set of all potential sampling locations, with number of elements n^*.
-
X_0 is the initial sample, with number of elements n_0.
-
b is the batch size.
-
n = n_0 + kb is the total sample size.
-
{\cal X}_j, j ≥ 1 is the set of locations added in the j^{th} batch, with number of elements b.
-
A_j = {\cal X}^* \setminus {\cal X}_0 \cup … \cup X_j is the set of available locations after addition of the j^{th} batch.
1. Prediction variance criterion.
For each x \in A_0, denote by PV(x) the prediction variance, \code{Var}(T|Y_0). The algorithm then proceeds as follows.
Step 1. Use a non-adaptive design to determine {\cal X}_0.
Step 2. Set j = 0.
Step 3. For each x \in A_j, calculate PV(x).
Step 3.(i) choose x^* = \code{arg max}_{A_j} PV(x),
Step 3.(ii) if ||x^* - x_i|| > δ, \forall i=1,…,n_0 + jb, add x^* to the design,
Step 4. Repeat step 3 until b locations have been added to form the set X_{j+1}.
Step 5. Set A_j = A_{j=1} \setminus {\cal X}_j and we update j to j + 1.
Step 6. Repeat steps 3 to 5 until the total number of sampled locations is n or A_j = \emptyset.
2. Exceedance probability criterion.
For each x \in A_0, denote by EP(x) the exceedance probability, P[\{T(x) > t | y_0\} - 0.5] for a specified threshold t. The algorithm proceeds as above, with changes only in step 3, as follows.
Step 3. For each x \in A_j, calculate EP(x).
Step 3.(i) choose x^* = \code{arg min}_{A_j}EP(x).
Value
A list with the following four components:
total.size: the total number of locations, n, sampled.
delta: the value of δ.
criterion: the sample selection criterion used for adaptive sampling.
sample.locs: a list of objects for sample locations. It has the following components.
curr.sample: a sf or sp object of dimension n by 2 containing all sampled locations, where n is the total sample size (initial plus newly added sample locations).
prev.sample: a sf or sp object of dimension n_{i} by 2 containing initial sample locations, where n_{i} < n.
added.sample: a sf or sp object of dimension n_{a} by 2 containing additional sample locations, i.e. adaptively sampled locations, where n_a = b, the batch size.
Note
The function can only add a single batch at a time.
Author(s)
Michael G. Chipeta mchipeta@mlw.mw
Peter J. Diggle p.diggle@lancaster.ac.uk
References
Chipeta M G, Terlouw D J, Phiri K S and Diggle P J. (2016a). Adaptive geostatistical design and analysis for prevalence surveys, Spatial Statistics 15, pp. 70-84.
Giorgi E and Diggle P J. (2017). PrevMap: an R package for prevalence mapping. Journal of Statistical Software. 78:1-29, doi: 10.18637/jss.v078.i08
Kabaghe A N, Chipeta M G, McCann R S, Phiri K S, Van Vugt M, Takken W, Diggle P J, and Terlouw D J. (2017). Adaptive geostatistical sampling enables efficient identification of malaria hotspots in repeated cross-sectional surveys in rural Malawi, PLoS One 12(2) pp. e0172266
See Also
discrete.inhibit.sample and contin.inhibit.sample
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 | #example using toy datasets
#1. sampling locations with associated prediction variance and exceedance probabilities
set.seed(1234)
xy.all <- expand.grid(x = seq(0,1, l = 10),y = seq(0,1, l = 10))
xy.all$predvar <- runif(100, min=0, max = 2.5)
xy.all$exceedprob <- runif(100, min = 0, max = 1)
obj1 <- sf::st_as_sf(xy.all, coords = c('x', 'y'))
#2. initial sample design
set.seed(1234)
xy.sample <- discrete.inhibit.sample(obj = obj1, size = 70,
delta = 0.075, k = 0,
plotit = TRUE)
init.design <- xy.sample$sample.locs
#3. adaptive sampling designs
#a. using prediction variance criterion
adapt.design.pv <- adaptive.sample(obj1 = obj1, obj2 = init.design,
pred.var.col = 1, criterion = "predvar",
delta = 0.1, batch.size = 10,
poly = NULL, plotit = TRUE)
#b. using exceedance probability criterion
adapt.design.ep <- adaptive.sample(obj1 = obj1, obj2 = init.design,
excd.prob.col = 2, criterion = "exceedprob",
delta = 0.1, batch.size = 10,
poly = NULL, plotit = TRUE)
## Not run:
data("sim.data")
library("PrevMap")
library("sf")
#1. Generate inhibitory design without close pairs using discrete.inhibit.sample().
set.seed(1234)
xy.sample <- discrete.inhibit.sample(obj = sim.data, size = 100, delta = 0.075,
k = 0, plotit = TRUE)
names(xy.sample)
init.design <- xy.sample$sample.locs
#2. Data analysis
knots <- as.matrix(expand.grid(seq(-0.2, 1.2, length = 15),
seq(-0.2, 1.2, length = 15)))
lr.mcmc <- control.mcmc.MCML(n.sim = 10000, burnin = 1000, thin = 6)
par0.lr <- c(0.001, 1, 0.4)
fit.MCML.lr <- binomial.logistic.MCML(y ~ 1,
units.m = ~units.m, coords = ~st_coordinates(init.design),
data = init.design, par0 = par0.lr, fixed.rel.nugget = 0,
start.cov.pars = par0.lr[3], control.mcmc = lr.mcmc,
low.rank = TRUE, knots = knots, kappa = 1.5,
method = "nlminb", messages = TRUE,
plot.correlogram = FALSE)
summary(fit.MCML.lr, log.cov.pars = FALSE)
# Note: parameter estimation above can and should be repeated several times with updated starting
# values for the covariance function.
#3. Plug-in prediction using estimated parameters
pred.MCML.lr <- spatial.pred.binomial.MCML(object = fit.MCML.lr,
control.mcmc = lr.mcmc,
grid.pred = st_coordinates(sim.data),
type = "joint", messages = TRUE,
scale.predictions = "prevalence",
standard.errors = TRUE, thresholds = 0.45,
scale.thresholds = "prevalence")
#4. Visualisation of analysis from initial sample
plot(pred.MCML.lr, type = "prevalence", summary = "predictions",
zlim = c(0, 1), main = "Prevalence - predictions")
contour(pred.MCML.lr, "prevalence", "predictions",
zlim = c(0, 1), levels = seq(0.1,0.9, 0.1), add = TRUE)
plot(pred.MCML.lr, summary = "exceedance.prob",
zlim = c(0, 1), main = "Prevalence - exceedance probability")
contour(pred.MCML.lr, summary = "exceedance.prob",
zlim = c(0, 1), levels = seq(0.1,0.3, 0.1), add = TRUE)
plot(pred.MCML.lr, type = "prevalence", summary = "standard.errors",
main = "Prevalence - standard errors")
#5. Adaptive sampling
#create data frame of ingredients to adaptive sampling from spatial predictions above
obj1 <- as.data.frame(cbind(pred.MCML.lr$grid,
c(pred.MCML.lr$prevalence$standard.errors)^2,
pred.MCML.lr$exceedance.prob))
colnames(obj1) <- c("x", "y", "pred.var", "exceed.prob")
obj1 <- sf::st_as_sf(obj1, coords = c('x', 'y'))
#adaptive sampling using prediction variance criterion.
adapt.design.pv <- adaptive.sample(obj1 = obj1, obj2 = init.design,
pred.var.col = 1, excd.prob.col = 2,
criterion = "predvar", delta = 0.08,
batch.size = 10, poly = NULL, plotit = TRUE)
#adaptive sampling using exceedance probability criterion.
adapt.design.ep <- adaptive.sample(obj1 = obj1, obj2 = init.design,
pred.var.col = 1, excd.prob.col = 2,
criterion = "exceedprob", delta = 0.08,
batch.size = 10, poly = NULL, plotit = TRUE)
## End(Not run)
|
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.