/
package.R
321 lines (320 loc) · 15.8 KB
/
package.R
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
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
#' The sparr Package: Spatial and Spatiotemporal Relative Risk
#'
#' Provides functions to estimate fixed and adaptive kernel-smoothed spatial relative
#' risk surfaces via the density-ratio method and perform subsequent inference. Fixed-bandwidth spatiotemporal density and relative risk estimation is also supported.
#'
#' @template version
#' @details
#'
#' Kernel smoothing, and the
#' flexibility afforded by this methodology, provides an attractive approach to
#' estimating complex probability density functions.
#'
#' The \emph{spatial relative risk function}, constructed as a ratio of estimated case
#' to control densities (Bithell, 1990; 1991; Kelsall and Diggle, 1995a,b), describes the variation in the
#' `risk' of the disease, given the underlying at-risk population. This is a
#' technique that has been applied successfully for mainly exploratory purposes
#' in a number of different analyses (see for example Sabel et al., 2000;
#' Prince et al., 2001; Wheeler, 2007, Elson et al., 2021). It has also grown in popularity in very
#' different fields that pose similarly styled research questions, such as ecology
#' (e.g. Campos and Fedigan, 2014); physiology (Davies et al., 2013); and archaeology
#' (e.g. Bevan, 2012; Smith et al. 2015).
#'
#' This package provides functions for spatial (i.e. bivariate/planar/2D) kernel density estimation
#' (KDE), implementing both fixed and `variable' or `adaptive' (Abramson, 1982)
#' smoothing parameter options. A selection of bandwidth calculators for bivariate KDE and the
#' relative risk function are provided, including one based on the maximal
#' smoothing principle (Terrell, 1990), and others involving a leave-one-out
#' cross-validation (see below). In addition, the ability to
#' construct both Monte-Carlo and asymptotic \emph{p}-value surfaces (`tolerance'
#' contours of which signal statistically significant sub-regions of extremity
#' in a risk surface - Hazelton and Davies, 2009; Davies and Hazelton, 2010) as
#' well as some visualisation tools are provided.
#'
#' Spatiotemporal estimation is also supported, largely following developments
#' in Fernando and Hazelton (2014). This includes their fixed-bandwith kernel estimator
#' of spatiotemporal densities, relative risk, and asymptotic tolerance contours.
#'
#' Key content of \code{sparr} can be broken up as follows:\cr
#'
#' \bold{DATASETS/DATA GENERATION}
#'
#' \code{\link{pbc}} a case/control planar point pattern (\code{\link[spatstat.geom:ppp]{ppp.object}}) concerning liver disease in northern
#' England.
#'
#' \code{\link{fmd}} an anonymised (jittered) case/control spatiotemporal point pattern of the 2001 outbreak of veterinary foot-and-mouth disease in Cumbria (courtesy of the Animal and Plant Health Agency, UK).
#'
#' \code{\link{burk}} a spatiotemporal point pattern of Burkitt's lymphoma in Uganda; artificially simulated control data are also provided for experimentation.
#'
#' Also available are a number of relevant additional spatial datasets built-in to the
#' \code{\link[spatstat]{spatstat}} package (Baddeley and Turner, 2005; Baddeley et al., 2015) through \code{spatstat.data}, such as
#' \code{\link[spatstat.data]{chorley}}, which concerns the distribution of
#' laryngeal cancer in an area of Lancashire, UK.
#'
#' \code{\link{rimpoly}} a wrapper function of \code{\link[spatstat.random]{rpoint}} to allow generated
#' spatial point patterns based on a pixel \code{\link[spatstat.geom]{im}}age to be returned with a
#' polygonal \code{\link[spatstat.geom]{owin}}.\cr
#'
#'
#' \bold{SPATIAL}
#'
#' \emph{Bandwidth calculators}
#'
#' \code{\link{OS}} estimation of an isotropic
#' smoothing parameter for fixed-bandwidth bivariate KDE, based on the
#' oversmoothing principle introduced by Terrell (1990).
#'
#' \code{\link{NS}}
#' estimation of an isotropic smoothing parameter for fixed-bandwidth bivariate
#' KDE, based on the asymptotically optimal value for a normal density
#' (bivariate normal scale rule - see e.g. Wand and Jones, 1995).
#'
#' \code{\link{LSCV.density}} a least-squares cross-validated (LSCV) estimate
#' of an isotropic fixed bandwidth for bivariate, edge-corrected KDE (see e.g. Bowman and
#' Azzalini, 1997).
#'
#' \code{\link{LIK.density}} a likelihood cross-validated (LIK) estimate
#' of an isotropic fixed bandwidth for bivariate, edge-corrected KDE (see e.g. Silverman, 1986).
#'
#' \code{\link{SLIK.adapt}} an experimental likelihood cross-validation function
#' for simultaneous global/pilot bandwidth selection for adaptive density estimates.
#'
#' \code{\link{BOOT.density}} a bootstrap approach to optimisation
#' of an isotropic fixed bandwidth for bivariate, edge-corrected KDE (see e.g. Taylor, 1989).
#'
#' \code{\link{LSCV.risk}} Estimation of a jointly optimal,
#' common isotropic case-control fixed bandwidth for the kernel-smoothed risk
#' function based on the mean integrated squared error (MISE), a weighted MISE,
#' or the asymptotic MISE (see respectively Kelsall and Diggle, 1995a; Hazelton, 2008;
#' Davies, 2013).
#'
#' \emph{Density and relative risk estimation}
#'
#' \code{\link{bivariate.density}} kernel density
#' estimate of bivariate data; fixed or adaptive smoothing.
#'
#' \code{\link{multiscale.density}} multi-scale adaptive kernel density
#' estimates for multiple global bandwidths as per Davies and Baddeley
#' (2018).
#'
#' \code{\link{multiscale.slice}} a single adaptive kernel estimate
#' based on taking a slice from a multi-scale estimate.
#'
#' \code{\link{risk}} estimation of a (log) spatial relative risk function, either from data or
#' pre-existing bivariate density estimates; fixed (Kelsall and Diggle, 1995a); fixed with shrinkage (Hazelton, 2023); or both asymmetric (Davies and Hazelton, 2010) and symmetric (Davies et al., 2016) adaptive estimates are possible.
#'
#' \code{\link{tolerance}}
#' calculation of asymptotic or Monte-Carlo \emph{p}-value surfaces.
#'
#' \emph{Visualisation}
#'
#' \code{S3} methods of the \code{plot} function; see
#' \code{\link{plot.bivden}} for visualising a single bivariate density
#' estimate from \code{\link{bivariate.density}}, \code{\link{plot.rrs}} for
#' visualisation of a spatial relative risk function from
#' \code{\link{risk}}, or \code{\link{plot.msden}} for viewing animations of
#' multi-scale density estimates from \code{\link{multiscale.density}}.
#'
#' \code{\link{tol.contour}} provides more flexibility for plotting and
#' superimposing tolerance contours upon an existing plot of spatial relative risk (i.e. given output from
#' \code{\link{tolerance}}).
#'
#' \emph{Printing and summarising}
#'
#' \code{S3} methods (\code{\link{print.bivden}}, \code{\link{print.rrs}},
#' \code{\link{print.msden}}, \code{\link{summary.bivden}},
#' \code{\link{summary.rrs}}, and \code{\link{summary.msden}}) are available for
#' the bivariate density, spatial relative risk, and multi-scale adaptive density objects.
#'
#'
#' \bold{SPATIOTEMPORAL}
#'
#' \emph{Bandwidth calculators}
#'
#' \code{\link{OS.spattemp}} estimation of an isotropic
#' smoothing parameter for the spatial margin and another for the temporal margin
#' for spatiotemporal densities, based on the 2D and 1D versions, respectively, of the
#' oversmoothing principle introduced by Terrell (1990).
#'
#' \code{\link{NS.spattemp}} as above, based on the 2D and 1D versions of the
#' normal scale rule (Silverman, 1986).
#'
#' \code{\link{LSCV.spattemp}} least-squares cross-validated (LSCV) estimates
#' of scalar spatial and temporal bandwidths for edge-corrected spatiotemporal KDE.
#'
#' \code{\link{LIK.spattemp}} as above, based on likelihood cross-validation.
#'
#' \code{\link{BOOT.spattemp}} bootstrap bandwidth selection for the spatial and temporal margins;
#' for spatiotemporal, edge-corrected KDE (Taylor, 1989).
#'
#'
#' \emph{Density and relative risk estimation}
#'
#' \code{\link{spattemp.density}} fixed-bandwidth kernel density estimate of spatiotemporal data.
#'
#' \code{\link{spattemp.risk}} fixed-bandwidth kernel density estimate of spatiotemporal relative risk, either with a time-static or time-varying control density (Fernando and Hazelton, 2014).
#'
#' \code{\link{spattemp.slice}} extraction function of the spatial density/relative risk at prespecified time(s).
#'
#'
#'
#' \emph{Visualisation}
#'
#' \code{S3} methods of the \code{plot} function; see
#' \code{\link{plot.stden}} for various options (including animation) for visualisation of a spatiotemporal density,
#' and \code{\link{plot.rrst}} for viewing spatiotemporal relative risk surfaces (including animation and tolerance contour superimposition).
#'
#'
#' \emph{Printing and summarising objects}
#'
#' \code{S3} methods (\code{\link{print.stden}}, \code{\link{print.rrst}}, \code{\link{summary.stden}}, and \code{\link{summary.rrst}}) are available for
#' the spatiotemporal density and spatiotemporal relative risk objects respectively.
#'
#'
#'
#'
#'
#' @name sparr-package
#' @aliases sparr-package sparr
#' @docType package
#' @section Dependencies: The \code{sparr} package depends upon
#' \code{\link[spatstat]{spatstat}}. In particular, the user should familiarise
#' themselves with \code{\link[spatstat.geom]{ppp}} objects and
#' \code{\link[spatstat.geom]{im}} objects, which are used throughout. For spatiotemporal density estimation, \code{sparr} is assisted by importing from the \code{misc3d} package, and for the
#' experimental capabilities involving parallel processing, \code{sparr} also
#' currently imports \code{\link[doParallel]{doParallel}},
#' \code{\link[parallel]{parallel}}, and \code{\link[foreach]{foreach}}.
#'
#' @author T.M. Davies\cr \emph{Dept. of Mathematics & Statistics, University of
#' Otago, Dunedin, New Zealand.}\cr
#' J.C. Marshall\cr
#' \emph{Institute of Fundamantal Sciences, Massey University, Palmerston North, New Zealand.}\cr
#'
#' Maintainer: T.M.D. \email{tilman.davies@@otago.ac.nz}
#'
#' @section Citation:
#' To cite use of current versions of \code{sparr} in publications or research projects please use:\cr
#'
#' Davies, T.M., Marshall, J.C. and Hazelton, M.L. (2018) Tutorial on kernel estimation of continuous spatial
#' and spatiotemporal relative risk, \emph{Statistics in Medicine}, \bold{37}(7), 1191-1221. <DOI:10.1002/sim.7577>
#'
#' Old versions of \code{sparr} (<= 2.1-09) can be referenced by Davies et al. (2011) (see reference list).
#'
#'
#' @references
#' Abramson, I. (1982), On bandwidth variation in kernel estimates
#' --- a square root law, \emph{Annals of Statistics}, \bold{10}(4),
#' 1217-1223.
#'
#' Baddeley, A. and Turner, R. (2005),
#' spatstat: an R package for analyzing spatial point patterns, \emph{Journal
#' of Statistical Software}, \bold{12}(6), 1-42.
#'
#' Baddeley, A., Rubak, E. and Turner, R. (2015) \emph{Spatial Point Patterns: Methodology and Applications with R}, Chapman and Hall/CRC Press, UK.
#'
#' Bevan A. (2012), Spatial methods for analysing large-scale artefact inventories. \emph{Antiquity}, \bold{86}, 492-506.
#'
#' Bithell, J.F. (1990), An
#' application of density estimation to geographical epidemiology,
#' \emph{Statistics in Medicine}, \bold{9}, 691-701.
#'
#' Bithell, J.F. (1991),
#' Estimation of relative risk function, \emph{Statistics in Medicine},
#' \bold{10}, 1745-1751.
#'
#' Bowman, A.W. and Azzalini, A. (1997), \emph{Applied
#' Smoothing Techniques for Data Analysis: The Kernel Approach with S-Plus
#' Illustrations.} Oxford University Press Inc., New York. ISBN
#' 0-19-852396-3.
#'
#' Campos, F.A. and Fedigan, L.M. (2014) Spatial ecology of perceived predation risk and vigilance behavior in white-faced capuchins, \emph{Behavioral Ecology}, \bold{25}, 477-486.
#'
#' Davies, T.M. (2013), Jointly optimal bandwidth selection
#' for the planar kernel-smoothed density-ratio, \emph{Spatial and
#' Spatio-temporal Epidemiology}, \bold{5}, 51-65.
#'
#' Davies, T.M. and Baddeley A. (2018), Fast computation of spatially adaptive kernel estimates,
#' \emph{Statistics and Computing}, \bold{28}(4), 937-956.
#'
#' Davies, T.M., Cornwall, J. and Sheard, P.W. (2013) Modelling dichotomously marked muscle fibre configurations, \emph{Statistics in Medicine}, \bold{32}, 4240-4258.
#'
#' Davies, T.M. and Hazelton, M.L. (2010), Adaptive kernel
#' estimation of spatial relative risk, \emph{Statistics in Medicine},
#' \bold{29}(23) 2423-2437.
#'
#' Davies, T.M., Hazelton, M.L. and Marshall, J.C.
#' (2011), \code{sparr}: Analyzing spatial relative risk using fixed and
#' adaptive kernel density estimation in \code{R}, \emph{Journal of Statistical
#' Software} \bold{39}(1), 1-14.
#'
#' Davies, T.M., Jones, K. and Hazelton, M.L.
#' (2016), Symmetric adaptive smoothing regimens for estimation of the spatial
#' relative risk function, \emph{Computational Statistics & Data Analysis},
#' \bold{101}, 12-28.
#'
#' Elson, R., Davies, T. M., Lake, I. R., Vivancos, R., Blomquist, P. B., Charlett, A. and Dabrera, G. (2021), The spatio-temporal distribution of COVID-19 infection in England between January and June 2020, \emph{Epidemiology and Infection}, \bold{149}, e73.
#'
#' Fernando, W.T.P.S. and Hazelton, M.L. (2014), Generalizing the spatial relative risk function, \emph{Spatial and Spatio-temporal Epidemiology}, \bold{8}, 1-10.
#'
#' Hazelton, M.L. (2008), Letter to the editor: Kernel
#' estimation of risk surfaces without the need for edge correction,
#' \emph{Statistics in Medicine}, \bold{27}, 2269-2272.
#'
#' Hazelton, M.L. (2023), Shrinkage estimators of the spatial relative
#' risk function, \emph{Submitted for publication}.
#'
#' Hazelton, M.L. and
#' Davies, T.M. (2009), Inference based on kernel estimates of the relative
#' risk function in geographical epidemiology, \emph{Biometrical Journal},
#' \bold{51}(1), 98-109.
#'
#' Kelsall, J.E. and Diggle, P.J. (1995a), Kernel
#' estimation of relative risk, \emph{Bernoulli}, \bold{1}, 3-16.
#'
#' Kelsall, J.E. and Diggle, P.J. (1995b), Non-parametric estimation of spatial
#' variation in relative risk, \emph{Statistics in Medicine}, \bold{14},
#' 2335-2342.
#'
#' Prince, M. I., Chetwynd, A., Diggle, P. J., Jarner, M.,
#' Metcalf, J. V. and James, O. F. W. (2001), The geographical distribution of
#' primary biliary cirrhosis in a well-defined cohort, \emph{Hepatology}
#' \bold{34}, 1083-1088.
#'
#' Sabel, C. E., Gatrell, A. C., Loytonen, M.,
#' Maasilta, P. and Jokelainen, M. (2000), Modelling exposure opportunitites:
#' estimating relative risk for motor disease in Finland, \emph{Social Science
#' & Medicine} \bold{50}, 1121-1137.
#'
#' Smith, B.A., Davies, T.M. and Higham, C.F.W. (2015) Spatial and social variables in the Bronze Age phase 4 cemetery of Ban Non Wat, Northeast Thailand, \emph{Journal of Archaeological Science: Reports}, \bold{4}, 362-370.
#'
#' Taylor, C.C. (1989) Bootstrap choice of the smoothing parameter in kernel density estimation, \emph{Biometrika}, \bold{76}, 705-712.
#'
#' Terrell, G.R. (1990), The maximal
#' smoothing principle in density estimation, \emph{Journal of the American
#' Statistical Association}, \bold{85}, 470-477.
#'
#' Venables, W. N. and Ripley,
#' B. D. (2002). \emph{Modern Applied Statistics with S}, Fourth Edition,
#' Springer, New York.
#'
#' Wand, M.P. and Jones, C.M., 1995. \emph{Kernel
#' Smoothing}, Chapman & Hall, London.
#'
#' Wheeler, D. C. (2007), A comparison
#' of spatial clustering and cluster detection techniques for childhood
#' leukemia incidence in Ohio, 1996-2003, \emph{International Journal of Health
#' Geographics}, \bold{6}(13).
#'
#' @keywords package
NULL
#' @importFrom utils setTxtProgressBar txtProgressBar packageDescription packageVersion
#' @importFrom stats IQR density dnorm fft optimise pnorm quantile rnorm sd var bw.SJ spline optim
#' @importFrom graphics axis box contour pairs par plot points title
#' @importFrom grDevices dev.hold dev.flush
#' @importFrom spatstat.utils prange tapplysum inside.range
#' @importFrom parallel detectCores
#' @importFrom doParallel registerDoParallel
#' @importFrom foreach %dopar% foreach
#' @importFrom misc3d kde3d
#' @import spatstat.geom spatstat.explore spatstat
NULL