Spatial Resampling for Permutation Testing

Performs bin-wise spatial resampling to preserve local spatial structure while breaking cross-type coordination. This is used for permutation testing in CoPro to generate null distributions that account for spatial autocorrelation.

Usage

resample_spatial(
  location_data,
  num_bins_x = 10,
  num_bins_y = 10,
  match_quantile = FALSE
)

Arguments

location_data

Data frame with columns: x, y, cell_ID. Optionally can include pre-computed x_bin, y_bin columns.

num_bins_x

Number of bins in the x direction (default: 10). Larger values preserve more local structure but may have sparse bins.

num_bins_y

Number of bins in the y direction (default: 10).

match_quantile

Logical. If TRUE, matches cells between original and target tiles based on their relative (quantile) positions within each tile. This better preserves within-tile spatial structure. Default: FALSE.

Value

Data frame with resampled cell assignments. The x, y coordinates remain fixed, but cell_ID is shuffled according to the bin-wise resampling.

Details

The algorithm:

1. Divides the spatial domain into a grid of bins

2. Creates a random mapping (shuffle) between bins

3. For each original bin, samples cells from the mapped target bin

4. If target bin has insufficient cells, expands to neighboring bins

When match_quantile = TRUE, step 3 uses quantile-based matching instead of random sampling. This matches cells based on their relative x/y positions within each tile (using rank quantiles), better preserving within-tile spatial autocorrelation structure.

This preserves spatial autocorrelation within cell types while breaking the cross-type coordination that would indicate true co-progression.

Examples

if (FALSE) { # \dontrun{
# Create example data
loc_data <- data.frame(
  x = runif(100, 0, 10),
  y = runif(100, 0, 10),
  cell_ID = paste0("cell_", 1:100)
)

# Check bin distribution first
diagnose_bin_distribution(loc_data, num_bins_x = 5, num_bins_y = 5)

# Perform spatial resampling (random within tile)
resampled <- resample_spatial(loc_data, num_bins_x = 5, num_bins_y = 5)

# Perform spatial resampling (quantile-matched within tile)
resampled_matched <- resample_spatial(loc_data, num_bins_x = 5, num_bins_y = 5,
                                      match_quantile = TRUE)
} # }