Classify Points by Distance to Polygon Boundaries
The areaOfEffect package classifies spatial points relative to polygon boundaries, labeling each point as core (inside), halo (in a buffer zone), or pruning it (too far). It handles projection, buffering, and point-in-polygon operations automatically. Pass a dataframe with a country name or your own sf polygon, get classified points back.
Quick Start
library(areaOfEffect)
# Your point data
observations <- data.frame(
id = c("A", "B", "C", "D"),
lon = c(14.5, 15.2, 16.8, 20.0),
lat = c(47.5, 48.1, 47.2, 48.5)
)
# Classify relative to Austria
result <- aoe(observations, "Austria")
result$aoe_class
#> [1] "core" "core" "halo"
# (point D pruned - outside buffer zone)Statement of Need
Classifying points by their position relative to polygon boundaries is a common spatial task: which customers are inside vs. near a service area, which sensors fall within vs. outside a study region, which events occurred inside vs. near a border. The underlying sf operations are straightforward but repetitive: load boundaries, handle CRS, compute buffers, run intersections.
This package wraps that boilerplate into a single function. It also solves a less obvious problem: what buffer distance should you use? A 10km buffer means something different for Luxembourg than for Brazil. By default, areaOfEffect computes a buffer that produces equal core and halo areas, giving a scale-independent definition of “near the boundary.”
For coastal or irregular regions, the buffer can extend into areas you don’t care about (ocean, neighboring countries). The mask parameter clips the halo to relevant areas, and the area parameter adjusts the buffer to achieve your target area after masking.
Features
- Dataframes or sf objects: pass either, get classified results back
-
Bundled country boundaries: just pass
"Austria"or"AT", no need to find shapefiles -
Border classification:
aoe_border()classifies points by distance to a line (e.g., international borders) - Coordinate column detection (handles
lon/long/longitude/x, etc.) - Equal-area projection for accurate buffering
- Area-proportional buffer calculation
- Point-in-polygon classification
- Coastline masking (optional, with bundled land polygon)
Installation
# Install from CRAN
install.packages("areaOfEffect")
# Or install development version from GitHub
# install.packages("pak")
pak::pak("gcol33/areaOfEffect")Usage
From a Dataframe
library(areaOfEffect)
# Plain dataframe with coordinates
df <- data.frame(
id = 1:4,
longitude = c(14.5, 15.2, 16.8, 20.0),
latitude = c(47.5, 48.1, 47.2, 48.5)
)
# Classify relative to Austria
result <- aoe(df, "Austria")Coastline Masking
For coastal countries, the buffer (scaled to equal area by default) extends into the sea. If you’re working with terrestrial data, that’s useless area. The mask parameter clips the halo to land:
# Use the bundled Natural Earth land polygon
result <- aoe(df, "Portugal", mask = "land")
# Or bring your own mask
result <- aoe(df, "Portugal", mask = my_land_polygon)The area parameter finds the buffer size that gives you the target halo area after clipping. So area = 1 guarantees equal land area in core and halo, even for countries like Japan where half the buffer would otherwise be ocean.
# Equal land area, not equal total area
result <- aoe(df, "Japan", mask = "land", area = 1)Scale
The scale parameter controls halo size as a proportion of core area.
Default: sqrt(2) - 1 ≈ 0.414, which gives equal core and halo areas.
| Scale | Halo:Core Area |
|---|---|
sqrt(2) - 1 (default) |
1:1 |
1 |
3:1 |
0.5 |
1.25:1 |
Support
“Software is like sex: it’s better when it’s free.” — Linus Torvalds
I’m a PhD student who builds R packages in my free time because I believe good tools should be free and open. I started these projects for my own work and figured others might find them useful too.
If this package saved you some time, buying me a coffee is a nice way to say thanks. It helps with my coffee addiction.
