Determine which areas in a sample unit should be prioritized

This function offers guidance for prioritizing sample locations and orders. It has two parts, the first essentially creates a very simple 'heatmap' tapering off from the geographic center of each polygon to be sampled for a germplasm collection. To keep the spatial data 'light' here, we use also hard angled edges (ala vectorization of a raster), and only suggest a few n_breaks per polygon. Each of the levels from this side of the function relate to increasing distances from the geographic center of the polygon. With cells denoted '1' being the most ideal areas to sample from in each polygon to maintain well spaced distances across the focal taxons range.

The second part offers a loose order for prioritizing the general order of collections. Using a user specified metric it attempts to 'spread' samples across the range to reduce the variance in the distances between samples in case the desired number of samples is not achieved.

within the individual sample units returned by each *Sample function. The goal of either method is to avoid having collectors teams 'cheat' the system by repeatedly collecting along the border between two or more grid cells. While we understand that many teams may be collecting closely due to the species biology, land management, or other restrictions, the goal of this function is to try and guide them in dispersing there activity.

The method used computes the geometric centroid of each region, if the center falls outside of the grid, it is snapped back onto the nearest location by default. Once the centers of each cell are calculated the remaining area of each grid has distances calculated between the centers and there locations. In final processing n_breaks are applied based on distances from the desired cell center to partition the space into different priority collection units.

Note that if you are submitting data from the PolygonBasedSample, the column n, must be maintained.

Usage

PrioritizeSample(
  x,
  n_breaks = 3,
  verbose = TRUE,
  metric = c("var", "sd", "energy", "cv")
)

Arguments

x

an sf/tibble/dataframe. a set of sample grids from any of the *Sample functions

n_breaks

Numeric. The number of breaks to return from the function, defaults to 3. Values beyond 5 of are questionable utility.

verbose

Bool. Whether to print messages to console or not, defaults to TRUE.

metric

character. The metric to minimize when ordering zones. Options are "var" (variance), "sd" (standard deviation), "energy" (sum of squared distances), and "cv" (coefficient of variation).

Value

An sf object containing the prioritization zones within each sample unit, with columns: ID, SampleOrder, Level, and geometry. The ID corresponds to the sample unit, SampleOrder is the order in which to prioritize sampling from each unit, Level is the priority level within each unit (1 being highest), and geometry is the spatial geometry of the prioritization zones.

Examples

if (FALSE) { # \dontrun{
nc <- sf::st_read(system.file("shape/nc.shp", package="sf"), quiet = TRUE) |>
  dplyr::select(NAME) |>
  sf::st_transform(5070) # should be in planar coordinate system.

set.seed(1)
zones <- EqualAreaSample(nc, n = 20, pts = 1000, planar_proj = 32617, reps = 100)

# the function requires an input sampling strategy to create the prioritization areas
ps <- PrioritizeSample(zones$Geometry, n_breaks = 3, metric = 'energy')

ggplot2::ggplot() +
  ggplot2::geom_sf(data = ps[['Geometry']],
  ggplot2::aes(fill = factor(Level)), color = 'white', lwd = 1) +
  ggplot2::theme_void() +
  ggplot2::labs(fill = 'Within Zone Priority:', title = 'Focal areas to center sampling within') +
  ggplot2::theme(legend.position= 'bottom')

ps[['Geometry']] |> ### to visualize without the priority zones within.
  dplyr::group_by(SampleOrder) |>
  dplyr::summarize(geometry = sf::st_union(geometry)) |>

  ggplot2::ggplot() +
  ggplot2::geom_sf(ggplot2::aes(fill = SampleOrder), color = 'white') +
  ggplot2::geom_sf_label(ggplot2::aes(label = SampleOrder), color = 'white', size = 7) +
  ggplot2::labs(fill = 'Sample Order', title = 'Priority guidance for sampling order') +
  ggplot2::theme_void() +
  ggplot2::theme(legend.position= 'bottom')
} # }