logrr {smacpod}

Log ratio of spatial densities

Description

logrr computes the estimated log relative risk of cases relative to controls. The log relative risk at location s is defined as r(s) = ln(f(s)/g(s)). The numerator, f(s), is the spatial density of the case group. The denominator, g(s), is the spatial density of the control group. If nsim > 0, then pointwise (at each pixel) tolerance envelopes are estimated under the random labeling hypothesis. The tolerance envelopes can be used to assess pixels where the log relative risk differs significantly from zero. See Details.

Usage

logrr(
  x,
  sigma = NULL,
  sigmacon = NULL,
  case = 2,
  nsim = 0,
  level = 0.9,
  alternative = "two.sided",
  envelope = "pixelwise",
  ...,
  bwargs = list(),
  weights = NULL,
  edge = TRUE,
  varcov = NULL,
  at = "pixels",
  leaveoneout = TRUE,
  adjust = 1,
  diggle = FALSE,
  kernel = "gaussian",
  scalekernel = is.character(kernel),
  positive = FALSE,
  verbose = TRUE,
  return_sims = FALSE
)

Arguments

x

A ppp object package with marks for the case and control groups. x$marks is assumed to be a factor. Automatic conversion is attempted if it is not.

sigma

Standard deviation of isotropic smoothing kernel for cases. Either a numerical value, or a function that computes an appropriate value of sigma. If not specified, then bw.relrisk is used.

sigmacon

Standard deviation of isotropic smoothing kernel for controls. Default is the same as sigma.

case

The name of the desired "case" group in levels(x$marks). Alternatively, the position of the name of the "case" group in levels(x$marks). Since we don't know the group names, the default is 2, the second position of levels(x$marks). x$marks is assumed to be a factor. Automatic conversion is attempted if it is not.

nsim

The number of simulated data sets from which to construct tolerance envelopes under the random labeling hypothesis. The default is 0 (i.e., no envelopes).

level

The level of the tolerance envelopes.

alternative

The type of envelopes to construct. The default is "two.sided" (upper and lower envelopes). The values "less" (lower envelope) and "greater" (upper envelope) are also valid.

envelope

The type of envelope to construct. The default is "pixelwise". The other option is "simulataneous", which controls the tolerance level across the entire study area.

...

Additional arguments passed to pixellate.ppp and as.mask to determine the pixel resolution, or passed to sigma if it is a function.

bwargs

A list of arguments for the bandwidth function supplied to sigma and sigmacon, if applicable.

weights

Optional weights to be attached to the points. A numeric vector, numeric matrix, an expression, or a pixel image.

edge

Logical value indicating whether to apply edge correction.

varcov

Variance-covariance matrix of anisotropic smoothing kernel. Incompatible with sigma.

at

String specifying whether to compute the intensity values at a grid of pixel locations (at="pixels") or only at the points of x (at="points").

leaveoneout

Logical value indicating whether to compute a leave-one-out estimator. Applicable only when at="points".

adjust

Optional. Adjustment factor for the smoothing parameter.

diggle

Logical. If TRUE, use the Jones-Diggle improved edge correction, which is more accurate but slower to compute than the default correction.

kernel

The smoothing kernel. A character string specifying the smoothing kernel (current options are "gaussian", "epanechnikov", "quartic" or "disc"), or a pixel image (object of class "im") containing values of the kernel, or a function(x,y) which yields values of the kernel.

scalekernel

Logical value. If scalekernel=TRUE, then the kernel will be rescaled to the bandwidth determined by sigma and varcov: this is the default behaviour when kernel is a character string. If scalekernel=FALSE, then sigma and varcov will be ignored: this is the default behaviour when kernel is a function or a pixel image.

positive

Logical value indicating whether to force all density values to be positive numbers. Default is FALSE.

verbose

Logical value indicating whether to issue warnings about numerical problems and conditions.

return_sims

A logical value indicating whether parts of the simulated data shoudl be returned. The default is FALSE. This is mostly used for debugging purposes.

Details

If nsim=0, the plot function creates a heat map of the log relative risk. If nsim > 0, the plot function colors the pixels where the estimated log relative risk is outside the tolerance envelopes created under the random labeling hypothesis (i.e., pixels with potential clustering of cases or controls). Colored regions with values above 0 indicate a cluster of cases relative to controls (without controlling for multiple comparisons), i.e., a region where the the density of the cases is greater than the the density of the controls. Colored regions with values below 0 indicate a cluster of controls relative to cases (without controlling for multiple comparisons), i.e., a region where the density of the controls is greater than the density of the cases.

The two.sided alternative test constructs two-sided tolerance envelopes to assess whether the estimated r(s) deviates more than what is expected under the random labeling hypothesis. The greater alternative constructs an upper tolerance envelope to assess whether the estimated r(s) is greater than what is expected under the random labeling hypothesis, i.e., where there is clustering of cases relative to controls. The lower alternative constructs a lower tolerance envelope to assess whether the estimated r(s) is lower than what is expected under the random labeling hypothesis, i.e., where there is clustering of controls relative to cases.

If the estimated density of the case or control group becomes too small, this function may produce warnings due to numerical underflow. Increasing the bandwidth (sigma) may help.

Value

The function produces an object of type logrrenv. Its components are similar to those returned by the density.ppp, with the intensity values replaced by the log ratio of spatial densities of f and g. Includes an array simr of dimension c(nx, ny, nsim + 1), where nx and ny are the number of x and y grid points used to estimate the spatial density. simr[,,1] is the log ratio of spatial densities for the observed data, and the remaining nsim elements in the third dimension of the array are the log ratios of spatial densities from a new ppp simulated under the random labeling hypothesis.

Author(s)

Joshua French (and a small chunk by the authors of the density.ppp) function for consistency with the default behavior of that function).

References

Waller, L.A. and Gotway, C.A. (2005). Applied Spatial Statistics for Public Health Data. Hoboken, NJ: Wiley.

Kelsall, Julia E., and Peter J. Diggle. "Kernel estimation of relative risk." Bernoulli (1995): 3-16.

Kelsall, Julia E., and Peter J. Diggle. "Non-parametric estimation of spatial variation in relative risk." Statistics in Medicine 14.21-22 (1995): 2335-2342.

Hegg, Alex and French, Joshua P. (2022) "Simultaneous tolerance bands of log relative risk for case-control point data. Technical report.

Examples

data(grave)
# estimate and plot log relative risk
r = logrr(grave, case = "affected")
plot(r)
# use scott's bandwidth
r2 = logrr(grave, case = 2, sigma = spatstat.explore::bw.scott)
plot(r2)
# construct pointwise tolerance envelopes for log relative risk
## Not run: 
renv = logrr(grave, nsim = 9)
print(renv) # print information about envelopes
plot(renv) # plot results
# plot using a better gradient
grad = gradient.color.scale(min(renv$v, na.rm = TRUE), max(renv$v, na.rm = TRUE))
plot(renv, col = grad$col, breaks = grad$breaks, conlist = list(col = "lightgrey"))
## End(Not run)