sparrpowR: Power analysis to detect spatial relative clusters

<!-- badges: end -->

Date repository last updated: August 28, 2025

Overview

The sparrpowR package is a suite of R functions to calculate the statistical power to detect clusters using the kernel-based spatial relative risk function that is estimated using the sparr package. Basic visualization is also supported.

Installation

To install the release version from CRAN:

install.packages("sparrpowR")

To install the development version from GitHub:

devtools::install_github("machiela-lab/sparrpowR")

Available functions

Authors

• Ian D. Buller - DLH, LLC (formerly Social & Scientific Systems, Inc.), Bethesda, Maryland (current) - Occupational and Environmental Epidemiology Branch, Division of Cancer Epidemiology and Genetics, National Cancer Institute, National Institutes of Health, Rockville, Maryland (original) - GitHub - ORCID

• Derek W. Brown - Integrative Tumor Epidemiology Branch, Division of Cancer Epidemiology and Genetics, National Cancer Institute, National Institutes of Health, Rockville, Maryland (original) - GitHub - ORCID

See also the list of contributors who participated in this package, including:

• Tim A. Myers - Laboratory of Genetic Susceptibility, Division of Cancer Epidemiology and Genetics, National Cancer Institute, National Institutes of Health, Rockville, Maryland - GitHub

Usage

``` r set.seed(1234) # for reproducibility

------------------

Necessary packages

------------------

library(sparrpowR) library(spatstat.geom) library(stats)

-----------------

Run spatial_power

-----------------

Circular window with radius 0.5

Uniform case sampling within a disc of radius of 0.1 at the center of the window

Complete Spatial Randomness control sampling

20% prevalence (n = 300 total locations)

Statistical power to detect both case and control relative clustering

100 simulations (more recommended for power calculation)

unit.circle <- spatstat.geom::disc(radius = 0.5, centre = c(0.5,0.5))

foo <- sparrpowR::spatialpower(win = unit.circle, simtotal = 100, xcase = 0.5, ycase = 0.5, sampcase = "uniform", sampcontrol = "CSR", rcase = 0.1, ncase = 50, n_control = 250)

-----------------------

Outputs from iterations

-----------------------

Mean and standard deviation of simulated sample sizes and bandwidth

stats::mean(foo$ncon); stats::sd(foo$ncon) # controls stats::mean(foo$ncas); stats::sd(foo$ncas) # cases stats::mean(foo$bandw); stats::sd(foo$bandw) # bandwidth of case density (if fixed, same for control density)

Global Test Statistics

Global maximum relative risk: Null hypothesis is mu = 1

stats::t.test(x = foo$s_obs, mu = 0, alternative = "two.sided")

Integral of log relative risk: Null hypothesis is mu = 0

stats::t.test(x = foo$t_obs, mu = 1, alternative = "two.sided")

-----------------

Run spatial_plots

-----------------

Statistical power for case-only clustering (one-tailed test)

sparrpowR::spatial_plots(foo) ```

```

Statistical power for case clustering and control

clustering (two-tailed test)

Only showing second and third plot

sparrpowR::spatial_plots(foo, cascon = TRUE) ```

```

---------------------------

Multiple Testing Correction

---------------------------

Same parameters as above

Apply a conservative Bonferroni correction

set.seed(1234) # reset RNG

Run spatial_power()

foo <- sparrpowR::spatialpower(win = unit.circle, simtotal = 100, xcase = 0.5, ycase = 0.5, sampcase = "uniform", sampcontrol = "CSR", rcase = 0.1, ncase = 50, ncontrol = 250, alpha = 0.05, pcorrect = "Bonferroni")

median(foo$alpha) # critical p-value of 3e-6

Run spatial_plots() for case-only clustering

Only showing third plot

sparrpowR::spatial_plots(foo, cascon = TRUE) ```

Funding

This package was developed while the authors were originally postdoctoral fellows supported by the Cancer Prevention Fellowship Program at the National Cancer Institute. Any modifications since December 05, 2022 were made while the author I.D.B. was an employee of DLH, LLC (formerly Social & Scientific Systems, Inc.).

Acknowledgments

When citing this package for publication, please follow:

citation("sparrpowR")

Questions? Feedback?

For questions about the package please contact the maintainer Dr. Ian D. Buller or submit a new issue.