Kernel density estimation for prevR object.

This function allows to calculate a prevalence surface (ratio of two intensity surfaces) and/or a relative risks surface (ratio of two density surfaces) using gaussian kernel estimators with adaptative bandwidths of equal number of observations or equal radius.

Usage

# S4 method for class 'prevR'
kde(
  object,
  N = NULL,
  R = NULL,
  weighted = TRUE,
  risk.ratio = FALSE,
  keep.details = FALSE,
  nb.cells = 100,
  cell.size = NULL,
  progression = TRUE,
  short.names = FALSE
)

Arguments

object: object of class prevR.
N: integer or list of integers corresponding to the rings to use.
R: integer or list of integers corresponding to the rings to use.
weighted: use weighted data (TRUE, FALSE or 2)?
risk.ratio: calculate a relative risks surface instead of a prevalence surface (TRUE, FALSE or 2)?
keep.details: return surface of positive cases and surface of observed cases?
nb.cells: number of cells on the longest side of the studied area (unused if cell.size is defined).
cell.size: size of each cell (in the unit of the projection).
progression: show a progress bar?
short.names: should names of the output be short?

Value

Object of class sf::sf. Surfaces are named according to the name of the corresponding N and R (for example: k.prev.N300.RInf). If short.names is TRUE and if there is only one combination of couples (N, R), variable names will not be suffixed by the value of N and R.

Estimated variables are (depending on the function parameters) :

"k.pos" unweighted intensity surface of positive cases.
"k.obs" unweighted intensity surface of observed cases.
"k.prev" unweighted surface of prevalence (k.pos/k.obs).
"k.case" unweighted density surface of positive cases.
"k.control" unweighted density surface of observed cases.
"k.rr" unweighted surface of relative risks (k.case/k.control).
"k.wpos" weighted intensity surface of positive cases.
"k.wobs" weighted intensity surface of observed cases.
"k.wprev" weighted surface of prevalence (k.wpos/k.wobs).
"k.wcase" weighted density surface of positive cases.
"k.wcontrol" weighted density surface of observed cases.
"k.wrr" weighted surface of relative risks (k.wcase/k.wcontrol).

Details

This function calculates a prevalence surface as the ratio of the intensity surface (expressed in cases per surface unit) of positive cases on the intensity surface of observed cases and could also calculate a relative risks surface corresponding to the ratio of the density surface (whose integral has been normalized to one) of positive cases on density surface of observed cases.

This method is a variant of the nearest neighbor technique. Surfaces are estimated using gaussian kernel estimators with adaptative bandwidths, bandwidth size being determined by a minimum number of observations in the neighborhood (see rings() for more details). Fixed bandwidths could also be used. More precisely, the bandwidth used is half the radius of rings of equal number of observations or equal radius (parameters N and R) calculated by the' function rings().

See references for a detailed explanation of the implemented methodology.

N and R determine the rings to use for the estimation. If they are not defined, surfaces will be estimated for each available couples (N,R) available in object. Several estimations could be simultaneously calculated if several values of N and R are defined.

A suggested value of N could be computed with Noptim().

Note

Results could be plotted with sf::plot() or with ggplot2 using ggplot2::geom_sf(). See examples.

prevR provides several continuous color palettes (see prevR.colors).

Results could be turned into a stars raster using stars::st_rasterize().

To export to ASCII grid, rasterize the results with stars::st_rasterize(), convert to SpatRast with terra::rast(), extract the desired layer with [[]] and then use terra::writeRaster(). See examples.

See the package sparr for another methodology to estimate relative risks surfaces, adapted for other kind of data than Demographic and Health Surveys (DHS).

References

Larmarange Joseph, Vallo Roselyne, Yaro Seydou, Msellati Philippe and Meda Nicolas (2011) "Methods for mapping regional trends of HIV prevalence from Demographic and Health Surveys (DHS)", Cybergeo: European Journal of Geography, no 558, https://journals.openedition.org/cybergeo/24606, DOI: 10.4000/cybergeo.24606.

Examples

if (FALSE) { # \dontrun{
dhs <- rings(fdhs, N = c(100, 200, 300, 400, 500))

prev.N300 <- kde(dhs, N = 300, nb.cells = 200)

plot(prev.N300, lty = 0)

library(ggplot2)
ggplot(prev.N300) +
  aes(fill = k.wprev.N300.RInf) +
  geom_sf(colour = "transparent") +
  scale_fill_gradientn(colors = prevR.colors.red()) +
  theme_prevR_light()

# Export k.wprev.N300.RInf surface in ASCII Grid
r <- terra::rast(stars::st_rasterize(prev.N300))
# writeRaster(r[[2]], "kprev.N300.asc")
} # }