Classify and Prune Points by Area of Effect

Given a set of points and one or more support polygons, aoe() classifies points as "core" (inside original support) or "halo" (inside the area of effect but outside original support), pruning all points outside.

Usage

aoe(
  points,
  support = NULL,
  scale = NULL,
  area = NULL,
  method = c("buffer", "stamp"),
  reference = NULL,
  mask = NULL,
  largest_polygon = TRUE,
  coords = NULL
)

Arguments

points

An sf object with POINT geometries.

support

One of:

sf object with POLYGON/MULTIPOLYGON geometries
Country name or ISO code: "France", "FR", "FRA"
Vector of countries: c("France", "Germany")
Missing: auto-detects countries containing the points

scale

Numeric scale factor (default sqrt(2) - 1, approximately 0.414). Controls the size of the halo relative to the core:

sqrt(2) - 1 (default): equal core/halo areas, ratio 1:1
1: area ratio 1:3 (halo is 3x core area)

For method = "buffer", determines the target halo area as original_area * ((1 + scale)^2 - 1).

For method = "stamp", the multiplier 1 + scale is applied to distances from the reference point.

Cannot be used together with area.

area

Numeric area proportion (alternative to scale). Specifies the target halo area as a proportion of the original support area. For example, area = 1 means halo area equals the original support area.

Unlike scale, this parameter accounts for masking: the function finds the scale that produces the target halo area after mask intersection. This is useful when you need a specific effective area regardless of how much gets clipped by coastlines or borders.

Cannot be used together with scale.

method

Method for computing the area of effect:

"buffer" (default): Uniform buffer around the support boundary. Robust for any polygon shape. Buffer distance is calculated to achieve the target halo area.
"stamp": Scale vertices outward from the centroid (or reference point). Preserves shape proportions but only guarantees containment for star-shaped polygons. May leave small gaps for highly concave shapes.

reference

Optional sf object with a single POINT geometry.

If NULL (default), the centroid of each support is used. Only valid when support has a single row and method = "stamp".

mask

Optional mask for clipping the area of effect. Can be:

sf object with POLYGON or MULTIPOLYGON geometry
"land": use the bundled global land mask to exclude sea areas If provided, each area of effect is intersected with this mask.

largest_polygon

Logical (default TRUE). When the support contains multiple polygons (e.g., mainland plus islands), use only the largest polygon by area. This is typically the mainland. Points near dropped polygons will be pruned entirely (not classified). Set to FALSE to include all polygons, in which case area = "equal" uses total area with redistribution across all polygons.

coords

Column names for coordinates when points is a data.frame, e.g. c("lon", "lat"). If NULL, auto-detects common names.

Value

An aoe_result object (extends sf) containing only the supported points, with columns:

point_id: Original point identifier (row name or index)
support_id: Identifier for which support the classification refers to
aoe_class: Classification: "core" or "halo"

When multiple supports are provided, points may appear multiple times (once per support whose AoE contains them).

The result has S3 methods for print(), summary(), and plot(). Use aoe_geometry() to extract the AoE polygons.

Details

By default, the area of effect is computed using a buffer that produces equal core and halo areas. This means the AoE has twice the area of the original support, split evenly between core (inside) and halo (outside).

Buffer method (default)

Computes a uniform buffer distance $d$ such that the buffered area equals the target. The buffer distance is found by solving: $$\pi d^2 + P \cdot d = A_{target}$$ where $P$ is the perimeter and $A_{target}$ is the desired halo area.

Stamp method

Applies an affine transformation to each vertex: $$p' = r + (1 + s)(p - r)$$ where $r$ is the reference point (centroid), $p$ is each vertex, and $s$ is the scale factor. This method preserves shape proportions but only guarantees the AoE contains the original for star-shaped polygons (where the centroid can "see" all boundary points).

Points exactly on the original support boundary are classified as "core".

The support geometry is validated internally using sf::st_make_valid().

Examples

library(sf)

# Single support
support <- st_as_sf(
  data.frame(id = 1),
  geometry = st_sfc(st_polygon(list(
    cbind(c(0, 10, 10, 0, 0), c(0, 0, 10, 10, 0))
  ))),
  crs = 32631
)

pts <- st_as_sf(
  data.frame(id = 1:4),
  geometry = st_sfc(
    st_point(c(5, 5)),
    st_point(c(2, 2)),
    st_point(c(15, 5)),
    st_point(c(30, 30))
  ),
  crs = 32631
)

result <- aoe(pts, support)

# Multiple supports (e.g., admin regions)
supports <- st_as_sf(
  data.frame(region = c("A", "B")),
  geometry = st_sfc(
    st_polygon(list(cbind(c(0, 10, 10, 0, 0), c(0, 0, 10, 10, 0)))),
    st_polygon(list(cbind(c(8, 18, 18, 8, 8), c(0, 0, 10, 10, 0))))
  ),
  crs = 32631
)

result <- aoe(pts, supports)
# Points near the boundary may appear in both regions' AoE