sparrpowR: Power analysis to detect spatial relative clusters

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

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::spatial_power(win = unit.circle,
                                sim_total = 100,
                                x_case = 0.5,
                                y_case = 0.5,
                                samp_case = "uniform",
                                samp_control = "CSR",
                                r_case = 0.1,
                                n_case = 50,
                                n_control = 250)
                     
# ----------------------- #
# Outputs from iterations #
# ----------------------- #

# Mean and standard deviation of simulated sample sizes and bandwidth
stats::mean(foo$n_con); stats::sd(foo$n_con)    # controls
stats::mean(foo$n_cas); stats::sd(foo$n_cas)    # 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::spatial_power(win = unit.circle,
                                sim_total = 100,
                                x_case = 0.5,
                                y_case = 0.5,
                                samp_case = "uniform",
                                samp_control = "CSR",
                                r_case = 0.1,
                                n_case = 50,
                                n_control = 250,
                                alpha = 0.05,
                                p_correct = "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.