Title:	Spatial Support at Scale
Version:	0.2.4
Description:	Formalizes spatial support at scale for ecological and geographical analysis. Given points and support polygons, classifies points as "core" (inside original support) or "halo" (inside scaled support but outside original), pruning all others. The default scale produces equal core and halo areas - a geometrically derived choice requiring no tuning. An optional mask enforces hard boundaries such as coastlines. Political borders are treated as soft boundaries with no ecological meaning.
License:	MIT + file LICENSE
URL:	https://gillescolling.com/areaOfEffect/, https://github.com/gcol33/areaOfEffect
BugReports:	https://github.com/gcol33/areaOfEffect/issues
Encoding:	UTF-8
Language:	en-US
RoxygenNote:	7.3.3
Imports:	methods, sf
Suggests:	lwgeom, testthat (≥ 3.0.0), knitr, rmarkdown, svglite
VignetteBuilder:	knitr
Config/testthat/edition:	3
Depends:	R (≥ 3.5)
LazyData:	true
NeedsCompilation:	no
Packaged:	2026-02-03 20:41:48 UTC; Gilles Colling
Author:	Gilles Colling [aut, cre, cph]
Maintainer:	Gilles Colling <gilles.colling051@gmail.com>
Repository:	CRAN
Date/Publication:	2026-02-06 19:40:14 UTC

Subset method for aoe_result

Description

Preserves aoe_result attributes when subsetting.

Usage

## S3 method for class 'aoe_result'
x[i, ...]

Arguments

Value

An aoe_result object (or sf if support_id removed)

Classify and Prune Points by Area of Effect

Description

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

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().

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.

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

Compute Area Statistics for AoE

Description

Calculate area statistics for the original supports and their areas of effect, including expansion ratios, masking effects, and core/halo balance.

Usage

aoe_area(x)

Arguments

Details

With scale s, the AoE expands by multiplier (1+s) from centroid, resulting in (1+s)^2 times the area. The theoretical halo:core ratio is (1+s)^2 - 1:

• Scale 1 (default): ratio 3.0 (core 1 part, halo 3 parts)

• Scale 0.414: ratio 1.0 (equal areas)

Masking reduces the halo (and thus the ratio) when the AoE extends beyond hard boundaries.

Value

An aoe_area_result data frame with one row per support:

support_id

Support identifier

area_core

Area of core region (same as original support)

area_halo

Area of halo region (AoE minus core, after masking)

area_aoe

Total AoE area after masking

halo_core_ratio

Ratio of halo to core area (theoretically 3.0 without mask)

pct_masked

Percentage of theoretical AoE area removed by masking

Examples

library(sf)

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:3),
  geometry = st_sfc(
    st_point(c(5, 5)),
    st_point(c(15, 5)),
    st_point(c(2, 2))
  ),
  crs = 32631
)

result <- aoe(pts, support)
aoe_area(result)

Classify Points by Distance from a Border

Description

Given a set of points and a border (line), aoe_border() classifies points by their side relative to the border and their distance from it. Creates equal-area buffer zones on both sides of the border.

Usage

aoe_border(
  points,
  border,
  width = NULL,
  area = NULL,
  halo_width = NULL,
  halo_area = NULL,
  mask = NULL,
  bbox = NULL,
  side_names = c("side_1", "side_2"),
  coords = NULL
)

Arguments

Details

The function creates symmetric buffer zones around a border line:

1. Core zone: Points within width (or area) distance of the border

2. Halo zone: Points beyond core but within width + halo_width

3. Pruned: Points outside the halo zone (not returned)

Each zone is split by the border line to determine which side the point falls on.

Equal area across sides

When using the area parameter, the buffer width is calculated to produce equal area on both sides of the border. With masking, the width is adjusted so that the masked area on each side equals the target.

Value

An aoe_border_result object (extends sf) containing classified points with columns:

point_id

Original point identifier

side

Which side of the border: value from side_names

aoe_class

Distance class: "core" or "halo"

Points outside the study area are pruned (not returned).

Examples

library(sf)

# Create a border line
border <- st_as_sf(
  data.frame(id = 1),
  geometry = st_sfc(st_linestring(matrix(
    c(0, 0, 100, 100), ncol = 2, byrow = TRUE
  ))),
  crs = 32631
)

# Create points
pts <- st_as_sf(
  data.frame(id = 1:6),
  geometry = st_sfc(
    st_point(c(10, 20)),   # near border, side 1
    st_point(c(30, 10)),   # near border, side 2
    st_point(c(50, 80)),   # far from border, side 1
    st_point(c(80, 40)),   # far from border, side 2
    st_point(c(5, 5)),     # very close to border
    st_point(c(200, 200))  # outside study area
  ),
  crs = 32631
)

# Classify by distance from border
result <- aoe_border(pts, border, width = 20)

Adaptive AoE Expansion to Capture Minimum Points

Description

Expands the area of effect just enough to capture at least min_points, subject to hard caps on expansion. This is useful when a fixed scale leaves some supports with insufficient data for stable modelling.

Usage

aoe_expand(
  points,
  support = NULL,
  min_points,
  max_area = 2,
  max_dist = NULL,
  method = c("buffer", "stamp"),
  reference = NULL,
  mask = NULL,
  coords = NULL
)

Arguments

Details

Unlike aoe(), which applies consistent geometry across all supports, aoe_expand() adapts the scale per-support based on local point density. Use with caution: this can make AoEs incomparable across regions with different point densities.

Algorithm

For each support, binary search finds the minimum scale where point count >= min_points. The search is bounded by:

• Lower: scale = 0 (core only)

• Upper: minimum of max_area cap and max_dist cap

If the caps prevent reaching min_points, a warning is issued and the result uses the maximum allowed scale.

Caps

Two caps ensure AoE doesn't expand unreasonably:

max_area (relative): Limits halo area to max_area times the original. The corresponding scale is sqrt(1 + max_area) - 1. Default max_area = 2 means scale <= 0.732 (total area <= 3x).

max_dist (absolute): Limits expansion distance in CRS units. For buffer method, this is the buffer distance directly. For stamp method, converted to scale via max_dist / characteristic_radius where characteristic_radius = sqrt(area / pi).

Value

An aoe_result object (same as aoe()) with additional attributes:

target_reached

Logical: was min_points achieved for all supports? Use attr(result, "expansion_info") for per-support details.

expansion_info

Data frame with per-support expansion details: support_id, scale_used, points_captured, target_reached, cap_hit.

See Also

aoe() for fixed-scale AoE computation

Examples

library(sf)

# Create a support with sparse points
support <- st_as_sf(
  data.frame(id = 1),
  geometry = st_sfc(st_polygon(list(
    cbind(c(0, 100, 100, 0, 0), c(0, 0, 100, 100, 0))
  ))),
  crs = 32631
)

# Points scattered around
set.seed(42)
pts <- st_as_sf(
  data.frame(id = 1:50),
  geometry = st_sfc(lapply(1:50, function(i) {
    st_point(c(runif(1, -50, 150), runif(1, -50, 150)))
  })),
  crs = 32631
)

# Expand until we have at least 20 points
result <- aoe_expand(pts, support, min_points = 20)

# Check expansion info
attr(result, "expansion_info")

Extract AoE Geometries

Description

Extract the original support polygons and/or the area of effect polygons from an aoe_result object.

Usage

aoe_geometry(x, which = c("aoe", "original", "both"), support_id = NULL)

Arguments

Value

An sf object with polygon geometries and columns:

support_id

Support identifier

type

"original" or "aoe"

Examples

library(sf)

support <- 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(15, 25, 25, 15, 15), 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(12, 5)),
    st_point(c(20, 5)),
    st_point(c(27, 5))
  ),
  crs = 32631
)

result <- aoe(pts, support)

# Get AoE polygons
aoe_polys <- aoe_geometry(result, "aoe")

# Get both original and AoE for comparison
both <- aoe_geometry(result, "both")

# Filter to one support (uses row names as support_id)
region_1 <- aoe_geometry(result, "aoe", support_id = "1")

Stratified Sampling from AoE Results

Description

Sample points from an aoe_result with control over core/halo balance. This is useful when core regions dominate due to point density, and you want balanced representation for modelling.

Usage

aoe_sample(x, ...)

## Default S3 method:
aoe_sample(x, ...)

## S3 method for class 'aoe_result'
aoe_sample(
  x,
  n = NULL,
  ratio = c(core = 0.5, halo = 0.5),
  replace = FALSE,
  by = c("overall", "support"),
  ...
)

Arguments

Details

Sampling modes

Fixed n: When n is specified, the function samples exactly n points (or fewer if not enough available), distributed according to ratio.

Balanced downsampling: When n is NULL, the function downsamples the larger stratum to match the smaller one according to ratio. For example, with ratio c(core = 0.5, halo = 0.5) and 100 core + 20 halo points, it returns 20 core + 20 halo = 40 points.

Multiple supports

With by = "support", sampling is done independently within each support, then results are combined. This ensures each support contributes balanced samples. With by = "overall", all points are pooled first.

Value

An aoe_result object containing the sampled points, preserving all original columns and attributes. Has additional attribute sample_info with details about the sampling.

See Also

aoe() for computing AoE classifications

Examples

library(sf)

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

# Many points in core, few in halo
set.seed(42)
pts <- st_as_sf(
  data.frame(id = 1:60),
  geometry = st_sfc(c(
    lapply(1:50, function(i) st_point(c(runif(1, 10, 90), runif(1, 10, 90)))),
    lapply(1:10, function(i) st_point(c(runif(1, 110, 140), runif(1, 10, 90))))
  )),
  crs = 32631
)

result <- aoe(pts, support, scale = 1)

# Balance core/halo (downsamples core to match halo)
balanced <- aoe_sample(result)

# Fixed sample size with 70/30 split
sampled <- aoe_sample(result, n = 20, ratio = c(core = 0.7, halo = 0.3))

Stratified Sampling from Border AoE Results

Description

Sample points from an aoe_border_result with control over side and/or core/halo balance.

Usage

## S3 method for class 'aoe_border_result'
aoe_sample(
  x,
  n = NULL,
  ratio = NULL,
  by = c("side", "class"),
  replace = FALSE,
  ...
)

Arguments

Value

An aoe_border_result object containing the sampled points.

Examples

library(sf)

# Create a border line
border <- st_as_sf(
  data.frame(id = 1),
  geometry = st_sfc(st_linestring(matrix(
    c(0, 0, 100, 100), ncol = 2, byrow = TRUE
  ))),
  crs = 32631
)

# Create points
pts <- st_as_sf(
  data.frame(id = 1:6),
  geometry = st_sfc(
    st_point(c(10, 20)),
    st_point(c(30, 10)),
    st_point(c(50, 80)),
    st_point(c(80, 40)),
    st_point(c(5, 5)),
    st_point(c(95, 95))
  ),
  crs = 32631
)

result <- aoe_border(pts, border, width = 20,
                     side_names = c("west", "east"))

# Equal sampling from each side
balanced <- aoe_sample(result, ratio = c(west = 0.5, east = 0.5))

# Sample by core/halo instead
by_class <- aoe_sample(result, ratio = c(core = 0.5, halo = 0.5),
                       by = "class")

Summarize Area of Effect Results

Description

Compute summary statistics for an AoE classification result, including counts and proportions of core vs halo points per support.

Usage

aoe_summary(x)

Arguments

Value

A data frame with one row per support, containing:

support_id

Support identifier

n_total

Total number of supported points

n_core

Number of core points

n_halo

Number of halo points

prop_core

Proportion of points that are core

prop_halo

Proportion of points that are halo

Examples

library(sf)

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(12, 5))
  ),
  crs = 32631
)

result <- aoe(pts, support)
aoe_summary(result)

Convert bbox to polygon

Description

Convert bbox to polygon

Usage

bbox_to_polygon(bbox, crs)

Arguments

Value

sfc polygon

World Country Polygons with Pre-calculated AoE Bounds

Description

An sf object containing country polygons from Natural Earth (1:50m scale) with pre-calculated bounding boxes for area of effect analysis.

Usage

countries

Format

An sf data frame with 237 rows and 9 variables:

iso2

ISO 3166-1 alpha-2 country code (e.g., "FR", "BE")

iso3

ISO 3166-1 alpha-3 country code (e.g., "FRA", "BEL")

name

Country name

continent

Continent name

bbox

Original bounding box (xmin, ymin, xmax, ymax) in Mollweide

bbox_equal_area

AoE bounding box at scale sqrt(2)-1 (equal areas)

bbox_equal_ray

AoE bounding box at scale 1 (equal linear distance)

halo_equal_area_scale

Scale factor that produces halo area = country area (with land mask)

geometry

Country polygon in WGS84 (EPSG:4326)

Source

Natural Earth https://www.naturalearthdata.com/

Examples

# Get France
france <- countries[countries$iso3 == "FRA", ]

# Use directly with aoe()

Pre-computed Equal-Area Country Halos

Description

A named list of pre-computed halo geometries for each country where the halo area equals the country area (area proportion = 1). These halos account for land masking (sea areas excluded).

Usage

country_halos

Format

A named list with ISO3 country codes as names. Each element is either an sfc geometry (POLYGON or MULTIPOLYGON) in WGS84, or NULL if computation failed for that country.

Details

Each halo is a "donut" shape: the area between the original country boundary and the expanded boundary, clipped to land.

Source

Computed from Natural Earth country polygons and land mask.

Examples

# Get France's equal-area halo
france_halo <- country_halos[["FRA"]]

Determine which side of a line each point is on

Description

Determine which side of a line each point is on

Usage

determine_sides(points, line)

Arguments

Value

Vector of side assignments (1 or 2)

Find buffer width that produces target area per side

Description

Find buffer width that produces target area per side

Usage

find_border_width(border_geom, target_area, mask_geom, crs)

Arguments

Value

Buffer width

Find additional halo width for target halo area

Description

Find additional halo width for target halo area

Usage

find_halo_width(border_geom, core_width, target_halo_area, mask_geom, crs)

Arguments

Value

Additional width for halo

Get Country Polygon by Name or ISO Code

Description

Quick accessor for country polygons from the bundled dataset.

Usage

get_country(x)

Arguments

Value

An sf object with the country polygon, or error if not found.

Examples

get_country("Belgium")
get_country("BE")
get_country("BEL")

Global Land Mask

Description

An sf object containing the global land polygon from Natural Earth (1:50m scale). Used for masking area of effect computations to exclude ocean areas.

Usage

land

Format

An sf data frame with 1 row:

name

Description ("Global Land")

geometry

Land multipolygon in WGS84 (EPSG:4326)

Source

Natural Earth https://www.naturalearthdata.com/

Examples

# Use as mask to exclude sea

dummy <- sf::st_as_sf(
  data.frame(id = 1),
  geometry = sf::st_sfc(sf::st_point(c(14.5, 47.5))),
  crs = 4326
)
result <- aoe(dummy, "AT", mask = land)

Plot method for aoe_border_result

Description

Plot method for aoe_border_result

Usage

## S3 method for class 'aoe_border_result'
plot(x, ...)

Arguments

Value

NULL (called for side effect)

Plot method for aoe_result

Description

Visualize an AoE classification result, showing points colored by class and optionally the support and AoE boundaries.

Usage

## S3 method for class 'aoe_result'
plot(
  x,
  support_id = NULL,
  show_aoe = TRUE,
  show_original = TRUE,
  col_core = "#2E7D32",
  col_halo = "#F57C00",
  col_original = "#000000",
  col_aoe = "#9E9E9E",
  pch = 16,
  cex = 0.8,
  main = NULL,
  ...
)

Arguments

Value

Invisibly returns x

Examples

library(sf)

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
)

set.seed(42)
pts <- st_as_sf(
  data.frame(id = 1:50),
  geometry = st_sfc(lapply(1:50, function(i) {
    st_point(c(runif(1, -5, 15), runif(1, -5, 15)))
  })),
  crs = 32631
)

result <- aoe(pts, support)
plot(result)

Print method for aoe_area_result

Description

Print method for aoe_area_result

Usage

## S3 method for class 'aoe_area_result'
print(x, ...)

Arguments

Value

Invisibly returns x

Print method for aoe_border_result

Description

Print method for aoe_border_result

Usage

## S3 method for class 'aoe_border_result'
print(x, ...)

Arguments

Value

Invisibly returns x

Print method for aoe_expand_result

Description

Print method for aoe_expand_result

Usage

## S3 method for class 'aoe_expand_result'
print(x, ...)

Arguments

Value

Invisibly returns x

Print method for aoe_result

Description

Print method for aoe_result

Usage

## S3 method for class 'aoe_result'
print(x, ...)

Arguments

Value

Invisibly returns x

Print method for aoe_summary_result

Description

Print method for aoe_summary_result

Usage

## S3 method for class 'aoe_summary_result'
print(x, ...)

Arguments

Value

Invisibly returns x

Split polygon using buffer method (fallback)

Description

Split polygon using buffer method (fallback)

Usage

split_by_buffer(polygon, line, crs)

Arguments

Value

List with side1 and side2

Split a polygon by a line into two sides

Description

Split a polygon by a line into two sides

Usage

split_by_line(polygon, line, crs)

Arguments

Value

List with side1 and side2 geometries

Summary method for aoe_result

Description

Summary method for aoe_result

Usage

## S3 method for class 'aoe_result'
summary(object, ...)

Arguments

Value

An aoe_summary_result object