Package ‘SpatialEpi’
August 29, 2016
Title Methods and Data for Spatial Epidemiology
Version 1.2.2
Depends R (>= 3.0.2), sp
Imports Rcpp, MASS, maptools, spdep, methods, grDevices, graphics,
stats
LinkingTo Rcpp, RcppArmadillo
Maintainer Albert Y. Kim <[email protected]>
Description Methods and data for cluster detection and disease mapping.
License GPL-2
LazyData true
NeedsCompilation yes
Author Cici Chen [ctb],
Albert Y. Kim [aut, cre],
Michelle Ross [ctb],
Jon Wakefield [aut]
Repository CRAN
Date/Publication 2016-01-29 01:02:40
R topics documented:
SpatialEpi-package
bayes_cluster . . .
besag_newell . . .
coeff . . . . . . . .
create_geo_objects
eBayes . . . . . . .
EBpostdens . . . .
EBpostthresh . . .
expected . . . . . .
GammaPriorCh . .
kulldorff . . . . . .
latlong2grid . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2
3
5
7
8
9
10
11
12
13
14
17
2
SpatialEpi-package
ldmultinom . . . . . . .
LogNormalPriorCh . . .
mapvariable . . . . . . .
normalize . . . . . . . .
NumericVectorEquality .
NYleukemia . . . . . . .
pennLC . . . . . . . . .
plotmap . . . . . . . . .
polygon2spatial_polygon
scotland . . . . . . . . .
zones . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Index
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
18
19
20
21
21
22
23
24
25
27
28
29
SpatialEpi-package
Methods and Data for Spatial Epidemiology
Description
This package contains methods for cluster detection and disease mapping, as well as plotting methods using the sp package.
Details
Package:
Type:
Version:
Date:
License:
LazyLoad:
SpatialEpi
Package
1.2.1
2014-06-03
GPL
yes
Author(s)
Cici Chen
Albert Y. Kim
Michelle E. Ross
Jon Wakefield
See Also
sp
<[email protected]>
<[email protected]>
<[email protected]>
<[email protected]>
bayes_cluster
3
Examples
data(pennLC)
data(scotland)
data(NYleukemia)
?kulldorff
?besag_newell
?bayes_cluster
bayes_cluster
Bayesian Cluster Detection Method
Description
Implementation of the Bayesian Cluster detection model of Wakefield and Kim (2013) for a study
region with n areas. The prior and posterior probabilities of each of the n.zones single zones being
a cluster/anti-cluster are estimated using Markov chain Monte Carlo. Furthermore, the posterior
probability of k clusters/anti-clusters is computed.
Usage
bayes_cluster(y, E, population, sp.obj, centroids, max.prop, shape, rate, J, pi0,
n.sim.lambda, n.sim.prior, n.sim.post, burnin.prop = 0.1,
theta.init = vector(mode="numeric", length=0))
Arguments
y
vector of length n of the observed number of disease in each area
E
vector of length n of the expected number of disease in each area
population
vector of length n of the population in each area
sp.obj
an object of class SpatialPolygons (See SpatialPolygons-class) representing the
study region
centroids
n x 2 table of the (x,y)-coordinates of the area centroids. The coordinate system
must be grid-based
max.prop
maximum proportion of the study region’s population each single zone can contain
shape
vector of length 2 of narrow/wide shape parameter for gamma prior on relative
risk
rate
vector of length 2 of narrow/wide rate parameter for gamma prior on relative
risk
J
maximum number of clusters/anti-clusters
pi0
prior probability of no clusters/anti-clusters
n.sim.lambda
number of importance sampling iterations to estimate lambda
n.sim.prior
number of MCMC iterations to estimate prior probabilities associated with each
single zone
4
bayes_cluster
n.sim.post
number of MCMC iterations to estimate posterior probabilities associated with
each single zone
burnin.prop
proportion of MCMC samples to use as burn-in
theta.init
Initial configuration used for MCMC sampling
Value
List containing
prior.map
A list containing, for each area: 1) high.area the prior probability of cluster membership, 2) low.area anti-cluster membership, and 3) RR.est.area
smoothed prior estimates of relative risk
post.map
A list containing, for each area: 1) high.area the posterior probability of cluster membership, 2) low.area anti-cluster membership, and 3) RR.est.area
smoothed posterior estimates of the relative risk
pk.y
posterior probability of k clusters/anti-clusters given y for k=0,...,J
Author(s)
Albert Y. Kim
References
Wakefield J. and Kim A.Y. (2013) A Bayesian model for cluster detection. Biostatistics, 14, 752–
765.
See Also
kulldorff
Examples
##
##
##
##
Note for the NYleukemia example, 4 census tracts were completely surrounded
by another unique census tract; when applying the Bayesian cluster detection
model in \code{\link{bayes_cluster}}, we merge them with the surrounding
census tracts yielding \code{n=277} areas.
## Load data and convert coordinate system from latitude/longitude to grid
data(NYleukemia)
sp.obj <- NYleukemia$spatial.polygon
population <- NYleukemia$data$population
cases <- NYleukemia$data$cases
centroids <- latlong2grid(NYleukemia$geo[, 2:3])
## Identify the 4 census tract to be merged into their surrounding census tracts
remove <- NYleukemia$surrounded
add <- NYleukemia$surrounding
## Merge population and case counts and geographical objects accordingly
population[add] <- population[add] + population[remove]
besag_newell
5
population <- population[-remove]
cases[add] <- cases[add] + cases[remove]
cases <- cases[-remove]
sp.obj <SpatialPolygons(sp.obj@polygons[-remove], proj4string=CRS("+proj=longlat +ellps=WGS84"))
centroids <- centroids[-remove, ]
## Set parameters
y <- cases
E <- expected(population, cases, 1)
max.prop <- 0.15
shape <- c(2976.3, 2.31)
rate <- c(2977.3, 1.31)
J <- 7
pi0 <- 0.95
n.sim.lambda <- 10^4
n.sim.prior <- 10^5
n.sim.post <- 10^5
## (Uncomment first) Compute output
#output <- bayes_cluster(y, E, population, sp.obj, centroids, max.prop,
# shape, rate, J, pi0, n.sim.lambda, n.sim.prior, n.sim.post)
#plotmap(output$prior.map$high.area, sp.obj)
#plotmap(output$post.map$high.area, sp.obj)
#plotmap(output$post.map$RR.est.area, sp.obj, log=TRUE)
#barplot(output$pk.y, names.arg=0:J, xlab="k", ylab="P(k|y)")
besag_newell
Besag-Newell Cluster Detection Method
Description
Besag-Newell cluster detection method. There are differences with the original paper and our implementation:
• we base our analysis on k cases, rather than k other cases as prescribed in the paper.
• we do not subtract 1 from the accumulated numbers of other cases and accumulated numbers
of others at risk, as was prescribed in the paper to discount selection bias
• M is the total number of areas included, not the number of additional areas included. i.e. M
starts at 1, not 0.
• p-values are not based on the original value of k, rather the actual number of cases observed
until we view k or more cases. Ex: if k = 10, but as we consider neighbors we encounter 1,
2, 9 then 12 cases, we base our p-values on k = 12
• we do not provide a Monte-Carlo simulated R: the number of tests that attain significance at
a fixed level α
The first two and last differences are because we view the testing on an area-by-area level, rather
than a case-by-case level.
6
besag_newell
Usage
besag_newell(geo, population, cases, expected.cases=NULL, k, alpha.level)
Arguments
geo
an n x 2 table of the (x,y)-coordinates of the area centroids
cases
aggregated case counts for all n areas
population
aggregated population counts for all n areas
expected.cases expected numbers of disease for all n areas
k
number of cases to consider
alpha.level
alpha-level threshold used to declare significance
Details
For the population and cases tables, the rows are bunched by areas first, and then for each area,
the counts for each strata are listed. It is important that the tables are balanced: the strata information
are in the same order for each area, and counts for each area/strata combination appear exactly once
(even if zero).
Value
List containing
clusters
information on all clusters that are α-level significant, in decreasing order of the
p-value
p.values
for each of the n areas, p-values of each cluster of size at least k
m.values
for each of the n areas, the number of areas need to observe at least k cases
observed.k.values
based on m.values, the actual number of cases used to compute the p-values
Note
The clusters list elements are themselves lists reporting:
location.IDs.included
population
number.of.cases
expected.cases
SMR
p.value
Author(s)
Albert Y. Kim
ID’s of areas in cluster, in order of distance
population of cluster
number of cases in cluster
expected number of cases in cluster
estimated SMR of cluster
p-value
coeff
7
References
Besag J. and Newell J. (1991) The Detection of Clusters in Rare Diseases Journal of the Royal
Statistical Society. Series A (Statistics in Society), 154, 143–155
See Also
pennLC, expected, besag_newell_internal
Examples
## Load Pennsylvania Lung Cancer Data
data(pennLC)
data <- pennLC$data
## Process geographical information and convert to grid
geo <- pennLC$geo[,2:3]
geo <- latlong2grid(geo)
## Get aggregated counts of population and cases for each county
population <- tapply(data$population,data$county,sum)
cases <- tapply(data$cases,data$county,sum)
## Based on the 16 strata levels, computed expected numbers of disease
n.strata <- 16
expected.cases <- expected(data$population, data$cases, n.strata)
## Set Parameters
k <- 1250
alpha.level <- 0.05
# not controlling for stratas
results <- besag_newell(geo, population, cases, expected.cases=NULL, k,
alpha.level)
# controlling for stratas
results <- besag_newell(geo, population, cases, expected.cases, k, alpha.level)
coeff
Compute log Bayes Factors
Description
Compute log Bayes Factors for each single zone based on observed and expected counts from n
areas
Usage
coeff(y_vector, E_vector, a_values, b_values, cluster_list)
8
create_geo_objects
Arguments
y_vector
Vector of length n of cases
E_vector
Vector of length n of expected cases
a_values
Vector of length 2 of shape parameters (wide, narrow)
b_values
Vector of length 2 of rate parameters
cluster_list
Output of create_geo_objects: list of length n.zones listing, for each single
zone, its component areas
Value
Vector of length n.zones with log Bayes Factor for each single zone.
Author(s)
Albert Y. Kim
References
Wakefield J. and Kim A.Y. (2013) A Bayesian model for cluster detection. Biostatistics, 14, 752–
765.
create_geo_objects
Create geographical objects to be used in Bayesian Cluster Detection
Method
Description
This internal function creates the geographical objects needed to run the Bayesian cluster detection
method in bayes_cluster. Specifically it creates all single zones based data objects, where single
zones are the zones defined by Kulldorff (1997).
Usage
create_geo_objects(max.prop, population, centroids, sp.obj)
Arguments
max.prop
maximum proportion of study region’s population each single zone can contain
population
vector of length n of the population of each area
centroids
n x 2 table of the (x,y)-coordinates of the area centroids. The coordinate system
must be grid-based
sp.obj
object of class SpatialPolygons (See SpatialPolygons-class) representing the
study region
eBayes
9
Value
overlap
list with two elements: 1. presence which lists for each area all the single
zones it is present in and 2. cluster.list for each single zone its component
areas
cluster.coords n.zones x 2 matrix of the center and radial area of each single zone
Author(s)
Albert Y. Kim
References
Wakefield J. and Kim A.Y. (2013) A Bayesian model for cluster detection. Biostatistics, 14, 752–
765.
See Also
latlong2grid, zones
Examples
data(pennLC)
max.prop <- 0.15
population <- tapply(pennLC$data$population, pennLC$data$county, sum)
centroids <- latlong2grid(pennLC$geo[, 2:3])
sp.obj <- pennLC$spatial.polygon
output <- create_geo_objects(max.prop, population, centroids, sp.obj)
## number of single zones
nrow(output$cluster.coords)
eBayes
Empirical Bayes Estimates of Relative Risk
Description
The computes empirical Bayes estimates of relative risk of study region with n areas, given observed
and expected numbers of counts of disease and covariate information.
Usage
eBayes(Y, E, Xmat = NULL)
Arguments
Y
a length n vector of observed cases
E
a length n vector of expected number of cases
Xmat
n x p dimension matrix of covariates
10
EBpostdens
Value
A list with 5 elements:
RR
the ecological relative risk posterior mean estimates
RRmed
the ecological relative risk posterior mean estimates
beta
the MLE’s of the regression coefficients
alpha
the MLE of negative binomial dispersion parameter
SMR
the standardized mortality/morbidity ratio Y/E
References
Clayton D. and Kaldor J. (1987) Empirical Bayes estimates of age-standardized relative risks for
use in disease mapping. Biometrics, 43, 671–681
See Also
scotland, mapvariable
Examples
data(scotland)
data <- scotland$data
x <- data$AFF
Xmat <- cbind(x,x^2)
results <- eBayes(data$cases,data$expected,Xmat)
scotland.map <- scotland$spatial.polygon
mapvariable(results$RR, scotland.map)
EBpostdens
Produce plots of emprical Bayes posterior densities when the data Y
are Poisson with expected number E and relative risk theta, with the
latter having a gamma distribution with known values alpha and beta,
which are estimated using empirical Bayes.
Description
This function produces plots of empirical Bayes posterior densities which are gamma distributions
with parameters (alpha+Y, (alpha+E*mu)/mu) where mu = exp(x beta). The SMRs are drawn on
for comparison.
Usage
EBpostdens(Y, E, alpha, beta, Xrow = NULL, lower = NULL, upper = NULL, main = "")
EBpostthresh
11
Arguments
Y
observed disease counts
E
expected disease counts
alpha
beta
Xrow
lower
upper
main
Value
A plot containing the gamma posterior distribution
Author(s)
Jon Wakefield
See Also
EBpostthresh, eBayes
Examples
data(scotland)
Y <- scotland$data$cases
E <- scotland$data$expected
ebresults <- eBayes(Y,E)
EBpostdens(Y[1], E[1], ebresults$alpha, ebresults$beta, lower=0, upper=15,
main="Area 1")
EBpostthresh
Produce the probabilities of exceeding a threshold given a posterior
gamma distribution.
Description
This function produces the posterior probabilities of exceeding a threshold given a gamma distributions with parameters (alpha+Y, (alpha+E*mu)/mu) where mu = exp(x beta). This model arises
from Y being Poisson with mean theta times E where theta is the relative risk and E are the expected
numbers. The prior on theta is gamma with parameters alpha and beta. The parameters alpha and
beta may be estimated using empirical Bayes.
Usage
EBpostthresh(Y, E, alpha, beta, Xrow = NULL, rrthresh)
12
expected
Arguments
Y
observed disease counts
E
expected disease counts
alpha
beta
Xrow
rrthresh
Value
Posterior probabilities of exceedence are returned.
Author(s)
Jon Wakefield
See Also
eBayes
Examples
data(scotland)
Y <- scotland$data$cases
E <- scotland$data$expected
ebresults <- eBayes(Y,E)
# Find probabilities of exceedence of 3
thresh3 <- EBpostthresh(Y, E, alpha=ebresults$alpha, beta=ebresults$beta,
rrthresh=3)
mapvariable(thresh3, scotland$spatial.polygon)
expected
Compute Expected Numbers of Disease
Description
Compute the internally indirect standardized expected numbers of disease.
Usage
expected(population, cases, n.strata)
Arguments
population
a vector of population counts for each strata in each area
cases
a vector of the corresponding number of cases
n.strata
number of strata considered
GammaPriorCh
13
Details
The population and cases vectors must be balanced: all counts are sorted by area first, and then
within each area the counts for all strata are listed (even if 0 count) in the same order.
Value
expected.cases a vector of the expected numbers of disease for each area
Author(s)
Albert Y. Kim
References
Elliot, P. et al. (2000) Spatial Epidemiology: Methods and Applications. Oxford Medical Publications.
Examples
data(pennLC)
population <- pennLC$data$population
cases <- pennLC$data$cases
## In each county in Pennsylvania, there are 2 races, gender and 4 age bands
## considered = 16 strata levels
pennLC$data[1:16,]
expected(population, cases, 16)
GammaPriorCh
Compute Parameters to Calibrate a Gamma Distribution
Description
Compute parameters to calibrate the prior distribution of a relative risk that has a gamma distribution.
Usage
GammaPriorCh(theta, prob, d)
Arguments
theta
upper quantile
prob
upper quantile
d
degrees of freedom
14
kulldorff
Value
A list containing
a
b
shape parameter
rate parameter
Author(s)
Jon Wakefield
See Also
LogNormalPriorCh
Examples
param <- GammaPriorCh(5, 0.975,1)
curve(dgamma(x,shape=param$a,rate=param$b),from=0,to=6,n=1000,ylab="density")
kulldorff
Kulldorff Cluster Detection Method
Description
Kulldorff spatial cluster detection method for a study region with n areas. The method constructs
zones by consecutively aggregating nearest-neighboring areas until a proportion of the total study
population is included. Given the observed number of cases, the likelihood of each zone is computed
using either binomial or poisson likelihoods. The procedure reports the zone that is the most likely
cluster and generates significance measures via Monte Carlo sampling. Further, secondary clusters,
whose Monte Carlo p-values are below the α-threshold, are reported as well.
Usage
kulldorff(geo, cases, population, expected.cases=NULL, pop.upper.bound,
n.simulations, alpha.level, plot=TRUE)
Arguments
geo
an n x 2 table of the (x,y)-coordinates of the area centroids
cases
aggregated case counts for all n areas
population
aggregated population counts for all n areas
expected.cases expected numbers of disease for all n areas
pop.upper.bound
the upper bound on the proportion of the total population each zone can include
n.simulations number of Monte Carlo samples used for significance measures
alpha.level
alpha-level threshold used to declare significance
plot
flag for whether to plot histogram of Monte Carlo samples of the log-likelihood
of the most likely cluster
kulldorff
15
Details
If expected.cases is specified to be NULL, then the binomial likelihood is used. Otherwise, a
Poisson model is assumed. Typical values of n.simulations are 99, 999, 9999...
Value
List containing:
most.likely.cluster
information on the most likely cluster
secondary.clusters
information on secondary clusters, if none NULL is returned
type
type of likelihood
log.lkhd
log-likelihood of each zone considered
simulated.log.lkhd
n.simulations Monte Carlo samples of the log-likelihood of the most likely
cluster
Note
The most.likely.cluster and secondary.clusters list elements are themselves lists reporting:
location.IDs.included
population
number.of.cases
expected.cases
SMR
log.likelihood.ratio
monte.carlo.rank
p.value
ID’s of areas in cluster, in order of distance
population of cluster
number of cases in cluster
expected number of cases in cluster
estimated SMR of cluster
log-likelihood of cluster
rank of lkhd of cluster within Monte Carlo simulated values
Monte Carlo p-value
Author(s)
Albert Y. Kim
References
SatScan: Software for the spatial, temporal, and space-time scan statistics http://www.satscan.
org/ Kulldorff, M. (1997) A spatial scan statistic. Communications in Statistics: Theory and Methods, 26, 1481–1496.
Kulldorff M. and Nagarwalla N. (1995) Spatial disease clusters: Detection and Inference. Statistics
in Medicine, 14, 799–810.
16
kulldorff
See Also
pennLC, expected
Examples
## Load Pennsylvania Lung Cancer Data
data(pennLC)
data <- pennLC$data
## Process geographical information and convert to grid
geo <- pennLC$geo[,2:3]
geo <- latlong2grid(geo)
## Get aggregated counts of population and cases for each county
population <- tapply(data$population,data$county,sum)
cases <- tapply(data$cases,data$county,sum)
## Based on the 16 strata levels, computed expected numbers of disease
n.strata <- 16
expected.cases <- expected(data$population, data$cases, n.strata)
## Set Parameters
pop.upper.bound <- 0.5
n.simulations <- 999
alpha.level <- 0.05
plot <- TRUE
## Kulldorff using Binomial likelihoods
binomial <- kulldorff(geo, cases, population, NULL, pop.upper.bound, n.simulations,
alpha.level, plot)
cluster <- binomial$most.likely.cluster$location.IDs.included
## plot
plot(pennLC$spatial.polygon,axes=TRUE)
plot(pennLC$spatial.polygon[cluster],add=TRUE,col="red")
title("Most Likely Cluster")
## Kulldorff using Poisson likelihoods
poisson <- kulldorff(geo, cases, population, expected.cases, pop.upper.bound,
n.simulations, alpha.level, plot)
cluster <- poisson$most.likely.cluster$location.IDs.included
## plot
plot(pennLC$spatial.polygon,axes=TRUE)
plot(pennLC$spatial.polygon[cluster],add=TRUE,col="red")
title("Most Likely Cluster Controlling for Strata")
latlong2grid
17
latlong2grid
Convert Coordinates from Latitude/Longitude to Grid
Description
Convert geographic latitude/longitude coordinates to kilometer-based grid coordinates.
Usage
latlong2grid(input)
Arguments
input
either an n x 2 matrix of longitude and latitude coordinates in decimal format
or an object of class SpatialPolygons (See SpatialPolygons-class)
Details
Longitude/latitudes are not a grid-based coordinate system: latitudes are equidistant but the distance
between longitudes varies.
Value
Either a data frame with the corresponding (x,y) kilometer-based grid coordinates, or a SpatialPolygons object with the coordinates changed.
Note
Rough conversion of US lat/long to km (used by GeoBUGS): (see also forum.swarthmore.edu/dr.math/problems/longandlat.ht
Radius of earth: r = 3963.34 (equatorial) or 3949.99 (polar) mi = 6378.2 or 6356.7 km, which implies: km per mile = 1.609299 or 1.609295 a change of 1 degree of latitude corresponds to the same
number of km, regardless of longitude. arclength=r*theta, so the multiplier for coord\$y should
probably be just the radius of earth. On the other hand, a change of 1 degree in longitude corresponds to a different distance, depending on latitude. (at N pole, the change is essentially 0. at the
equator, use equatorial radius.
Author(s)
Lance A. Waller
Examples
## Convert coordinates
coord <- data.frame(rbind(
# Montreal, QC: Latitude: 45deg 28' 0" N (deg min sec), Longitude: 73deg 45' 0" W
c(-73.7500, 45.4667),
# Vancouver, BC: Latitude: 45deg 39' 38" N (deg min sec), Longitude: 122deg 36' 15" W
c(-122.6042, 45.6605)
))
18
ldmultinom
latlong2grid(coord)
## Convert SpatialPolygon
data(pennLC)
new <- latlong2grid(pennLC$spatial.polygon)
par(mfrow=c(1,2))
plot(pennLC$spatial.polygon,axes=TRUE)
title("Lat/Long")
plot(new,axes=TRUE)
title("Grid (in km)")
ldmultinom
log multinomial Density
Description
Compute log of density of multinomial
Usage
ldmultinom(x, prob)
Arguments
x
vector of multinomial counts
prob
vector of bin probabilities
Value
log of density of multinomial
Author(s)
Albert Y. Kim
Examples
p <- rep(0.2, 5)
x <- rmultinom(1, 10, p)
dmultinom(x, prob=p, log=TRUE)
ldmultinom(x, p)
LogNormalPriorCh
LogNormalPriorCh
19
Compute Parameters to Calibrate a Log-normal Distribution
Description
Compute parameters to calibrate the prior distribution of a relative risk that has a log-normal distribution.
Usage
LogNormalPriorCh(theta1, theta2, prob1, prob2)
Arguments
theta1
lower quantile
theta2
upper quantile
prob1
lower probability
prob2
upper probability
Value
A list containing:
mu
mean of log-normal distribution
sigma
variance of log-normal distribution
Author(s)
Jon Wakefield
See Also
GammaPriorCh
Examples
# Calibrate the log-normal distribution s.t. the 95% confidence interval is [0.2, 5]
param <- LogNormalPriorCh(0.2, 5, 0.025, 0.975)
curve(dlnorm(x,param$mu,param$sigma), from=0, to=6, ylab="density")
20
mapvariable
mapvariable
Plot Levels of a Variable in a Colour-Coded Map
Description
Plot levels of a variable in a colour-coded map along with a legend.
Usage
mapvariable(y, spatial.polygon, ncut=1000, nlevels=10, lower=NULL, upper=NULL,
main=NULL, xlab=NULL, ylab=NULL)
Arguments
y
variable to plot
spatial.polygon
an object of class SpatialPolygons (See SpatialPolygons-class)
ncut
number of cuts in colour levels to plot
nlevels
number of levels to include in legend
lower
lower bound of levels
upper
upper bound of levels
main
an overall title for the plot
xlab
a title for the x axis
ylab
a title for the y axis
Value
A map colour-coded to indicate the different levels of y
Author(s)
Jon Wakefield, Nicky Best, Sebastien Haneuse, and Albert Y. Kim
References
Bivand, R. S., Pebesma E. J., and Gomez-Rubio V. (2008) Applied Spatial Data Analysis with R.
Springer Series in Statistics.
E. J. Pebesma and R. S. Bivand. (2005) Classes and methods for spatial data in R. R News, 5, 9–13.
Examples
data(scotland)
map <- scotland$spatial.polygon
y <- scotland$data$cases
E <- scotland$data$expected
SMR <- y/E
mapvariable(SMR,map,main="Scotland",xlab="Eastings (km)",ylab="Northings (km)")
normalize
normalize
21
Normalize vector to sum to 1.
Description
Divide each element in the vector by the sum of the vector elements.
Usage
normalize(x)
Arguments
x
Vector to be normalized
Value
Normalized vector
Author(s)
Albert Y. Kim
Examples
x <- rep(1, 10)
x <- normalize(x)
x
NumericVectorEquality Test if two numeric vectors are equal
Description
Test if two numeric vectors are equal in their length and their elements
Usage
NumericVectorEquality(x, y)
Arguments
x
NumericVector
y
NumericVector
22
NYleukemia
Value
1 if equal, 0 if not.
Author(s)
Albert Y. Kim
Examples
x <- c(1:10)
y <- rev(c(10:1))
NumericVectorEquality(x,y)
NYleukemia
Upstate New York Leukemia Data
Description
Census tract level (n=281) leukemia data for the 8 counties in upstate New York from 1978-1982,
paired with population data from the 1980 census. Note that 4 census tracts were completely surrounded by another unique census tract; when applying the Bayesian cluster detection model in
bayes_cluster, we merge them with the surrounding census tracts yielding n=277 areas.
Usage
data(NYleukemia)
Format
List with 5 items:
geo
data
spatial.polygon
surrounded
surrounding
table of the FIPS code, longitude, and latitude of the geographic centroid of each census tract
table of the FIPS code, number of cases, and population of each census tract
object of class SpatialPolygons (See SpatialPolygons-class) containing a map of the study region
row IDs of the 4 census tracts that are completely surrounded by the surrounding census tracts
row IDs of the 4 census tracts that completely surround the surrounded census tracts
Source
http://www.sph.emory.edu/~lwaller/ch4index.htm
References
Turnbull, B. W. et al (1990) Monitoring for clusters of disease: application to leukemia incidence
in upstate New York American Journal of Epidemiology, 132, 136–143
pennLC
23
See Also
scotland, pennLC
Examples
## Load data and convert coordinate system from latitude/longitude to grid
data(NYleukemia)
map <- NYleukemia$spatial.polygon
population <- NYleukemia$data$population
cases <- NYleukemia$data$cases
centroids <- latlong2grid(NYleukemia$geo[, 2:3])
## Identify the 4 census tract to be merged into their surrounding census tracts.
remove <- NYleukemia$surrounded
add <- NYleukemia$surrounding
## Merge population and case counts
population[add] <- population[add] + population[remove]
population <- population[-remove]
cases[add] <- cases[add] + cases[remove]
cases <- cases[-remove]
## Modify geographical objects accordingly
map <- SpatialPolygons(map@polygons[-remove], proj4string=CRS("+proj=longlat +ellps=WGS84"))
centroids <- centroids[-remove, ]
## Plot incidence in latitude/longitude
plotmap(cases/population, map, log=TRUE, nclr=5)
points(grid2latlong(centroids), pch=4)
pennLC
Pennsylvania Lung Cancer
Description
County-level (n=67) population/case data for lung cancer in Pennsylvania in 2002, stratified on
race (white vs non-white), gender and age (Under 40, 40-59, 60-69 and 70+). Additionally, countyspecific smoking rates.
Usage
data(pennLC)
Format
List of 3 items:
geo
data
a table of county IDs, longitude/latitude of the geographic centroid of each county
a table of county IDs, number of cases, population and strata information
24
plotmap
smoking
spatial.polygon
a table of county IDs and proportion of smokers
an object of class SpatialPolygons (See SpatialPolygons-class)
Source
Population data was obtained from the 2000 decennial census, lung cancer and smoking data were
obtained from the Pennsylvania Department of Health website: http://www.dsf.health.state.
pa.us/
See Also
scotland, NYleukemia
Examples
data(pennLC)
pennLC$geo
pennLC$data
pennLC$smoking
# Map smoking rates in Pennsylvania
mapvariable(pennLC$smoking[,2], pennLC$spatial.polygon)
plotmap
Plot Levels of a Variable in a Colour-Coded Map
Description
Plot levels of a variable in a colour-coded map.
Usage
plotmap(values, map, log = FALSE, nclr = 7, include.legend = TRUE, lwd = 0.5,
round = 3, brks = NULL, legend = NULL, location = "topright", rev = FALSE)
Arguments
values
variable to plot
map
an object of class SpatialPolygons (See SpatialPolygons-class)
log
boolean of whether to plot values on log scale
nclr
number of colour-levels to use
include.legend boolean of whether to include legend
lwd
line width of borders of areas
round
number of digits to round to in legend
brks
if desired, pre-specified breaks for legend
polygon2spatial_polygon
legend
location
rev
25
if desired, a pre-specified legend
location of legend
boolean of whether to reverse colour scheme (darker colours for smaller values)
Value
A map colour-coded to indicate the different levels of values.
Author(s)
Albert Y. Kim
See Also
mapvariable
Examples
## Load data
data(scotland)
map <- scotland$spatial.polygon
y <- scotland$data$cases
E <- scotland$data$expected
SMR <- y/E
## Plot SMR
plotmap(SMR, map, nclr=9, location="topleft")
polygon2spatial_polygon
Convert a Polygon to a Spatial Polygons Object
Description
Converts a polygon (a matrix of coordinates with NA values to separate subpolygons) into a Spatial
Polygons object.
Usage
polygon2spatial_polygon(poly, coordinate.system, area.names = NULL, nrepeats = NULL)
Arguments
poly
a 2-column matrix of coordinates, where each complete subpolygon is separated
by NA’s
coordinate.system
the coordinate system to use
area.names
names of all areas
nrepeats
number of subpolygons for each area
26
polygon2spatial_polygon
Details
Just as when plotting with the polygon function, it is assumed that each subpolygon is to be closed
by joining the last point to the first point. In the matrix poly, NA values separate complete subpolygons.
coordinate.system must be either '+proj=utm' or '+proj=longlat'.
In the case with an area consists of more than one separate closed polygon, nrepeats specifies the
number of closed polygons associated with each area.
Value
An object of class SpatialPolygons (See SpatialPolygons-class from the sp package).
Author(s)
Albert Y. Kim
References
Bivand, R. S., Pebesma E. J., and Gomez-Rubio V. (2008) Applied Spatial Data Analysis with R.
Springer Series in Statistics.
E. J. Pebesma and R. S. Bivand. (2005) Classes and methods for spatial data in R. R News, 5, 9–13.
Examples
data(scotland)
polygon <- scotland$polygon$polygon
coord.system <- '+proj=utm'
names <- scotland$data$county.names
nrepeats <- scotland$polygon$nrepeats
spatial.polygon <- polygon2spatial_polygon(polygon,coord.system,names,nrepeats)
par(mfrow=c(1,2))
# plot using polygon function
plot(polygon,type='n',xlab="Eastings (km)",ylab="Northings (km)",main="Polygon File")
polygon(polygon)
# plot as spatial polygon object
plot(spatial.polygon,axes=TRUE)
title(xlab="Eastings (km)",ylab="Northings (km)",main="Spatial Polygon")
# Note that area 23 (argyll-bute) consists of 8 separate polygons
nrepeats[23]
plot(spatial.polygon[23],add=TRUE,col="red")
scotland
scotland
27
Lip Cancer in Scotland
Description
County-level (n=56) data for lip cancer among males in Scotland between 1975-1980
Usage
data(scotland)
Format
List containing:
geo
data
spatial.polygon
polygon
a table of county IDs, x-coordinates (eastings) and y-coordinates (northings) of the geographic centroid o
a table of county IDs, number of cases, population and strata information
a Spatial Polygons class (See SpatialPolygons-class) map of Scotland
a polygon map of Scotland (See polygon2spatial_polygon)
Source
Kemp I., Boyle P., Smans M. and Muir C. (1985) Atlas of cancer in Scotland, 1975-1980, incidence
and epidemiologic perspective International Agency for Research on Cancer 72.
References
Clayton D. and Kaldor J. (1987) Empirical Bayes estimates of age-standardized relative risks for
use in disease mapping. Biometrics, 43, 671–681
See Also
mapvariable, polygon2spatial_polygon, pennLC, NYleukemia
Examples
data(scotland)
data <- scotland$data
scotland.map <- scotland$spatial.polygon
SMR <- data$cases/data$expected
mapvariable(SMR,scotland.map)
28
zones
zones
Create set of all single zones and output geographical information
Description
Based on the population counts and centroid coordinates of each of n areas, output the set of
n.zones single zones as defined by Kulldorff and other geographical information.
Usage
zones(geo, population, pop.upper.bound)
Arguments
geo
n x 2 table of the (x,y)-coordinates of the area centroids
population
a vector of population counts of each area
pop.upper.bound
maximum proportion of study region each zone can contain
Value
A list containing
nearest.neighbors
list of n elements, where each element is a vector of the nearest neighbors in
order of distance up until pop.upper.bound of the total population is attained
cluster.coords n.zones x 2 table of the center and the radial area for each zone
dist
n x n inter-point distance matrix of the centroids
Author(s)
Albert Y. Kim
References
Kulldorff, M. (1997) A spatial scan statistic. Communications in Statistics: Theory and Methods,
26, 1481–1496.
Kulldorff M. and Nagarwalla N. (1995) Spatial disease clusters: Detection and Inference. Statistics
in Medicine, 14, 799–810.
Examples
data(pennLC)
geo <- pennLC$geo[,2:3]
geo <- latlong2grid(geo)
population <- tapply(pennLC$data$population, pennLC$data$county, sum)
pop.upper.bound <- 0.5
geo.info <- zones(geo, population, pop.upper.bound)
Index
kulldorff, 4, 14
∗Topic datasets
NYleukemia, 22
pennLC, 23
scotland, 27
∗Topic file
bayes_cluster, 3
besag_newell, 5
create_geo_objects, 8
eBayes, 9
EBpostdens, 10
EBpostthresh, 11
expected, 12
GammaPriorCh, 13
kulldorff, 14
latlong2grid, 17
ldmultinom, 18
LogNormalPriorCh, 19
mapvariable, 20
normalize, 21
NumericVectorEquality, 21
plotmap, 24
polygon2spatial_polygon, 25
zones, 28
∗Topic interal
coeff, 7
∗Topic package
SpatialEpi-package, 2
latlong2grid, 9, 17
ldmultinom, 18
LogNormalPriorCh, 14, 19
mapvariable, 10, 20, 25, 27
normalize, 21
NumericVectorEquality, 21
NYleukemia, 22, 24, 27
pennLC, 7, 16, 23, 23, 27
plotmap, 24
polygon, 26
polygon2spatial_polygon, 25, 27
scotland, 10, 23, 24, 27
sp, 2
SpatialEpi (SpatialEpi-package), 2
SpatialEpi-package, 2
SpatialPolygons-class, 3, 8, 17, 20, 22, 24,
26, 27
zones, 9, 28
bayes_cluster, 3, 8, 22
besag_newell, 5
besag_newell_internal, 7
coeff, 7
create_geo_objects, 8, 8
eBayes, 9, 11, 12
EBpostdens, 10
EBpostthresh, 11, 11
expected, 7, 12, 16
GammaPriorCh, 13, 19
29