Skip to contents

Create a random sampling domain polygon

Source: R/domain.R
create_sampling_domain.Rd

Generates a single polygon intended to represent a realistic study area for spatial simulation.

The original domain generator in spesim produced an "organic" outline derived from a radius–angle curve; while random, this tended to yield variations on the same motif. This function now supports multiple shape families so that default domains can look genuinely different between runs:

  • Concave / irregular (star-like, anisotropic, with indented bays)

  • Convex / irregular (random convex hulls)

  • Regular convex (circles/ellipses and boxy rectangles/squares)

Units: The default domain uses an arbitrary planar coordinate system (i.e., it is unitless). If you need real-world units (m, km) or a known CRS, supply your own sf polygon domain to the simulation/plotting functions.

Usage

create_sampling_domain(
  shape = c("mixed", "concave", "convex", "ellipse", "rectangle"),
  n_vertices = 80L,
  size = 10,
  aspect = NULL,
  rotation = NULL,
  probs = c(concave = 0.35, convex = 0.25, ellipse = 0.2, rectangle = 0.2),
  concave_lobes = NULL,
  attempts = 20L
)

Arguments

shape

Character. Which family of shapes to generate.

  • "mixed" (default): randomly chooses among concave, convex, ellipse, and rectangle-like shapes.

  • "concave": irregular, often concave, optionally anisotropic.

  • "convex": irregular but convex (convex hull of random points).

  • "ellipse": oval/circular (superellipse with exponent 2).

  • "rectangle": boxy rectangle/square (superellipse with large exponent).

n_vertices

Integer >= 12. Number of vertices used to trace the outline (more vertices => smoother shapes).

size

Positive numeric. Controls the overall scale (roughly the semi-axis length for regular shapes, and base radius for irregular shapes).

aspect

Optional numeric. Controls anisotropy as a y/x scale factor.

  • If NULL (default), an aspect ratio is drawn at random.

  • If a single number, it is used directly.

  • If length-2, a random value is drawn uniformly from that range.

rotation

Optional numeric (radians). If NULL, a random rotation is used.

probs

Numeric named vector of probabilities used when shape = "mixed". Names must be a subset of c("concave","convex","ellipse","rectangle").

concave_lobes

Optional integer in [2, 5]. Only used when shape = "concave" (or when shape = "mixed" selects a concave domain). Lower values yield simpler, less-lobed concave polygons; higher values yield more star-like outlines.

attempts

Integer. If a generated polygon is invalid (e.g. self-intersecting), retry up to this many times before falling back to a safe convex shape.

Value

An sf object with one row and a POLYGON geometry.

See also

sf::st_polygon(), sf::st_sf()

Examples

if (FALSE) { # \dontrun{
# default: a genuinely varied random domain
dom1 <- create_sampling_domain()
dom2 <- create_sampling_domain()

# force a family
dom_c <- create_sampling_domain(shape = "concave", concave_lobes = 3)
dom_e <- create_sampling_domain(shape = "ellipse", aspect = 1) # circle
dom_r <- create_sampling_domain(shape = "rectangle", aspect = c(0.6, 1.8))
} # }