smacpod: logrr – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

logrr

Log ratio of spatial densities

Description

logrr computes the log ratio of spatial density functions for cases and controls. The numerator in this ratio is related to the "cases" and the denominator to the "controls". If nsim > 0, then pointwise non-rejection envelopes are used to assess potential clustering of cases and controls relative to each other.

Usage

logrr(
  x,
  sigma = NULL,
  sigmacon = NULL,
  case = 2,
  nsim = 0,
  level = 0.9,
  alternative = "two.sided",
  ...,
  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
)

Arguments

`x`	Point pattern (object of class `"ppp"`).
`sigma`	Standard deviation of isotropic smoothing kernel for cases. Either a numerical value, or a function that computes an appropriate value of `sigma`.
`sigmacon`	Standard deviation of isotropic smoothing kernel for controls. Default is the same as `sigma`.
`case`	The position of the name of the "case" group in `levels(x$marks)`. The default is 2. `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 the non-rejection envelopes under the random labeling hypothesis. Default is 0 (i.e., no envelopes).
`level`	The level used for the pointwise non-rejection envelopes.
`alternative`	The direction of the significance test to identify potential clusters using a Monte Carlo test based on the pointwise non-rejection envelopes. Default is `"two.sided"` (logrr != 0). The values `"less"` (logrr < 0) and `"greater"` (logrr > 0) are also valid.
`...`	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.

Details

The plot function makes it easy to visualize the log ratio of spatial densities (if nsim = 0) or the regions where the log ratio deviates farther from than what is expected under the random labeling hypothesis (i.e., the locations of potential clustering). The shaded regions indicate the locations of potential clustering.

The two.sided alternative test assesses whether the observed ratio of log densities deviates more than what is expected under the random labeling hypothesis. When the test is significant, this suggests that the cases and controls are clustered, relative to the other. The greater alternative assesses whehter the cases are more clustered than the controls. The less alternative assesses whether the controls are more clustered than the 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 function from the spatstat.core package, 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.

Examples

data(grave)
r = logrr(grave)
plot(r)
r2 = logrr(grave, sigma = spatstat.core::bw.scott)
plot(r2)
rsim = logrr(grave, nsim = 9)
plot(rsim)

smacpod

Statistical Methods for the Analysis of Case-Control Point Data

v2.1.1

GPL (>= 2)

Authors

Joshua French [aut, cre] (<https://orcid.org/0000-0002-9708-3353>)

Initial release