jitter_power: Power of SRR function for previously collected data.

In sparrpowR: Power Analysis to Detect Spatial Relative Risk Clusters

Power of SRR function for previously collected data.

Description

Compute the statistical power of a spatial relative risk function using previously collected data.

Usage

jitter_power(
  obs_data,
  sim_total = 2,
  samp_control = c("uniform", "CSR", "MVN"),
  s_control = 1,
  alpha = 0.05,
  p_correct = "none",
  parallel = FALSE,
  n_core = 2,
  verbose = TRUE,
  ...,
  cascon = lifecycle::deprecated(),
  lower_tail = lifecycle::deprecated(),
  upper_tail = lifecycle::deprecated()
)

Arguments

obs_data	A bivariate point pattern (a multitype point pattern of object of class "ppp") with two types of points in a factor valued mark.
sim_total	Integer, specifying the number of simulation iterations to perform.
samp_control	Character string specifying whether to randomize the control locations uniformly (samp_control="uniform"), with complete spatial randomness (samp_control="CSR"), or multivariate normal (samp_control="MVN").
s_control	Optional. Numeric value for the standard deviation of the multivariate normal distribution in the units of the obs_data. The default value (1) assumes a unit square window. Ignored if Ignored if samp_control="uniform" or samp_control="CSR".
alpha	Optional. Numeric value of the critical p-value (default=0.05).
p_correct	Optional. Character string specifying whether to apply a correction for multiple comparisons including a False Discovery Rate p_correct = "FDR", a Sidak correction p_correct = "uncorrelated Sidak", and a Bonferroni correction p_correct = "uncorrelated Bonferroni". If p_correct = "none" (the default), then no correction is applied.
parallel	Logical. If TRUE, will execute the function in parallel. If FALSE (the default), will not execute the function in parallel.
n_core	Optional. Integer specifying the number of CPU cores on current host to use for parallelization (the default is 2 cores).
verbose	Logical. If TRUE (the default), will print function progress during execution. If FALSE, will not print.
...	Arguments passed to risk to select bandwidth, edge correction, and resolution.
cascon	cascon is no longer supported and this function will output power for case-only and case/control clustering. This argument has been moved to spatial_plots function.
lower_tail	lower_tail is no longer supported; this function uses alpha to set the critical p-value.
upper_tail	upper_tail is no longer supported; this function uses alpha to set the critical p-value.

Details

This function computes the statistical power of the spatial relative risk function (nonparametric estimate of relative risk by kernel smoothing) for previously collected studies with known case and control locations.

The function uses the risk function to estimate the spatial relative risk function and forces the tolerate argument to be TRUE in order to calculate asymptotic p-values.

If samp_control = "uniform" the control locations are randomly generated uniformly within the dow of obs_data. By default, the resolution is an integer value of 128 and can be specified using the resolution argument in the internally called risk function.

If samp_control = "CSR" the control locations are randomly generated assuming complete spatial randomness (homogeneous Poisson process) within the dow of obs_data with a lambda = number of controls / [resolution x resolution]. By default, the resolution is an integer value of 128 and can be specified using the resolution argument in the internally called risk function.

If samp_control = "MVN" the control locations are randomly generated assuming a multivariate normal distribution centered at each observed location. The optional argument s_control specifies the standard deviation of the multivariate normal distribution (1 by default) in the units of the obs_data.

The function computes a one-sided hypothesis test for case clustering (alpha = 0.05 by default). The function also computes a two-sided hypothesis test for case clustering and control clustering (lower tail = 0.025 and upper tail = 0.975).

The function has functionality for a correction for multiple testing. If p_correct = "FDR", calculates a False Discovery Rate by Benjamini and Hochberg. If p_correct = "Sidak", calculates a Sidak correction. If p_correct = "Bonferroni", calculates a Bonferroni correction. If p_correct = "none" (the default), then the function does not account for multiple testing and uses the uncorrected alpha level. See the internal pval_correct function documentation for more details.

Value

An object of class "list". This is a named list with the following components:

sim

An object of class 'rrs' for the first iteration of simulated data.

out

An object of class 'rrs' for the observed spatial relative risk function without randomization.

rr_mean

Vector of length [resolution x resolution] of the mean relative risk values at each gridded knot.

pval_mean

Vector of length [resolution x resolution] of the mean asymptotic p-value at each gridded knot.

rr_sd

Vector of length [resolution x resolution] of the standard deviation of relative risk values at each gridded knot.

pval_prop_cascon

Vector of length [resolution x resolution] of the proportion of asymptotic p-values that were significant for both case and control locations at each gridded knot.

pval_prop_cas

Vector of length [resolution x resolution] of the proportion of asymptotic p-values that were significant for only case locations at each gridded knot.

rx

Vector of length [resolution x resolution] of the x-coordinates of each gridded knot.

ry

Vector of length [resolution x resolution] of the y-coordinates of each gridded knot.

n_cas

Vector of length sim_total of the number of case locations simulated in each iteration.

n_con

Vector of length sim_total of the number of control locations simulated in each iteration.

bandw

Vector of length sim_total of the bandwidth (of numerator) used in each iteration.

s_obs

Vector of length sim_total of the global s statistic.

t_obs

Vector of length sim_total of the global t statistic.

alpha

Vector of length sim_total of the (un)corrected critical p-values.

See Also

risk for additional arguments for bandwidth selection, edge correction, and resolution.

Examples

# Using the 'chorley' data set from 'spatstat.data' package
 data(chorley, package="spatstat.data")
 f1 <- jitter_power(obs_data = unique(chorley),
                    samp_control = "CSR",
                    verbose = FALSE)

sparrpowR documentation built on Aug. 29, 2025, 5:35 p.m.