Explore the relationship between search radius and neighborhood size
Source:R/Explore_Radius_Neighborhood.R
Explore_Radius_Neighborhood.RdEstimates the mean number of neighboring cells as a function of search
radius, using a randomly sampled subset of cells for efficiency. Designed
to help users choose a radius parameter before calling
create_NICHESObject().
Usage
Explore_Radius_Neighborhood(
coord,
r.min = NULL,
r.max = NULL,
r.step = NULL,
n.sample = 2000L,
seed = 42L,
n.cores = 1L,
show.plot = TRUE
)Arguments
- coord
data.frame. First two columns must be numeric x and y coordinates. Row names must be unique cell barcodes.
- r.min
numeric(1). Minimum radius to evaluate. Default: 1% of the bounding-box diagonal.
- r.max
numeric(1). Maximum radius to evaluate. Default: 20% of the bounding-box diagonal.
- r.step
numeric(1). Step size between evaluated radii. Default:
(r.max - r.min) / 50(50 evenly spaced evaluation points).- n.sample
integer(1) or NULL. Number of cells to randomly sample for the neighborhood estimate. Default 2000. Set to
NULLto use all cells – not recommended for large datasets.- seed
integer(1) or NULL. Random seed for reproducible sampling. Default 42. The caller's random number state is restored on exit.
- n.cores
integer(1). Number of parallel workers (socket cluster) for distributing the radius evaluation. Default 1.
- show.plot
logical. Whether to print the summary ggplot before returning. Default
TRUE.
Value
A data.table with columns:
- radius
evaluated radius value
- mean.neighbors
mean neighbor count across sampled cells
- sd.neighbors
standard deviation of neighbor count
- median.neighbors
median neighbor count (robust to density outliers)
Returned invisibly when show.plot = TRUE.
Details
A single kd-tree query via dbscan::frNN() is run at r.max;
all smaller radii are evaluated by thresholding the already-retrieved
distance lists, so the kd-tree is built only once regardless of how many
radius steps are requested.
Examples
# \donttest{
data(NICHESv2_inputs)
# Build a coord data.frame from the example metadata
coord <- NICHESv2_inputs$meta.data[, c("x", "y")]
rownames(coord) <- rownames(NICHESv2_inputs$meta.data)
# Sweep radius across the bounding box; small dataset -> use all 80 cells
radius.curve <- Explore_Radius_Neighborhood(
coord = coord,
n.sample = 80L,
n.cores = 1L,
show.plot = FALSE
)
head(radius.curve)
#> radius mean.neighbors sd.neighbors median.neighbors
#> <num> <num> <num> <num>
#> 1: 0.01317801 0.100 0.3765264 0
#> 2: 0.01828785 0.200 0.5372221 0
#> 3: 0.02339769 0.350 0.7647288 0
#> 4: 0.02850753 0.525 0.8711261 0
#> 5: 0.03361737 0.675 0.9246963 0
#> 6: 0.03872721 0.775 0.9933322 1
# }