Prepare fixed-radius concentration hotspot analysis — prepare

`prepare_spatialrisk()`, `select_candidates()`, and `optimize_hotspot()` expose the main steps used by concentration_hotspot. They are useful when the intermediate search state needs to be inspected or when the same prepared portfolio is used in more than one hotspot search strategy.

Usage

prepare_spatialrisk(
  data,
  value,
  radius = 200,
  cell_size = 100,
  lon = "lon",
  lat = "lat",
  crs_metric = 3035
)

select_candidates(
  x,
  grid_spacing = 1,
  max_refinement_points = 1000,
  method = c("continuous", "observed", "grid"),
  threshold = NULL,
  progress = TRUE,
  grid_precision = lifecycle::deprecated()
)

optimize_hotspot(
  x,
  n_hotspots = 1,
  progress = TRUE,
  top_n = lifecycle::deprecated()
)

# S3 method for class 'spatialrisk_hotspot_workflow'
plot(x, type = c("auto", "raster", "candidates"), ...)

Arguments

data: A data.frame containing point-level exposures. Must include longitude, latitude, and the value of interest.
value: A string giving the numeric column in `data` to aggregate within each radius.
radius: Numeric. Radius of the circle in meters.
cell_size: Numeric. Size of the raster cells used for the initial screening raster.
lon: A string giving the longitude column in `data`.
lat: A string giving the latitude column in `data`.
crs_metric: Numeric. EPSG code for a projected CRS with meter units. The default `3035` is ETRS89 / LAEA Europe.
x: A prepared spatial-risk workflow object returned by `prepare_spatialrisk()` or `select_candidates()`.
grid_spacing: Numeric. Spacing between candidate grid centres in the units of `crs_metric`; for the default metric CRS these units are meters. Used for grid-based refinement.
max_refinement_points: Positive integer. Maximum number of local points used for pair-intersection refinement before falling back to grid refinement in a search state produced by `select_candidates()`. Direct optimisation of a prepared object never falls back to a grid; values above this limit produce a computational-cost warning instead.
method: Hotspot search strategy. `"continuous"` is the default and searches for centres that may lie between observed points. `"observed"` searches only observed point locations. `"grid"` uses the grid-refinement workflow.
threshold: Optional numeric lower bound for candidate focal cells. If `NULL`, the lower bound is estimated using the same preliminary refinement step as `concentration_hotspot()`.
progress: Logical. Whether to print progress messages.
grid_precision: Deprecated. Use `grid_spacing` instead.
n_hotspots: Positive integer. Number of non-overlapping hotspots to return.
top_n: Deprecated. Use `n_hotspots` instead.
type: Plot type. `"auto"` shows the prepared raster before candidate selection and selected focal candidate cells afterwards.
...: Additional arguments passed to `mapview::mapview()`.

Value

`prepare_spatialrisk()` and `select_candidates()` return an object of class `spatialrisk_hotspot_workflow`. `optimize_hotspot()` returns the same `hotspot` object structure as concentration_hotspot.

Details

The three-step interface decomposes the hotspot workflow without replacing `concentration_hotspot()`. The wrapper remains the simplest public function for normal use, while the decomposed functions make the intermediate candidate selection visible.

`optimize_hotspot()` optimises over the candidate search state supplied to it. Called directly on the output of `prepare_spatialrisk()`, it performs a full geometric search: candidate centres are the active observed locations and the valid radius-circle intersections generated by every active point pair no farther than twice the radius apart. This route does not use raster screening or grid fallback and is intended mainly for small portfolios, diagnostics, validation, and methodological benchmarks. Pair generation can be computationally expensive.

In `select_candidates()`, `threshold = NULL` estimates a lower bound by taking the highest focal raster cells, refining those cells on a small local grid, and using the best refined value as the candidate-cell threshold. The selected candidates are focal cells whose moving-window sum is at least this lower bound. The focal window includes the requested radius plus a raster-cell diagonal. With non-negative values, its sum is therefore an upper bound for every exact centre located in that focal cell. Under the default automatic threshold, observed and pair-intersection centres are mapped back to the raster and an exact radius sum is calculated only when the centre itself lies in a selected cell. For a point pair, its two possible circle centres are screened separately. This reduces exact evaluations without changing the screened search result under these assumptions. The pruning rule is not used for a user-supplied threshold or negative values.

Candidate screening never defines the evaluation portfolio. Every retained centre is scored against all records in the complete active portfolio, so a point outside the candidate-generation subset still contributes when it lies within the radius. Point-to-raster-cell membership is stored during preparation and reused to retrieve nearby records; candidate regions within one hotspot iteration share one exact-evaluation index. When `optimize_hotspot(n_hotspots > 1)` or `concentration_hotspot(n_hotspots > 1)` is used, the points in the selected hotspot are removed and the candidate-selection logic is run again for the next hotspot. Therefore the number of candidate cells shown by `select_candidates()` for the first iteration does not limit the number of hotspots returned by `n_hotspots`.

Author

Martin Haringa

Examples

portfolio <- Groningen[1:200, c("lon", "lat", "amount")]

model <- prepare_spatialrisk(portfolio, value = "amount", radius = 200,
                             cell_size = 100)

# Full geometric reference search
full <- optimize_hotspot(model, progress = FALSE)

# Screened production search
screened <- model |>
  select_candidates(progress = FALSE) |>
  optimize_hotspot(progress = FALSE)

full$hotspots
#>   id      lon      lat amount_sum
#> 1  1 6.554816 53.19424       1315
screened$hotspots
#>   id      lon      lat amount_sum
#> 1  1 6.558472 53.19492       1315