spatial_power: Power of SRR function for randomly generated data.

In sparrpowR: Power Analysis to Detect Spatial Relative Risk Clusters

Power of SRR function for randomly generated data.

Description

Compute the statistical power of a spatial relative risk function using randomly generated data.

Usage

spatial_power(
  win = spatstat.geom::unit.square(),
  sim_total = 2,
  x_case,
  y_case,
  samp_case = c("uniform", "MVN", "CSR", "IPP"),
  samp_control = c("uniform", "systematic", "MVN", "CSR", "IPP", "clustered"),
  x_control = NULL,
  y_control = NULL,
  n_case = NULL,
  n_control = NULL,
  npc_control = NULL,
  r_case = NULL,
  r_control = NULL,
  s_case = NULL,
  s_control = NULL,
  l_case = NULL,
  l_control = NULL,
  e_control = NULL,
  alpha = 0.05,
  p_correct = "none",
  verbose = TRUE,
  parallel = FALSE,
  n_core = 2,
  ...,
  cascon = lifecycle::deprecated(),
  lower_tail = lifecycle::deprecated(),
  upper_tail = lifecycle::deprecated()
)

Arguments

win	Window in which to simulate the random data. An object of class "owin" or something acceptable to as.owin.
sim_total	Integer, specifying the number of simulation iterations to perform.
x_case	Numeric value, or numeric vector, of x-coordinate(s) of case cluster(s).
y_case	Numeric value, or numeric vector, of y-coordinate(s) of case cluster(s).
samp_case	Character string specifying whether to randomize the case locations uniformly (samp_control="uniform"), multivariate normal (samp_control="MVN"), with complete spatial randomness (samp_control="CSR"), or using the inhomogeneous Poisson process (samp_control="IPP") around each case centroid.
samp_control	Character string specifying whether to randomize the control locations uniformly (samp_control="uniform"), systematically (samp_control="systematic"), multivariate normal (samp_control="MVN"), with complete spatial randomness (samp_control="CSR"), using the inhomogeneous Poisson process (samp_control="IPP"), or a realization of the Neyman-Scott cluster process (samp_control="clustered").
x_control	Numeric value, or numeric vector, of x-coordinate(s) of case cluster(s). Ignored if samp_control!="MVN".
y_control	Numeric value, or numeric vector, of y-coordinate(s) of case cluster(s). Ignored if samp_control!="MVN".
n_case	Numeric value, or numeric vector, of the sample size for case locations in each cluster.
n_control	Numeric value, or numeric vector, of the sample size for control locations in each cluster.
npc_control	Optional. Numeric value of the number of clusters of control locations. Ignored if samp_control!="clustered".
r_case	Optional. Numeric value, or numeric vector, of radius (radii) of case cluster(s) in the units of win. Ignored if samp_case="MVN".
r_control	Optional. Numeric value, or numeric vector, of radius (radii) of control cluster(s) in the units of win. Ignored if samp_control!="clustered".
s_case	Optional. Numeric value, or numeric vector, for the standard deviation(s) of the multivariate normal distribution for case locations in the units of win. Ignored if samp_control!="MVN".
s_control	Optional. Numeric value, or numeric vector, for the standard deviation(s) of the multivariate normal distribution for control locations in the units of win. Ignored if samp_control!="MVN".
l_case	Optional. A single positive number, a vector of positive numbers, a function(x,y, ...), or a pixel image. Intensity of the Poisson process for case clusters. Ignored if samp_control!="IPP".
l_control	Optional. A single positive number, a vector of positive numbers, a function(x,y, ...), or a pixel image. Intensity of the Poisson process for control clusters. Ignored if samp_control="uniform", samp_control="systematic", samp_control="MVN", or samp_control="CSR".
e_control	Optional. A single non-negative number for the size of the expansion of the simulation window for generating parent points. Ignored if samp_control!="clustered".
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.
verbose	Logical. If TRUE (the default), will print function progress during execution. If FALSE, will not print.
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).
...	Arguments passed to runifdisc, disc, rpoispp, rsyst, or rNeymanScott depending on samp_control or samp_control. Arguments also 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	lupper_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 randomly generated data using various random point pattern generators from the spatstat.random package.

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_case = "uniform" the case locations are randomly generated uniformly within a disc of radius r_case (or discs of radii r_case) centered at coordinates (x_case, y_case).

If samp_case = "MVN" the case locations are randomly generated assuming a multivariate normal distribution centered at coordinates (x_case, y_case) with a standard deviation of s_case.

If samp_case = "CSR" the case locations are randomly generated assuming complete spatial randomness (homogeneous Poisson process) within a disc of radius r_case (or discs of radii r_case) centered at coordinates (x_case, y_case) with lambda = n_case / area of disc.

If samp_case = "IPP" the case locations are randomly generated assuming an inhomogeneous Poisson process with a disc of radius r_case (or discs of radii r_case) centered at coordinates (x_case, y_case) with lambda = l_case, a function.

If samp_control = "uniform" the control locations are randomly generated uniformly within the window win.

If samp_control = "systematic" the control locations are randomly generated systematically within the window win consisting of a grid of equally-spaced points with a random common displacement.

If samp_control = "MVN" the control locations are randomly generated assuming a multivariate normal distribution centered at coordinates (x_control, y_control) with a standard deviation of s_control.

If samp_control = "CSR" the control locations are randomly generated assuming complete spatial randomness (homogeneous Poisson process) within the window win with a lambda = n_control / [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 = "IPP" the control locations are randomly generated assuming an inhomogeneous Poisson process within the window win with a lambda = l_control, a function.

If samp_control = "clustered" the control locations are randomly generated with a realization of the Neyman-Scott process within the window win with the intensity of the Poisson process cluster centres (kappa = l_control), the size of the expansion of the simulation window for generative parent points (e_control), and the radius (or radii) of the disc for each cluster (r_control).

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.

Examples

 spatial_power(x_case = c(0.25, 0.5, 0.75),
               y_case = c(0.75, 0.25, 0.75),
               samp_case = "MVN", 
               samp_control = "MVN",
               x_control = c(0.25, 0.5, 0.75),
               y_control = c(0.75, 0.25, 0.75),
               n_case = 100,
               n_control = c(100,500,300),
               s_case = c(0.05,0.01,0.05),
               s_control = 0.05,
               verbose = FALSE)

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