random_points: Generate random points within a stars object.

In BigelowLab/twinkle: twinkle

Generate random points within a stars object.

Description

Providing a polygon to limit the search area can speed up the search if the polygon is small relative to the spatial cover of the stars geometry.

Usage

random_points(
  x = volcano_multi(what = "bands", threshold = 120),
  n = 100,
  m = 2,
  na.rm = FALSE,
  points = NULL,
  polygon = NULL,
  form = c("table", "sf")[1]
)

Arguments

x	stars object
n	numeric, the number of points to return
m	multiplier to use when seeking to avoid missing values. Ignored if polygon is provided.
na.rm	logical, if TRUE then avoid cells with missing values.
points	a table of points to avoid. If na.rm is TRUE that is handled first, then point avoidance is handled. Ignored if NULL.
polygon	polygon (sf) that describes the region to select points from. Ignored if NULL.
form	character, specifies output format as "table" (default) or "sf"

Details

Note that it is possible to filter the available pool of candidate cells to something less than the requested sample size, n. In such cases you might try adjusting the value of m higher. If you still have issues then investigate the presence of NAs (if na.rm = TRUE), or the size of the polygon (if provided.)

Value

a table or sf POINT object of locations with values.

Examples

## Not run: 
# generate a multiband array, points and a polygon
set.seed(1)
x <- volcano_multi(what = 'bands', threshold = 120)
pts <- volcano_points(x, n = 30)
poly <- volcano_polygon()

# generate random points across layers that avoid where the array values are missing
p <- random_points(x, na.rm = TRUE, n = 30, form = "sf") |>
  dplyr::filter(band == 1)
plot(x[,,,1], reset = FALSE, axes = TRUE, main = "avoiding NAs")
plot(sf::st_geometry(dplyr::filter(p, band == 1)),
     add = TRUE, pch = 19, col = "orange")

# generate random points that avoid other known points
p <- random_points(x, points = pts, form = "sf", n = 30) |>
  dplyr::filter(band == 1)
plot(x[,,,1], reset = FALSE, axes = TRUE, main = "avoiding points")
plot(sf::st_geometry(dplyr::filter(p, band == 1)),
     add = TRUE, pch = 19, col = "orange")
plot(sf::st_geometry(dplyr::filter(pts, band == "1")),
     add = TRUE, pch = 15, col = "green")

# generate points within a polygon
set.seed(2)
p <- random_points(x, polygon = poly, form = "sf", n = 30) |>
  dplyr::filter(band == 1)
plot(x[,,,1], reset = FALSE, axes = TRUE, main = "within a polygon")
plot(sf::st_geometry(dplyr::filter(p, band == 1)),
     add = TRUE, pch = 19, col = "orange")
plot(sf::st_geometry(poly), add = TRUE, border = "green", col = NA)

# generate points within a polygon that also avoid NAs
# first, nudge the polygon to lower right
poly = twinkle::st_translate(poly, d=c(100, -100))
p <- random_points(x, polygon = poly, na.rm = TRUE, form = "sf") |>
  dplyr::filter(band == 1)
plot(x[,,,1], reset = FALSE, axes = TRUE, main = "within a polygon avoiding NAs")
plot(sf::st_geometry(dplyr::filter(p, band == 1)),
     add = TRUE, pch = 19, col = "orange")
plot(sf::st_geometry(poly),
     add = TRUE, border = "green", col = NA)


## End(Not run)

BigelowLab/twinkle documentation built on Jan. 26, 2025, 6:34 a.m.